Fix bezel path duplication and background draw order without resizing canvas

BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,47 +2,50 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-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_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND.zip`
+Create `BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER`.
+
+Implement the confirmed Asteroids runtime fixes:
+
+1. Fix fullscreen bezel path duplication
+   - current bad URL example:
+     `http://127.0.0.1:5500/games/Asteroids/games/Asteroids/assets/images/bezel.png`
+   - normalize asset path resolution so bezel resolves once to:
+     `games/Asteroids/assets/images/bezel.png`
+
+2. Preserve canvas layout
+   - do NOT resize the canvas
+   - do NOT stretch the canvas to the viewport
+   - keep canvas centered
+   - preserve intended game W x H dimensions
+
+3. Fix background rendering
+   - keep `backgroundImage` as a separate class/module from `fullscreenBezel`
+   - draw `backgroundImage` only during gameplay states
+   - draw it immediately after clear
+   - draw it before starfield and before all other world/gameplay content
+   - inspect Asteroids render order and fix any layer that currently hides the background
+
+4. Keep bezel as HTML overlay
+   - keep `fullscreenBezel` as a separate HTML/container-level overlay
+   - only show it in fullscreen
+   - ensure it is visibly on screen, not just present in the DOM
+
+5. Validate
+   - bezel URL/path not duplicated
+   - bezel visible in fullscreen
+   - canvas size unchanged
+   - canvas centered
+   - background visible during gameplay
+   - background absent in non-gameplay states
+   - starfield no longer hides background incorrectly
+
+6. Final packaging step is REQUIRED
+   - package ALL changed files into this exact repo-structured ZIP:
+     `<project folder>/tmp/BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER.zip`
 
 Hard rules:
-- do real implementation work
-- include changed source files in the ZIP
-- no docs-only completion
+- write implementation code only through Codex
+- include changed implementation files in Codex ZIP
+- no docs-only completion by Codex
 - no missing ZIP
 - no unrelated repo changes

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Implement real fullscreen bezel and gameplay background runtime delta
-BUILD_PR_LEVEL_10_19_REAL_IMPLEMENTATION_DELTA_FULLSCREEN_BEZEL_AND_BACKGROUND
+Fix bezel path duplication and background draw order without resizing canvas
+BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_10_20_VERIFY_ASTEROIDS_FULLSCREEN_BEZEL_ON_SCREEN
+BUILD_PR_LEVEL_10_21_VERIFY_CENTERED_CANVAS_BEZEL_AND_GAMEPLAY_BACKGROUND

docs/dev/reports/change_summary.txt

@@ -1,4 +1,5 @@
-- 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
+- Reissued as strict docs-only BUILD_PR bundle
+- Codex instructed to fix bezel path duplication
+- Canvas must remain centered at original W x H
+- backgroundImage must render after clear and before starfield/world
+- backgroundImage limited to gameplay states only

docs/dev/reports/validation_checklist.txt

@@ -1,7 +1,8 @@
-- 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`
+- Bundle is docs-only
+- Codex command requires implementation by Codex, not ChatGPT
+- Bezel URL/path must resolve once
+- Canvas must remain centered and unchanged in size
+- Background must draw only during gameplay
+- Background must draw before starfield/world content
+- Codex output ZIP path must be:
+  <project folder>/tmp/BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER.zip

docs/pr/BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER.md

@@ -0,0 +1,63 @@
+# BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER
+
+## Purpose
+Prepare a docs-only BUILD_PR bundle for Codex to implement the confirmed Asteroids runtime fixes.
+
+## Confirmed issues
+1. Fullscreen bezel asset path is duplicated.
+   Example bad URL:
+   `http://127.0.0.1:5500/games/Asteroids/games/Asteroids/assets/images/bezel.png`
+
+2. Canvas must remain centered and keep its intended W x H dimensions.
+
+3. Background is still not visible and is likely being covered by starfield or another later draw pass.
+
+4. Background should render only during gameplay, not attract, title, select-player, menu, or other non-gameplay states.
+
+## Required implementation for Codex
+
+### A. Fix fullscreen bezel path resolution
+- Resolve bezel asset path exactly once.
+- Use:
+  `games/Asteroids/assets/images/bezel.png`
+- Do not duplicate the `games/Asteroids/` prefix.
+- Keep bezel as an HTML-level overlay above the canvas.
+
+### B. Preserve canvas sizing and centering
+- Do not resize the canvas.
+- Do not stretch the canvas to the viewport.
+- Keep the game canvas centered.
+- Preserve intended game width and height.
+
+### C. Background draw order and state gating
+- Keep `backgroundImage` separate from `fullscreenBezel`.
+- `backgroundImage` draws to the canvas.
+- Draw `backgroundImage` immediately after clear.
+- Draw `backgroundImage` before starfield and before all other world/gameplay layers.
+- Draw `backgroundImage` only during gameplay states.
+- Do not draw `backgroundImage` during attract/title/select-player/menu/non-gameplay states.
+
+### D. Bezel behavior
+- Keep `fullscreenBezel` separate from canvas rendering.
+- Render `fullscreenBezel` at the HTML/container level.
+- Show bezel only while fullscreen is active.
+- Ensure bezel is visibly on screen, not just present in the DOM.
+
+## Validation targets
+Codex must validate:
+- bezel URL/path is not duplicated
+- bezel is visible in fullscreen
+- canvas dimensions are unchanged
+- canvas remains centered
+- background is visible during gameplay
+- background does not render in non-gameplay states
+- starfield no longer hides background by draw order mistake
+
+## Packaging requirement
+Codex must package all changed files into:
+`<project folder>/tmp/BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER.zip`
+
+## Scope guard
+- Docs-first PR bundle only
+- Codex writes implementation code
+- No unrelated repo changes

