Fix bezel path and gameplay background draw order, add transparent-window canvas fitting

BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER & Fix bezel path and gameplay background draw order, improve transparent-window canvas fitting
BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER & Fix bezel path and gameplay background draw order, add exact transparency-window fitting rule
BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER

Author: DavidQ

asteroids.txt

@@ -13,10 +13,10 @@ Implement the confirmed Asteroids runtime fixes:
      `games/Asteroids/assets/images/bezel.png`
 
 2. Preserve canvas layout
-   - do NOT resize the canvas
-   - do NOT stretch the canvas to the viewport
+   - do NOT resize the canvas internal game dimensions
+   - do NOT stretch the game resolution
    - keep canvas centered
-   - preserve intended game W x H dimensions
+   - preserve intended game width and height
 
 3. Fix background rendering
    - keep `backgroundImage` as a separate class/module from `fullscreenBezel`
@@ -30,16 +30,32 @@ Implement the confirmed Asteroids runtime fixes:
    - only show it in fullscreen
    - ensure it is visibly on screen, not just present in the DOM
 
-5. Validate
+5. Use this exact bezel transparency fit rule
+   - from left to right, find first transparent pixel
+   - from right to left, find first transparent pixel
+   - from top to bottom, find first transparent pixel
+   - from bottom to top, find first transparent pixel
+   - use those four values as the transparency window
+   - maintain canvas aspect ratio
+   - stretch the displayed canvas to fill the transparency window as much as possible
+   - keep the displayed canvas centered in that window
+   - do NOT change internal game resolution
+   - if top/bottom does not fill, use that result for resize
+   - if left/right does not fill, use that result for resize
+   - if no valid transparency window is found, fall back to existing centered-canvas behavior
+
+6. Validate
    - bezel URL/path not duplicated
    - bezel visible in fullscreen
-   - canvas size unchanged
+   - canvas internal size unchanged
    - canvas centered
+   - exact four-direction transparency rule used
+   - displayed canvas fills transparency window as fully as possible while preserving aspect ratio
    - background visible during gameplay
    - background absent in non-gameplay states
    - starfield no longer hides background incorrectly
 
-6. Final packaging step is REQUIRED
+7. 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`
 

docs/dev/CODEX_COMMANDS.md

@@ -1,2 +1,2 @@
-Fix bezel path duplication and background draw order without resizing canvas
+Fix bezel path and gameplay background draw order, add exact transparency-window fitting rule
 BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,6 @@
 - Reissued as strict docs-only BUILD_PR bundle
 - Codex instructed to fix bezel path duplication
-- Canvas must remain centered at original W x H
+- Canvas internal size must remain unchanged and centered
 - backgroundImage must render after clear and before starfield/world
 - backgroundImage limited to gameplay states only
+- Updated bezel fitting requirement to use the exact four-direction first-transparent-pixel rule

docs/dev/reports/change_summary.txt

@@ -1,7 +1,10 @@
 - 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
+- Canvas internal size must remain unchanged
+- Canvas must remain centered
+- Transparency window must use the exact four-direction first-transparent-pixel rule
+- Canvas display box must fill the transparency window as fully as possible while preserving aspect ratio
 - Background must draw only during gameplay
 - Background must draw before starfield/world content
 - Codex output ZIP path must be:

docs/dev/reports/validation_checklist.txt

@@ -8,12 +8,14 @@ Prepare a docs-only BUILD_PR bundle for Codex to implement the confirmed Asteroi
    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.
+2. Canvas must keep its intended internal W x H dimensions and remain centered.
 
 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.
 
+5. When a bezel image is loaded, the displayed canvas should be fit to the bezel transparency using the exact edge-detection rule below.
+
 ## Required implementation for Codex
 
 ### A. Fix fullscreen bezel path resolution
@@ -24,8 +26,8 @@ Prepare a docs-only BUILD_PR bundle for Codex to implement the confirmed Asteroi
 - 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.
+- Do not resize the canvas internal game dimensions.
+- Do not stretch the game resolution.
 - Keep the game canvas centered.
 - Preserve intended game width and height.
 
@@ -43,12 +45,39 @@ Prepare a docs-only BUILD_PR bundle for Codex to implement the confirmed Asteroi
 - Show bezel only while fullscreen is active.
 - Ensure bezel is visibly on screen, not just present in the DOM.
 
+### E. Exact bezel transparency fit rule
+When `bezel.png` is loaded, determine the transparent gameplay window exactly as follows:
+
+1. From left to right, find the first transparent pixel.
+2. From right to left, find the first transparent pixel.
+3. From top to bottom, find the first transparent pixel.
+4. From bottom to top, find the first transparent pixel.
+
+Use those four bounds as the bezel transparency window.
+
+Then:
+- maintain canvas aspect ratio
+- stretch the displayed canvas to fill the transparency window as much as possible
+- do not change internal game resolution
+- keep the displayed canvas centered in that window
+
+Selection rule:
+- If top/bottom does not fill, use that result for resize.
+- If left/right does not fill, use that result for resize.
+
+Interpretation:
+- the display box should be driven by the transparency bounds
+- the goal is to fill the transparent gameplay area as fully as possible while keeping aspect ratio
+- fallback to existing centered-canvas behavior only if a valid transparency window cannot be determined
+
 ## Validation targets
 Codex must validate:
 - bezel URL/path is not duplicated
 - bezel is visible in fullscreen
-- canvas dimensions are unchanged
+- canvas internal dimensions are unchanged
 - canvas remains centered
+- transparency bounds are determined by the exact four-direction first-transparent-pixel rule
+- displayed canvas fills the transparency window as fully as possible while preserving aspect ratio
 - background is visible during gameplay
 - background does not render in non-gameplay states
 - starfield no longer hides background by draw order mistake

docs/pr/BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER.md

@@ -140,7 +140,13 @@ export default class backgroundImage {
       return;
     }
 
-    const image = this.imageFactory(this.layer.path);
+    const runtimePath = resolveRuntimeAssetUrl(this.layer.path, this.documentRef);
+    if (!runtimePath) {
+      this.layer.status = "missing";
+      return;
+    }
+
+    const image = this.imageFactory(runtimePath);
     if (!image || typeof image !== "object") {
       this.layer.status = "missing";
       return;
@@ -157,7 +163,7 @@ export default class backgroundImage {
     };
 
     try {
-      image.src = resolveRuntimeAssetUrl(this.layer.path, this.documentRef);
+      image.src = runtimePath;
     } catch {
       this.layer.status = "missing";
     }