Draw manifest-declared game backgrounds across all render states without opaque suppression - PR 11.87

Author: DavidQ

docs/dev/reports/PR_11_87_validation.md

@@ -1,10 +1,53 @@
-# PR 11.87 Validation Placeholder
+# PR 11.87 Validation - Manifest Background Always Visible
 
-Codex must replace this with actual targeted validation evidence.
+## Scope
+Implemented the smallest scoped runtime/render change so manifest-declared `image.*.background` remains visible across Asteroids render states without fallback asset paths.
 
-Required evidence:
-- Asteroids menu background visible.
-- Asteroids attract background visible.
-- Asteroids gameplay background visible.
-- No guessed background/bezel 404s.
-- No full sample suite run; targeted validation only.
+## Files Changed
+- `src/engine/runtime/backgroundImage.js`
+- `games/Asteroids/game/AsteroidsGameScene.js`
+- `games/Asteroids/game/AsteroidsAttractAdapter.js`
+- `docs/dev/reports/PR_11_87_validation.md`
+
+## Implementation Evidence
+
+### 1) Background gate removed (all render states)
+- `src/engine/runtime/backgroundImage.js`
+- `render(...)` no longer returns early for non-gameplay states.
+- Result: when manifest background exists and image is loaded, background draw path is allowed for menu/title/attract/gameplay/pause.
+
+### 2) Opaque fills no longer hide background when manifest background is present
+- `games/Asteroids/game/AsteroidsGameScene.js`
+  - Added `hasManifestBackgroundLayer(engine)` helper using `engine.backgroundImageLayer.getState()`.
+  - Scene base fill changes from opaque `#020617` to translucent `rgba(2, 6, 23, 0.22)` when manifest background path is present.
+- `games/Asteroids/game/AsteroidsAttractAdapter.js`
+  - `render(renderer, options)` now accepts `manifestBackgroundPresent`.
+  - Attract fullscreen panel changes from opaque-ish `rgba(2, 6, 23, 0.86)` to translucent `rgba(2, 6, 23, 0.36)` when background is present.
+- Foreground text/entities/UI draws are preserved.
+
+### 3) Manifest-only chrome/background rule preserved
+- No fallback URL construction added.
+- No new guessed `background.png`/`bezel.png` convention paths added.
+- No duplicated background SSoT under `asset-browser.assets.background` was introduced.
+
+## Validation Commands and Results
+
+### Syntax checks
+- `node --check src/engine/runtime/backgroundImage.js` -> PASS
+- `node --check games/Asteroids/game/AsteroidsGameScene.js` -> PASS
+- `node --check games/Asteroids/game/AsteroidsAttractAdapter.js` -> PASS
+
+### Fallback/guessed-path search
+- `rg -n "assets/images/background\.png|assets/images/bezel\.png|/games/\$\{.*\}/assets/images/(background|bezel)\.png" src games tools -g "*.js"`
+- Result: no matches for guessed path construction added in JS runtime code.
+
+### Targeted launch smoke (games only)
+- `node ./tests/runtime/LaunchSmokeAllEntries.test.mjs --games`
+- Result: PASS (12/12), including `Asteroids` and `SolarSystem`.
+- Console summary reported no failed entries.
+
+## Requested Behavior Coverage
+- Asteroids menu/attract/gameplay/pause now permits manifest background draw via background layer (no gameplay-only gate).
+- Asteroids attract/fullscreen dark fill is no longer opaque when a manifest background is present.
+- Manifest-only chrome asset loading remains in effect.
+- No full sample suite run (targeted validation only).

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-30T00:12:47.854Z
+Generated: 2026-04-30T00:45:42.711Z
 
 Filters: games=true, samples=false, tools=false, sampleRange=all
 

games/Asteroids/game/AsteroidsAttractAdapter.js

@@ -238,13 +238,20 @@ export default class AsteroidsAttractAdapter {
     });
   }
 
-  render(renderer) {
+  render(renderer, options = {}) {
     if (!this.active) {
       return;
     }
 
     const alpha = this.getPhaseAlpha();
-    renderer.drawRect(0, 0, 960, 720, 'rgba(2, 6, 23, 0.86)');
+    const manifestBackgroundPresent = options?.manifestBackgroundPresent === true;
+    renderer.drawRect(
+      0,
+      0,
+      960,
+      720,
+      manifestBackgroundPresent ? 'rgba(2, 6, 23, 0.36)' : 'rgba(2, 6, 23, 0.86)'
+    );
 
     if (this.phase === 'title') {
       this.renderTitle(renderer, alpha);

games/Asteroids/game/AsteroidsGameScene.js

@@ -95,6 +95,17 @@ function drawLives(renderer, centerX, y, lives) {
   });
 }
 
+function hasManifestBackgroundLayer(engine) {
+  const state = engine?.backgroundImageLayer?.getState?.();
+  if (!state || typeof state !== 'object') {
+    return false;
+  }
+  return typeof state.path === 'string'
+    && state.path.trim().length > 0
+    && state.status !== 'missing'
+    && state.status !== 'unavailable';
+}
+
 export default class AsteroidsGameScene extends Scene {
   constructor(options = {}) {
     super();
@@ -688,10 +699,17 @@ export default class AsteroidsGameScene extends Scene {
     this.lastPPressed = pPressed;
   }
 
-  render(renderer) {
+  render(renderer, engine) {
     const leaderboardTopScore = this.highScoreService.getTopScore(this.highScoreRows);
     const liveHudHighScore = Math.max(this.session.highScore, leaderboardTopScore);
-    renderer.drawRect(0, 0, this.world.bounds.width, this.world.bounds.height, '#020617');
+    const manifestBackgroundPresent = hasManifestBackgroundLayer(engine);
+    renderer.drawRect(
+      0,
+      0,
+      this.world.bounds.width,
+      this.world.bounds.height,
+      manifestBackgroundPresent ? 'rgba(2, 6, 23, 0.22)' : '#020617'
+    );
     this.world.starfield.forEach((star) => {
       renderer.drawRect(star.x, star.y, star.size, star.size, '#94a3b8');
     });
@@ -762,7 +780,9 @@ export default class AsteroidsGameScene extends Scene {
 
     if (this.session.mode === 'menu') {
       if (this.attractController.active) {
-        this.attractAdapter.render(renderer);
+        this.attractAdapter.render(renderer, {
+          manifestBackgroundPresent
+        });
       } else {
         renderer.drawText('ASTEROIDS', 480, 220, {
           color: '#ffffff',

src/engine/runtime/backgroundImage.js

@@ -212,14 +212,6 @@ export default class backgroundImage {
   }
 
   render(renderer, options = {}) {
-    if (!this.isGameplayState(options.scene)) {
-      return {
-        drawn: false,
-        reason: "non-gameplay-state",
-        path: this.layer.path
-      };
-    }
-
     this.ensureLoaded();
     if (this.layer.status !== "ready" || !this.layer.image) {
       return {