Document Object Vector Studio V2 and World Vector Studio V2 architectural split and migration direction - PR_26132_003-vector-studio-readme-alignment

Author: DavidQ

docs/pr/PR_26132_003-vector-studio-readme-alignment.md

@@ -0,0 +1,41 @@
+# PR_26132_003-vector-studio-readme-alignment
+
+## Purpose
+
+Align Object Vector Studio V2 and World Vector Studio V2 README/how-to documentation around their architectural split, migration direction, and example use cases.
+
+## Changes
+
+- Expanded Object Vector Studio V2 docs around reusable gameplay entities, ships, enemies, pickups, actors, weapons, UI vector assets, SVG/vector authoring, primitives/shapes/path editing, animation-ready structures, and "Build the thing."
+- Expanded World Vector Studio V2 docs around terrain, maps, tile/world geometry, layered scenes, parallax, environment composition, collision/world regions, level layout, spawn placement, camera zones, and "Build the place."
+- Documented migration direction:
+  - SVG Asset Studio functionality moves toward Object Vector Studio V2.
+  - Primitive Skin Editor remains deprecated compatibility.
+  - Vector Map Editor remains deprecated compatibility.
+  - Old tools remain available during transition.
+- Added examples:
+  - Asteroids ship/UFO -> Object Vector Studio V2.
+  - Platformer level/parallax scene -> World Vector Studio V2.
+- Updated the compact BUILD PR template with a copy-friendly commit comment control/button pattern for future generated docs/templates.
+
+## Playwright Impact
+
+Playwright impacted: No.
+
+No Playwright impact. This PR is documentation/template guidance only.
+
+## Validation
+
+- Playwright was not run because this PR is documentation only.
+- Full samples smoke test was not run per BUILD scope; this PR does not modify samples or runtime behavior.
+
+## Manual Validation
+
+1. Open `tools/object-vector-studio-v2/README.md` and `tools/object-vector-studio-v2/how_to_use.html`.
+2. Confirm Object Vector Studio V2 is documented as "Build the thing" and covers reusable gameplay entities, ships, enemies, pickups, actors, weapons, UI vector assets, SVG/vector authoring, primitives/shapes/path editing, and animation-ready structures.
+3. Open `tools/world-vector-studio-v2/README.md` and `tools/world-vector-studio-v2/how_to_use.html`.
+4. Confirm World Vector Studio V2 is documented as "Build the place" and covers terrain, maps, tile/world geometry, layered scenes, parallax, environment composition, collision/world regions, level layout, spawn placement, and camera zones.
+5. Confirm migration direction and examples are present.
+6. Open `docs/pr/templates/BUILD_PR_ULTRA_COMPACT.md` and confirm commit comment output uses a copy-friendly textarea/button pattern.
+
+Expected outcome: docs clearly distinguish the two vector studios and no runtime behavior is changed.

docs/pr/templates/BUILD_PR_ULTRA_COMPACT.md

@@ -22,3 +22,14 @@
 
 ## Output
 <project>/tmp/<NAME>_delta.zip
+
+## Generated Response Support
+When generated docs/templates include a commit comment, render it in a copy-friendly control/button pattern:
+
+```html
+<div class="copy-control" data-copy-kind="commit-comment">
+  <label for="commitCommentText">Commit comment</label>
+  <textarea id="commitCommentText" readonly><description> - <PR info></textarea>
+  <button type="button" data-copy-target="commitCommentText">Copy commit comment</button>
+</div>
+```

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

@@ -1,26 +1,50 @@
 # Object Vector Studio V2
 
-Object Vector Studio V2 is a First-Class Tool V2 surface for ships, enemies, pickups, actors, and reusable gameplay entities.
+Object Vector Studio V2 is the vector authoring surface for reusable gameplay entities: ships, enemies, pickups, actors, weapons, UI vector assets, and other object-level game pieces.
+
+Tagline: "Build the thing."
 
 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
