Add first-class tool Playwright depth guidance and deprecate tools/shared usage in templates - PR_26126_065-tool-template-playwright-e2e-depth

Author: DavidQ

docs/dev/reports/tool_template_playwright_e2e_depth.txt

@@ -0,0 +1,36 @@
+# PR_26126_065 Tool Template Playwright E2E Depth
+
+Scope:
+- Updated tools/templates/first-class-tool-starter only.
+- Added required review reports under docs/dev/reports.
+- Preserved runtime behavior outside tools/templates.
+
+Template updates:
+- Updated index.html header markup to follow the Palette Manager V2 pattern: body.tools-platform-tool-page, collapsible header/details, #shared-theme-header, and a tool-local header host.
+- Added template-local Playwright config at tools/templates/first-class-tool-starter/playwright.config.mjs.
+- Added starter Playwright behavior coverage at tools/templates/first-class-tool-starter/tests/playwright/FirstClassToolStarter.spec.mjs.
+- Updated README Playwright guidance to require meaningful behavior validation instead of page-load-only checks.
+- Updated README and contracts to explicitly document tools/shared/ as deprecated for first-class tools: no imports, no script references, no CSS references, no runtime dependency.
+- Kept existing external CSS and external JavaScript module structure; no inline handlers were added.
+
+Template Playwright coverage demonstrates:
+- tool launch
+- Palette Manager-style header shell presence
+- accordion expand/collapse behavior
+- primary action button state transition when required input becomes valid
+- missing input/failure state
+- status/log clear behavior
+
+Validation:
+- Playwright impacted: No for active runtime.
+- No active runtime/workspace/toolState behavior changed; this PR changes starter template files only.
+- Ran template-local Playwright validation: npx playwright test --config tools/templates/first-class-tool-starter/playwright.config.mjs --reporter=list -> 5 passed.
+- Syntax checked all first-class-tool-starter JavaScript and Playwright files with node --check.
+- Verified template HTML has no inline script blocks, style blocks, or inline event handlers.
+- Verified docs clearly state tools/shared/ deprecation.
+- Verified no tracked roadmap, sample, start_of_day, games, src, tools/shared, package, or package-lock files changed.
+- Did not run npm run test:workspace-v2 because active workspace/tool runtime was not impacted.
+
+Manual test notes:
+- Run npx playwright test --config tools/templates/first-class-tool-starter/playwright.config.mjs --reporter=list and confirm all starter behavior tests pass.
+- Open tools/templates/first-class-tool-starter/index.html through an HTTP server and confirm header, accordions, Run state, status logging, and Clear still behave as shown by the starter tests.

tools/templates/first-class-tool-starter/README.md

@@ -9,6 +9,7 @@ Copy this folder to `tools/<tool-id>/`, then rename the class prefixes, visible
 ```text
 tools/<tool-id>/
   index.html
+  playwright.config.mjs
   README.md
   docs/
     CONTROL_SERVICE_CONTRACTS.md
@@ -26,17 +27,22 @@ tools/<tool-id>/
       StatusLogControl.js
     services/
       ToolStateSerializer.js
+  tests/
+    playwright/
+      FirstClassToolStarter.spec.mjs
 ```
 
 ## Required Files
 
 - `index.html`: semantic tool shell with no inline `<script>`, no inline `<style>`, and no inline event handlers.
+- `playwright.config.mjs`: template-local Playwright config for validating the copied starter before registry integration.
 - `styles/*.css`: all tool styles.
 - `js/bootstrap.js`: small startup file that creates class instances and wires dependencies.
 - `js/ToolStarterApp.js`: app/root coordinator only.
 - `js/controls/*.js`: one class per UI control or section.
 - `js/services/*.js`: focused non-UI helper classes when needed.
 - `docs/CONTROL_SERVICE_CONTRACTS.md`: required control, service, app/root, logger, and batch processor contracts.
+- `tests/playwright/*.spec.mjs`: starter behavior coverage to copy and rename with the new tool.
 - `README.md`: tool-specific usage, contracts, and validation notes.
 
 ## Required Contracts
@@ -55,13 +61,18 @@ The contracts define:
 
 - One class per file.
 - One control or section per class.
+- Header markup follows the Palette Manager V2 pattern: `body.tools-platform-tool-page`, collapsible header/details, `#shared-theme-header`, and a tool-local header host.
 - App/root class coordinates only and must not own DOM logic or business logic.
 - Controls own their DOM and their events.
 - Controls communicate through injected callbacks or the app coordinator.
 - Services contain non-DOM logic and return results/errors for the app, controls, or logger to display.
 - Logger is the single writer for status/log output.
 - Reusable UI behavior must live in reusable classes such as `AccordionSection`.
