Add World Vector Studio V2 and Object Vector Studio V2 from Tool Template V2 - PR_26132_001-add-world-object-vector-studios

Author: DavidQ

docs/pr/PR_26132_001-add-world-object-vector-studios.md

@@ -0,0 +1,20 @@
+# PR_26132_001-add-world-object-vector-studios
+
+## Purpose
+
+Add World Vector Studio and Object Vector Studio as copied First-Class Tool V2 starter surfaces while keeping Primitive Skin Editor and Vector Map Editor intact.
+
+## Changes
+
+- Copied `tools/templates-v2/` into `tools/world-vector-studio-v2/`.
+- Copied `tools/templates-v2/` into `tools/object-vector-studio-v2/`.
+- Updated copied tool ids, visible titles, headers, README documentation, and copied launch checks.
+- Registered both new tools in `tools/toolRegistry.js` for registry-driven tools index launch wiring.
+- Marked Vector Map Editor and Primitive Skin Editor as deprecated in tool tiles and their existing documentation only.
+- Added How To Use pages for the two new studio tools.
+- Added Workspace Manager V2 Playwright coverage for tools index cards, launch definitions, and direct launch of both copied tool shells.
+
+## Validation
+
+- `npm run test:workspace-v2` passed: 38 tests.
+- Full samples smoke test was not run per BUILD scope.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -982,6 +982,18 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       await expect(textToSpeechToolCard).toBeVisible();
       await expect(textToSpeechToolCard.locator("a", { hasText: "Text to Speech V2" })).toHaveAttribute("href", "/tools/text2speech-V2/index.html");
       await expect(textToSpeechToolCard).toContainText("First-Class Tool V2 for browser speech synthesis");
