Standardize first-class tool panel roles and move status to right-bottom output area - PR_26126_069-tool-template-panel-role-standardization

Author: DavidQ

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -567,6 +567,10 @@ No PR is complete with:
 - Tools must use consistent header, NAV, panel, accordion, status, and action patterns.
 - Left and right tool panels must use working accordion sections unless explicitly exempted.
 - Dead accordion controls are prohibited.
+- Left panel = user input/setup.
+- Center = primary work surface.
+- Right panel = output/status/logging/diagnostics.
+- Status/log sections belong at the bottom of the right panel unless explicitly justified otherwise.
 
 ## INPUT RESOLUTION RULES
 

docs/dev/reports/playwright_v8_coverage_report.txt

@@ -18,10 +18,7 @@ Exercised tool entry points detected:
 (0%) Workspace Manager - not exercised by this Playwright run
 
 Changed runtime JS files covered:
-(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
+(100%) none changed - no changed runtime JS files
 
 Files with executed line/function counts where available:
 (2%) src/engine/input/ActionInputService.js - executed lines 397/397; executed functions 1/51
@@ -157,12 +154,8 @@ Files with executed line/function counts where available:
 (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 - no low-coverage changed runtime JS files
+(100%) none changed - no changed runtime JS files
 
 Changed JS files considered:
 (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_panel_role_standardization.txt

@@ -0,0 +1,51 @@
+PR_26126_069-tool-template-panel-role-standardization
+
+Scope:
+- Updated the official first-class tool starter layout at tools/templates/first-class-tool-starter/.
+- Updated first-class tool template README and control/service contracts.
+- Added the panel role standard to docs/dev/PROJECT_INSTRUCTIONS.md under UI CONSISTENCY CONTRACT.
+- Updated existing Playwright coverage for panel role placement.
+- No live tools outside tools/templates, samples, schemas, roadmap, start_of_day folders, or tools/shared files were modified.
+
+Changes:
+- Moved the Status accordion from the left column to the bottom of the right column.
+- Kept Output Summary above Status in the right column.
+- Left column now contains only user-editable/setup controls in the starter.
+- Center column remains the primary preview/work surface.
+- Right column now owns generated output, summary, status, and logging in the starter.
+- Documented the standard three-column first-class tool layout in:
+  - tools/templates/first-class-tool-starter/README.md
+  - tools/templates/first-class-tool-starter/docs/CONTROL_SERVICE_CONTRACTS.md
+  - docs/dev/PROJECT_INSTRUCTIONS.md
+- Preserved Preview Generator V2 visual/theme alignment, src/engine/theme usage, and 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 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 layout and panel-role placement.
+- npm run test:workspace-v2 passed.
+- Template-local Playwright passed.
+
+Playwright behavior validated:
+- Starter left panel contains Input Source and does not contain Status.
+- Starter center panel contains Preview.
+- Starter right panel contains Output Summary and Status.
+- Status remains a working accordion and remains the last accordion in the right panel.
+- Existing starter nav modes, accordion behavior, required-field gating, primary action, and status clear behavior still work.
+
+Manual test notes:
+- Open tools/templates/first-class-tool-starter/index.html.
+- Confirm the left panel contains only Input Source.
+- Confirm the center panel contains Preview.
+- Confirm the right panel contains Output Summary above Status.
+- Confirm Status collapses/expands and Clear still empties the status log.
+
+Full samples smoke test:
+- Skipped. This PR only changes the first-class tool starter template, template documentation, project instructions wording, and targeted tests.

tests/playwright/PreviewGeneratorV2Baseline.spec.mjs

@@ -472,6 +472,12 @@ test.describe("Preview Generator V2 baseline", () => {
       await expect(page.locator("#toolExportButton")).toHaveText("Export");
       await expect(page.locator("#toolCopyJsonButton")).toHaveText("Copy JSON");
       await expect(page.locator("#toolExportToolStateButton")).toHaveText("Export toolState");
+      await expect(page.locator(".tool-starter__panel--left #sourceInputContent")).toBeVisible();
+      await expect(page.locator(".tool-starter__panel--left #statusLogContent")).toHaveCount(0);
+      await expect(page.locator(".tool-starter__panel--center #previewPanelContent")).toBeVisible();
+      await expect(page.locator(".tool-starter__panel--right #inspectorContent")).toBeVisible();
+      await expect(page.locator(".tool-starter__panel--right #statusLogContent")).toBeVisible();
+      await expect(page.locator(".tool-starter__panel--right .accordion-v2").last()).toContainText("Status");
 
       const duplicateIds = await page.evaluate(() => {
         const ids = [...document.querySelectorAll("[id]")].map((element) => element.id);

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

@@ -79,6 +79,17 @@ The contracts define:
 - Do not use inline event handlers such as `onclick`, `onchange`, or `oninput`.
 - Do not add hidden defaults or silent fallback data.
 
+## Panel Layout Standard
+
+First-class tools use a consistent three-column layout:
+
+- Left panel: user input, setup, and intent controls only.
+- Center panel: primary work surface, editor, canvas, or preview.
+- Right panel: generated output, summaries, diagnostics, logs, and status.
+- Status/log sections belong at the bottom of the right panel unless a PR explicitly justifies a different placement.
+
+The starter demonstrates this standard with Input Source on the left, Preview in the center, and Output Summary above Status on the right.
+
 ## Creating A New Tool
 
 1. Copy `tools/templates/first-class-tool-starter/` to `tools/<tool-id>/`.

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

@@ -39,6 +39,17 @@ Common methods:
 
 Controls communicate through injected callbacks, injected services, or the app/root coordinator. A control must not directly edit another control's DOM or internal state.
 
+## Panel Role Contract
+
+First-class tools use a consistent three-column layout contract:
+
+- Left panel owns user input, setup, and intent controls only.
+- Center panel owns the primary work surface, editor, canvas, or preview.
+- Right panel owns generated output, summaries, diagnostics, logs, and status.
+- Status and log controls belong at the bottom of the right panel unless a PR explicitly justifies a different placement.
+
+Controls should be placed according to these panel roles before adding new sections. A control that mixes input and output responsibilities should be split into separate controls.
+
 ## Service Contract
 
 Services contain non-DOM logic.

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

@@ -64,16 +64,6 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface</h2>
           </div>
         </section>
 
-        <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
-          <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="statusLogContent">
-            <span>Status</span>
-            <span class="accordion-v2__icon" aria-hidden="true">+</span>
-          </button>
-          <div id="statusLogContent" class="accordion-v2__content">
-            <button id="clearStatusButton" type="button">Clear</button>
-            <textarea id="statusLog" readonly rows="10" aria-label="Status log"></textarea>
-          </div>
-        </section>
       </aside>
 
       <section class="tool-starter__panel tool-starter__panel--center" aria-label="Tool preview">
@@ -100,6 +90,17 @@ <h2 class="tools-platform-frame__eyebrow">First-Class Tools Surface</h2>
             <pre id="inspectorOutput" class="tool-starter__output">{}</pre>
           </div>
         </section>
+
+        <section class="accordion-v2 tool-starter__accordion is-open" data-accordion-v2-open="true">
+          <button class="accordion-v2__header" type="button" aria-expanded="true" aria-controls="statusLogContent">
+            <span>Status</span>
+            <span class="accordion-v2__icon" aria-hidden="true">+</span>
+          </button>
+          <div id="statusLogContent" class="accordion-v2__content">
+            <button id="clearStatusButton" type="button">Clear</button>
+            <textarea id="statusLog" readonly rows="10" aria-label="Status log"></textarea>
+          </div>
+        </section>
       </aside>
     </main>
     <script type="module" src="../../../src/engine/theme/mount-shared-header.js"></script>

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

@@ -97,6 +97,19 @@ test.describe("First-Class Tool Starter", () => {
     await expect(workspaceNav.getByRole("button", { name: "Export manifest" })).toBeVisible();
   });
 
+  test("uses standardized panel roles", async ({ page }) => {
+    const leftPanel = page.locator(".tool-starter__panel--left");
+    const centerPanel = page.locator(".tool-starter__panel--center");
+    const rightPanel = page.locator(".tool-starter__panel--right");
+
+    await expect(leftPanel.locator("#sourceInputContent")).toBeVisible();
+    await expect(leftPanel.locator("#statusLogContent")).toHaveCount(0);
+    await expect(centerPanel.locator("#previewPanelContent")).toBeVisible();
+    await expect(rightPanel.locator("#inspectorContent")).toBeVisible();
+    await expect(rightPanel.locator("#statusLogContent")).toBeVisible();
+    await expect(rightPanel.locator(".accordion-v2").last()).toContainText("Status");
+  });
+
   test("Hide Header and Details toggles header state", async ({ page }) => {
     const summary = page.locator("[data-tool-starter-summary]");
     const details = page.locator(".is-collapsible");