games/Asteroids/game/AsteroidsGameScene.js

@@ -690,7 +690,9 @@ export default class AsteroidsGameScene extends Scene {
   render(renderer) {
     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');
+    if (this.session.mode !== 'playing') {
+      renderer.drawRect(0, 0, this.world.bounds.width, this.world.bounds.height, '#020617');
+    }
     this.world.starfield.forEach((star) => {
       renderer.drawRect(star.x, star.y, star.size, star.size, '#94a3b8');
     });

src/engine/runtime/backgroundImage.js

@@ -1,4 +1,4 @@
-import { resolveGameImageConventionPaths } from "./gameImageConvention.js";
+import { resolveGameImageConventionPaths, resolveRuntimeAssetUrl } from "./gameImageConvention.js";
 
 const NON_GAMEPLAY_MODE_TOKENS = Object.freeze([
   "menu",
@@ -76,9 +76,10 @@ function sceneModeCandidates(scene) {
 
 export default class backgroundImage {
   constructor(options = {}) {
+    this.documentRef = options.documentRef || globalThis.document || null;
     const resolved = resolveGameImageConventionPaths({
       gameId: options.gameId,
-      documentRef: options.documentRef || globalThis.document || null
+      documentRef: this.documentRef
     });
     this.gameId = resolved.gameId;
     this.layer = createLayerState(resolved.backgroundPath);
@@ -156,7 +157,7 @@ export default class backgroundImage {
     };
 
     try {
-      image.src = this.layer.path;
+      image.src = resolveRuntimeAssetUrl(this.layer.path, this.documentRef);
     } catch {
       this.layer.status = "missing";
     }

src/engine/runtime/fullscreenBezel.js

@@ -1,4 +1,4 @@
-import { resolveGameImageConventionPaths } from "./gameImageConvention.js";
+import { resolveGameImageConventionPaths, resolveRuntimeAssetUrl } from "./gameImageConvention.js";
 
 function toDisplayValue(visible) {
   return visible ? "block" : "none";
@@ -184,7 +184,7 @@ export default class fullscreenBezel {
       this.missing = true;
       element.style.display = "none";
     };
-    element.src = this.path;
+    element.src = resolveRuntimeAssetUrl(this.path, this.documentRef);
 
     this.host.appendChild?.(element);
     this.element = element;

src/engine/runtime/gameImageConvention.js

@@ -6,6 +6,10 @@ function normalizePath(value) {
   return safeText(value, "").replace(/\\/g, "/");
 }
 
+function hasUrlProtocol(value) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(value);
+}
+
 function discoverGameIdFromDocument(documentRef) {
   const pathname = normalizePath(documentRef?.location?.pathname || "");
   if (!pathname) {
@@ -23,6 +27,32 @@ function toImagePath(gameId, fileName) {
   return `games/${id}/assets/images/${fileName}`;
 }
 
+export function resolveRuntimeAssetUrl(pathValue, documentRef = null) {
+  const normalized = normalizePath(pathValue);
+  if (!normalized) {
+    return "";
+  }
+
+  if (hasUrlProtocol(normalized) || normalized.startsWith("//")) {
+    return normalized;
+  }
+
+  if (normalized.startsWith("/")) {
+    return normalized;
+  }
+
+  if (normalized.startsWith("./") || normalized.startsWith("../")) {
+    try {
+      const baseHref = safeText(documentRef?.location?.href, "http://localhost/");
+      return new URL(normalized, baseHref).pathname;
+    } catch {
+      return `/${normalized.replace(/^\/+/, "")}`;
+    }
+  }
+
+  return `/${normalized.replace(/^\/+/, "")}`;
+}
+
 export function resolveGameImageConventionPaths(options = {}) {
   const gameId = safeText(options.gameId, "") || discoverGameIdFromDocument(options.documentRef || null);
   return {