Normalize game manifests to current schema and validate manifest preview assets - PR_26139_019-game-manifest-version-preview-normalization

DavidQ · DavidQ · commit e42cc95408c8 · 2026-05-19T18:17:09.000-04:00
diff --git a/docs/dev/reports/PR_26139_019-game-manifest-version-preview-normalization_report.md b/docs/dev/reports/PR_26139_019-game-manifest-version-preview-normalization_report.md
@@ -0,0 +1,44 @@
+# PR_26139_019 Game Manifest Version Preview Normalization Report
+
+## Summary
+- Added current `$schema` declarations and Asset Manager V2 preview registries to older game manifests that only had legacy tool payloads.
+- Preserved existing populated preview paths for Asteroids (`assets/images/preview.png`), Gravity Well (`assets/images/preview.svg`), and Pong (`assets/images/preview1.svg`).
+- Added the missing `games/vector-arcade-sample/assets/images/preview.svg` file so the newly required preview manifest entry resolves on disk.
+- Tightened `game.manifest.schema.json` so game manifests require `tools.asset-manager-v2` and validate that payload against the Asset Manager V2 schema.
+- Extended game manifest validation to check the current game manifest schema and preview file existence for every game manifest.
+
+## Manifest Updates
+- Added `assets.image.preview.preview -> assets/images/preview.svg` to:
+  - `AITargetDummy`
+  - `Bouncing-ball`
+  - `Breakout`
+  - `Pacman`
+  - `SolarSystem`
+  - `SpaceDuel`
+  - `SpaceInvaders`
+  - `vector-arcade-sample`
+- Left existing preview paths unchanged:
+  - `Asteroids -> assets/images/preview.png`
+  - `GravityWell -> assets/images/preview.svg`
+  - `Pong -> assets/images/preview1.svg`
+
+## Validation
+- PASS: `npm run build:manifest`
+- PASS: `node scripts/validate-json-contracts.mjs --mode=games --details`
+  - `game_manifest_schema_validation: total=11 invalid=0`
+- PASS: preview file existence check
+  - `OK preview assets exist for 11 games`
+- PASS: `npx playwright test tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - `4 passed`
+- PASS: `node --check scripts/validate-json-contracts.mjs`
+- PASS: `node --check tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs`
+- PASS: `git diff --check`
+
+## Manual Validation
+- Open `/games/index.html` and confirm each game card thumbnail renders from the manifest preview asset.
+- Open `/games/Pong/index.html` and confirm the thumbnail uses `assets/images/preview1.svg`.
+- Confirm no page requests `/games/Pong/assets/images/preview.svg`.
+
+## Notes
+- `games/index.html` and `games/Pong/index.html` remain manifest-driven; no preview path was hardcoded into HTML or runtime.
+- Full samples smoke test was skipped because this PR is limited to game manifest normalization and targeted game preview validation.
diff --git a/docs/dev/reports/game_manifest_schema_validation.csv b/docs/dev/reports/game_manifest_schema_validation.csv
@@ -1,5 +1,4 @@
 filePath,status,errorCount,firstErrors
-games/_template/game.manifest.json,valid,0,
 games/AITargetDummy/game.manifest.json,valid,0,
 games/Asteroids/game.manifest.json,valid,0,
 games/Bouncing-ball/game.manifest.json,valid,0,
diff --git a/games/AITargetDummy/game.manifest.json b/games/AITargetDummy/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "AI Target Dummy Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "asset-browser": {
       "assets": {
         "image.ai-target-dummy.preview": {
diff --git a/games/Pacman/game.manifest.json b/games/Pacman/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Pacman Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "asset-browser": {
       "assets": {
         "image.pacman.preview-svg": {
diff --git a/games/SolarSystem/game.manifest.json b/games/SolarSystem/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Solar System Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "primitive-skin-editor": {
       "skins": [
         {
diff --git a/games/SpaceDuel/game.manifest.json b/games/SpaceDuel/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Space Duel Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "primitive-skin-editor": {
       "skins": [],
       "schema": "html-js-gaming.tool.primitive-skin-editor",
diff --git a/games/SpaceInvaders/game.manifest.json b/games/SpaceInvaders/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Space Invaders Next Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "primitive-skin-editor": {
       "skins": [],
       "schema": "html-js-gaming.tool.primitive-skin-editor",
diff --git a/games/bouncing-ball/game.manifest.json b/games/bouncing-ball/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Bouncing Ball Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "primitive-skin-editor": {
       "skins": [
         {
diff --git a/games/breakout/game.manifest.json b/games/breakout/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Breakout Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "primitive-skin-editor": {
       "skins": [
         {
diff --git a/games/vector-arcade-sample/assets/images/preview.svg b/games/vector-arcade-sample/assets/images/preview.svg
@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360" role="img" aria-labelledby="title desc">
+  <title id="title">Vector Arcade Sample Preview</title>
+  <desc id="desc">Vector arcade sample preview with player ship, obstacles, and HUD frame.</desc>
+  <rect width="640" height="360" fill="#05070d"/>
+  <g fill="none" stroke="#6fd3ff" stroke-width="4" stroke-linejoin="round">
+    <path d="M40 44h560v272H40z"/>
+    <path d="M74 78h492v52H74z" opacity=".45"/>
+    <path d="M104 104h92"/>
+    <path d="M444 104h92"/>
+  </g>
+  <g fill="none" stroke="#e8f0ff" stroke-width="7" stroke-linecap="square" stroke-linejoin="round">
+    <path d="M320 124l42 112-42-26-42 26z"/>
+    <path d="M304 246l16-30 16 30"/>
+  </g>
+  <g fill="none" stroke="#ffb347" stroke-width="5" stroke-linejoin="round">
+    <path d="M150 194l34-48 52 24 18 58-38 46-58-10-34-42z"/>
+    <path d="M448 164l24-28 38 12 22 36-14 42-42 22-40-26z"/>
+    <path d="M486 258l14-18 24 8 10 22-16 18-22 2-18-14z"/>
+  </g>
+  <g fill="#6fd3ff">
+    <rect x="82" y="270" width="110" height="12"/>
+    <rect x="448" y="270" width="110" height="12"/>
+  </g>
+</svg>
diff --git a/games/vector-arcade-sample/game.manifest.json b/games/vector-arcade-sample/game.manifest.json
@@ -1,4 +1,5 @@
 {
+  "$schema": "tools/schemas/game.manifest.schema.json",
   "schema": "html-js-gaming.game-manifest",
   "version": 1,
   "game": {
@@ -12,6 +13,22 @@
     "workspaceManagerOptional": true
   },
   "tools": {
+    "asset-manager-v2": {
+      "$schema": "tools/schemas/tools/asset-manager-v2.schema.json",
+      "schema": "html-js-gaming.asset-manager-v2",
+      "version": 1,
+      "name": "Vector Arcade Sample Asset Manager V2 Registry",
+      "source": "manifest",
+      "assets": {
+        "assets.image.preview.preview": {
+          "path": "assets/images/preview.svg",
+          "type": "image",
+          "kind": "svg",
+          "role": "preview",
+          "source": "manifest"
+        }
+      }
+    },
     "primitive-skin-editor": {
       "skins": [],
       "schema": "html-js-gaming.tool.primitive-skin-editor",
diff --git a/scripts/validate-json-contracts.mjs b/scripts/validate-json-contracts.mjs
diff --git a/tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs b/tests/playwright/games/GameIndexPreviewManifestResolution.spec.mjs
diff --git a/tools/schemas/game.manifest.schema.json b/tools/schemas/game.manifest.schema.json

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`filePath,status,errorCount,firstErrors`
`2`		`-games/_template/game.manifest.json,valid,0,`
`3`	`2`	`games/AITargetDummy/game.manifest.json,valid,0,`
`4`	`3`	`games/Asteroids/game.manifest.json,valid,0,`
`5`	`4`	`games/Bouncing-ball/game.manifest.json,valid,0,`