Standardize bezel/background conventions and align template

DavidQ · DavidQ · commit 643d065c8e7e · 2026-04-14T17:51:12.000-04:00
BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,52 +1,23 @@
+
 MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_10_21_VERIFY_CENTERED_CANVAS_BEZEL_AND_GAMEPLAY_BACKGROUND`.
-
-Verify the completed Asteroids fullscreen bezel and gameplay-background implementation end to end.
-
-Validation targets:
-
-1. Centered canvas
-   - internal resolution unchanged
-   - canvas remains centered
-   - no distortion in fullscreen
-   - no viewport-stretch behavior
-
-2. Bezel
-   - no duplicated path resolution
-   - HTML-layer rendering
-   - visible only in fullscreen
-   - visible on screen
-   - transparency-window fit rule is active
-   - shared stretch override is honored
-
-3. Override file
-   - if bezel exists and
-     `games/<game>/assets/images/bezel.stretch.override.json`
-     is missing,
-     auto-create it during startup/init before gameplay
-   - do not overwrite existing file
-
-4. Background
-   - separate from bezel
-   - gameplay only
-   - after clear
-   - before starfield/world
-   - visible during gameplay
-   - absent during non-gameplay states
-
-5. If validation finds real defects
-   - make only the smallest required surgical fixes
-   - do not expand scope
-
-6. Final packaging step is REQUIRED
-   - package ALL changed files into this exact repo-structured ZIP:
-     `<project folder>/tmp/BUILD_PR_LEVEL_10_21_VERIFY_CENTERED_CANVAS_BEZEL_AND_GAMEPLAY_BACKGROUND.zip`
-
-Hard rules:
-- verification-focused PR
-- keep fixes minimal
-- no unrelated repo changes
-- no missing ZIP
+Create `BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION`
+
+1. Align games/_template structure with Asteroids asset conventions
+2. Ensure shared pipeline handles:
+   - backgroundImage (gameplay-only)
+   - fullscreenBezel (fullscreen-only HTML layer)
+3. Ensure override file:
+   - auto-created at startup if bezel exists
+   - not overwritten
+4. Remove any game-specific coupling from shared code
+5. Validate across template + Asteroids
+
+Package:
+<project folder>/tmp/BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION.zip
+
+Rules:
+- minimal changes
+- no unrelated edits
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,2 +1,2 @@
-Verify centered canvas, fullscreen bezel, override creation, and gameplay background
-BUILD_PR_LEVEL_10_21_VERIFY_CENTERED_CANVAS_BEZEL_AND_GAMEPLAY_BACKGROUND
+Standardize bezel/background conventions and align template
+BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION
+BUILD_PR_LEVEL_10_23_MULTI_GAME_VALIDATION_PASS
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,3 +1,3 @@
-- Added verification PR for completed Asteroids bezel/background work
-- Focused on centered canvas, fullscreen bezel visibility, override-file creation, and gameplay-only background
-- Allows only minimal surgical fixes if validation finds real defects
+- Standardized bezel/background conventions
+- Aligned template structure
+- Ensured override auto-create behavior
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,12 +1,6 @@
-- Canvas internal size unchanged
-- Canvas remains centered
-- Bezel path not duplicated
-- Bezel visible only in fullscreen
-- Bezel visible on screen
-- Stretch override honored
-- Missing override file auto-created before gameplay
-- Existing override file preserved
-- Background draws only during gameplay
-- Background draws after clear and before starfield/world
-- Output ZIP path:
-  <project folder>/tmp/BUILD_PR_LEVEL_10_21_VERIFY_CENTERED_CANVAS_BEZEL_AND_GAMEPLAY_BACKGROUND.zip
+
+- Template structure matches Asteroids
+- Background gameplay-only
+- Bezel fullscreen-only
+- Override file auto-created
+- No game-specific coupling
diff --git a/docs/pr/BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION.md b/docs/pr/BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION.md
@@ -0,0 +1,63 @@
+
+# BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION
+
+## Purpose
+Standardize bezel + background behavior across all games and align `games/_template` with Asteroids conventions.
+
+## Scope
+
+### A. Template alignment
+- Ensure `games/_template` includes:
+  - assets/images/background.png (optional)
+  - assets/images/bezel.png (optional)
+  - assets/images/bezel.stretch.override.json (auto-created behavior defined)
+
+### B. Background convention
+- `backgroundImage`
+  - canvas-rendered
+  - draws after clear
+  - draws before all world/gameplay layers
+  - gameplay-only (not attract/menu/etc)
+
+### C. Bezel convention
+- `fullscreenBezel`
+  - HTML overlay
+  - fullscreen-only
+  - uses transparency window fit
+  - uses shared stretch override
+
+### D. Override behavior
+- file: `assets/images/bezel.stretch.override.json`
+- auto-created at startup if bezel exists and file missing
+- never overwritten
+
+### E. Cross-game rule
+- behavior must be consistent across all games
+- no Asteroids-specific logic in shared pipeline
+
+## Validation
+- template contains correct structure
+- new games inherit behavior automatically
+- existing games not broken
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION.zip`
+
+## Implementation Delta
+- Added shared resolver `resolveBezelStretchOverridePath` in `src/engine/runtime/gameImageConvention.js` so bezel override-path derivation remains centralized and game-agnostic.
+- Updated `src/engine/runtime/fullscreenBezel.js` to use that shared resolver (no Asteroids-specific path assumptions).
+- Aligned `_template` asset conventions by adding `games/_template/assets/tools.manifest.json` as the template asset-manifest foundation.
+- Strengthened template contract validation in `scripts/validate-games-template-contract.mjs` to require `assets/tools.manifest.json`.
+- Extended focused runtime tests in `tests/core/BackgroundImageAndFullscreenBezel.test.mjs` to validate:
+  - Asteroids + `_template` game-agnostic image/bezel convention paths
+  - startup/detection-based auto-create for `bezel.stretch.override.json` when missing
+  - non-overwrite behavior when the override file already exists
+
+## Validation Evidence (2026-04-14)
+- `node --check src/engine/runtime/gameImageConvention.js` PASS
+- `node --check src/engine/runtime/fullscreenBezel.js` PASS
+- `node --check tests/core/BackgroundImageAndFullscreenBezel.test.mjs` PASS
+- `node --check scripts/validate-games-template-contract.mjs` PASS
+- `BackgroundImageAndFullscreenBezel` focused test PASS
+- `GamesTemplateContractEnforcement` focused test PASS
+- `AsteroidsPresentation` focused regression test PASS
diff --git a/games/_template/assets/tools.manifest.json b/games/_template/assets/tools.manifest.json
@@ -0,0 +1,11 @@
+{
+  "schema": "html-js-gaming.game-asset-manifest",
+  "version": 1,
+  "gameId": "_template",
+  "domains": {
+    "sprites": [],
+    "tilemaps": [],
+    "parallax": [],
+    "vectors": []
+  }
+}
diff --git a/scripts/validate-games-template-contract.mjs b/scripts/validate-games-template-contract.mjs
@@ -27,6 +27,7 @@ const TEMPLATE_REQUIRED_ASSET_DIRS = [
 ];
 const TEMPLATE_REQUIRED_ASSET_FILES = [
   ".gitkeep",
+  "tools.manifest.json",
   "parallax/data/.gitkeep",
   "sprites/data/.gitkeep",
   "tilemaps/data/.gitkeep",
diff --git a/src/engine/runtime/fullscreenBezel.js b/src/engine/runtime/fullscreenBezel.js
@@ -1,4 +1,8 @@
-import { resolveGameImageConventionPaths, resolveRuntimeAssetUrl } from "./gameImageConvention.js";
+import {
+  resolveBezelStretchOverridePath,
+  resolveGameImageConventionPaths,
+  resolveRuntimeAssetUrl
+} from "./gameImageConvention.js";
 
 const TRANSPARENT_ALPHA_THRESHOLD = 8;
 const DEFAULT_BEZEL_STRETCH_OVERRIDE_FILENAME = "bezel.stretch.override.json";
@@ -114,15 +118,10 @@ export function sanitizeUniformEdgeStretchPx(value) {
 }
 
 export function resolveBezelStretchConfigPath(bezelPath, fileName = DEFAULT_BEZEL_STRETCH_OVERRIDE_FILENAME) {
-  const normalized = normalizePath(bezelPath).trim();
-  if (!normalized) {
-    return "";
-  }
-  const slashIndex = normalized.lastIndexOf("/");
-  if (slashIndex < 0) {
-    return fileName;
-  }
-  return `${normalized.slice(0, slashIndex + 1)}${fileName}`;
+  return resolveBezelStretchOverridePath({
+    bezelPath,
+    fileName
+  });
 }
 
 function parseStretchConfigObject(candidate) {
diff --git a/src/engine/runtime/gameImageConvention.js b/src/engine/runtime/gameImageConvention.js
@@ -27,6 +27,21 @@ function toImagePath(gameId, fileName) {
   return `games/${id}/assets/images/${fileName}`;
 }
 
+function resolveSiblingPath(pathValue, fileName) {
+  const normalizedPath = normalizePath(pathValue);
+  const normalizedName = safeText(fileName, "");
+  if (!normalizedPath || !normalizedName) {
+    return "";
+  }
+
+  const slashIndex = normalizedPath.lastIndexOf("/");
+  if (slashIndex < 0) {
+    return normalizedName;
+  }
+
+  return `${normalizedPath.slice(0, slashIndex + 1)}${normalizedName}`;
+}
+
 export function resolveRuntimeAssetUrl(pathValue, documentRef = null) {
   const normalized = normalizePath(pathValue);
   if (!normalized) {
@@ -61,3 +76,10 @@ export function resolveGameImageConventionPaths(options = {}) {
     bezelPath: toImagePath(gameId, "bezel.png")
   };
 }
+
+export function resolveBezelStretchOverridePath(options = {}) {
+  const fileName = safeText(options.fileName, "bezel.stretch.override.json");
+  const explicitBezelPath = safeText(options.bezelPath, "");
+  const bezelPath = explicitBezelPath || resolveGameImageConventionPaths(options).bezelPath;
+  return resolveSiblingPath(bezelPath, fileName);
+}
diff --git a/tests/core/BackgroundImageAndFullscreenBezel.test.mjs b/tests/core/BackgroundImageAndFullscreenBezel.test.mjs
@@ -11,7 +11,11 @@ import fullscreenBezel, {
   findTransparencyWindowFromEdges,
   fitAspectRatio
 } from "../../src/engine/runtime/fullscreenBezel.js";
-import { resolveGameImageConventionPaths, resolveRuntimeAssetUrl } from "../../src/engine/runtime/gameImageConvention.js";
+import {
+  resolveBezelStretchOverridePath,
+  resolveGameImageConventionPaths,
+  resolveRuntimeAssetUrl
+} from "../../src/engine/runtime/gameImageConvention.js";
 
 function createImageFactory(presentPaths) {
   return () => {
@@ -197,6 +201,28 @@ function testBackgroundGameplayGatingAndOrder() {
   assert.deepEqual(order, ["background:/games/Asteroids/assets/images/background.png"]);
 }
 
+function testGameImageConventionsAreGameAgnostic() {
+  const asteroidsPaths = resolveGameImageConventionPaths({
+    documentRef: { location: { pathname: "/games/Asteroids/index.html" } }
+  });
+  assert.equal(asteroidsPaths.backgroundPath, "games/Asteroids/assets/images/background.png");
+  assert.equal(asteroidsPaths.bezelPath, "games/Asteroids/assets/images/bezel.png");
+  assert.equal(
+    resolveBezelStretchOverridePath({ documentRef: { location: { pathname: "/games/Asteroids/index.html" } } }),
+    "games/Asteroids/assets/images/bezel.stretch.override.json"
+  );
+
+  const templatePaths = resolveGameImageConventionPaths({
+    documentRef: { location: { pathname: "/games/_template/index.html" } }
+  });
+  assert.equal(templatePaths.backgroundPath, "games/_template/assets/images/background.png");
+  assert.equal(templatePaths.bezelPath, "games/_template/assets/images/bezel.png");
+  assert.equal(
+    resolveBezelStretchOverridePath({ documentRef: { location: { pathname: "/games/_template/index.html" } } }),
+    "games/_template/assets/images/bezel.stretch.override.json"
+  );
+}
+
 function testNoOpWhenBackgroundMissing() {
   const layer = new backgroundImage({
     documentRef: { location: { pathname: "/games/MissingGame/index.html" } },
@@ -435,7 +461,7 @@ async function testBezelStretchConfigAutoCreate() {
 
 async function testBezelDetectionTriggersStretchConfigAutoCreate() {
   const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-detected-config-"));
-  const documentRef = createDocumentStub();
+  const documentRef = createDocumentStub("/games/_template/index.html");
   const host = createElement("div", documentRef);
   const canvas = createElement("canvas", documentRef);
   canvas.width = 960;
@@ -469,16 +495,59 @@ async function testBezelDetectionTriggersStretchConfigAutoCreate() {
       await bezel.stretchConfigPromise;
     }
 
-    const createdPath = path.resolve(tempRoot, "games/Asteroids/assets/images/bezel.stretch.override.json");
+    const createdPath = path.resolve(tempRoot, "games/_template/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/Asteroids/assets/images/bezel.stretch.override.json");
+    assert.equal(bezel.getState().stretchConfigPath, "games/_template/assets/images/bezel.stretch.override.json");
     assert.equal(bezel.getState().stretchConfigInitialized, true);
   } finally {
     await fs.rm(tempRoot, { recursive: true, force: true });
   }
 }
 
+async function testBezelDetectionDoesNotOverwriteExistingStretchConfig() {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "bezel-detected-existing-config-"));
+  const documentRef = createDocumentStub("/games/_template/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 expectedConfig = { uniformEdgeStretchPx: 14 };
+    const configPath = path.resolve(tempRoot, "games/_template/assets/images/bezel.stretch.override.json");
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, `${JSON.stringify(expectedConfig, null, 2)}\n`, "utf8");
+
+    const bezel = new fullscreenBezel({
+      canvas,
+      documentRef,
+      stretchConfigProvider(runtimeConfigPath) {
+        return ensureBezelStretchConfigFile(runtimeConfigPath, {
+          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 savedAfterStartup = JSON.parse(await fs.readFile(configPath, "utf8"));
+    assert.deepEqual(savedAfterStartup, expectedConfig);
+    assert.equal(bezel.getState().uniformEdgeStretchPx, expectedConfig.uniformEdgeStretchPx);
+  } finally {
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
 function testEngineRuntimeIntegration() {
   const animationFrame = createAnimationFrameStub();
   const originalDocument = globalThis.document;
@@ -614,6 +683,7 @@ function testEngineRuntimeIntegration() {
 
 export async function run() {
   testBackgroundGameplayGatingAndOrder();
+  testGameImageConventionsAreGameAgnostic();
   testNoOpWhenBackgroundMissing();
   testFullscreenBezelVisibilityAndHtmlAttachment();
   testNoOpWhenBezelMissing();
@@ -622,5 +692,6 @@ export async function run() {
   testFullscreenBezelSharedStretchAffectsAllSides();
   await testBezelStretchConfigAutoCreate();
   await testBezelDetectionTriggersStretchConfigAutoCreate();
+  await testBezelDetectionDoesNotOverwriteExistingStretchConfig();
   testEngineRuntimeIntegration();
 }

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_10_22_TEMPLATE_BEZEL_BACKGROUND_CONVENTION_FOUNDATION`
	`1`	`+BUILD_PR_LEVEL_10_23_MULTI_GAME_VALIDATION_PASS`