+## Architectural Split
+
+Object Vector Studio V2 owns the thing being placed, animated, reused, equipped, collected, or rendered as an object. World Vector Studio V2 owns the place where those things live.
+
+Use Object Vector Studio V2 for:
+
+- Reusable gameplay entities.
+- Ships.
+- Enemies.
+- Pickups.
+- Actors.
+- Weapons.
+- UI vector assets.
+- SVG/vector authoring.
+- Primitives, shapes, and path editing.
+- Animation-ready structures.
+
+Use World Vector Studio V2 instead for terrain, maps, tile/world geometry, layered scenes, parallax, environment composition, collision/world regions, level layout, spawn placement, and camera zones.
 
-- 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.
+## Migration Direction
+
+- SVG Asset Studio functionality moves toward Object Vector Studio V2.
+- Primitive Skin Editor remains deprecated compatibility during the transition.
+- Vector Map Editor remains deprecated compatibility during the transition.
+- Old tools remain available until replacement workflows are implemented and validated.
+
+## Examples
+
+- Asteroids ship/UFO -> Object Vector Studio V2.
+- Weapon icons, pickups, HUD markers, and actor silhouettes: Object Vector Studio V2.
+- Platformer level/parallax scene -> World Vector Studio V2.
 
 ## Runtime Notes
 
 - 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
 
-Targeted validation for this PR is:
-
-`npm run test:workspace-v2`
+This documentation PR has no Playwright impact. Runtime implementation remains future work.

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

@@ -12,15 +12,35 @@
     <main class="wrap">
       <section class="hero">
         <h1>Object Vector Studio V2</h1>
-        <p class="subtitle">Ships, enemies, pickups, actors, and reusable gameplay entities.</p>
+        <p class="subtitle">Reusable gameplay entities, SVG/vector authoring, primitives, shapes, paths, and animation-ready object structures. Build the thing.</p>
       </section>
+
       <section class="card">
         <h2>Use This For</h2>
-        <p>Use Object Vector Studio V2 for reusable gameplay entity vectors: ships, enemies, pickups, hazards, actors, and other object-level vector assets.</p>
+        <p>Use Object Vector Studio V2 for ships, enemies, pickups, actors, weapons, UI vector assets, reusable gameplay entities, SVG/vector authoring, primitives, shapes, path editing, and animation-ready structures.</p>
       </section>
+
+      <section class="card">
+        <h2>Architectural Split</h2>
+        <p><strong>Object Vector Studio V2:</strong> Build the thing. It owns object-level art and entity structures that can be placed in games and scenes.</p>
+        <p><strong>World Vector Studio V2:</strong> Build the place. It owns terrain, maps, tile/world geometry, layered scenes, parallax, environment composition, collision/world regions, level layout, spawn placement, and camera zones.</p>
+      </section>
+
+      <section class="card">
+        <h2>Migration Direction</h2>
+        <p>SVG Asset Studio functionality moves toward Object Vector Studio V2. Primitive Skin Editor and Vector Map Editor remain available as deprecated compatibility tools during the transition.</p>
+      </section>
+
+      <section class="card">
+        <h2>Examples</h2>
+        <p><strong>Asteroids ship/UFO -> Object Vector Studio V2.</strong></p>
+        <p><strong>Weapon icon, pickup, actor, or HUD vector:</strong> Object Vector Studio V2.</p>
+        <p><strong>Platformer level/parallax scene -> World Vector Studio V2.</strong></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 V2 lane. Primitive Skin Editor and Vector Map Editor remain available, but their launcher tiles are marked deprecated.</p>
+        <p>This tool is currently a copied First-Class Tool V2 starter shell with Object Vector Studio V2 naming and documentation. Runtime object editing behavior is planned but not implemented in this documentation PR.</p>
       </section>
     </main>
     <script type="module" src="../../src/engine/theme/mount-shared-header.js"></script>

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

@@ -1,26 +1,49 @@
 # World Vector Studio V2
 
-World Vector Studio V2 is a First-Class Tool V2 surface for terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures.
+World Vector Studio V2 is the vector authoring surface for terrain, maps, tile/world geometry, layered scenes, parallax, environment composition, collision/world regions, level layout, spawn placement, and camera zones.
+
+Tagline: "Build the place."
 
 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: `world-vector-studio-v2`.
 
