Multi-game validation pass for bezel/background system

DavidQ · DavidQ · commit ec256a868783 · 2026-04-14T18:00:52.000-04:00
BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,43 +1,25 @@
+
 MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_10_23_RESTORE_MASTER_ROADMAP_STATUS_ONLY`.
-
-1. Restore this exact file from git history:
-   `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
-
-2. Use the last known good FULL version from repo history.
-   - Do NOT reconstruct manually
-   - Do NOT use a shortened replacement
-   - Do NOT write a fresh roadmap
-   - Do NOT accept any restore under 600 lines
+Create `BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS`
 
-3. After restore, apply ONLY status-marker updates.
-   Allowed changes:
-   - `[ ]`
-   - `[x]`
-   - `[.]`
+1. Validate across:
+   - Asteroids
+   - games/_template
+   - another sample
 
-4. Forbidden changes:
-   - no text rewrites
-   - no formatting changes
-   - no new sections
-   - no deleted sections
-   - no line collapsing
-   - no summary replacement
+2. Verify:
+   - bezel behavior
+   - background behavior
+   - override file creation
 
-5. Validation is REQUIRED:
-   - report the git source used for restore
-   - report restored line count
-   - fail the task if the file is not 600+ lines before status-only edits
+3. Fix only real issues (minimal changes)
 
-6. Final packaging step is REQUIRED:
-   - package ALL changed files into this exact repo-structured ZIP:
-     `<project folder>/tmp/BUILD_PR_LEVEL_10_23_RESTORE_MASTER_ROADMAP_STATUS_ONLY.zip`
+4. Package:
+<project folder>/tmp/BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS.zip
 
-Hard rules:
-- exact historical restore
-- status-only update after restore
-- no unrelated repo changes
-- no missing ZIP
+Rules:
+- no scope expansion
+- no unnecessary changes
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Restore full MASTER_ROADMAP_HIGH_LEVEL from history and update status only
-BUILD_PR_LEVEL_10_23_RESTORE_MASTER_ROADMAP_STATUS_ONLY
+Multi-game validation pass for bezel/background system
+BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS
+BUILD_PR_LEVEL_10_25_POLISH_AND_EDGE_CASES
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,3 +1,3 @@
-- Reissued roadmap restore with strict historical-restore requirement
-- Added hard 600+ line guard
-- Limited post-restore edits to status markers only
+- Multi-game validation
+- Confirmed shared behavior
+- Minimal fixes if needed
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,8 +1,7 @@
-- Restored file came from git history
-- Restored file is the full correct roadmap
-- Restored file is 600+ lines
-- Only status markers changed after restore
-- No roadmap text was rewritten
-- No sections were added or removed
-- Output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_10_23_RESTORE_MASTER_ROADMAP_STATUS_ONLY.zip
+
+- Asteroids passes
+- Template passes
+- Another game passes
+- Bezel works
+- Background works
+- Override file works
diff --git a/docs/pr/BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS.md b/docs/pr/BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS.md
@@ -0,0 +1,61 @@
+
+# BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS
+
+## Purpose
+Validate bezel/background system across multiple games and template.
+
+## Scope
+- Asteroids (reference)
+- games/_template
+- at least one additional sample game
+
+## Validation Areas
+
+### A. Bezel
+- loads correctly
+- no path duplication
+- fullscreen only
+- visible on screen
+- transparency fit works
+- stretch override works
+
+### B. Background
+- gameplay only
+- after clear
+- before world/starfield
+- visible
+
+### C. Override File
+- auto-created when missing
+- not overwritten
+
+### D. Template
+- new game inherits behavior automatically
+
+## Fix Rule
+- only minimal surgical fixes allowed
+
+## Packaging
+<project folder>/tmp/BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS.zip
+
+## Implementation Delta
+- Extended focused multi-game validation in `tests/core/BackgroundImageAndFullscreenBezel.test.mjs` with `SpaceInvaders` coverage to satisfy the third target without scope expansion.
+- Added checks for additional-game behavior:
+  - background no-op in gameplay when `background.png` is missing
+  - bezel no-op in fullscreen when `bezel.png` is missing
+  - no duplicated bezel path resolution
+  - startup/detection-based override creation for `games/SpaceInvaders/assets/images/bezel.stretch.override.json`
+- No runtime/engine behavior changes were required because validation passed after adding cross-game coverage.
+
+## Validation Evidence (2026-04-14)
+- `node --check tests/core/BackgroundImageAndFullscreenBezel.test.mjs` PASS
+- `node --check tests/games/AsteroidsPresentation.test.mjs` PASS
+- `node --check tests/games/SpaceInvadersScene.test.mjs` PASS
+- `node --check tests/tools/GamesTemplateContractEnforcement.test.mjs` PASS
+- `BackgroundImageAndFullscreenBezel` focused validation PASS
+  - Asteroids bezel/background behavior
+  - `_template` override auto-create + non-overwrite
+  - SpaceInvaders sample-game bezel/background + override creation path
+- `AsteroidsPresentation` regression PASS
+- `SpaceInvadersScene` regression PASS
+- `GamesTemplateContractEnforcement` PASS
diff --git a/tests/core/BackgroundImageAndFullscreenBezel.test.mjs b/tests/core/BackgroundImageAndFullscreenBezel.test.mjs
@@ -234,6 +234,39 @@ function testNoOpWhenBackgroundMissing() {
   assert.equal(order.length, 0);
 }
 
