Implement real fullscreen bezel and gameplay background runtime delta

BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND

Author: DavidQ

asteroids.txt

@@ -2,43 +2,47 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_10_17_HTML_FULLSCREEN_BEZEL_AND_CANVAS_BACKGROUND_SPLIT` as one small testable PR.
-
-Implement the correction exactly as follows:
-
-1. Add a dedicated canvas class/module named `backgroundImage`
-   - autodiscover: `games/<gameId>/assets/images/background.png`
-   - render into the canvas
-   - draw immediately after screen clear
-   - draw before ALL other game/world content
-   - keep logic independent from bezel logic
-
-2. Add a dedicated HTML-overlay class/module named `fullscreenBezel`
-   - autodiscover: `games/<gameId>/assets/images/bezel.png`
-   - render at the HTML/container level above the canvas
-   - only show when fullscreen is active
-   - hide when not fullscreen
-   - no canvas drawing for bezel
-   - no Parallax coupling
-
-3. Remove any incorrect coupling between background and bezel behavior
-   - separate classes
-   - separate render paths
-   - separate responsibilities
-
-4. Validation/tests
-   - cover background draw order: after clear, before world render
-   - cover bezel fullscreen-only visibility
-   - cover bezel attachment to HTML/container layer rather than canvas
-   - verify Asteroids uses:
-     - `games/Asteroids/assets/images/background.png` when present
-     - `games/Asteroids/assets/images/bezel.png` in fullscreen
+Create `BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND` as a real implementation PR, not a docs-only PR.
+
+Assume these files already exist and are the correct conventions:
+- `games/Asteroids/assets/images/background.png`
+- `games/Asteroids/assets/images/bezel.png`
+
+Implement all of the following with actual runtime code changes:
+
+1. Add/use a dedicated `backgroundImage` class/module
+   - autodiscover `games/<gameId>/assets/images/background.png`
+   - canvas-rendered
+   - draw immediately after clear
+   - draw before all world/gameplay content
+   - render ONLY during gameplay states
+   - do NOT render in attract/title/select-player/menu/non-gameplay states
+
+2. Add/use a dedicated `fullscreenBezel` class/module
+   - autodiscover `games/<gameId>/assets/images/bezel.png`
+   - HTML/container level overlay above canvas
+   - only visible in fullscreen
+   - must be visibly on screen, not DOM-only
+   - verify/fix sizing, positioning, stacking context, host attachment, z-index, overflow, opacity, and fullscreen lifecycle wiring
+
+3. Add focused tests/validation covering:
+   - gameplay-only background gating
+   - background draw order after clear and before world render
+   - fullscreen bezel visibility on screen
+   - bezel hidden outside fullscreen
+   - no-op when files are missing
+
+4. REQUIRED OUTPUT CONTENT
+   The final ZIP MUST include actual changed implementation files.
+   Docs-only output is not acceptable.
 
 5. Final packaging step is REQUIRED
-   - package ALL changed files into this exact repo-structured ZIP:
-     `<project folder>/tmp/BUILD_PR_LEVEL_10_17_HTML_FULLSCREEN_BEZEL_AND_CANVAS_BACKGROUND_SPLIT.zip`
+   Package ALL changed files into this exact repo-structured ZIP:
+   `<project folder>/tmp/BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`
 
 Hard rules:
-- no commit-only result
+- do real implementation work
+- include changed source files in the ZIP
+- no docs-only completion
 - no missing ZIP
 - no unrelated repo changes

docs/dev/CODEX_COMMANDS.md

@@ -1,2 +1,2 @@
-Split canvas background and HTML fullscreen bezel into separate classes
-BUILD_PR_LEVEL_10_17_HTML_FULLSCREEN_BEZEL_AND_CANVAS_BACKGROUND_SPLIT
+Implement real fullscreen bezel and gameplay background runtime delta
+BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_10_18_FULLSCREEN_BEZEL_VISIBILITY_VALIDATION
+BUILD_PR_LEVEL_10_20_VERIFY_ASTEROIDS_FULLSCREEN_BEZEL_ON_SCREEN

docs/dev/NEXT_COMMAND.txt

@@ -1,5 +1,4 @@
-- Split bezel and background into separate explicit systems
-- backgroundImage is canvas-rendered after clear and before all other content
-- fullscreenBezel is HTML-layer rendered above canvas in fullscreen only
-- Removed coupling between background and bezel behavior
-- Codex ZIP output explicitly required
+- Reframed the next PR to require actual implementation files in the ZIP
+- Locked asset assumptions to images/background.png and images/bezel.png
+- Kept separate classes: backgroundImage and fullscreenBezel
+- Enforced gameplay-only background and visible fullscreen bezel behavior

docs/dev/reports/change_summary.txt

@@ -1,7 +1,7 @@
-- `backgroundImage` exists as separate class/module
-- `fullscreenBezel` exists as separate class/module
-- Background draws after clear and before world render
-- Bezel is HTML-level, not canvas-level
-- Bezel only appears in fullscreen
-- Missing files do not break runtime
-- Output ZIP created at `<project folder>/tmp/BUILD_PR_LEVEL_10_17_HTML_FULLSCREEN_BEZEL_AND_CANVAS_BACKGROUND_SPLIT.zip`
+- ZIP contains changed implementation files, not docs only
+- Background renders only during gameplay
+- Background draws after clear and before world/gameplay
+- Bezel is visibly on screen in fullscreen
+- Bezel is hidden when not fullscreen
+- Missing background/bezel files do not break runtime
+- Output ZIP created at `<project folder>/tmp/BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`

docs/dev/reports/validation_checklist.txt

@@ -0,0 +1,62 @@
+# BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND
+
+## Purpose
+Force a real implementation delta for Asteroids fullscreen bezel and gameplay-only background rendering.
+
+## Why this PR exists
+Previous bundles did not produce a meaningful runtime delta in Git.
+This PR corrects that by requiring actual changed implementation files in the returned ZIP, not docs-only packaging.
+
+Assumed asset paths are correct:
+
+- `games/Asteroids/assets/images/background.png`
+- `games/Asteroids/assets/images/bezel.png`
+
+No subfolders are involved.
+
+## Required runtime behavior
+
+### A. `backgroundImage`
+- Dedicated class/module name: `backgroundImage`
+- Uses `games/<gameId>/assets/images/background.png`
+- Drawn to canvas
+- Drawn only during gameplay states
+- Drawn immediately after clear and before all other world/gameplay content
+- Not drawn during attract/title/select-player/menu/non-gameplay screens
+
+### B. `fullscreenBezel`
+- Dedicated class/module name: `fullscreenBezel`
+- Uses `games/<gameId>/assets/images/bezel.png`
+- Rendered at HTML/container level above the canvas
+- Only visible while fullscreen is active
+- Must be visually visible on screen, not merely present in the DOM
+
+## Required implementation delta
+The returned ZIP must contain real changed source files if needed, such as:
+- runtime/game integration files
+- render pipeline files
+- DOM/fullscreen host files
+- focused tests/validation files
+
+This PR is not complete if the ZIP only contains docs.
+
+## Required validation evidence
+Implementation must prove:
+- background renders in gameplay only
+- bezel appears on screen in fullscreen
+- bezel is above the canvas
+- games without those files do not break
+
+## Packaging rule
+Return a repo-structured ZIP at:
+`<project folder>/tmp/BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`
+
+The ZIP must include:
+1. changed implementation files
+2. changed tests/validation files
+3. docs/pr/*
+4. docs/dev/codex_commands.md
+5. docs/dev/commit_comment.txt
+6. docs/dev/reports/*
+
+If no implementation files are changed, this PR is considered failed.

docs/pr/BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND.md

@@ -9,7 +9,7 @@ import RuntimeMetrics from './RuntimeMetrics.js';
 import FrameClock from './FrameClock.js';
 import FixedTicker from './FixedTicker.js';
 import EventBus from '../events/EventBus.js';
-import { backgroundImage, fullscreenBezel, FullscreenService } from '../runtime/index.js';
+import { backgroundImage, fullscreenBezel, FullscreenService, resolvePreferredFullscreenTarget } from '../runtime/index.js';
 import { AudioService } from '../audio/index.js';
 import { Logger } from '../logging/index.js';
 import { SettingsSystem } from '../release/index.js';
@@ -41,6 +41,11 @@ export default class Engine {
     this.canvas.height = height;
 
     this.renderer = new CanvasRenderer(this.ctx);
+    this.documentRef = globalThis.document ?? null;
+    this.fullscreenTarget = resolvePreferredFullscreenTarget({
+      canvas,
+      documentRef: this.documentRef,
+    }) || canvas;
     this.input = input;
     this.events = events || new EventBus();
     this.metrics = metrics || new RuntimeMetrics();
@@ -50,15 +55,16 @@ export default class Engine {
       maxCatchUpSteps: Number.POSITIVE_INFINITY,
     });
     this.fullscreen = fullscreen || FullscreenService.fromBrowser({
-      documentRef: globalThis.document ?? null,
-      target: canvas,
+      documentRef: this.documentRef,
+      target: this.fullscreenTarget,
     });
     this.backgroundImageLayer = backgroundImageLayer || new backgroundImage({
-      documentRef: globalThis.document ?? null
+      documentRef: this.documentRef
     });
     this.fullscreenBezelLayer = fullscreenBezelLayer || new fullscreenBezel({
       canvas,
-      documentRef: globalThis.document ?? null
+      host: this.fullscreenTarget,
+      documentRef: this.documentRef
     });
     this.audio = audio || new AudioService();
     this.logger = logger || new Logger({ channel: 'engine' });
@@ -105,10 +111,15 @@ export default class Engine {
       this.audio.attach(this.canvas);
     }
     if (this.fullscreen && typeof this.fullscreen.attach === 'function') {
-      this.fullscreen.attach(this.canvas);
+      this.fullscreen.attach(this.fullscreenTarget);
     }
     if (this.fullscreenBezelLayer && typeof this.fullscreenBezelLayer.attach === 'function') {
       this.fullscreenBezelLayer.attach();
+      const fullscreenActive = this.fullscreen?.getState?.().active === true;
+      const fullscreenElement = this.fullscreen?.documentRef?.fullscreenElement
+        || this.documentRef?.fullscreenElement
+        || null;
+      this.fullscreenBezelLayer.sync({ fullscreenActive, fullscreenElement });
     }
 
     this.frameClock.reset();
@@ -161,12 +172,15 @@ export default class Engine {
 
     const renderStart = performance.now();
     this.renderer.clear();
-    this.backgroundImageLayer?.render?.(this.renderer);
+    this.backgroundImageLayer?.render?.(this.renderer, { scene: this.scene, engine: this });
     if (this.scene && typeof this.scene.render === 'function') {
       this.scene.render(this.renderer, this);
     }
     const fullscreenActive = this.fullscreen?.getState?.().active === true;
-    this.fullscreenBezelLayer?.sync?.({ fullscreenActive });
+    const fullscreenElement = this.fullscreen?.documentRef?.fullscreenElement
+      || this.documentRef?.fullscreenElement
+      || null;
+    this.fullscreenBezelLayer?.sync?.({ fullscreenActive, fullscreenElement });
     renderDurationMs = performance.now() - renderStart;
 
     this.metrics.recordFrame({

src/engine/core/Engine.js

@@ -1,5 +1,28 @@
 import { resolveGameImageConventionPaths } from "./gameImageConvention.js";
 
+const NON_GAMEPLAY_MODE_TOKENS = Object.freeze([
+  "menu",
+  "title",
+  "attract",
+  "select-player",
+  "player-select",
+  "intro",
+  "splash",
+  "game-over",
+  "credits",
+  "pause"
+]);
+
+const GAMEPLAY_MODE_TOKENS = Object.freeze([
+  "playing",
+  "gameplay",
+  "in-game",
+  "ingame",
+  "combat",
+  "runtime",
+  "active"
+]);
+
 function createLayerState(path) {
   return {
     path,
@@ -27,6 +50,30 @@ function drawFullscreenImage(renderer, image) {
   return true;
 }
 
+function toModeText(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+
+function sceneModeCandidates(scene) {
+  if (!scene || typeof scene !== "object") {
+    return [];
+  }
+
+  return [
+    scene.mode,
+    scene.state,
+    scene.status,
+    scene.screen,
+    scene.view,
+    scene.phase,
+    scene.session?.mode,
+    scene.session?.state,
+    scene.session?.status
+  ]
+    .map(toModeText)
+    .filter(Boolean);
+}
+
 export default class backgroundImage {
   constructor(options = {}) {
     const resolved = resolveGameImageConventionPaths({
@@ -48,6 +95,38 @@ export default class backgroundImage {
     };
   }
 
+  isGameplayState(scene) {
+    if (!scene || typeof scene !== "object") {
+      return true;
+    }
+
+    if (typeof scene.isGameplayStateActive === "function") {
+      const explicit = scene.isGameplayStateActive();
+      if (typeof explicit === "boolean") {
+        return explicit;
+      }
+    }
+    if (typeof scene.isGameplayStateActive === "boolean") {
+      return scene.isGameplayStateActive;
+    }
+
+    const modes = sceneModeCandidates(scene);
+    for (const mode of modes) {
+      if (NON_GAMEPLAY_MODE_TOKENS.some((token) => mode.includes(token))) {
+        return false;
+      }
+      if (GAMEPLAY_MODE_TOKENS.some((token) => mode.includes(token))) {
+        return true;
+      }
+    }
+
+    if (scene.attractController?.active === true) {
+      return false;
+    }
+
+    return true;
+  }
+
   ensureLoaded() {
     if (!this.layer.path) {
       this.layer.status = "unavailable";
@@ -83,7 +162,15 @@ export default class backgroundImage {
     }
   }
 
-  render(renderer) {
+  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 {