Add Object Vector Studio V2 reusable asset library and inheritance foundation - PR_26132_016-object-vector-asset-library-and-inheritance

Author: DavidQ

docs/dev/reports/playwright_v8_coverage.txt

@@ -20,10 +20,10 @@ Exercised tool entry points detected:
 (0%) Workspace Manager - not exercised by this Playwright run
 
 Changed runtime JS files covered:
-(80%) tools/object-vector-studio-v2/js/bootstrap.js - executed lines 91/91; executed functions 4/5
-(92%) tools/object-vector-studio-v2/js/ToolStarterApp.js - executed lines 2595/2595; executed functions 295/319
-(93%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - executed lines 307/307; executed functions 37/40
-(99%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - executed lines 752/752; executed functions 88/89
+(80%) tools/object-vector-studio-v2/js/bootstrap.js - executed lines 100/100; executed functions 4/5
+(92%) tools/object-vector-studio-v2/js/ToolStarterApp.js - executed lines 2805/2805; executed functions 327/355
+(95%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - executed lines 406/406; executed functions 52/55
+(98%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - executed lines 919/919; executed functions 105/107
 (100%) src/engine/rendering/index.js - executed lines 12/12; executed functions 1/1
 
 Files with executed line/function counts where available:
@@ -101,7 +101,7 @@ Files with executed line/function counts where available:
 (47%) src/engine/input/InputService.js - executed lines 185/185; executed functions 14/30
 (47%) src/engine/runtime/backgroundImage.js - executed lines 205/205; executed functions 8/17
 (47%) src/engine/runtime/RuntimeMonitoringHooks.js - executed lines 191/191; executed functions 8/17
-(50%) games/Asteroids/index.js - executed lines 206/206; executed functions 6/12
+(50%) games/Asteroids/index.js - executed lines 207/207; executed functions 6/12
 (50%) src/engine/camera/ZoneCameraSystem.js - executed lines 26/26; executed functions 1/2
 (50%) src/engine/collision/aabb.js - executed lines 14/14; executed functions 1/2
 (50%) src/engine/config/ConfigStore.js - executed lines 46/46; executed functions 3/6
@@ -117,7 +117,7 @@ Files with executed line/function counts where available:
 (50%) src/shared/utils/stringifyValueUtils.js - executed lines 8/8; executed functions 1/2
 (50%) tools/common/PaletteUsageService.js - executed lines 5/5; executed functions 1/2
 (50%) tools/world-vector-studio-v2/js/ToolStarterApp.js - executed lines 98/98; executed functions 8/16
-(52%) games/Asteroids/game/AsteroidsGameScene.js - executed lines 845/845; executed functions 25/48
+(52%) games/Asteroids/game/AsteroidsGameScene.js - executed lines 846/846; executed functions 25/48
 (54%) src/engine/audio/MediaTrackService.js - executed lines 139/139; executed functions 7/13
 (54%) tools/preview-generator-v2/PreviewGeneratorV2Capture.js - executed lines 497/497; executed functions 14/26
 (55%) tools/palette-manager-v2/modules/PaletteManagerApp.js - executed lines 975/975; executed functions 63/115
@@ -170,7 +170,7 @@ Files with executed line/function counts where available:
 (80%) src/engine/persistence/StorageService.js - executed lines 49/49; executed functions 4/5
 (80%) tools/asset-manager-v2/js/controls/AccordionSection.js - executed lines 27/27; executed functions 4/5
 (80%) tools/asset-manager-v2/js/controls/AssetFormControl.js - executed lines 563/563; executed functions 49/61
-(80%) tools/object-vector-studio-v2/js/bootstrap.js - executed lines 91/91; executed functions 4/5
+(80%) tools/object-vector-studio-v2/js/bootstrap.js - executed lines 100/100; executed functions 4/5
 (80%) tools/palette-manager-v2/modules/PaletteHistoryStack.js - executed lines 54/54; executed functions 8/10
 (80%) tools/preview-generator-v2/controls/AccordionSection.js - executed lines 31/31; executed functions 4/5
 (80%) tools/preview-generator-v2/PreviewGeneratorV2Logger.js - executed lines 19/19; executed functions 4/5
@@ -203,17 +203,17 @@ Files with executed line/function counts where available:
 (91%) tools/toolRegistry.js - executed lines 526/526; executed functions 10/11
 (91%) tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js - executed lines 1598/1598; executed functions 145/159
 (92%) tools/object-vector-studio-v2/js/controls/ToolStarterShellControl.js - executed lines 112/112; executed functions 11/12
-(92%) tools/object-vector-studio-v2/js/ToolStarterApp.js - executed lines 2595/2595; executed functions 295/319
+(92%) tools/object-vector-studio-v2/js/ToolStarterApp.js - executed lines 2805/2805; executed functions 327/355
 (93%) tools/asset-manager-v2/js/services/WorkspaceBridge.js - executed lines 305/305; executed functions 25/27
-(93%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - executed lines 307/307; executed functions 37/40
 (93%) tools/session-inspector-v2/js/SessionInspectorV2App.js - executed lines 337/337; executed functions 42/45
 (93%) tools/text2speech-V2/js/controls/QueueControl.js - executed lines 122/122; executed functions 26/28
 (93%) tools/workspace-manager-v2/js/controls/GameSelectorControl.js - executed lines 59/59; executed functions 13/14
 (93%) tools/workspace-manager-v2/js/controls/ToolTilesControl.js - executed lines 137/137; executed functions 14/15
 (94%) games/shared/workspaceGameMetadataHydrator.js - executed lines 106/106; executed functions 16/17
 (94%) tools/common/PaletteSortService.js - executed lines 103/103; executed functions 17/18
+(95%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - executed lines 406/406; executed functions 52/55
 (95%) tools/session-inspector-v2/js/services/SessionInspectorV2StorageService.js - executed lines 142/142; executed functions 18/19
-(99%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - executed lines 752/752; executed functions 88/89
+(98%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - executed lines 919/919; executed functions 105/107
 (100%) games/Asteroids/entities/Asteroid.js - executed lines 72/72; executed functions 11/11
 (100%) games/Asteroids/flow/attract.js - executed lines 17/17; executed functions 1/1
 (100%) games/Asteroids/flow/highscore.js - executed lines 16/16; executed functions 1/1
@@ -300,6 +300,6 @@ Changed JS files considered:
 (52%) games/Asteroids/game/AsteroidsGameScene.js - changed JS file with browser V8 coverage
 (80%) tools/object-vector-studio-v2/js/bootstrap.js - changed JS file with browser V8 coverage
 (92%) tools/object-vector-studio-v2/js/ToolStarterApp.js - changed JS file with browser V8 coverage
-(93%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - changed JS file with browser V8 coverage
-(99%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - changed JS file with browser V8 coverage
+(95%) tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js - changed JS file with browser V8 coverage
+(98%) src/engine/rendering/ObjectVectorRuntimeAssetService.js - changed JS file with browser V8 coverage
 (100%) src/engine/rendering/index.js - changed JS file with browser V8 coverage

docs/pr/PR_26132_016-object-vector-asset-library-and-inheritance.md

@@ -0,0 +1,78 @@
+# PR_26132_016-object-vector-asset-library-and-inheritance
+
+## Scope
+
+Adds the Object Vector Studio V2 reusable asset library and inheritance foundation, then wires Asteroids runtime rendering to resolve assets through library entries. Palette remains a workspace/session runtime resource and is not embedded in Object Vector JSON.
+
+## Changes
+
+- Added durable `assetLibrary.assets` schema support with category, tags, and object references.
+- Added object-level inheritance metadata through `baseObjectId`.
+- Added strict validation for duplicate object ids, duplicate asset ids, missing base objects, missing library object references, circular inheritance chains, and inherited shape/frame references.
+- Added Object Vector Studio V2 library browser UI, asset category/tag controls, library asset creation, usage reporting, dependency graph display, readonly inherited-field indicators, and Duplicate As Local workflow.
+- Added runtime inherited object resolution, inherited render-payload cache, asset-id resolution, dependency logging, and cache hit/miss diagnostics.
+- Registered Asteroids ship, asteroid, and UFO object vectors through reusable `asset.asteroids.*` library entries.
+- Updated Asteroids gameplay rendering to resolve ship, asteroid, and UFO vectors through asset ids instead of direct object ids.
+
+## Validation
+
+Playwright impacted: Yes.
+
+Commands run:
+
+- `node --check src/engine/rendering/ObjectVectorRuntimeAssetService.js`
+- `node --check tools/object-vector-studio-v2/js/ToolStarterApp.js`
+- `node --check tools/object-vector-studio-v2/js/bootstrap.js`
+- `node --check tools/object-vector-studio-v2/js/services/ObjectVectorStudioV2SchemaService.js`
+- `node --check games/Asteroids/index.js`
+- `node --check games/Asteroids/game/AsteroidsGameScene.js`
+- `node --check tests/playwright/tools/WorkspaceManagerV2.spec.mjs`
+- Object Vector schema validation against `games/Asteroids/game.manifest.json`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list -g "asset library inheritance|loads Object Vector Studio V2 runtime|Object Vector Studio V2 animation"`
+- `npm run test:workspace-v2`
+- `git diff --check`
+
+Result:
+
+- Targeted Object Vector/Asteroids runtime validation passed: 3 passed.
+- Full Workspace Manager V2 suite passed: 45 passed.
+- Playwright V8 coverage generated at `docs/dev/reports/playwright_v8_coverage.txt`.
+- Full samples smoke test skipped per request.
+
+## Playwright Coverage
+
+Validates:
+
+- Library asset creation.
+- Asset browser entries, category/tag metadata, usage report, and dependency graph.
+- Inherited asset rendering through runtime preview.
+- Duplicate As Local removes inheritance metadata from the local copy.
+- Circular inheritance rejection.
+- Missing dependency failure handling.
+- Asteroids runtime asset loading through reusable library asset ids.
+
+Expected pass behavior:
+
+- Valid library assets and inheritance chains validate, resolve, cache, and render through the runtime vector pipeline.
+
+Expected fail behavior:
+
+- Missing dependencies, circular inheritance, invalid references, and invalid runtime payloads fail visibly before render with actionable FAIL logs.
+
+## Manual Validation
+
+1. Open `tools/object-vector-studio-v2/index.html`.
+2. Import an Object Vector Studio V2 payload with `assetLibrary.assets` and at least one derived object using `baseObjectId`.
+3. Confirm the asset library browser, usage report, dependency graph, inherited-field indicators, Runtime Preview, and Duplicate As Local.
+4. Open Asteroids and start gameplay.
+5. Confirm the ship, asteroids, and UFOs render from `asset.asteroids.*` library entries.
+
+Expected outcome:
+
+- Valid assets render, inherited assets resolve through their base object, duplicate local copies no longer include `baseObjectId`, and invalid inheritance payloads are rejected before render.
+
+## Out Of Scope
+
+- No World Vector Studio V2 changes.
+- No sample JSON changes.
+- No full samples smoke test.

games/Asteroids/game.manifest.json

@@ -212,6 +212,52 @@
           "version": 1,
           "toolId": "object-vector-studio-v2",
           "name": "Asteroids Object Vector Assets",
+          "assetLibrary": {
+            "assets": [
+              {
+                "id": "asset.asteroids.ship",
+                "name": "Asteroids Ship",
+                "objectId": "object.asteroids.ship",
+                "category": "ship",
+                "tags": ["asteroids", "player", "ship"]
+              },
+              {
+                "id": "asset.asteroids.asteroid.large",
+                "name": "Large Asteroid",
+                "objectId": "object.asteroids.asteroid.large",
+                "category": "object",
+                "tags": ["asteroids", "asteroid", "large"]
+              },
+              {
+                "id": "asset.asteroids.asteroid.medium",
+                "name": "Medium Asteroid",
+                "objectId": "object.asteroids.asteroid.medium",
+                "category": "object",
+                "tags": ["asteroids", "asteroid", "medium"]
+              },
+              {
+                "id": "asset.asteroids.asteroid.small",
+                "name": "Small Asteroid",
+                "objectId": "object.asteroids.asteroid.small",
+                "category": "object",
+                "tags": ["asteroids", "asteroid", "small"]
+              },
+              {
+                "id": "asset.asteroids.ufo.large",
+                "name": "Large UFO",
+                "objectId": "object.asteroids.ufo.large",
+                "category": "enemy",
+                "tags": ["asteroids", "ufo", "large"]
+              },
+              {
+                "id": "asset.asteroids.ufo.small",
+                "name": "Small UFO",
+                "objectId": "object.asteroids.ufo.small",
+                "category": "enemy",
+                "tags": ["asteroids", "ufo", "small"]
+              }
+            ]
+          },
           "objects": [
             {
               "id": "object.asteroids.ship",

games/Asteroids/game/AsteroidsGameScene.js

@@ -25,16 +25,16 @@ const SCORE_TWO_X = 824;
 const LIFE_SPACING = 22;
 const PAUSE_OVERLAY_COLOR = 'rgba(2, 6, 23, 0.58)';
 const INITIALS_OVERLAY_COLOR = 'rgba(1, 6, 19, 0.62)';
-const ASTEROID_OBJECT_VECTOR_IDS = Object.freeze({
-  1: "object.asteroids.asteroid.small",
-  2: "object.asteroids.asteroid.medium",
-  3: "object.asteroids.asteroid.large",
+const ASTEROID_OBJECT_VECTOR_ASSET_IDS = Object.freeze({
+  1: "asset.asteroids.asteroid.small",
+  2: "asset.asteroids.asteroid.medium",
+  3: "asset.asteroids.asteroid.large",
 });
-const UFO_OBJECT_VECTOR_IDS = Object.freeze({
-  large: "object.asteroids.ufo.large",
-  small: "object.asteroids.ufo.small",
+const UFO_OBJECT_VECTOR_ASSET_IDS = Object.freeze({
+  large: "asset.asteroids.ufo.large",
+  small: "asset.asteroids.ufo.small",
 });
-const SHIP_OBJECT_VECTOR_ID = "object.asteroids.ship";
+const SHIP_OBJECT_VECTOR_ASSET_ID = "asset.asteroids.ship";
 const LIFE_ICON_POINTS = [
   [14, 0],
   [-10, -8],
@@ -735,7 +735,7 @@ export default class AsteroidsGameScene extends Scene {
       this.drawObjectVectorAsset(renderer, "asteroids", {
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: ASTEROID_OBJECT_VECTOR_IDS[asteroid.size],
+        assetId: ASTEROID_OBJECT_VECTOR_ASSET_IDS[asteroid.size],
         rotation: asteroid.angle,
         stateId: "active",
         x: asteroid.x,
@@ -747,7 +747,7 @@ export default class AsteroidsGameScene extends Scene {
       this.drawObjectVectorAsset(renderer, "ufo", {
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: UFO_OBJECT_VECTOR_IDS[this.world.ufo.type],
+        assetId: UFO_OBJECT_VECTOR_ASSET_IDS[this.world.ufo.type],
         stateId: "active",
         x: this.world.ufo.x,
         y: this.world.ufo.y,
@@ -768,7 +768,7 @@ export default class AsteroidsGameScene extends Scene {
       this.drawObjectVectorAsset(renderer, "ship", {
         elapsedMs: this.objectVectorPlaybackMs,
         fps: 12,
-        objectId: SHIP_OBJECT_VECTOR_ID,
+        assetId: SHIP_OBJECT_VECTOR_ASSET_ID,
         rotation: this.world.ship.angle + Math.PI / 2,
         stateId: this.world.ship.thrusting && this.session.mode === 'playing' ? "thrust" : "idle",
         x: this.world.ship.x,
@@ -845,12 +845,12 @@ export default class AsteroidsGameScene extends Scene {
 
   drawObjectVectorAsset(renderer, renderKey, options) {
     if (!this.objectVectorRuntime || !this.objectVectorAssets) {
-      this.recordObjectVectorRenderFailure(renderKey, options.objectId, "validated Object Vector runtime assets are not loaded");
+      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId, "validated Object Vector runtime assets are not loaded");
       return false;
     }
     const result = this.objectVectorRuntime.renderObject(renderer, this.objectVectorAssets, options);
     if (!result.ok) {
-      this.recordObjectVectorRenderFailure(renderKey, options.objectId, "runtime render returned failed result");
+      this.recordObjectVectorRenderFailure(renderKey, options.assetId || options.objectId, "runtime render returned failed result");
       return false;
     }
     this.objectVectorRenderCounts[renderKey] = (this.objectVectorRenderCounts[renderKey] || 0) + 1;
@@ -875,6 +875,7 @@ export default class AsteroidsGameScene extends Scene {
     try {
       globalThis.__asteroidsObjectVectorRuntime = {
         ...(this.objectVectorRuntime?.getDiagnostics?.() || {}),
+        assetCount: this.objectVectorAssets?.assetsById?.size || 0,
         loaded: Boolean(this.objectVectorAssets),
         objectCount: this.objectVectorAssets?.objectsById?.size || 0,
         renderCounts: { ...this.objectVectorRenderCounts },

games/Asteroids/index.js

@@ -146,6 +146,7 @@ export async function bootAsteroidsNew({
       sourceLabel: "Asteroids game.manifest.json"
     });
     publishObjectVectorRuntimeDiagnostics(objectVectorRuntime, {
+      assetCount: objectVectorAssets?.assetsById?.size || 0,
       loaded: Boolean(objectVectorAssets),
       objectCount: objectVectorAssets?.objectsById?.size || 0
     });