-- Do not depend on `tools/shared`.
+- `tools/shared/` is deprecated for first-class tools:
+  - no imports
+  - no script references
+  - no CSS references
+  - no runtime dependency
 - Do not use inline event handlers such as `onclick`, `onchange`, or `oninput`.
 - Do not add hidden defaults or silent fallback data.
 
@@ -80,18 +91,28 @@ The contracts define:
 
 Every new first-class tool must include Playwright coverage that launches the tool and validates meaningful behavior.
 
+The starter includes `tests/playwright/FirstClassToolStarter.spec.mjs` as a copyable baseline. Rename it with the new tool and keep the behavior depth.
+
 Minimum coverage:
 
 - tool page loads without runtime errors
+- Palette Manager-style header shell is present
 - primary user action can be triggered or correctly blocked
-- required controls render and respond
 - accordion sections expand and collapse
+- primary action button changes state when required input becomes valid
+- status/log clear behavior works
 - at least one failure state is visible when invalid input is applicable
 
 The required validation command for impacted tool runtime or UI work is:
 
 `npm run test:workspace-v2`
 
+When validating only the copied starter before registry integration, run the copied tool's Playwright spec directly and then add it to the relevant workspace/tool test lane.
+
+Template-local command:
+
+`npx playwright test --config tools/<tool-id>/playwright.config.mjs`
+
 ## Review Artifacts
 
 Every PR that creates or changes a first-class tool must produce:

tools/templates/first-class-tool-starter/docs/CONTROL_SERVICE_CONTRACTS.md

@@ -2,6 +2,17 @@
 
 These contracts define the required structure for first-class tool code created from this starter.
 
+## Deprecated Shared Tool Surface
+
+`tools/shared/` is deprecated for first-class tools.
+
+First-class tools must have:
+
+- no imports from `tools/shared/`
+- no script references to `tools/shared/`
+- no CSS references to `tools/shared/`
+- no runtime dependency on `tools/shared/`
+
 ## Control Contract
 
 Controls own one UI control or one UI section.
@@ -146,5 +157,4 @@ Before a first-class tool PR is ready:
 - Batch work logs per item and summarizes counts.
 - No inline event handlers exist in HTML.
 - No inline `<script>` or `<style>` blocks exist in HTML.
-- No `tools/shared` dependency exists.
-
+- No `tools/shared/` dependency exists.

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

@@ -7,14 +7,20 @@
     <link rel="stylesheet" href="./styles/toolStarter.css">
     <script type="module" src="./js/bootstrap.js"></script>
   </head>
-  <body>
-    <header id="shared-theme-header" class="tool-starter__header">
-      <div>
-        <h1>First-Class Tool Starter</h1>
-        <p>Replace this shell with the new tool name and purpose.</p>
+  <body class="tools-platform-tool-page hub-page-tools" data-tool-id="first-class-tool-starter">
+    <details class="is-collapsible" open>
+      <summary class="is-collapsible__summary" data-tool-starter-summary>Hide Header and Details</summary>
+      <div class="is-collapsible__content">
+        <div id="shared-theme-header"></div>
+        <div class="tool-starter__header" data-tool-starter-header>
+          <div>
+            <h1>First-Class Tool Starter</h1>
+            <p>Replace this shell with the new tool name and purpose.</p>
+          </div>
+          <p class="tool-starter__header-meta">Self-contained starter</p>
+        </div>
       </div>
-      <p class="tool-starter__header-meta">Self-contained starter</p>
-    </header>
+    </details>
 
     <nav class="tool-starter__menu" aria-label="Tool actions">
       <button id="runToolButton" type="button">Run</button>

tools/templates/first-class-tool-starter/playwright.config.mjs

@@ -0,0 +1,10 @@
+export default {
+  testDir: "./tests/playwright",
+  timeout: 30000,
+  outputDir: "./tests/results",
+  use: {
+    headless: true,
+    trace: "retain-on-failure"
+  }
+};
+

tools/templates/first-class-tool-starter/styles/toolStarter.css

@@ -49,13 +49,36 @@ textarea:focus-visible {
   outline-offset: 2px;
 }
 
+.is-collapsible {
+  border-bottom: 1px solid var(--tool-starter-line);
+  background: #151a24;
+}
+
+.is-collapsible__summary {
+  min-height: 36px;
+  display: flex;
+  align-items: center;
+  cursor: pointer;
+  color: var(--tool-starter-muted);
+  font-weight: 700;
+  padding: 8px 18px;
+}
+
+.is-collapsible__content {
+  display: grid;
+  gap: 0;
+}
+
+#shared-theme-header {
+  min-height: 0;
+}
+
 .tool-starter__header {
   min-height: 76px;
   display: flex;
   align-items: center;
   justify-content: space-between;
   gap: 16px;
-  border-bottom: 1px solid var(--tool-starter-line);
   background: #151a24;
   padding: 14px 18px;
 }