-## Scope
+## Architectural Split
+
+World Vector Studio V2 owns the place: the terrain, map structure, camera regions, spawn regions, collision regions, and layered world composition. Object Vector Studio V2 owns the reusable things that live in that place.
+
+Use World Vector Studio V2 for:
+
+- Terrain.
+- Maps.
+- Tile/world geometry.
+- Layered scenes.
+- Parallax.
+- Environment composition.
+- Collision/world regions.
+- Level layout.
+- Spawn placement.
+- Camera zones.
+
+Use Object Vector Studio V2 instead for reusable gameplay entities, ships, enemies, pickups, actors, weapons, UI vector assets, SVG/vector authoring, primitives/shapes/path editing, and animation-ready structures.
 
-- Terrain and world-scale vector geometry.
-- Tile/world scene layout.
-- Layered scene composition.
-- Level and environment layout.
-- Parallax and background structures.
+## Migration Direction
+
+- Vector Map Editor remains deprecated compatibility during the transition.
+- Primitive Skin Editor remains deprecated compatibility during the transition.
+- SVG Asset Studio functionality moves toward Object Vector Studio V2, not World Vector Studio V2.
+- Old tools remain available until replacement workflows are implemented and validated.
+
+## Examples
+
+- Platformer level/parallax scene -> World Vector Studio V2.
+- Asteroids arena background, spawn/camera/collision zones, or layered starfield scene: World Vector Studio V2.
+- Asteroids ship/UFO -> Object Vector Studio V2.
 
 ## Runtime Notes
 
 - The current implementation is the copied Tool Template V2 shell with World 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.
-- 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`
+This documentation PR has no Playwright impact. Runtime implementation remains future work.

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

@@ -12,15 +12,35 @@
     <main class="wrap">
       <section class="hero">
         <h1>World Vector Studio V2</h1>
-        <p class="subtitle">Terrain, tile/world geometry, layered scenes, level/environment layout, and parallax/background structures.</p>
+        <p class="subtitle">Terrain, maps, world geometry, layered scenes, parallax, layout regions, spawn placement, and camera zones. Build the place.</p>
       </section>
+
       <section class="card">
         <h2>Use This For</h2>
-        <p>Use World Vector Studio V2 for world-scale vector authoring: terrain shapes, tile and world geometry, layered environment scenes, parallax/background structures, and level layout foundations.</p>
+        <p>Use World Vector Studio V2 for terrain, maps, tile/world geometry, layered scenes, parallax, environment composition, collision/world regions, level layout, spawn placement, and camera zones.</p>
       </section>
+
+      <section class="card">
+        <h2>Architectural Split</h2>
+        <p><strong>World Vector Studio V2:</strong> Build the place. It owns the map, world, and environment structures where game objects appear and move.</p>
+        <p><strong>Object Vector Studio V2:</strong> Build the thing. It owns reusable gameplay entities, ships, enemies, pickups, actors, weapons, UI vector assets, SVG/vector authoring, primitives/shapes/path editing, and animation-ready structures.</p>
+      </section>
+
+      <section class="card">
+        <h2>Migration Direction</h2>
+        <p>Vector Map Editor remains available as deprecated compatibility during the transition. Primitive Skin Editor remains available as deprecated compatibility. SVG Asset Studio functionality moves toward Object Vector Studio V2.</p>
+      </section>
+
+      <section class="card">
+        <h2>Examples</h2>
+        <p><strong>Platformer level/parallax scene -> World Vector Studio V2.</strong></p>
+        <p><strong>Spawn/camera/collision zones:</strong> World Vector Studio V2.</p>
+        <p><strong>Asteroids ship/UFO -> Object Vector Studio V2.</strong></p>
+      </section>
+
       <section class="card">
         <h2>Current State</h2>
-        <p>This PR registers the copied First-Class Tool V2 starter shell as the World Vector Studio V2 lane. Primitive Skin Editor and Vector Map Editor remain available, but their launcher tiles are marked deprecated.</p>
+        <p>This tool is currently a copied First-Class Tool V2 starter shell with World Vector Studio V2 naming and documentation. Runtime world editing behavior is planned but not implemented in this documentation PR.</p>
       </section>
     </main>
     <script type="module" src="../../src/engine/theme/mount-shared-header.js"></script>