Continue Phase 2 extraction of duplicated repo-owned helpers into shared utility modules - PR_26140_033-shared-utils-phase-2

DavidQ · DavidQ · commit 5328c3689154 · 2026-05-19T23:20:49.000-04:00
diff --git a/docs/dev/reports/PR_26140_033-shared-utils-phase-2_report.md b/docs/dev/reports/PR_26140_033-shared-utils-phase-2_report.md
@@ -0,0 +1,40 @@
+# PR_26140_033 Shared Utils Phase 2 Report
+
+## Summary
+- Added shared string helpers for `normalizeText`, `normalizeToken`, and case-preserving `normalizeGameId`.
+- Added shared `toObject` in `src/shared/utils/objectUtils.js` for callers that intentionally allow arrays, while preserving existing `asObject` array-rejecting semantics.
+- Replaced exact-match local helpers across active game, engine, and tool code for `sanitizeText`, `normalizeToken`, `normalizeGameId`, `toObject`, and `positiveInteger`.
+- Left lowercasing/slug `normalizeGameId` variants and other differing semantics in place.
+
+## Duplicate Scan
+- Re-ran `tools/shared/powerShell/find_dupes_called.ps1` into `tmp/dupes_called.txt`.
+- Verified `node_modules` paths are not present in the regenerated duplicate report.
+- Selected duplicate block counts from `tmp/dupes_called.txt`:
+  - `function sanitizeText(value)`: 41 -> 38
+  - `export function sanitizeText(value)`: 3 -> 0
+  - `function toObject(value)`: 12 -> 2
+  - `function normalizeToken(value)`: 5 -> 2
+  - `function normalizeGameId(value)`: 5 -> 2
+  - `function positiveInteger(value)`: 3 -> 0
+
+## Scope Notes
+- No vendor, generated bundle, `node_modules`, `tests/results`, or archived tool files were modified.
+- `normalizeGameId` variants that lowercase or slugify game IDs remain local because their behavior differs from case-preserving game ID trimming.
+- `normalizeString` helpers that coerce non-strings through `String(value || "")` remain local because they differ from the shared string-only trim semantics.
+- `distance`/`near` helpers were not migrated in this pass because the remaining candidates either use different distance metrics or are outside the requested validation surface.
+
+## Validation
+- PASS: `npm run build:manifest`
+- PASS: `node tests\games\AsteroidsValidation.test.mjs`
+- PASS: `node tests\games\AsteroidsManifestScreenDimensions.test.mjs`
+- PASS: `node tests\games\AsteroidsPresentation.test.mjs`
+- PASS: `node tests\tools\ObjectVectorFinalRuntimeCleanup.test.mjs`
+- PASS: `node tests\tools\ObjectVectorStudioV2DeleteCleanup.test.mjs`
+- PASS: `npm run test:workspace-v2` (58 passed)
+- PASS: `npx playwright test tests/playwright/tools/ObjectVectorStudioV2FirstClassToolStarter.spec.mjs --project=playwright --workers=1 --reporter=list` (4 passed)
+- PASS: `npx playwright test tests/playwright/tools/AsteroidsGameSceneCleanup.spec.mjs --project=playwright --workers=1 --reporter=list` (1 passed)
+- PASS: `git diff --check` (no whitespace errors; Git reported existing CRLF/LF normalization warnings for two modified files)
+
+## Corrected During Validation
+- The first Asteroids Node validation exposed a new browser-absolute import in `games/shared/workspaceGameAssetCatalog.js`; switched new `games/shared` and `games/index.render.js` imports to relative paths and reran validation successfully.
+- A first Playwright invocation used Windows backslashes and matched no tests; reran with forward slashes successfully.
diff --git a/games/Asteroids/debug/asteroidsShowcaseDebug.js b/games/Asteroids/debug/asteroidsShowcaseDebug.js
@@ -6,10 +6,7 @@ asteroidsShowcaseDebug.js
 */
 
 import { asArray, asObject } from "../../../src/engine/debug/inspectors/shared/inspectorUtils.js";