+function testSampleGameBackgroundAndBezelNoOpWhenMissing() {
+  const documentRef = createDocumentStub("/games/SpaceInvaders/index.html");
+  const paths = resolveGameImageConventionPaths({ documentRef });
+  assert.equal(paths.backgroundPath, "games/SpaceInvaders/assets/images/background.png");
+  assert.equal(paths.bezelPath, "games/SpaceInvaders/assets/images/bezel.png");
+
+  const backgroundLayer = new backgroundImage({
+    documentRef,
+    imageFactory: createImageFactory(new Set())
+  });
+  const backgroundOrder = [];
+  const backgroundResult = backgroundLayer.render(createRendererSpy(backgroundOrder), {
+    scene: { session: { mode: "playing" } }
+  });
+  assert.equal(backgroundResult.drawn, false);
+  assert.equal(backgroundResult.path, "games/SpaceInvaders/assets/images/background.png");
+  assert.equal(backgroundOrder.length, 0);
+
+  const host = createElement("div", documentRef);
+  const canvas = createElement("canvas", documentRef);
+  host.appendChild(canvas);
+  documentRef.body.appendChild(host);
+
+  const bezel = new fullscreenBezel({ canvas, documentRef });
+  bezel.attach();
+  assert.equal(bezel.element.src, "/games/SpaceInvaders/assets/images/bezel.png");
+  assert.equal(bezel.element.src.includes("/games/SpaceInvaders/games/SpaceInvaders/"), false);
+  bezel.element.onerror?.();
+  const bezelResult = bezel.sync({ fullscreenActive: true, fullscreenElement: host });
+  assert.equal(bezelResult.visible, false);
+  assert.equal(bezel.element.style.display, "none");
+}
+
 function testFullscreenBezelVisibilityAndHtmlAttachment() {
   const documentRef = createDocumentStub();
   const host = createElement("div", documentRef);
@@ -548,6 +581,46 @@ async function testBezelDetectionDoesNotOverwriteExistingStretchConfig() {
   }
 }
 
+async function testSampleGameBezelDetectionCreatesStretchConfig() {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-detected-spaceinvaders-config-"));
+  const documentRef = createDocumentStub("/games/SpaceInvaders/index.html");
+  const host = createElement("div", documentRef);
+  const canvas = createElement("canvas", documentRef);
+  canvas.width = 960;
+  canvas.height = 720;
+  host.appendChild(canvas);
+  documentRef.body.appendChild(host);
+
+  try {
+    const bezel = new fullscreenBezel({
+      canvas,
+      documentRef,
+      stretchConfigProvider(configPath) {
+        return ensureBezelStretchConfigFile(configPath, {
+          cwd: tempRoot,
+          fsModule: fs,
+          pathModule: path
+        });
+      }
+    });
+
+    bezel.attach();
+    bezel.element.naturalWidth = 1920;
+    bezel.element.naturalHeight = 1080;
+    bezel.element.onload?.();
+    if (bezel.stretchConfigPromise) {
+      await bezel.stretchConfigPromise;
+    }
+
+    const createdPath = path.resolve(tempRoot, "games/SpaceInvaders/assets/images/bezel.stretch.override.json");
+    const saved = JSON.parse(await fs.readFile(createdPath, "utf8"));
+    assert.deepEqual(saved, { uniformEdgeStretchPx: 0 });
+    assert.equal(bezel.getState().stretchConfigPath, "games/SpaceInvaders/assets/images/bezel.stretch.override.json");
+  } finally {
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
 function testEngineRuntimeIntegration() {
   const animationFrame = createAnimationFrameStub();
   const originalDocument = globalThis.document;
@@ -685,6 +758,7 @@ export async function run() {
   testBackgroundGameplayGatingAndOrder();
   testGameImageConventionsAreGameAgnostic();
   testNoOpWhenBackgroundMissing();
+  testSampleGameBackgroundAndBezelNoOpWhenMissing();
   testFullscreenBezelVisibilityAndHtmlAttachment();
   testNoOpWhenBezelMissing();
   testTransparentWindowDetectionAndAspectFit();
@@ -693,5 +767,6 @@ export async function run() {
   await testBezelStretchConfigAutoCreate();
   await testBezelDetectionTriggersStretchConfigAutoCreate();
   await testBezelDetectionDoesNotOverwriteExistingStretchConfig();
+  await testSampleGameBezelDetectionCreatesStretchConfig();
   testEngineRuntimeIntegration();
 }

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_10_24_MULTI_GAME_VALIDATION_PASS`
	`1`	`+BUILD_PR_LEVEL_10_25_POLISH_AND_EDGE_CASES`