Define Object Vector Studio V2 requirements and correct V2 naming - PR_26132_002-object-vector-studio-v2-requirements

Author: DavidQ

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

@@ -2,7 +2,7 @@
 
 ## 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.
+Add World Vector Studio V2 and Object Vector Studio V2 as copied First-Class Tool V2 starter surfaces while keeping Primitive Skin Editor and Vector Map Editor intact.
 
 ## Changes
 

docs/pr/PR_26132_002-object-vector-studio-v2-requirements.md

@@ -0,0 +1,31 @@
+# PR_26132_002-object-vector-studio-v2-requirements
+
+## Purpose
+
+Document Object Vector Studio V2 requirements before runtime implementation and normalize user-facing studio names to `Object Vector Studio V2` and `World Vector Studio V2`.
+
+## Changes
+
+- Updated user-facing labels for the new studios to include `V2`.
+- Added Object Vector Studio V2 requirements/design documentation at `tools/object-vector-studio-v2/docs/OBJECT_VECTOR_STUDIO_V2_REQUIREMENTS.md`.
+- Documented schema-only session loading, launched-with-parameters file reads, required palette behavior, responsive hide-header layout, accordion space sharing, scrollable controls, selected item visibility, object tiles, column responsibilities, workspace nav, and tool nav.
+- Kept Primitive Skin Editor and Vector Map Editor available and only updated their deprecation text to point to the V2 studio names.
+
+## Playwright Impact
+
+Playwright impacted: No.
+
+No Playwright impact. This PR is requirements/docs and user-facing naming only.
+
+## Validation
+
+- Playwright was not run because this PR does not implement runtime behavior.
+- Full samples smoke test was not run per BUILD scope; this is requirements/docs only.
+
+## Manual Validation
+
+1. Open `tools/object-vector-studio-v2/docs/OBJECT_VECTOR_STUDIO_V2_REQUIREMENTS.md`.
+2. Confirm it covers schema-only session loading, launched-with-parameters file read, required palette, responsive hide-header layout, accordion behavior, scrollable controls, selected item visibility, left/right column responsibilities, object tiles, workspace nav, and tool nav.
+3. Open the tool index after the previous PR is applied and confirm the user-facing names read `Object Vector Studio V2` and `World Vector Studio V2`.
+
+Expected outcome: documentation is present and no runtime behavior is added in this PR.

tests/playwright/tools/WorkspaceManagerV2.spec.mjs

@@ -982,13 +982,13 @@ 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" }) });
+      const worldVectorStudioCard = page.locator(".tools-platform-card", { has: page.locator("h3", { hasText: "World Vector Studio V2" }) });
       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.locator("a", { hasText: "World Vector Studio V2" })).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" }) });
+      const objectVectorStudioCard = page.locator(".tools-platform-card", { has: page.locator("h3", { hasText: "Object Vector Studio V2" }) });
       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.locator("a", { hasText: "Object Vector Studio V2" })).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");
@@ -1060,7 +1060,7 @@ 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.allCards).toEqual(expect.arrayContaining(["World Vector Studio V2", "Object Vector Studio V2"]));
       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");
@@ -1112,7 +1112,7 @@ test.describe("Workspace Manager V2 bootstrap", () => {
     }
   });
 