-
-function sanitizeText(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { sanitizeText } from "../../../src/shared/string/index.js";
 
 function formatNumber(value, fallback = 0) {
   return Number.isFinite(value) ? Number(value) : fallback;
diff --git a/games/Asteroids/game/AsteroidsGameScene.js b/games/Asteroids/game/AsteroidsGameScene.js
@@ -6,6 +6,7 @@ AsteroidsGameScene.js
 */
 import { AttractModeController, Scene } from '../../../src/engine/scene/index.js';
 import { ParticleSystem } from '../../../src/engine/fx/index.js';
+import { asPositiveInteger } from '../../../src/shared/number/index.js';
 import AsteroidsSession from './AsteroidsSession.js';
 import AsteroidsWorld from './AsteroidsWorld.js';
 import AsteroidsAudio from '../systems/AsteroidsAudio.js';
@@ -69,14 +70,9 @@ function logSceneBootStage(stage, details = null) {
   }
 }
 
-function positiveInteger(value) {
-  const parsed = Math.floor(Number(value));
-  return Number.isNaN(parsed) || Math.abs(parsed) === Infinity || parsed <= 0 ? 0 : parsed;
-}
-
 function screenDimensionsFromOptions(options) {
-  const width = positiveInteger(options?.screenDimensions?.width);
-  const height = positiveInteger(options?.screenDimensions?.height);
+  const width = asPositiveInteger(options?.screenDimensions?.width, 0);
+  const height = asPositiveInteger(options?.screenDimensions?.height, 0);
   if (!width || !height) {
     throw new Error('AsteroidsGameScene requires screenDimensions.width and screenDimensions.height from game.manifest.json.');
   }
diff --git a/games/Asteroids/index.js b/games/Asteroids/index.js
@@ -8,6 +8,7 @@ import { ObjectVectorRuntimeAssetService } from "../../src/engine/rendering/inde
 import { Theme, ThemeTokens } from "../../src/engine/theme/index.js";
 import { resolveDebugConfig } from "../../src/shared/utils/debugConfigUtils.js";
 import { createNoopDevConsoleIntegration } from "../../src/shared/utils/createNoopDevConsoleIntegration.js";
+import { asPositiveInteger } from "../../src/shared/number/index.js";
 import AsteroidsGameScene from "./game/AsteroidsGameScene.js";
 import { loadAsteroidsObjectGeometryFromManifest } from "./game/asteroidsObjectGeometryManifest.js";
 import { preloadWorkspaceGameAssetCatalog } from "../shared/workspaceGameAssetCatalog.js";
@@ -73,14 +74,9 @@ async function loadAsteroidsManifestPayload(manifestPath, manifestPayload = null
   return response.json();
 }
 
-function positiveInteger(value) {
-  const parsed = Math.floor(Number(value));
-  return Number.isNaN(parsed) || Math.abs(parsed) === Infinity || parsed <= 0 ? 0 : parsed;
-}
-
 export function resolveAsteroidsScreenDimensions(manifest) {
-  const width = positiveInteger(manifest?.screen?.width);
-  const height = positiveInteger(manifest?.screen?.height);
+  const width = asPositiveInteger(manifest?.screen?.width, 0);
+  const height = asPositiveInteger(manifest?.screen?.height, 0);
   if (!width || !height) {
     throw new Error("Asteroids game.manifest.json requires screen.width and screen.height.");
   }
diff --git a/games/SolarSystem/game/SolarSystemScene.js b/games/SolarSystem/game/SolarSystemScene.js
@@ -6,6 +6,7 @@ SolarSystemScene.js
 */
 import { Scene } from '/src/engine/scene/index.js';
 import SolarSystemWorld from './SolarSystemWorld.js';
+import { toObject } from '/src/shared/utils/objectUtils.js';
 
 const VIEW = { width: 960, height: 720 };
 
@@ -18,10 +19,6 @@ const DEFAULT_COLORS = {
   panel: '#07101d',
 };
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function sanitizeSolarSceneColors(skin) {
   const colors = toObject(skin?.colors);
   return {
diff --git a/games/SolarSystem/game/SolarSystemWorld.js b/games/SolarSystem/game/SolarSystemWorld.js
@@ -4,6 +4,8 @@ David Quesenberry
 03/24/2026
 SolarSystemWorld.js
 */
+import { toObject } from '/src/shared/utils/objectUtils.js';
+
 const MAX_STEP_SECONDS = 1 / 60;
 
 const TIME_SCALES = [
@@ -84,10 +86,6 @@ function clampIndex(value, max) {
   return Math.max(0, Math.min(max, value));
 }
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function toFiniteNumber(value, fallback) {
   const numeric = Number(value);
   return Number.isFinite(numeric) ? numeric : fallback;
diff --git a/games/bouncing-ball/game/BouncingBallScene.js b/games/bouncing-ball/game/BouncingBallScene.js
@@ -9,6 +9,7 @@ import BouncingBallAudio from './BouncingBallAudio.js';
 import BouncingBallInputController from './BouncingBallInputController.js';
 import BouncingBallWorld from './BouncingBallWorld.js';
 import { wrapTextByCharacterCount } from '/src/shared/utils/index.js';
+import { toObject } from '/src/shared/utils/objectUtils.js';
 
 const VIEW = {
   width: 960,
@@ -24,10 +25,6 @@ const DEFAULT_COLORS = {
   ball: '#f4f4ef',
 };
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function sanitizeBouncingBallSceneColors(skin) {
   const colors = toObject(skin?.colors);
   return {
diff --git a/games/bouncing-ball/game/BouncingBallWorld.js b/games/bouncing-ball/game/BouncingBallWorld.js
@@ -5,6 +5,7 @@ David Quesenberry
 BouncingBallWorld.js
 */
 import { clamp } from '/src/shared/utils/mathUtils.js';
+import { toObject } from '/src/shared/utils/objectUtils.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 const DEFAULT_BOUNCING_BALL_WORLD_SKIN = Object.freeze({
@@ -17,10 +18,6 @@ const DEFAULT_BOUNCING_BALL_WORLD_SKIN = Object.freeze({
   }
 });
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function toFiniteNumber(value, fallback) {
   const numeric = Number(value);
   return Number.isFinite(numeric) ? numeric : fallback;
diff --git a/games/breakout/game/BreakoutScene.js b/games/breakout/game/BreakoutScene.js
@@ -9,6 +9,7 @@ import BreakoutAudio from './BreakoutAudio.js';
 import BreakoutInputController from './BreakoutInputController.js';
 import BreakoutWorld from './BreakoutWorld.js';
 import { wrapTextByCharacterCount } from '/src/shared/utils/index.js';
+import { toObject } from '/src/shared/utils/objectUtils.js';
 
 const VIEW = {
   width: 960,
@@ -25,10 +26,6 @@ const DEFAULT_COLORS = {
   panel: '#000000',
 };
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function sanitizeBreakoutSceneColors(skin) {
   const colors = toObject(skin?.colors);
   return {
diff --git a/games/breakout/game/BreakoutWorld.js b/games/breakout/game/BreakoutWorld.js
@@ -5,6 +5,7 @@ David Quesenberry
 BreakoutWorld.js
 */
 import { clamp } from '/src/shared/utils/mathUtils.js';
+import { toObject } from '/src/shared/utils/objectUtils.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 
@@ -33,10 +34,6 @@ const DEFAULT_BREAKOUT_SKIN = Object.freeze({
   }
 });
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function toFiniteNumber(value, fallback) {
   const numeric = Number(value);
   return Number.isFinite(numeric) ? numeric : fallback;
diff --git a/games/breakout/main.js b/games/breakout/main.js
@@ -9,15 +9,12 @@ import { InputService } from '/src/engine/input/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import { resolveDebugConfig } from '../../src/shared/utils/debugConfigUtils.js';
 import { createNoopDevConsoleIntegration } from '../../src/shared/utils/createNoopDevConsoleIntegration.js';
+import { sanitizeText } from '../../src/shared/string/index.js';
 import BreakoutScene from './game/BreakoutScene.js';
 
 const theme = new Theme(ThemeTokens);
 const DEBUG_STATE_STORAGE_KEY = 'toolbox.sample.breakout.debug.enabled';
 
-function sanitizeText(value) {
-  return typeof value === 'string' ? value.trim() : '';
-}
-
 function applyDefaultDebugPreset(devConsoleIntegration) {
   if (!devConsoleIntegration || typeof devConsoleIntegration.executeCommand !== 'function') {
     return '';
diff --git a/games/index.render.js b/games/index.render.js
@@ -1,18 +1,11 @@
 import { getToolRegistry } from "../tools/toolRegistry.js";
 import { resolveGamePreviewMap } from "./shared/gameManifestPreviewResolver.js";
+import { normalizeText as normalize, normalizeToken } from "../src/shared/string/index.js";
 import { launchWithExternalToolWorkspaceReset, resolveGameWorkspaceLaunchHref } from "../tools/shared/toolLaunchSSoT.js";
 
 const METADATA_PATH = "./metadata/games.index.metadata.json";
 const GAMES_PINNED_KEY = "games-index-pinned";
 
-function normalize(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizeToken(value) {
-  return normalize(value).toLowerCase();
-}
-
 function normalizeTag(value) {
   return normalizeToken(value).replace(/[_\s]+/g, "-").replace(/-+/g, "-");
 }
diff --git a/games/pong/game/PongScene.js b/games/pong/game/PongScene.js
@@ -9,6 +9,7 @@ import PongInputController from './PongInputController.js';
 import PongAudio from './PongAudio.js';
 import { getPongModes } from './PongModeConfig.js';
 import { wrapTextByCharacterCount } from '/src/shared/utils/index.js';
+import { toObject } from '/src/shared/utils/objectUtils.js';
 
 const COURT = {
   width: 960,
@@ -36,10 +37,6 @@ const DEFAULT_SIZING = {
   ballRadius: 8
 };
 
-function toObject(value) {
-  return value && typeof value === 'object' ? value : {};
-}
-
 function toFiniteNumber(value, fallback) {
   const numeric = Number(value);
   return Number.isFinite(numeric) ? numeric : fallback;
diff --git a/games/shared/workspaceGameAssetCatalog.js b/games/shared/workspaceGameAssetCatalog.js
@@ -1,3 +1,5 @@
+import { toObject } from "../../src/shared/utils/objectUtils.js";
+
 const GAME_ASSET_CATALOG_SCHEMA = "html-js-gaming.game-asset-catalog";
 const GAME_ASSET_CATALOG_VERSION = 1;
 const GAME_MANIFEST_SCHEMA = "html-js-gaming.game-manifest";
@@ -9,10 +11,6 @@ function normalizeGameId(value) {
   return typeof value === "string" ? value.trim().toLowerCase() : "";
 }
 
-function toObject(value) {
-  return value && typeof value === "object" ? value : {};
-}
-
 function normalizeCatalogPath(value) {
   const raw = typeof value === "string" ? value.trim() : "";
   if (!raw) {
diff --git a/games/shared/workspaceGameBoot.js b/games/shared/workspaceGameBoot.js
@@ -1,10 +1,7 @@
 import { enforceWorkspaceGameLaunch } from "/games/shared/workspaceGameLaunchGuard.js";
 import { hydrateWorkspaceGameRuntime } from "/games/shared/workspaceGameRuntimeHydrator.js";
 import { hydrateWorkspaceGameMetadata } from "/games/shared/workspaceGameMetadataHydrator.js";
-
-function normalizeGameId(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { normalizeGameId } from "../../src/shared/string/index.js";
 
 export function bootWorkspaceGame(gameId) {
   const normalizedGameId = normalizeGameId(gameId);
diff --git a/games/shared/workspaceGameLaunchGuard.js b/games/shared/workspaceGameLaunchGuard.js
@@ -1,8 +1,5 @@
 import { readToolHostSharedContextFromLocation } from "/tools/shared/toolHostSharedContext.js";
-
-function normalizeGameId(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { normalizeGameId } from "../../src/shared/string/index.js";
 
 function resolveWorkspaceHostedContext(normalizedGameId) {
   const url = new URL(window.location.href);
diff --git a/games/shared/workspaceGameMetadataHydrator.js b/games/shared/workspaceGameMetadataHydrator.js
@@ -1,15 +1,9 @@
+import { normalizeText, normalizeToken } from "../../src/shared/string/index.js";
+
 const GAMES_METADATA_PATH = "/games/metadata/games.index.metadata.json";
 
 let gamesMetadataPromise = null;
 
-function normalizeText(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizeToken(value) {
-  return normalizeText(value).toLowerCase();
-}
-
 function whenDocumentReady(documentRef, callback) {
   if (!documentRef) {
     return;
diff --git a/games/shared/workspaceGameRuntimeHydrator.js b/games/shared/workspaceGameRuntimeHydrator.js
@@ -1,9 +1,6 @@
 import { getWorkspaceGameRuntimeContext } from "/games/shared/workspaceGameRuntimeContext.js";
 import { primeWorkspaceGameAssetCatalog } from "/games/shared/workspaceGameAssetCatalog.js";
-
-function normalizeGameId(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { normalizeGameId } from "../../src/shared/string/index.js";
 
 export function hydrateWorkspaceGameRuntime(gameId) {
   const expectedGameId = normalizeGameId(gameId);
diff --git a/src/engine/debug/standard/threeD/shared/threeDDebugUtils.js b/src/engine/debug/standard/threeD/shared/threeDDebugUtils.js
@@ -5,9 +5,9 @@ David Quesenberry
 threeDDebugUtils.js
 */
 
-export function sanitizeText(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
+import { sanitizeText } from "../../../../../shared/string/index.js";
+
+export { sanitizeText };
 
 export function asObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value)
diff --git a/src/engine/rendering/WorldScreenTransformService.js b/src/engine/rendering/WorldScreenTransformService.js
@@ -1,3 +1,4 @@
+import { asPositiveInteger } from "../../shared/number/index.js";
 import { rotationRadians } from "./OrientationTransform.js";
 
 export const CANONICAL_WORLD_TO_SCREEN_SCALE = 1;
@@ -7,11 +8,6 @@ function finiteNumber(value, fallback = 0) {
   return Number.isFinite(number) ? number : fallback;
 }
 
-function positiveInteger(value, fallback = 1) {
-  const number = Math.floor(Number(value));
-  return Number.isFinite(number) && number > 0 ? number : fallback;
-}
-
 function positiveScale(value, fallback = 1) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? number : fallback;
@@ -24,8 +20,8 @@ export class WorldScreenTransformService {
     userZoom = 1,
     worldScale = CANONICAL_WORLD_TO_SCREEN_SCALE
   } = {}) {
-    this.screenHeight = positiveInteger(screenHeight);
-    this.screenWidth = positiveInteger(screenWidth);
+    this.screenHeight = asPositiveInteger(screenHeight);
+    this.screenWidth = asPositiveInteger(screenWidth);
     this.userZoom = positiveScale(userZoom);
     this.worldScale = positiveScale(worldScale, CANONICAL_WORLD_TO_SCREEN_SCALE);
     this.center = Object.freeze({
diff --git a/src/engine/runtime/gameImageConvention.js b/src/engine/runtime/gameImageConvention.js
@@ -1,11 +1,9 @@
+import { toObject } from "../../shared/utils/objectUtils.js";
+
 function safeText(value, fallback = "") {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
 
-function toObject(value) {
-  return value && typeof value === "object" ? value : {};
-}
-
 function normalizePath(value) {
   return safeText(value, "").replace(/\\/g, "/");
 }
diff --git a/src/shared/string/index.js b/src/shared/string/index.js
diff --git a/src/shared/string/stringHelpers.js b/src/shared/string/stringHelpers.js
diff --git a/src/shared/utils/index.js b/src/shared/utils/index.js
diff --git a/src/shared/utils/objectUtils.js b/src/shared/utils/objectUtils.js
diff --git a/src/tools/common/GameManifestLoader.js b/src/tools/common/GameManifestLoader.js
diff --git a/tools/palette-manager-v2/modules/paletteUtils.js b/tools/palette-manager-v2/modules/paletteUtils.js
diff --git a/tools/shared/paletteDocumentContract.js b/tools/shared/paletteDocumentContract.js
diff --git a/tools/shared/pipeline/runtimeAssetLookup.js b/tools/shared/pipeline/runtimeAssetLookup.js
diff --git a/tools/shared/toolLaunchSSoTData.js b/tools/shared/toolLaunchSSoTData.js
