Rename first-class tool template to V2 and update references - PR_26126_070-tool-template-v2-rename

Author: DavidQ

docs/design/tools/TOOLS_REENGINEERING_INDEX.md

@@ -27,7 +27,7 @@ This index lists the remaining rebuild anchors, schema baseline, and support fol
 | `codex` | `tools/codex` | support folder | reference-only | none | reference only; no normal rebuild doc |
 | `dev` | `tools/dev` | support folder | reference-only | none | reference only; no normal rebuild doc |
 | `shared` | `tools/shared` | support folder | reference-only | none | reference only; no normal rebuild doc |
-| `templates` | `tools/templates` | support folder | reference-only | none | reference only; no normal rebuild doc |
+| `templates-v2` | `tools/templates-v2` | support folder | reference-only | none | reference only; no normal rebuild doc |
 
 ## Classification Definitions
 - `global tool`: a launchable global surface. Palette Manager V2 is the only core rebuild anchor in this group.

docs/dev/PROJECT_INSTRUCTIONS.md

@@ -656,3 +656,15 @@ New first-class tools must include registry, index, and NAV wiring where applica
 New first-class tools must include Playwright launch coverage.
 
 Tool registration must not rely on hidden defaults or silent fallback.
+
+## TOOL TEMPLATE V2 LOCATION
+
+The official First-Class Tool V2 starter is:
+
+`tools/templates-v2/`
+
+Use the V2 naming consistently:
+- Tool Template V2
+- First-Class Tool Starter V2
+- First-Class Tools Surface V2
+- First-Class Tool V2

docs/dev/reports/playwright_v8_coverage_report.txt

@@ -13,12 +13,13 @@ 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
-(84%) First-Class Tool Starter Template - exercised 10 runtime JS files
+(84%) Tool Template V2 - 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
+(0%) tools/shared/vectorNativeTemplate.js - not covered
+(0%) tools/shared/vectorTemplateSampleGame.js - not covered
 
 Files with executed line/function counts where available:
 (2%) src/engine/input/ActionInputService.js - executed lines 397/397; executed functions 1/51
@@ -85,7 +86,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/templates-v2/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
@@ -108,10 +109,10 @@ Files with executed line/function counts where available:
 (80%) src/engine/theme/accordionV2/accordionV2.js - executed lines 26/26; executed functions 4/5
 (81%) tools/preview-generator-v2/PreviewGeneratorV2App.js - executed lines 539/539; executed functions 47/58
 (82%) samples/shared/sampleDetailPageEnhancement.js - executed lines 471/471; executed functions 41/50
-(86%) tools/templates/first-class-tool-starter/js/controls/StatusLogControl.js - executed lines 21/21; executed functions 6/7
+(86%) tools/templates-v2/js/controls/StatusLogControl.js - executed lines 21/21; executed functions 6/7
 (87%) tools/common/PaletteSortService.js - executed lines 103/103; executed functions 13/15
-(88%) tools/templates/first-class-tool-starter/js/controls/SourceInputControl.js - executed lines 33/33; executed functions 7/8
-(92%) tools/templates/first-class-tool-starter/js/controls/ToolStarterShellControl.js - executed lines 111/111; executed functions 11/12
+(88%) tools/templates-v2/js/controls/SourceInputControl.js - executed lines 33/33; executed functions 7/8
+(92%) tools/templates-v2/js/controls/ToolStarterShellControl.js - executed lines 111/111; executed functions 11/12
 (100%) samples/phase-01/0102/main.js - executed lines 23/23; executed functions 1/1
 (100%) samples/shared/numberUtils.js - executed lines 7/7; executed functions 1/1
 (100%) src/engine/audio/index.js - executed lines 15/15; executed functions 1/1
