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

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,8 +1,8 @@
-# Codex Command — PR 11.86
+# Codex Commands — PR 11.87
 
 Model: GPT-5.4
 Reasoning: high
 
-```bash
-codex exec --model gpt-5.4 --reasoning high "Apply PR 11.86. Enforce bezel stretch SSoT in game manifests: move/remove any stretchOverride.uniformEdgeStretchPx from asset-browser.assets.bezel or equivalent duplicate browser/chrome config, and keep/add it only on image.*.bezel manifest entries. Ensure image.asteroids.bezel has stretchOverride.uniformEdgeStretchPx set to 10. Do not add fallback bezel/background loading. Do not add aliases or duplicate contracts. Produce a report under docs/dev/reports."
+```powershell
+codex exec --model gpt-5.4 --reasoning high "Run BUILD_PR_11_87_MANIFEST_BACKGROUND_ALWAYS_VISIBLE. Make manifest-declared image.*.background draw in all render states, prevent opaque clears/fills from hiding a present background, preserve manifest-only chrome asset loading, and write targeted validation evidence to docs/dev/reports/PR_11_87_validation.md. Do not run the full sample suite. Return a repo-structured ZIP at tmp/PR_11_87_MANIFEST_BACKGROUND_ALWAYS_VISIBLE.zip."
 ```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Keep bezel stretch override on image bezel manifest entries only - PR 11.86
+Draw manifest-declared game backgrounds across all render states without opaque suppression - PR 11.87

docs/dev/reports/PR_11_87_validation.md

@@ -0,0 +1,10 @@
+# PR 11.87 Validation Placeholder
+
+Codex must replace this with actual targeted validation evidence.
+
+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.

docs/pr/BUILD_PR_11_87_MANIFEST_BACKGROUND_ALWAYS_VISIBLE.md

@@ -0,0 +1,86 @@
+# BUILD_PR_11_87_MANIFEST_BACKGROUND_ALWAYS_VISIBLE
+
+## Codex Task
+Implement the smallest safe change so manifest-declared backgrounds are always drawn and are not hidden by clear/fill behavior.
+
+## Required Changes
+
+### 1. Background rendering gate
+Find the background rendering helper/module, likely near:
+
+```text
+src/**/backgroundImage.js
+```
+
+Change the logic so a valid manifest-declared background is not restricted to gameplay-only modes.
+
+Required behavior:
+
+```text
+if manifest has image.*.background and image loaded:
+  draw background for menu/title/attract/gameplay/pause/etc.
+else:
+  keep existing safe empty/no-background behavior
+```
+
+Do not add fallback paths.
+
+### 2. Clear/fill behavior
+Find scene code that clears or paints full-screen dark fills before/after background draw, especially:
+
+```text
+games/Asteroids/**/AsteroidsGameScene.js
+games/Asteroids/**/AsteroidsAttractAdapter.js
+```
+
+When a manifest background is present:
+- do not paint an opaque clear/fill that hides it
+- keep overlays translucent if needed for readability
+- preserve foreground UI/text/asteroids/title drawing
+
+### 3. Manifest-only rule
+Confirm bezel/background loading only comes from `game.manifest.json` entries like:
+
+```json
+"image.asteroids.background": {
+  "path": "/games/Asteroids/assets/images/deluxe.png",
+  "kind": "image",
+  "source": "workspace-manager"
+}
+```
+
+Remove or reject any newly discovered guessed paths like:
+
+```text
+/games/<Game>/assets/images/background.png
+/games/<Game>/assets/images/bezel.png
+```
+
+### 4. No duplicated SSoT
+Do not add background display options under `asset-browser.assets.background`.
+Background image behavior belongs to `image.*.background` manifest entries and renderer behavior only.
+
+## Validation
+Run targeted validation only:
+
+```text
+Asteroids menu state: deluxe.png visible
+Asteroids attract state: deluxe.png visible, not hidden by full-screen dark rect
+Asteroids gameplay state: deluxe.png visible
+Asteroids pause state: deluxe.png visible if pause is available
+Browser console: no missing bezel/background 404s
+Search: no guessed background/bezel path fallback added
+```
+
+Write evidence to:
+
+```text
+docs/dev/reports/PR_11_87_validation.md
+```
+
+## Constraints
+- No full sample suite.
+- No broad render architecture refactor.
+- No hardcoded default assets.
+- No alias/pass-through helpers.
+- No unrelated file changes.

docs/pr/PLAN_PR_11_87_MANIFEST_BACKGROUND_ALWAYS_VISIBLE.md

@@ -0,0 +1,33 @@
+# PLAN_PR_11_87_MANIFEST_BACKGROUND_ALWAYS_VISIBLE
+
+## Purpose
+Make manifest-declared game background images visible in all game presentation states, including menu/title/attract/pause, instead of being suppressed by gameplay-only render gates or hidden by clear/fill overlays.
+
+## Problem
+Asteroids can declare a valid background image in `game.manifest.json`, but it is not visible because background rendering is gated to gameplay states and attract/menu rendering can paint near-opaque full-screen fills over it.
+
+Known evidence from user validation:
+- `backgroundImage.js` only draws in gameplay states.
+- `AsteroidsGameScene.js` handles `session.mode === 'menu'`.
+- `AsteroidsAttractAdapter.js` draws a near-opaque full-screen dark rect in attract mode.
+- The manifest entry and `deluxe.png` are valid; this is render-state behavior, not a missing-file issue.
+
+## Scope
+- Manifest-declared `image.*.background` is the source of truth for background loading.
+- If a background exists and loads, draw it for all states before scene-specific foreground overlays.
+- Do not clear/fill over a present background in a way that makes it invisible.
+- Allow menu/attract/pause overlays to be transparent/translucent only if the background remains visible.
+
+## Out of Scope
+- No new default/fallback background paths.
+- No hidden sample/default assets.
+- No hardcoded `/assets/images/background.png` guesses.
+- No manifest schema expansion beyond using existing `image.*.background` entries.
+- No unrelated render refactors.
+
+## Acceptance
+- Asteroids `deluxe.png` background is visible on menu/attract/gameplay/pause when declared in manifest.
+- No 404 for guessed background paths.
+- No hardcoded chrome asset fallback remains.
+- Background draw path is manifest-only.
+- Targeted validation documented in `docs/dev/reports/PR_11_87_validation.md`.

games/Asteroids/game/AsteroidsGameScene.js

@@ -14,7 +14,8 @@ import AsteroidsAttractAdapter from './AsteroidsAttractAdapter.js';
 import AsteroidsHighScoreService from '../systems/AsteroidsHighScoreService.js';
 import AsteroidsInitialsEntry from '../systems/AsteroidsInitialsEntry.js';
 import {
-  ASTEROIDS_GAME_OVER_AUTO_EXIT_SECONDS, ASTEROIDS_GAME_OVER_RETURN_MODE } from "../rules/flowRules.js";
+  ASTEROIDS_GAME_OVER_AUTO_EXIT_SECONDS, ASTEROIDS_GAME_OVER_RETURN_MODE
+} from "../rules/flowRules.js";
 import { ASTEROIDS_GAME_OVER_RETURN_STATUS } from "../rules/flowContent.js";
 
 const HUD_FONT = '"Vector Battle", monospace';