Remove Asteroids-specific debug storage key from shared debug config utility - PR_26139_023-shared-debug-config-normalization

Author: DavidQ

docs/dev/reports/PR_26139_023-shared-debug-config-normalization_report.md

@@ -0,0 +1,28 @@
+# PR_26139_023 Shared Debug Config Normalization Report
+
+## Summary
+- Removed the Asteroids-specific debug storage key from `src/shared/utils/debugConfigUtils.js`.
+- Added a caller-supplied `storageKey` option to `resolveDebugConfig`.
+- Preserved Asteroids debug persistence by passing `toolbox.sample.asteroids.debug.enabled` from Asteroids-specific boot code.
+- Wired Breakout to pass its existing Breakout debug storage key instead of depending on shared utility state.
+- Audited nearby shared utilities for similar game-specific debug constants; none remain.
+
+## Scope
+- Kept changes limited to shared debug config normalization and direct callers of `resolveDebugConfig`.
+- Did not change debug query parsing, debug mode defaults, local-development behavior, or dev console wiring.
+
+## Shared Utility Behavior
+- `resolveDebugConfig(documentRef, { storageKey })` now reads and writes remembered debug state only when a caller provides `storageKey`.
+- Calls without `storageKey` still resolve query/local debug state, but do not persist remembered debug state to a hardcoded key.
+- `src/shared/utils/debugConfigUtils.js` no longer contains `Asteroids`, `asteroids`, or `toolbox.sample.asteroids`.
+
+## Validation
+- PASS: `npm run build:manifest`
+- PASS: `node tests\games\AsteroidsValidation.test.mjs`
+- PASS: shared utility import/storage validation with caller-supplied Asteroids key
+- PASS: no Asteroids string remains in `src/shared/utils/debugConfigUtils.js`
+- PASS: nearby shared utility audit found no game-specific debug storage constants
+
+## Generated Output Cleanup
+- `npm run build:manifest` generated `docs/build/sample-manifest.json`.
+- Removed `docs/build/` after validation so generated build output is not included in the delta.

games/Asteroids/index.js

@@ -20,6 +20,7 @@ export const asteroidFlow = Object.freeze({
 const theme = new Theme(ThemeTokens);
 const BOOT_TRACE_PREFIX = "Asteroids";
 const ASTEROIDS_MANIFEST_PATH = "/games/Asteroids/game.manifest.json";
+const ASTEROIDS_DEBUG_STORAGE_KEY = "toolbox.sample.asteroids.debug.enabled";
 
 function traceBoot(stage, details = null) {
   if (details === null) {
@@ -212,7 +213,9 @@ export async function bootAsteroidsNew({
 
     stage = "resolve-debug-config";
     traceBoot(stage);
-    const debugConfig = resolveDebugConfig(documentRef);
+    const debugConfig = resolveDebugConfig(documentRef, {
+      storageKey: ASTEROIDS_DEBUG_STORAGE_KEY
+    });
     const devConsoleIntegration = debugConfig.debugEnabled && typeof createDevConsoleIntegration === "function"
       ? createDevConsoleIntegration({
           sampleId: "asteroids-new-showcase",

games/breakout/main.js

@@ -7,21 +7,12 @@ main.js
 import Engine from '/src/engine/core/Engine.js';
 import { InputService } from '/src/engine/input/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
-import {
-  parseBooleanFlag,
-  normalizeDebugMode,
-  readStoredBoolean,
-  writeStoredBoolean,
-  isLocalDebugEnvironment,
-  resolveDebugConfig,
-} from '../../src/shared/utils/debugConfigUtils.js';
+import { resolveDebugConfig } from '../../src/shared/utils/debugConfigUtils.js';
 import { createNoopDevConsoleIntegration } from '../../src/shared/utils/createNoopDevConsoleIntegration.js';
 import BreakoutScene from './game/BreakoutScene.js';
 import { loadGameSkin } from '/games/shared/gameSkinLoader.js';
 
 const theme = new Theme(ThemeTokens);
-const BUILD_DEBUG_MODE = 'prod';
-const BUILD_DEBUG_ENABLED = false;
 const DEBUG_STATE_STORAGE_KEY = 'toolbox.sample.breakout.debug.enabled';
 
 function sanitizeText(value) {
@@ -117,7 +108,9 @@ export function bootBreakout({
     input,
   });
 
-  const debugConfig = resolveDebugConfig(documentRef);
+  const debugConfig = resolveDebugConfig(documentRef, {
+    storageKey: DEBUG_STATE_STORAGE_KEY,
+  });
   const devConsoleIntegration = debugConfig.debugEnabled
     ? createDevConsoleIntegration({
         sampleId: 'breakout-debug-showcase',

src/shared/utils/debugConfigUtils.js

@@ -1,7 +1,6 @@
 import { safeTrim, toLowerSafe } from './stringUtils.js';
 const BUILD_DEBUG_MODE = 'prod';
 const BUILD_DEBUG_ENABLED = false;
-const DEBUG_STATE_STORAGE_KEY = 'toolbox.sample.asteroids.debug.enabled';
 
 export function parseBooleanFlag(value, fallback) {
   const normalized = toLowerSafe(value);
@@ -68,7 +67,8 @@ export function isLocalDebugEnvironment(documentRef) {
   return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
 }
 
-export function resolveDebugConfig(documentRef) {
+export function resolveDebugConfig(documentRef, options = {}) {
+  const debugStateStorageKey = safeTrim(options?.storageKey);
   const search = safeTrim(documentRef?.location?.search) || safeTrim(globalThis?.location?.search);
   const searchParams = new URLSearchParams(search);
   const queryMode = searchParams.get('debugMode');
@@ -83,15 +83,15 @@ export function resolveDebugConfig(documentRef) {
     : normalizeDebugMode(BUILD_DEBUG_MODE, 'prod');
   const debugMode = normalizeDebugMode(queryMode, demoMode ? 'qa' : defaultMode);
   const fallbackEnabled = (BUILD_DEBUG_ENABLED === true || localDebugEnvironment) && debugMode !== 'prod';
-  const storedDebugEnabled = rememberDebugState && queryEnabled === null
-    ? readStoredBoolean(DEBUG_STATE_STORAGE_KEY)
+  const storedDebugEnabled = debugStateStorageKey && rememberDebugState && queryEnabled === null
+    ? readStoredBoolean(debugStateStorageKey)
     : null;
   const debugEnabled = demoMode
     ? true
     : parseBooleanFlag(queryEnabled, storedDebugEnabled ?? fallbackEnabled);
 
-  if (rememberDebugState) {
-    writeStoredBoolean(DEBUG_STATE_STORAGE_KEY, debugEnabled);
+  if (debugStateStorageKey && rememberDebugState) {
+    writeStoredBoolean(debugStateStorageKey, debugEnabled);
   }
 
   return {