+      const worldVectorStudioCard = page.locator(".tools-platform-card", { has: page.locator("h3", { hasText: "World Vector Studio" }) });
+      await expect(worldVectorStudioCard).toBeVisible();
+      await expect(worldVectorStudioCard.locator("a", { hasText: "World Vector Studio" })).toHaveAttribute("href", "/tools/world-vector-studio-v2/index.html");
+      await expect(worldVectorStudioCard).toContainText("Terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures");
+      const objectVectorStudioCard = page.locator(".tools-platform-card", { has: page.locator("h3", { hasText: "Object Vector Studio" }) });
+      await expect(objectVectorStudioCard).toBeVisible();
+      await expect(objectVectorStudioCard.locator("a", { hasText: "Object Vector Studio" })).toHaveAttribute("href", "/tools/object-vector-studio-v2/index.html");
+      await expect(objectVectorStudioCard).toContainText("Ships, enemies, pickups, actors, and reusable gameplay entities");
+      const vectorMapEditorCard = page.locator(".tools-platform-card", { has: page.locator("h3", { hasText: "Vector Map Editor" }) });
+      await expect(vectorMapEditorCard).toContainText("Deprecated");
+      const primitiveSkinEditorCard = page.locator(".tools-platform-card", { has: page.locator("h3", { hasText: "Primitive Skin Editor" }) });
+      await expect(primitiveSkinEditorCard).toContainText("Deprecated");
       const toolsIndexState = await page.evaluate(async () => {
         const registryModule = await import("/tools/toolRegistry.js");
         const launchModule = await import("/tools/shared/toolLaunchSSoTData.js");
@@ -1010,6 +1022,10 @@ test.describe("Workspace Manager V2 bootstrap", () => {
           plannedCards: Array.from(plannedToolsGrid?.querySelectorAll(".card h3") || [])
             .map((heading) => heading.textContent.trim()),
           registryIds: registryModule.getToolRegistry().map((tool) => tool.id),
+          studioLaunchDefinitions: {
+            world: launchModule.getSampleToolLaunchDefinition("world-vector-studio-v2"),
+            object: launchModule.getSampleToolLaunchDefinition("object-vector-studio-v2")
+          },
           removedLaunchDefinitions: {
             assetBrowser: launchModule.getSampleToolLaunchDefinition("asset-browser"),
             tileModelConverter: launchModule.getSampleToolLaunchDefinition("tile-model-converter")
@@ -1044,6 +1060,11 @@ test.describe("Workspace Manager V2 bootstrap", () => {
       expect(toolsIndexState.workflowCards).toEqual(["Workspace Manager V2"]);
       expect(toolsIndexState.utilitiesCards).not.toContain("Workspace Manager V2");
       expect(toolsIndexState.utilitiesCards).toContain("Text to Speech V2");
+      expect(toolsIndexState.allCards).toEqual(expect.arrayContaining(["World Vector Studio", "Object Vector Studio"]));
+      expect(toolsIndexState.registryIds).toEqual(expect.arrayContaining(["world-vector-studio-v2", "object-vector-studio-v2"]));
+      expect(toolsIndexState.launchIds).toEqual(expect.arrayContaining(["tool.world-vector-studio-v2", "tool.object-vector-studio-v2"]));
+      expect(toolsIndexState.studioLaunchDefinitions.world.launchDefinition.targetPath).toBe("/tools/world-vector-studio-v2/index.html");
+      expect(toolsIndexState.studioLaunchDefinitions.object.launchDefinition.targetPath).toBe("/tools/object-vector-studio-v2/index.html");
       expect(toolsIndexState.allCards).not.toContain("Asset Browser / Import Hub");
       expect(toolsIndexState.allCards).not.toContain("Tile Model Converter");
       expect(toolsIndexState.registryIds).not.toContain("asset-browser");
@@ -1091,6 +1112,48 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
+  test("launches World Vector Studio and Object Vector Studio copied tool shells", async ({ page }) => {
+    const server = await startRepoServer();
+    const pageErrors = [];
+
+    page.on("pageerror", (error) => {
+      pageErrors.push(error.message);
+    });
+
+    await coverageReporter.start(page);
+    try {
+      for (const tool of [
+        {
+          description: "Terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures",
+          id: "world-vector-studio-v2",
+          name: "World Vector Studio",
+          path: "world-vector-studio-v2"
+        },
+        {
+          description: "Ships, enemies, pickups, actors, and reusable gameplay entities",
+          id: "object-vector-studio-v2",
+          name: "Object Vector Studio",
+          path: "object-vector-studio-v2"
+        }
+      ]) {
+        await page.goto(`${server.baseUrl}/tools/${tool.path}/index.html`, { waitUntil: "networkidle" });
+        await expect(page.locator(`body.tools-platform-tool-page[data-tool-id="${tool.id}"]`)).toBeVisible();
+        await expect(page.locator("[data-tool-starter-header]")).toContainText(tool.name);
+        await expect(page.locator("[data-tool-starter-header]")).toContainText(tool.description);
+        await expect(page.locator(".tool-starter__tool__menu")).toBeVisible();
+        await expect(page.locator(".tool-starter__workspace__menu")).toBeHidden();
+        await page.locator("#sourceInput").fill(`${tool.name} launch coverage`);
+        await page.locator("#toolExportButton").click();
+        await expect(page.locator("#inspectorOutput")).toContainText(`"toolId": "${tool.id}"`);
+        await expect(page.locator("#statusLog")).toHaveValue(new RegExp(`Processed source value: ${tool.name} launch coverage`));
+      }
+      expect(pageErrors).toEqual([]);
+    } finally {
+      await coverageReporter.stop(page);
+      await server.close();
+    }
+  });
+
   test("uses First-Class Tool V2 theme contract", async ({ page }) => {
     const server = await openWorkspaceManagerV2(page);
     const pageErrors = [];

tools/SVG Asset Studio.zip

@@ -1,5 +1,7 @@
 # Skin Editor
 
+Deprecated: use Object Vector Studio for ships, enemies, pickups, actors, and reusable gameplay entities. Primitive Skin Editor remains available for existing workflows and has not been renamed or deleted.
+
 Skin Editor is a visual-plus-JSON skin workflow tool for:
 
 - Breakout

tools/Skin Editor/README.md

@@ -13,12 +13,13 @@
   <main class="wrap">
     <section class="hero">
       <h1>Skin Editor: How To Use</h1>
-      <p class="subtitle">Edit game skin JSON for Breakout, Pong, Solar System, and Bouncing Ball.</p>
+      <p class="subtitle">Deprecated: use Object Vector Studio for ships, enemies, pickups, actors, and reusable gameplay entities.</p>
     </section>
 
     <section class="section">
       <h2>Details</h2>
       <div class="card">
+        <p><strong>Deprecated:</strong> Primitive Skin Editor remains available for existing workflows and has not been renamed or deleted.</p>
         <p>Skin Editor manages color/size skin payloads for arcade games and stores overrides in browser local storage for immediate play-test loops.</p>
       </div>
     </section>

tools/Skin Editor/how_to_use.html

@@ -5,6 +5,8 @@ README.md
 
 # Vector Map Editor
 
+Deprecated: use World Vector Studio for terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures. Vector Map Editor remains available for existing workflows and has not been renamed or deleted.
+
 High-level overview for 'Vector Map Editor' under 'tools/Vector Map Editor/'.
 
 ## Purpose

tools/Vector Map Editor.zip

@@ -13,12 +13,13 @@
   <main class="wrap">
     <section class="hero">
       <h1>Vector Map Editor: How To Use</h1>
-      <p class="subtitle">Detailed workflow with practical steps and control guidance.</p>
+      <p class="subtitle">Deprecated: use World Vector Studio for terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures.</p>
     </section>
 
     <section class="section">
       <h2>Details</h2>
       <div class="card">
+        <p><strong>Deprecated:</strong> Vector Map Editor remains available for existing workflows and has not been renamed or deleted.</p>
         <p>Vector geometry authoring tool for map layout, collision review, and runtime export workflows.</p>
       </div>
     </section>

tools/Vector Map Editor/README.md

@@ -0,0 +1,25 @@
+# Object Vector Studio
+
+Object Vector Studio is a First-Class Tool V2 surface for ships, enemies, pickups, actors, and reusable gameplay entities.
+
+The tool folder was copied from `tools/templates-v2/` for `PR_26132_001-add-world-object-vector-studios`. It keeps the copied template CSS and modular control structure intact while giving the new studio its own first-class tool id: `object-vector-studio-v2`.
+
+## Scope
+
+- Ships and player/enemy actor vectors.
+- Pickups, hazards, projectiles, and reusable gameplay entities.
+- Entity-oriented vector object previews.
+- Reusable actor/object art structures for game manifests and future tool payloads.
+
+## Runtime Notes
+
+- The current implementation is the copied Tool Template V2 shell with Object Vector Studio naming and documentation.
+- JavaScript and CSS remain external.
+- The copied `docs/CONTROL_SERVICE_CONTRACTS.md` and `docs/BATCH_GUARDRAIL_CONTRACT.md` remain the local implementation contracts.
+- Primitive Skin Editor and Vector Map Editor remain available, but their active tool tiles are marked deprecated in favor of the new studio split.
+
+## Validation
+
+Targeted validation for this PR is:
+
+`npm run test:workspace-v2`

tools/Vector Map Editor/how_to_use.html

@@ -0,0 +1,51 @@
+# Tool Template V2 Batch Guardrail Contract
+
+Batch operations process repeated work across real discovered inputs. A First-Class Tool V2 batch flow must be explicit, observable, and safe to resume or diagnose.
+
+## Discovery Rules
+
+- Discover real files and directories.
+- Never assume numeric folder sequences.
+- Missing discovered candidates are logged as `SKIP`, not `FAIL`, unless the missing item is the selected single input.
+- Logs must identify the resolved input path or identifier for every item.
+
+## Per-Item Logging
+
+Every item must log exactly one terminal outcome through the tool logger:
+
+- `OK`: item completed and wrote or updated the expected output.
+- `WARN`: item completed with a recoverable warning.
+- `FAIL`: item failed with an actionable error.
+- `SKIP`: item was intentionally skipped.
+
+Per-item logs must include the item identifier and the reason for `WARN`, `FAIL`, or `SKIP`.
+
+## Failure Isolation
+
+- One item failure must not stop the batch unless the failure is global.
+- Global failures include missing required configuration, unavailable repo access, invalid destination root, or a cancelled run.
+- Batch processors must keep processing remaining discovered items after item-level `FAIL` or `SKIP` outcomes.
+
+## Summary Contract
+
+Every batch run must finish with a summary that includes:
+
+- `written`
+- `failed`
+- `skipped`
+- `warnings`
+
+The summary must match the per-item log outcomes.
+
+## Stop/Cancel Contract
+
+Long-running batches must support a stop or cancel pattern when applicable.
+
+- Stop/cancel requests must prevent new items from starting.
+- Already-running item work should finish or fail safely.
+- Cancelled remaining items should be logged as `SKIP` or another clearly documented non-success outcome.
+- The final summary must make cancellation visible.
+
+## No Silent Fallback
+
+Batch processors must not invent default inputs, substitute fallback targets, or claim success when a fallback or partial result occurred.