Finish manifest-driven runtime cleanup after background asset resolution - PR_26139_016-final-manifest-runtime-cleanup

Author: DavidQ

docs/dev/reports/PR_26139_016-final-manifest-runtime-cleanup_report.md

@@ -0,0 +1,80 @@
+# PR_26139_016-final-manifest-runtime-cleanup Report
+
+## Summary
+
+- Removed remaining optional chrome asset path assumptions from shared runtime conventions.
+- Background, bezel, and preview image paths now resolve from Asset Manager V2 manifest image assets by `role` only.
+- Optional background/bezel/preview assets remain optional: if the role is absent, the runtime/tool path is empty and no hardcoded file is requested.
+- Workspace Manager V2 preview tile lookup no longer invents `assets/images/preview.svg`; it uses the manifest preview asset role when present.
+- Preserved Asteroids manifest object geometry, ship flame flicker, asteroid scale tuning, and the shared collision/transform path.
+
+## Files Changed
+
+- `src/engine/runtime/gameImageConvention.js`
+- `src/engine/runtime/fullscreenBezel.js`
+- `tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- `tests/core/BackgroundImageAndFullscreenBezel.test.mjs`
+- `tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs`
+- `docs/dev/reports/PR_26139_016-final-manifest-runtime-cleanup_report.md`
+
+## Cleanup Decisions
+
+- `resolveGameImageConventionPaths()` now returns empty optional chrome paths for background, bezel, and preview. It no longer constructs game-local optional image filenames.
+- `resolveManifestChromeAssetPaths()` selects image assets only from `tools.asset-manager-v2.assets` where `type: "image"` and `role` is `background`, `bezel`, or `preview`.
+- `fullscreenBezel` accepts a provided manifest payload and waits for manifest chrome resolution before attaching a bezel element.
+- Workspace Manager V2 preview status now resolves the preview path from the active game manifest Asset Manager `role: "preview"` entry.
+- The remaining `vectorMaps` reference in Object Vector Studio V2 is an intentional deprecated-input rejection guard, not active runtime/tool dependency.
+- Asset Manager authoring defaults, Asteroids gameplay state defaults, ship flame flicker, and asteroid scale tuning were preserved as intentional behavior.
+
+## Asset Resolution Results
+
+- Current Asteroids background role resolves to `/games/Asteroids/assets/images/deluxe.png`.
+- Current Asteroids bezel role resolves to `/games/Asteroids/assets/images/bezel.png`.
+- Current Asteroids preview role resolves to `games/Asteroids/assets/images/preview.png` for Workspace Manager V2 repo-relative preview status.
+- Removing the background role leaves the background layer unavailable without requesting `background.png` or `deluxe.png`.
+- Removing the bezel role leaves the bezel layer detached with `path: ""` and no request for `bezel.png`.
+- No optional background/bezel/preview fallback path is produced by shared runtime conventions.
+
+## Validation
+
+- PASS: `node --check src/engine/runtime/gameImageConvention.js`
+- PASS: `node --check src/engine/runtime/fullscreenBezel.js`
+- PASS: `node --check tools/workspace-manager-v2/js/services/WorkspaceManagerV2ContextService.js`
+- PASS: `node --check tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs`
+- PASS: `node --check tests/core/BackgroundImageAndFullscreenBezel.test.mjs`
+- PASS: `npm run build:manifest`
+- PASS: `npx playwright test tests/playwright/tools/AsteroidsBackgroundAssetResolution.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - 3 passed.
+  - Verified no request for `/games/Asteroids/assets/images/background.png`.
+  - Verified background image loads only from the Asset Manager background role.
+  - Verified bezel image loads only from the Asset Manager bezel role.
+  - Verified absent background role causes no optional background image request or 404.
+  - Verified absent bezel role causes no optional bezel image request or 404.
+- PASS: `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - 4 passed.
+  - Verified Collision Inspector V2 remains on the shared manifest/collision path.
+- PASS: `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list --grep "loads Object Vector Studio V2 runtime assets into Asteroids gameplay rendering"`
+  - 1 passed.
+  - Verified Asteroids manifest object loading and Object Vector Studio V2 runtime geometry path.
+- PASS: targeted Asteroids launch validation
+  - Boot reached `boot-complete`.
+  - Object Vector runtime loaded from manifest objects.
+  - Background path was `/games/Asteroids/assets/images/deluxe.png`.
+  - Bezel path was `/games/Asteroids/assets/images/bezel.png`.
+  - No page errors or failed requests were observed.
+- PASS: targeted manifest chrome/Workspace preview validation
+  - Convention paths returned empty optional chrome paths.
+  - Manifest chrome resolved background, bezel, and preview from Asset Manager roles.
+  - Removing preview role returned an empty Workspace Manager preview path.
+- PASS: `git diff --check`
+  - Git emitted line-ending normalization warnings for two touched test files; command exit code was 0.
+
+## Non-Gate Note
+
+- Attempted `node -e "import('./tests/core/BackgroundImageAndFullscreenBezel.test.mjs').then((m)=>m.run())"`.
+- It failed at the existing fullscreen-host expectation before the new optional-asset assertions: `testResolvePreferredFullscreenTargetKeepsCanvasOnlyParent` still expects a canvas-only parent to remain the fullscreen target, while the current runtime wraps it in a dedicated fullscreen host.
+- This was treated as outside the PR_016 validation gate because the requested validations are the browser/runtime manifest asset paths and shared tool launch paths.
+
+## Full Regression
+
+- Full regression and full samples smoke were not run per the PR request.

src/engine/runtime/fullscreenBezel.js

@@ -733,6 +733,9 @@ export default class fullscreenBezel {
     this.manifestPath = resolved.manifestPath;
     this.path = resolved.bezelPath;
     this.stretchConfigPath = resolveBezelStretchConfigPath(this.path, DEFAULT_BEZEL_STRETCH_OVERRIDE_FILENAME, this.manifestPath);
+    this.manifestPayload = options.manifestPayload && typeof options.manifestPayload === "object" && !Array.isArray(options.manifestPayload)
+      ? options.manifestPayload
+      : null;
     this.host = null;
     this.element = null;
     this.ready = false;
@@ -780,7 +783,8 @@ export default class fullscreenBezel {
     this.manifestResolvePromise = resolveManifestChromeAssetPaths({
       gameId: this.gameId,
       manifestPath: this.manifestPath,
-      documentRef: this.documentRef
+      documentRef: this.documentRef,
+      manifestPayload: this.manifestPayload
     })
       .then((resolved) => {
         this.gameId = resolved.gameId || this.gameId;

src/engine/runtime/gameImageConvention.js

@@ -152,50 +152,26 @@ function collectColorEntriesFromManifest(manifestPayload) {
   return entries;
 }
 
-function chooseSemanticImagePath(entries, semanticToken) {
-  const token = safeText(semanticToken, "").toLowerCase();
-  if (!token) {
-    return "";
-  }
-
-  const normalizedEntries = Array.isArray(entries) ? entries : [];
-
-  const byId = normalizedEntries.find((entry) => {
-    const id = safeText(entry?.id, "").toLowerCase();
-    const role = safeText(entry?.role, "").toLowerCase();
-    return role === token || id.includes(token);
-  });
-  if (byId?.path) {
-    return byId.path;
-  }
-
-  const byFileName = normalizedEntries.find((entry) => {
-    const candidatePath = safeText(entry?.path, "").toLowerCase();
-    return candidatePath.includes(`/${token}.`) || candidatePath.includes(`/${token}-`) || candidatePath.includes(`_${token}.`);
-  });
-  if (byFileName?.path) {
-    return byFileName.path;
-  }
-
-  return "";
-}
-
 function chooseGameBackgroundColor(entries) {
   const normalizedEntries = Array.isArray(entries) ? entries : [];
   return normalizedEntries.find((entry) => entry.id === "assets.color.background.game")
     || normalizedEntries.find((entry) => entry.role === "background" && entry.id.includes(".background.game"))
     || null;
 }
 
-function chooseAssetManagerBackgroundImagePath(entries) {
+function chooseAssetManagerImagePath(entries, semanticRole) {
   const normalizedEntries = Array.isArray(entries) ? entries : [];
-  const backgroundAsset = normalizedEntries.find((entry) => (
+  const role = safeText(semanticRole, "").toLowerCase();
+  if (!role) {
+    return "";
+  }
+  const asset = normalizedEntries.find((entry) => (
     entry?.sourceToolId === "asset-manager-v2"
     && entry?.type === "image"
-    && entry?.role === "background"
+    && entry?.role === role
     && safeText(entry?.path, "")
   ));
-  return backgroundAsset?.path || "";
+  return asset?.path || "";
 }
 
 const manifestCache = new Map();
@@ -274,7 +250,8 @@ export function resolveGameImageConventionPaths(options = {}) {
     backgroundColorName: "",
     backgroundColorPath: "",
     backgroundPath: "",
-    bezelPath: gameId ? `games/${gameId}/assets/images/bezel.png` : ""
+    bezelPath: "",
+    previewPath: ""
   };
 }
 
@@ -300,8 +277,9 @@ export async function resolveManifestChromeAssetPaths(options = {}) {
     backgroundColorHex: backgroundColor?.hex || "",
     backgroundColorName: backgroundColor?.name || "",
     backgroundColorPath: backgroundColor?.path || "",
-    backgroundPath: chooseAssetManagerBackgroundImagePath(imageEntries),
-    bezelPath: chooseSemanticImagePath(imageEntries, "bezel")
+    backgroundPath: chooseAssetManagerImagePath(imageEntries, "background"),
+    bezelPath: chooseAssetManagerImagePath(imageEntries, "bezel"),
+    previewPath: chooseAssetManagerImagePath(imageEntries, "preview")
   };
 }
 

tests/core/BackgroundImageAndFullscreenBezel.test.mjs

@@ -20,8 +20,9 @@ import {
 } from "../../src/engine/runtime/gameImageConvention.js";
 
 const ASTEROIDS_BACKGROUND_RUNTIME_PATH = "/games/Asteroids/assets/images/deluxe.png";
+const ASTEROIDS_BEZEL_RUNTIME_PATH = "/games/Asteroids/assets/images/bezel.png";
 
-function createAssetManagerManifest({ includeBackground = true } = {}) {
+function createAssetManagerManifest({ includeBackground = true, includeBezel = true } = {}) {
   const assets = {
     "assets.color.background.game": {
       path: "palette://workspace/space-black",
@@ -33,13 +34,18 @@ function createAssetManagerManifest({ includeBackground = true } = {}) {
         name: "Space Black"
       }
     },
-    "assets.image.bezel.bezel": {
+  };
+  if (includeBezel) {
+    assets["assets.image.bezel.bezel"] = {
       path: "assets/images/bezel.png",
       type: "image",
       kind: "png",
-      role: "bezel"
-    }
-  };
+      role: "bezel",
+      stretchOverride: {
+        uniformEdgeStretchPx: 10
+      }
+    };
+  }
   if (includeBackground) {
     assets["assets.image.background.deluxe"] = {
       path: "assets/images/deluxe.png",
@@ -57,6 +63,15 @@ function createAssetManagerManifest({ includeBackground = true } = {}) {
   };
 }
 
+async function attachResolvedBezel(bezel, options = {}) {
+  bezel.attach();
+  if (bezel.manifestResolvePromise) {
+    await bezel.manifestResolvePromise;
+  }
+  bezel.sync(options);
+  return bezel.element;
+}
+
 function createImageFactory(presentPaths, onCreate = null) {
   return (requestedPath) => {
     onCreate?.(String(requestedPath || ""));
@@ -245,10 +260,10 @@ async function testBackgroundManifestRenderOrder() {
   const manifestPayload = createAssetManagerManifest();
   const paths = resolveGameImageConventionPaths({ documentRef });
   assert.equal(paths.backgroundPath, "");
-  assert.equal(paths.bezelPath, "games/Asteroids/assets/images/bezel.png");
+  assert.equal(paths.bezelPath, "");
   const manifestPaths = await resolveManifestChromeAssetPaths({ documentRef, manifestPayload });
   assert.equal(manifestPaths.backgroundPath, ASTEROIDS_BACKGROUND_RUNTIME_PATH);
-  assert.equal(manifestPaths.bezelPath, "/games/Asteroids/assets/images/bezel.png");
+  assert.equal(manifestPaths.bezelPath, ASTEROIDS_BEZEL_RUNTIME_PATH);
   const runtimeBackgroundPath = resolveRuntimeAssetUrl(manifestPaths.backgroundPath, documentRef);
 
   const layer = new backgroundImage({
@@ -296,7 +311,7 @@ async function testGameImageConventionsAreGameAgnostic() {
     documentRef: { location: { pathname: "/games/Asteroids/index.html" } }
   });
   assert.equal(asteroidsPaths.backgroundPath, "");
-  assert.equal(asteroidsPaths.bezelPath, "games/Asteroids/assets/images/bezel.png");
+  assert.equal(asteroidsPaths.bezelPath, "");
   assert.equal(
     resolveBezelStretchOverridePath({ documentRef: { location: { pathname: "/games/Asteroids/index.html" } } }),
     "/games/Asteroids/game.manifest.json"
@@ -311,7 +326,7 @@ async function testGameImageConventionsAreGameAgnostic() {
     documentRef: { location: { pathname: "/games/_template/index.html" } }
   });
   assert.equal(templatePaths.backgroundPath, "");
-  assert.equal(templatePaths.bezelPath, "games/_template/assets/images/bezel.png");
+  assert.equal(templatePaths.bezelPath, "");
   assert.equal(
     resolveBezelStretchOverridePath({ documentRef: { location: { pathname: "/games/_template/index.html" } } }),
     "/games/_template/game.manifest.json"
@@ -373,11 +388,11 @@ async function testNoOpWhenBackgroundMissing() {
   assert.equal(order.length, 0);
 }
 
-function testSampleGameBackgroundAndBezelNoOpWhenMissing() {
+async function testSampleGameBackgroundAndBezelNoOpWhenMissing() {
   const documentRef = createDocumentStub("/games/SpaceInvaders/index.html");
   const paths = resolveGameImageConventionPaths({ documentRef });
   assert.equal(paths.backgroundPath, "");
-  assert.equal(paths.bezelPath, "games/SpaceInvaders/assets/images/bezel.png");
+  assert.equal(paths.bezelPath, "");
 
   const backgroundLayer = new backgroundImage({
     documentRef,
@@ -398,32 +413,33 @@ function testSampleGameBackgroundAndBezelNoOpWhenMissing() {
   host.appendChild(canvas);
   documentRef.body.appendChild(host);
 
-  const bezel = new fullscreenBezel({ canvas, documentRef });
-  bezel.attach();
-  assert.equal(bezel.element.src, "/games/SpaceInvaders/assets/images/bezel.png");
-  assert.equal(bezel.element.src.includes("/games/SpaceInvaders/games/SpaceInvaders/"), false);
-  bezel.element.onerror?.();
+  const bezel = new fullscreenBezel({
+    canvas,
+    documentRef,
+    manifestPayload: createAssetManagerManifest({ includeBackground: false, includeBezel: false })
+  });
+  await attachResolvedBezel(bezel, { fullscreenActive: false, fullscreenElement: host });
+  assert.equal(bezel.element, null);
   const bezelResult = bezel.sync({ fullscreenActive: true, fullscreenElement: host });
   assert.equal(bezelResult.visible, false);
   assert.equal(bezelResult.canvasLayoutMode, "fullscreen-fit");
-  assert.equal(bezel.element.style.display, "none");
   assertNear(parseFloat(canvas.style.width), 1200, 0.6);
   assertNear(parseFloat(canvas.style.height), 900, 0.6);
 }
 
-function testFullscreenBezelVisibilityAndHtmlAttachment() {
+async function testFullscreenBezelVisibilityAndHtmlAttachment() {
   const documentRef = createDocumentStub();
   const host = createElement("div", documentRef);
   const canvas = createElement("canvas", documentRef);
   host.appendChild(canvas);
   documentRef.body.appendChild(host);
 
-  const bezel = new fullscreenBezel({ canvas, documentRef });
-  bezel.attach();
+  const bezel = new fullscreenBezel({ canvas, documentRef, manifestPayload: createAssetManagerManifest() });
+  await attachResolvedBezel(bezel, { fullscreenActive: false, fullscreenElement: host });
   assert.equal(bezel.getState().attached, true);
   assert.equal(bezel.element.parentElement, host);
   assert.equal(bezel.element.attributes["data-runtime-overlay"], "fullscreenBezel");
-  assert.equal(bezel.element.src, "/games/Asteroids/assets/images/bezel.png");
+  assert.equal(bezel.element.src, ASTEROIDS_BEZEL_RUNTIME_PATH);
   assert.equal(bezel.element.src.includes("/games/Asteroids/games/Asteroids/"), false);
 
   bezel.element.onload?.();
@@ -447,7 +463,7 @@ function testFullscreenBezelVisibilityAndHtmlAttachment() {
   assert.equal(Number(bezel.element.style.zIndex) > Number(canvas.style.zIndex), true);
 }
 
-function testNoOpWhenBezelMissing() {
+async function testNoOpWhenBezelMissing() {
   const documentRef = createDocumentStub("/games/MissingGame/index.html");
   const host = createElement("div", documentRef);
   const canvas = createElement("canvas", documentRef);
@@ -456,13 +472,16 @@ function testNoOpWhenBezelMissing() {
   host.appendChild(canvas);
   documentRef.body.appendChild(host);
 
-  const bezel = new fullscreenBezel({ canvas, documentRef });
-  bezel.attach();
-  bezel.element.onerror?.();
+  const bezel = new fullscreenBezel({
+    canvas,
+    documentRef,
+    manifestPayload: createAssetManagerManifest({ includeBackground: false, includeBezel: false })
+  });
+  await attachResolvedBezel(bezel, { fullscreenActive: false, fullscreenElement: host });
+  assert.equal(bezel.element, null);
   const result = bezel.sync({ fullscreenActive: true, fullscreenElement: host });
   assert.equal(result.visible, false);
   assert.equal(result.canvasLayoutMode, "fullscreen-fit");
-  assert.equal(bezel.element.style.display, "none");
   assertNear(parseFloat(canvas.style.width), 1200, 0.6);
   assertNear(parseFloat(canvas.style.height), 900, 0.6);
 }
@@ -1018,8 +1037,7 @@ async function testEngineRuntimeIntegration() {
     assert.equal(engine.canvas.style.margin, "0 auto");
     assert.equal(engine.canvas.style.width, "960px");
     assert.equal(engine.canvas.style.height, "720px");
-    assert.equal(engine.fullscreenBezelLayer.element.src, "/games/Asteroids/assets/images/bezel.png");
-    assert.equal(engine.fullscreenBezelLayer.element.src.includes("/games/Asteroids/games/Asteroids/"), false);
+    assert.equal(engine.fullscreenBezelLayer.element, null);
 
     engine.tick(1000);
     await Promise.all([
@@ -1037,6 +1055,8 @@ async function testEngineRuntimeIntegration() {
       `background:${ASTEROIDS_BACKGROUND_RUNTIME_PATH}`,
       "scene"
     ]);
+    assert.equal(engine.fullscreenBezelLayer.element.src, ASTEROIDS_BEZEL_RUNTIME_PATH);
+    assert.equal(engine.fullscreenBezelLayer.element.src.includes("/games/Asteroids/games/Asteroids/"), false);
 
     scene.session.mode = "playing";
     order.length = 0;
@@ -1084,9 +1104,9 @@ export async function run() {
   testResolvePreferredFullscreenTargetKeepsCanvasOnlyParent();
   testResolvePreferredFullscreenTargetCreatesCanvasOnlyHost();
   await testNoOpWhenBackgroundMissing();
-  testSampleGameBackgroundAndBezelNoOpWhenMissing();
-  testFullscreenBezelVisibilityAndHtmlAttachment();
-  testNoOpWhenBezelMissing();
+  await testSampleGameBackgroundAndBezelNoOpWhenMissing();
+  await testFullscreenBezelVisibilityAndHtmlAttachment();
+  await testNoOpWhenBezelMissing();
   testMalformedBezelImageIsTreatedAsUnavailable();
   testTransparentWindowDetectionAndAspectFit();
   testFullscreenBezelTransparentWindowCanvasFit();