Add pre-game bezel stretch override file auto-create

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,77 +1,15 @@
+
 MODEL: GPT-5.4
 REASONING: high
 
-COMMAND:
-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 internal game dimensions
-   - do NOT stretch the game resolution
-   - keep canvas centered
-   - preserve intended game width and height
-
-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. 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. Add one shared extra-stretch setting
-   - create one single developer-facing variable that applies equally to all four sides
-   - use it to push the displayed canvas slightly farther toward the bezel opening edges when the default fit is just short
-   - place this in a small easy-to-find config/override file, not hidden in code constants
-   - when bezel is detected, check whether that file exists
-   - if it does not exist, create it automatically for the developer with a safe default value
-   - keep filename/location obvious near the relevant game asset/config area
+UPDATE EXISTING PR:
 
-7. Validate
-   - bezel URL/path not duplicated
-   - bezel visible in fullscreen
-   - 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
-   - shared extra-stretch variable affects all four sides equally
-   - override/config file is auto-created when missing and bezel is detected
-   - background visible during gameplay
-   - background absent in non-gameplay states
-   - starfield no longer hides background incorrectly
+Add startup behavior:
 
-8. 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`
+- On game load (before gameplay)
+- If bezel detected AND override file missing:
+  create:
+  games/<game>/assets/images/bezel.stretch.override.json
 
-Hard rules:
-- 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
+- Do NOT overwrite if it already exists
+- Ensure this runs once during init

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1 @@
-Fix bezel path and gameplay background draw order, add bezel extra-stretch override
-BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER
+Add pre-game bezel stretch override file auto-create

docs/pr/BUILD_PR_LEVEL_10_20_FIX_BEZEL_PATH_AND_BACKGROUND_DRAW_ORDER_ADDENDUM.md

@@ -0,0 +1,17 @@
+
+## ADDITIONAL REQUIREMENT UPDATE
+
+When the game loads (pre-gameplay phase):
+
+If a bezel is detected AND the file:
+games/<game>/assets/images/bezel.stretch.override.json
+
+DOES NOT exist:
+- automatically create this file
+- create it BEFORE gameplay begins (startup/init phase)
+- include the shared stretch variable with a safe default
+- ensure this happens only once (do not overwrite existing file)
+
+Intent:
+- developer immediately sees where to tweak stretch
+- no manual setup required

games/Asteroids/assets/images/bezel.stretch.override.json

@@ -1,3 +1,3 @@
 {
-  "uniformEdgeStretchPx": 5
+  "uniformEdgeStretchPx": 10
 }

src/engine/runtime/fullscreenBezel.js

@@ -549,6 +549,7 @@ export default class fullscreenBezel {
       ? options.stretchConfigProvider
       : loadBezelStretchConfig;
     this.stretchConfigPromise = null;
+    this.stretchConfigInitialized = false;
     this.uniformEdgeStretchPx = 0;
     this.transparentWindowRect = null;
     this.imageSize = null;
@@ -565,6 +566,7 @@ export default class fullscreenBezel {
       canvasLayoutMode: this.canvasLayoutMode,
       transparentWindowRect: this.transparentWindowRect,
       stretchConfigPath: this.stretchConfigPath,
+      stretchConfigInitialized: this.stretchConfigInitialized,
       uniformEdgeStretchPx: this.uniformEdgeStretchPx
     };
   }
@@ -609,6 +611,11 @@ export default class fullscreenBezel {
   }
 
   refreshStretchConfig() {
+    if (this.stretchConfigInitialized) {
+      return this.stretchConfigPromise;
+    }
+    this.stretchConfigInitialized = true;
+
     if (!this.stretchConfigPath || typeof this.stretchConfigProvider !== "function") {
       this.applyStretchConfig(DEFAULT_BEZEL_STRETCH_CONFIG);
       return null;

tests/core/BackgroundImageAndFullscreenBezel.test.mjs

@@ -417,6 +417,17 @@ async function testBezelStretchConfigAutoCreate() {
     const absolutePath = path.resolve(tempRoot, configPath);
     const saved = JSON.parse(await fs.readFile(absolutePath, "utf8"));
     assert.deepEqual(saved, { uniformEdgeStretchPx: 0 });
+
+    const existingContent = { uniformEdgeStretchPx: 12 };
+    await fs.writeFile(absolutePath, `${JSON.stringify(existingContent, null, 2)}\n`, "utf8");
+    const loadedExisting = await ensureBezelStretchConfigFile(configPath, {
+      cwd: tempRoot,
+      fsModule: fs,
+      pathModule: path
+    });
+    const savedAfterReload = JSON.parse(await fs.readFile(absolutePath, "utf8"));
+    assert.deepEqual(loadedExisting, existingContent);
+    assert.deepEqual(savedAfterReload, existingContent);
   } finally {
     await fs.rm(tempRoot, { recursive: true, force: true });
   }
@@ -433,10 +444,12 @@ async function testBezelDetectionTriggersStretchConfigAutoCreate() {
   documentRef.body.appendChild(host);
 
   try {
+    let providerCalls = 0;
     const bezel = new fullscreenBezel({
       canvas,
       documentRef,
       stretchConfigProvider(configPath) {
+        providerCalls += 1;
         return ensureBezelStretchConfigFile(configPath, {
           cwd: tempRoot,
           fsModule: fs,
@@ -445,9 +458,13 @@ async function testBezelDetectionTriggersStretchConfigAutoCreate() {
       }
     });
     bezel.attach();
+    assert.equal(providerCalls, 0);
     bezel.element.naturalWidth = 1920;
     bezel.element.naturalHeight = 1080;
     bezel.element.onload?.();
+    assert.equal(providerCalls, 1);
+    bezel.sync({ fullscreenActive: false, fullscreenElement: host });
+    assert.equal(providerCalls, 1);
     if (bezel.stretchConfigPromise) {
       await bezel.stretchConfigPromise;
     }
@@ -456,6 +473,7 @@ async function testBezelDetectionTriggersStretchConfigAutoCreate() {
     const saved = JSON.parse(await fs.readFile(createdPath, "utf8"));
     assert.deepEqual(saved, { uniformEdgeStretchPx: 0 });
     assert.equal(bezel.getState().stretchConfigPath, "games/Asteroids/assets/images/bezel.stretch.override.json");
+    assert.equal(bezel.getState().stretchConfigInitialized, true);
   } finally {
     await fs.rm(tempRoot, { recursive: true, force: true });
   }