@@ -146,16 +147,21 @@ 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 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 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
+(100%) tools/templates-v2/js/bootstrap.js - executed lines 48/48; executed functions 4/4
+(100%) tools/templates-v2/js/controls/AccordionSection.js - executed lines 27/27; executed functions 5/5
+(100%) tools/templates-v2/js/controls/ActionNavControl.js - executed lines 51/51; executed functions 5/5
+(100%) tools/templates-v2/js/controls/InspectorControl.js - executed lines 8/8; executed functions 3/3
+(100%) tools/templates-v2/js/controls/PreviewPanelControl.js - executed lines 23/23; executed functions 5/5
+(100%) tools/templates-v2/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
+(0%) tools/shared/vectorNativeTemplate.js - uncovered
+(0%) tools/shared/vectorTemplateSampleGame.js - uncovered
 
 Changed JS files considered:
+(0%) tests/helpers/playwrightV8CoverageReporter.mjs - changed JS file not collected as browser runtime coverage
 (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
+(0%) tests/tools/RuntimeAssetLookupConsolidation.test.mjs - changed JS file not collected as browser runtime coverage
+(0%) tests/tools/VectorNativeTemplate.test.mjs - changed JS file not collected as browser runtime coverage
+(0%) tools/shared/vectorNativeTemplate.js - changed JS file not collected as browser runtime coverage
+(0%) tools/shared/vectorTemplateSampleGame.js - changed JS file not collected as browser runtime coverage

docs/dev/reports/tool_template_v2_rename.txt

@@ -0,0 +1,71 @@
+PR_26126_070-tool-template-v2-rename
+
+Scope:
+- Renamed the active template surface from tools/templates to tools/templates-v2.
+- Made tools/templates-v2/index.html the launchable Tool Template V2 entry point.
+- Moved support template folders under tools/templates-v2:
+  - starter-project-template
+  - vector-native-arcade
+- Updated active code, tests, and validation references that pointed at tools/templates.
+- No live tool folders, samples, schemas, start_of_day folders, or roadmap files were modified.
+
+Changes:
+- Removed the old tools/templates active folder surface.
+- Standardized visible/template wording to:
+  - First-Class Tool Starter V2
+  - First-Class Tools Surface V2
+  - Tool Template V2
+  - First-Class Tool V2
+- Updated Tool Template V2 root links to use src/engine/theme from its new depth.
+- Updated Tool Template V2 tool id to tool-template-v2.
+- Updated Tool Template V2 README and control/service contract docs.
+- Added Tool Template V2 location/naming guidance to docs/dev/PROJECT_INSTRUCTIONS.md.
+- Updated Playwright launch and coverage references from tools/templates/first-class-tool-starter to tools/templates-v2.
+- Updated vector-native and starter-project support paths to tools/templates-v2.
+- Updated the starter project validation script to use tools/templates-v2 and to resolve physical paths before optional fragment identifiers.
+- Updated the vector arcade sample README path reference to tools/templates-v2.
+
+Validation:
+- node --check tools/templates-v2/js/controls/ToolStarterShellControl.js
+- node --check tools/templates-v2/js/bootstrap.js
+- node --check tests/playwright/PreviewGeneratorV2Baseline.spec.mjs
+- node --check tests/helpers/playwrightV8CoverageReporter.mjs
+- node --check tools/shared/vectorNativeTemplate.js
+- node --check tools/shared/vectorTemplateSampleGame.js
+- node --check tools/templates-v2/tests/playwright/FirstClassToolStarter.spec.mjs
+- node --check scripts/validate-starter-project-template.mjs
+- node --test tests/tools/VectorNativeTemplate.test.mjs tests/tools/RuntimeAssetLookupConsolidation.test.mjs
+- node scripts/validate-starter-project-template.mjs
+- rg check confirmed tools/templates-v2/index.html has no inline style block, inline script block, or inline event handlers.
+- rg check confirmed active scripts, games README, tools, tests, docs/design index, and docs/dev/PROJECT_INSTRUCTIONS.md have no stale tools/templates path references.
+- git diff --check
+- npm run test:workspace-v2
+- npx playwright test --config tools/templates-v2/playwright.config.mjs --reporter=list
+
+Playwright impacted: Yes
+- This PR changes the launch path and visible identity for the Tool Template V2 surface.
+- npm run test:workspace-v2 passed.
+- Template-local Playwright passed.
+
+Playwright behavior validated:
+- tools/templates-v2/index.html launches.
+- tools/templates-v2/index.html?launch=workspace launches.
+- Default launch mode still shows tool NAV only.
+- Workspace launch mode still shows workspace NAV only.
+- Tool Template V2 uses src/engine/theme and has no tools/shared runtime dependency.
+- Existing accordions, panel role placement, primary action state, failure state, and status clear behavior still work.
+
+Old reference handling:
+- No active tools/templates folder remains.
+- No compatibility redirect folder was created.
+- Active code/test/reference paths were updated to tools/templates-v2.
+- Remaining old tools/templates references found outside active scope are historical roadmap, archived PR/report, move-history, or prior-run report records. They were intentionally not rewritten because this PR forbids roadmap changes and those files document historical state rather than active launch paths.
+
+Manual test notes:
+- Open tools/templates-v2/index.html and confirm First-Class Tool Starter V2 / First-Class Tools Surface V2 displays.
+- Confirm only the tool NAV is visible by default.
+- Open tools/templates-v2/index.html?launch=workspace and confirm only the workspace NAV is visible.
+- Confirm Status remains at the bottom of the right panel and still clears.
+
+Full samples smoke test:
+- Skipped. This PR only renames the template surface and updates targeted path references/tests.

games/vector-arcade-sample/README.md

@@ -1,6 +1,6 @@
 # Vector Arcade Sample
 
-This sample game is built from `tools/templates/vector-native-arcade/`.
+This sample game is built from `tools/templates-v2/vector-native-arcade/`.
 
 ## Baseline
 

scripts/validate-starter-project-template.mjs

@@ -13,7 +13,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const repoRoot = path.resolve(__dirname, "..");
 
-const TEMPLATE_MANIFEST_PATH = "tools/templates/starter-project-template/config/starter.project.json";
+const TEMPLATE_MANIFEST_PATH = "tools/templates-v2/starter-project-template/config/starter.project.json";
 const REPORT_PATH = "docs/dev/reports/starter_project_template_validation.txt";
 
 function assert(condition, message, issues) {
@@ -23,8 +23,9 @@ function assert(condition, message, issues) {
 }
 
 async function pathExists(repoRelativePath) {
+  const physicalPath = repoRelativePath.split("#")[0];
   try {
-    await fs.access(path.join(repoRoot, repoRelativePath));
+    await fs.access(path.join(repoRoot, physicalPath));
     return true;
   } catch {
     return false;

tests/helpers/playwrightV8CoverageReporter.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 
@@ -221,6 +222,7 @@ export class PlaywrightV8CoverageReporter {
       .filter(Boolean)
       .map((line) => this.pathFromStatusLine(line))
       .filter(Boolean)
+      .filter((filePath) => existsSync(path.resolve(this.repoRoot, filePath)))
       .filter((filePath) => filePath.endsWith(".js") || filePath.endsWith(".mjs"))
       .sort((left, right) => left.localeCompare(right));
   }
@@ -280,7 +282,7 @@ export class PlaywrightV8CoverageReporter {
     const toolEntryPoints = [
       { name: "Preview Generator V2", prefix: "tools/preview-generator-v2/" },
       { name: "Palette Manager", prefix: "tools/palette-manager-v2/" },
-      { name: "First-Class Tool Starter Template", prefix: "tools/templates/first-class-tool-starter/" },
+      { name: "Tool Template V2", prefix: "tools/templates-v2/" },
       { name: "Workspace V2", prefix: "tools/workspace-v2/" },
       { name: "Workspace Manager", prefix: "tools/workspace-manager/" }
     ];

tests/playwright/PreviewGeneratorV2Baseline.spec.mjs

@@ -123,7 +123,7 @@ async function openPaletteManager(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${query}`, { waitUntil: "networkidle" });
+  await page.goto(`${server.baseUrl}/tools/templates-v2/index.html${query}`, { waitUntil: "networkidle" });
   return server;
 }
 
@@ -451,7 +451,7 @@ test.describe("Preview Generator V2 baseline", () => {
     }
   });
 
-  test("launches first-class tool starter template with runtime-valid controls", async ({ page }) => {
+  test("launches Tool Template V2 with runtime-valid controls", async ({ page }) => {
     const server = await openToolTemplate(page);
     const pageErrors = [];
 
@@ -460,11 +460,12 @@ test.describe("Preview Generator V2 baseline", () => {
     });
 
     try {
-      await expect(page.locator("body.tools-platform-tool-page[data-tool-id='first-class-tool-starter']")).toBeVisible();
-      await expect(page.locator('link[href="../../../src/engine/theme/main.css"]')).toHaveCount(1);
-      await expect(page.locator('link[href="../../../src/engine/theme/accordionV2/accordionV2.css"]')).toHaveCount(1);
+      await expect(page.locator("body.tools-platform-tool-page[data-tool-id='tool-template-v2']")).toBeVisible();
+      await expect(page.locator('link[href="../../src/engine/theme/main.css"]')).toHaveCount(1);
+      await expect(page.locator('link[href="../../src/engine/theme/accordionV2/accordionV2.css"]')).toHaveCount(1);
       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-header]")).toContainText("First-Class Tool Starter V2");
+      await expect(page.locator("[data-tool-starter-header]")).toContainText("First-Class Tools Surface V2");
       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");
@@ -526,7 +527,7 @@ test.describe("Preview Generator V2 baseline", () => {
     }
   });
 
-  test("launches first-class tool starter template in workspace nav mode", async ({ page }) => {
+  test("launches Tool Template V2 in workspace nav mode", async ({ page }) => {
     const server = await openToolTemplate(page, "?launch=workspace");
     const pageErrors = [];
 

tests/tools/RuntimeAssetLookupConsolidation.test.mjs

@@ -52,16 +52,16 @@ export async function run() {
     gameId: "TemplateGame",
     runtimeAssetSources: {
       "vector.template.player": {
-        file: "tools/templates/vector-native-arcade/assets/data/vectors/template-player.vector.json",
-        path: "tools/templates/vector-native-arcade/assets/data/vectors/template-player.vector.json",
+        file: "tools/templates-v2/vector-native-arcade/assets/data/vectors/template-player.vector.json",
+        path: "tools/templates-v2/vector-native-arcade/assets/data/vectors/template-player.vector.json",
         kind: "vector"
       }
     },
     missingBindingBehavior: "static"
   });
 
   const fallbackResolved = fallbackLookup.resolvePackagedAsset({ id: "vector.template.player", type: "vector" });
-  assert.equal(fallbackResolved.file, "tools/templates/vector-native-arcade/assets/data/vectors/template-player.vector.json");
+  assert.equal(fallbackResolved.file, "tools/templates-v2/vector-native-arcade/assets/data/vectors/template-player.vector.json");
   assert.equal(fallbackLookup.binding.domains.vectors.length, 0);
   assert.equal(fallbackLookup.getErrors().some((entry) => entry.code === "RUNTIME_BINDING_REJECTED"), true);
   const fallbackDebug = fallbackLookup.getDebugState();

tests/tools/VectorNativeTemplate.test.mjs

@@ -3,7 +3,7 @@ import { buildVectorNativeTemplate, createVectorNativeTemplateDefinition, summar
 
 export async function run() {
   const definition = createVectorNativeTemplateDefinition();
-  assert.equal(definition.templatePath, "tools/templates/vector-native-arcade/");
+  assert.equal(definition.templatePath, "tools/templates-v2/vector-native-arcade/");
   assert.equal(definition.registry.sprites.length, 0);
   assert.equal(definition.registry.vectors.length, 5);