-  test("launches World Vector Studio and Object Vector Studio copied tool shells", async ({ page }) => {
+  test("launches World Vector Studio V2 and Object Vector Studio V2 copied tool shells", async ({ page }) => {
     const server = await startRepoServer();
     const pageErrors = [];
 
@@ -1126,13 +1126,13 @@ test.describe("Workspace Manager V2 bootstrap", () => {
         {
           description: "Terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures",
           id: "world-vector-studio-v2",
-          name: "World Vector Studio",
+          name: "World Vector Studio V2",
           path: "world-vector-studio-v2"
         },
         {
           description: "Ships, enemies, pickups, actors, and reusable gameplay entities",
           id: "object-vector-studio-v2",
-          name: "Object Vector Studio",
+          name: "Object Vector Studio V2",
           path: "object-vector-studio-v2"
         }
       ]) {

tools/Skin Editor/README.md

@@ -1,6 +1,6 @@
 # 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.
+Deprecated: use Object Vector Studio V2 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:
 

tools/Skin Editor/how_to_use.html

@@ -13,7 +13,7 @@
   <main class="wrap">
     <section class="hero">
       <h1>Skin Editor: How To Use</h1>
-      <p class="subtitle">Deprecated: use Object Vector Studio for ships, enemies, pickups, actors, and reusable gameplay entities.</p>
+      <p class="subtitle">Deprecated: use Object Vector Studio V2 for ships, enemies, pickups, actors, and reusable gameplay entities.</p>
     </section>
 
     <section class="section">

tools/Vector Map Editor/README.md

@@ -5,7 +5,7 @@ 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.
+Deprecated: use World Vector Studio V2 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/'.
 

tools/Vector Map Editor/how_to_use.html

@@ -13,7 +13,7 @@
   <main class="wrap">
     <section class="hero">
       <h1>Vector Map Editor: How To Use</h1>
-      <p class="subtitle">Deprecated: use World Vector Studio for terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures.</p>
+      <p class="subtitle">Deprecated: use World Vector Studio V2 for terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures.</p>
     </section>
 
     <section class="section">

tools/object-vector-studio-v2/README.md

@@ -1,6 +1,6 @@
-# Object Vector Studio
+# Object Vector Studio V2
 
-Object Vector Studio is a First-Class Tool V2 surface for ships, enemies, pickups, actors, and reusable gameplay entities.
+Object Vector Studio V2 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`.
 
@@ -13,9 +13,10 @@ The tool folder was copied from `tools/templates-v2/` for `PR_26132_001-add-worl
 
 ## Runtime Notes
 
-- The current implementation is the copied Tool Template V2 shell with Object Vector Studio naming and documentation.
+- The current implementation is the copied Tool Template V2 shell with Object Vector Studio V2 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.
+- `docs/OBJECT_VECTOR_STUDIO_V2_REQUIREMENTS.md` captures the future Object Vector Studio V2 requirements and design constraints.
 - 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

tools/object-vector-studio-v2/docs/OBJECT_VECTOR_STUDIO_V2_REQUIREMENTS.md

@@ -0,0 +1,121 @@
+# Object Vector Studio V2 Requirements
+
+This document defines the Object Vector Studio V2 requirements for a future implementation pass. It is design documentation only; `PR_26132_002-object-vector-studio-v2-requirements` does not implement runtime behavior.
+
+## Purpose
+
+Object Vector Studio V2 will author object-level vector entities such as ships, enemies, pickups, actors, hazards, projectiles, and reusable gameplay entities. It complements World Vector Studio V2, which owns terrain, world geometry, layered scenes, level/environment layout, and parallax/background structures.
+
+## Data Loading Contract
+
+- Session loading must be schema-only.
+- Every incoming toolState payload must validate against the Object Vector Studio V2 schema before render.
+- Invalid payloads must be rejected before render with visible, actionable status text.
+- Runtime UI state must not be accepted as persisted payload data unless the schema explicitly owns it.
+- No hidden defaults, silent fallback data, or partial rendering is allowed.
+
+## Launched-With-Parameters File Read
+
+- A launch with URL or workspace parameters may identify a source file to read.
+- The tool must resolve and log the exact source path before reading.
+- Missing or unreadable launched-with-parameters files must produce a visible actionable failure.
+- Successfully loaded files must report source path, payload type, validation result, and item counts.
+- Parameter-based file reads must still pass through schema validation before render.
+
+## Required Palette
+
+- Object Vector Studio V2 requires an active palette before object editing.
+- The palette source must be explicit and logged.
+- If no palette is available, the tool must show an actionable blocked state rather than creating default colors.
+- Object fills, strokes, and swatches must reference the active palette where applicable.
+- Palette changes must preserve selected object visibility and update palette-dependent controls without silently altering persisted object data.
+
+## Header And Responsive Layout
+
+- The tool must keep the copied First-Class Tool V2 header pattern.
+- Hide Header and Details must switch the page into the established fullscreen-style workspace mode.
+- In fullscreen-style mode, the left and right columns stay at the sides and the center work area fills the remaining horizontal space.
+- The center object preview/editor must not collapse when the header/details area is hidden.
+- The layout must remain usable at narrow widths by stacking or constraining columns without overlapping controls.
+
+## Accordion Space Sharing
+
+- Left and right column accordions must share available vertical space.
+- When one accordion is collapsed, remaining open accordions must redistribute the available space.
+- Collapsed accordions must collapse both content and container height in normal and fullscreen-style modes.
+- Accordion toggles must affect only their intended panel.
+- Header action buttons must not accidentally toggle the accordion.
+
+## Scrollable Control Content
+
+- Oversized control groups must scroll inside their own accordion content area.
+- Page-level scroll may exist only when the total content exceeds the viewport.
+- Object tiles, shape/tool controls, palette controls, JSON details, and status log panels must not push required panels offscreen.
+- Status log content must fill its available panel height and scroll internally when needed.
+
+## Selected Item Visibility
+
+- The selected object must remain visible in the object tile list and the center preview/editor when selection changes.
+- The active selection should be clearly marked in the tile list.
+- Object details and JSON details must reflect the same selected object.
+- If the selected object is deleted, selection must move to another existing object or clear to a valid empty selection state.
+- Empty-state messaging must be visible and actionable.
+
+## Left Column
+
+The left column owns user intent and setup controls.
+
+Required sections:
+
+- Object list and object management controls.
+- Shape and tool controls for creating/editing object primitives.
+- Mode controls for selection, move, scale, rotate, path/edit-point work, and grouping when implemented.
+- Add, duplicate, delete, reorder, and rename controls when supported by schema.
+
+Object controls must mark dirty only when they change schema-owned payload data.
+
+## Object Tiles
+
+- Object tiles must show object name, type/category, and selected state.
+- Tiles must support keyboard and pointer selection.
+- Tiles must remain stable in height so label changes do not cause layout jumps.
+- Tiles must expose enough metadata to distinguish ships, enemies, pickups, actors, and reusable gameplay entities.
+- Tiles should avoid rendering raw JSON as the primary visual label.
+
+## Right Column
+
+The right column owns output, diagnostics, and inspection.
+
+Required sections:
+
+- Palette: active palette source, swatches, and selected color context.
+- Object Details: selected object fields and shape-specific editable properties.
+- JSON Details: schema-valid payload or selected-object JSON preview.
+- Status Log: OK, WARN, FAIL, SKIP, and INFO messages with exact source/action context.
+
+Right-column content must remain scrollable and must not hide the status log.
+
+## Workspace Nav
+
+- Workspace launch must use the established workspace nav pattern.
+- Return to Workspace must preserve the active workspace/toolState context.
+- Return navigation must not mark dirty.
+- Workspace launch must log source binding, host context id, schema validation result, and payload counts.
+- Save-capable behavior belongs to the Workspace Manager V2 lifecycle and must not be silently assumed inside this tool.
+
+## Tool Nav
+
+- Standalone launch must use the established tool nav pattern.
+- Tool nav actions should include import/copy/export JSON only after the schema contract exists.
+- Import must validate before render.
+- Copy and export must emit only schema-owned payload data, not runtime-only UI state.
+- Failed import/export actions must produce visible actionable status text.
+
+## Out Of Scope For This PR
+
+- Runtime editor implementation.
+- Object Vector Studio V2 schema creation.
+- Workspace Manager V2 payload write-back changes.
+- Palette Manager V2 integration code.
+- Playwright runtime behavior coverage.
+- Sample JSON alignment.

tools/object-vector-studio-v2/how_to_use.html

@@ -3,24 +3,24 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>Object Vector Studio - How To Use</title>
+    <title>Object Vector Studio V2 - How To Use</title>
     <link rel="stylesheet" href="../../src/engine/theme/main.css">
     <link rel="stylesheet" href="../../src/engine/ui/hubCommon.css">
   </head>
   <body class="hub-page-tools" data-tools-platform-page="tool-doc">
     <div id="shared-theme-header"></div>
     <main class="wrap">
       <section class="hero">
-        <h1>Object Vector Studio</h1>
+        <h1>Object Vector Studio V2</h1>
         <p class="subtitle">Ships, enemies, pickups, actors, and reusable gameplay entities.</p>
       </section>
       <section class="card">
         <h2>Use This For</h2>
-        <p>Use Object Vector Studio for reusable gameplay entity vectors: ships, enemies, pickups, hazards, actors, and other object-level vector assets.</p>
+        <p>Use Object Vector Studio V2 for reusable gameplay entity vectors: ships, enemies, pickups, hazards, actors, and other object-level vector assets.</p>
       </section>
       <section class="card">
         <h2>Current State</h2>
-        <p>This PR registers the copied First-Class Tool V2 starter shell as the Object Vector Studio lane. Primitive Skin Editor and Vector Map Editor remain available, but their launcher tiles are marked deprecated.</p>
+        <p>This PR registers the copied First-Class Tool V2 starter shell as the Object Vector Studio V2 lane. Primitive Skin Editor and Vector Map Editor remain available, but their launcher tiles are marked deprecated.</p>
       </section>
     </main>
     <script type="module" src="../../src/engine/theme/mount-shared-header.js"></script>