@@ -273,4 +296,3 @@ textarea:focus-visible {
     text-align: left;
   }
 }
-

tools/templates/first-class-tool-starter/tests/playwright/FirstClassToolStarter.spec.mjs

@@ -0,0 +1,116 @@
+import { expect, test } from "@playwright/test";
+import { createServer } from "node:http";
+import { extname, join, normalize, relative, resolve } from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const STARTER_ROOT = resolve(fileURLToPath(new URL("../..", import.meta.url)));
+const CONTENT_TYPES = new Map([
+  [".css", "text/css; charset=utf-8"],
+  [".html", "text/html; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"]
+]);
+
+let server;
+let starterUrl;
+
+async function startStaticServer() {
+  server = createServer(async (request, response) => {
+    try {
+      const requestPath = request.url === "/" ? "/index.html" : new URL(request.url, "http://127.0.0.1").pathname;
+      const filePath = normalize(join(STARTER_ROOT, decodeURIComponent(requestPath)));
+      const relativePath = relative(STARTER_ROOT, filePath);
+      if (relativePath.startsWith("..")) {
+        response.writeHead(403);
+        response.end("Forbidden");
+        return;
+      }
+
+      const fileStat = await stat(filePath);
+      if (!fileStat.isFile()) {
+        response.writeHead(404);
+        response.end("Not found");
+        return;
+      }
+
+      const contentType = CONTENT_TYPES.get(extname(filePath)) || "application/octet-stream";
+      response.writeHead(200, { "content-type": contentType });
+      response.end(await readFile(filePath));
+    } catch {
+      response.writeHead(404);
+      response.end("Not found");
+    }
+  });
+
+  await new Promise((resolveServer) => {
+    server.listen(0, "127.0.0.1", resolveServer);
+  });
+  const address = server.address();
+  starterUrl = `http://127.0.0.1:${address.port}/index.html`;
+}
+
+test.describe("First-Class Tool Starter", () => {
+  test.beforeAll(async () => {
+    await startStaticServer();
+  });
+
+  test.afterAll(async () => {
+    await new Promise((resolveServer) => server.close(resolveServer));
+  });
+
+  test.beforeEach(async ({ page }) => {
+    await page.goto(starterUrl);
+  });
+
+  test("launches with Palette Manager-style header shell", async ({ page }) => {
+    await expect(page.locator("body.tools-platform-tool-page[data-tool-id='first-class-tool-starter']")).toBeVisible();
+    await expect(page.locator(".is-collapsible")).toBeVisible();
+    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]")).toContainText("Hide Header and Details");
+  });
+
+  test("accordion sections collapse and expand", async ({ page }) => {
+    const sourceHeader = page.getByRole("button", { name: "Input Source" });
+    const sourceContent = page.locator("#sourceInputContent");
+
+    await expect(sourceContent).toBeVisible();
+    await sourceHeader.click();
+    await expect(sourceContent).toBeHidden();
+    await expect(sourceHeader).toHaveAttribute("aria-expanded", "false");
+    await sourceHeader.click();
+    await expect(sourceContent).toBeVisible();
+    await expect(sourceHeader).toHaveAttribute("aria-expanded", "true");
+  });
+
+  test("primary action state changes when required input is valid", async ({ page }) => {
+    const runButton = page.locator("#runToolButton");
+    const exportButton = page.locator("#exportToolStateButton");
+    const sourceInput = page.locator("#sourceInput");
+
+    await expect(runButton).toBeDisabled();
+    await expect(exportButton).toBeDisabled();
+    await sourceInput.fill("starter value");
+    await expect(runButton).toBeEnabled();
+    await expect(exportButton).toBeEnabled();
+  });
+
+  test("missing input failure state is visible", async ({ page }) => {
+    const sourceInput = page.locator("#sourceInput");
+    const runButton = page.locator("#runToolButton");
+
+    await sourceInput.fill("starter value");
+    await sourceInput.fill("");
+    await expect(runButton).toBeDisabled();
+    await expect(page.locator("#sourceValidationMessage")).toContainText("Input is required");
+  });
+
+  test("status log clear behavior works after primary action", async ({ page }) => {
+    await page.locator("#sourceInput").fill("starter value");
+    await page.locator("#runToolButton").click();
+    await expect(page.locator("#statusLog")).toHaveValue(/Processed source value/);
+
+    await page.locator("#clearStatusButton").click();
+    await expect(page.locator("#statusLog")).toHaveValue("");
+  });
+});