Continue Phase 3 shared utility duplicate cleanup - PR_26140_034-shared-utils-phase-3

Author: DavidQ

docs/dev/reports/PR_26140_034-shared-utils-phase-3_report.md

@@ -0,0 +1,66 @@
+# PR_26140_034-shared-utils-phase-3 Report
+
+## Scope
+- Continued Phase 3 shared utility cleanup from PR_26140_033.
+- Extracted only behavior-identical helpers and switched local duplicates to shared imports.
+- Did not change gameplay logic, schema behavior, manifest contracts, generated/vendor/archive files, or report snapshots.
+
+## Implementation Summary
+- Added shared `normalizePathSeparators` to `src/shared/string/stringHelpers.js` and exported it through shared string/utils indexes.
+- Replaced behavior-identical local text helpers with shared `normalizeText` and `sanitizeText` imports across active game/tool/shared modules.
+- Replaced array-rejecting object helpers with shared `asObject`; replaced array-allowing pipeline helpers with shared `toObject` where semantics matched.
+- Replaced duplicated finite number helpers with shared `toFiniteNumber` or `asFiniteNumber` in runtime, games, and Collision Inspector V2.
+- Kept local helpers where semantics differ, including path helpers with slash-collapse/fallback differences and geometry point helpers with invalid-point/rounding differences.
+
+## Duplicate Scanner Results
+Source: `tools/shared/powerShell/find_dupes_called.ps1`, refreshed to `tmp/dupes_called.txt`.
+
+| Candidate | Before Phase 3 | After Phase 3 | Notes |
+| --- | ---: | ---: | --- |
+| `sanitizeText` | 38 | 8 | Remaining hits are samples and an old report snapshot, out of PR scope. |
+| `normalizeText` | 11 | 4 | Remaining active hits differ by lowercase semantics or deprecated tool scope; samples are out of scope. |
+| `normalizePath` | 4 | 2 | Remaining active helpers differ by fallback, trimming, or slash-collapse behavior. |
+| `asObject` | 8 | 2 | Remaining duplicate includes sample runtime plus shared utility. |
+| `toFiniteNumber` | 4 | 0 | Consolidated. |
+| `numberValue` | 2 | 0 | Consolidated active engine/tool numeric helpers; unrelated DOM-specific helper remains outside matched duplicate line. |
+| `normalizePoint` | 2 | 2 | Kept local because invalid point handling differs. |
+| `normalizePoints` | 2 | 2 | Kept local because filtering/rounding semantics differ. |
+| `toObject` | 2 | 2 | Remaining duplicate includes old report snapshot plus shared utility. |
+| `node_modules` paths | not found | not found | Scanner output stayed focused away from dependency tree. |
+
+## Remaining Repo-Owned Candidates
+- `src/engine/runtime/fullscreenBezel.js` and `tools/preview-generator-v2/PreviewGeneratorV2RepoAccess.js` both contain `normalizePath`, but they do not have identical behavior.
+- `tools/shared/assetPipelineConverters.js` has a path normalizer built around `normalizeProjectRelativePath` and fallback behavior, so it was left local.
+- `tools/asset-manager-v2/js/assetPreviewHelpers.js` has `normalizeText` with lowercase semantics, so it was not merged into the trim-only helper.
+- `src/engine/collision/objectVector.js` and `tools/shared/vector/vectorAssetContract.js` keep separate `normalizePoint(s)` helpers because invalid point and precision behavior differ.
+- Sample-phase helpers and old report snapshots are intentionally out of scope for this PR.
+
+## 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/CollisionInspectorV2.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: `tools/shared/powerShell/find_dupes_called.ps1` rerun and summarized above.
+- PASS: `git diff --check` (only existing CRLF normalization warnings reported; no whitespace errors).
+
+## Playwright Impact
+Playwright impacted: Yes. Shared runtime/tool JavaScript imports changed, so Workspace Manager V2, Object Vector Studio V2, Collision Inspector V2, and Asteroids gameplay smoke were validated.
+
+## Coverage
+- Produced advisory Playwright V8 coverage artifacts at `docs/dev/reports/playwright_v8_coverage_report.txt` and `docs/dev/reports/coverage_changed_js_guardrail.txt`.
+- Missing changed runtime JS coverage is reported as WARN per project rules, not FAIL.
+
+## Full Samples Smoke
+Skipped. This PR is a scoped utility extraction with targeted Workspace, Asteroids, Object Vector Studio V2, and Collision Inspector V2 validation; it does not broadly change the sample loader/framework.
+
+## Manual Validation Notes
+1. Open Workspace Manager V2 and confirm repo selection still populates games/tools.
+2. Launch Object Vector Studio V2 and Collision Inspector V2 from Workspace Manager V2.
+3. Launch Asteroids and confirm normal gameplay render/collision behavior.
+4. Review `tmp/dupes_called.txt` for remaining out-of-scope duplicate candidates listed above.

games/SolarSystem/game/SolarSystemWorld.js

@@ -5,6 +5,7 @@ David Quesenberry
 SolarSystemWorld.js
 */
 import { toObject } from '/src/shared/utils/objectUtils.js';
+import { toFiniteNumber } from '/src/shared/number/index.js';
 
 const MAX_STEP_SECONDS = 1 / 60;
 
@@ -86,11 +87,6 @@ function clampIndex(value, max) {
   return Math.max(0, Math.min(max, value));
 }
 
-function toFiniteNumber(value, fallback) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
 function sanitizeSolarWorldSkin(skin) {
   const entities = toObject(skin?.entities);
   const sun = toObject(entities.sun);

games/bouncing-ball/game/BouncingBallWorld.js

@@ -6,6 +6,7 @@ BouncingBallWorld.js
 */
 import { clamp } from '/src/shared/utils/mathUtils.js';
 import { toObject } from '/src/shared/utils/objectUtils.js';
+import { toFiniteNumber } from '/src/shared/number/index.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 const DEFAULT_BOUNCING_BALL_WORLD_SKIN = Object.freeze({
@@ -18,11 +19,6 @@ const DEFAULT_BOUNCING_BALL_WORLD_SKIN = Object.freeze({
   }
 });
 
-function toFiniteNumber(value, fallback) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
 function sanitizeBouncingBallWorldSkin(skin) {
   const colors = toObject(skin?.colors);
   const sizing = toObject(skin?.sizing);

games/breakout/game/BreakoutWorld.js

@@ -6,6 +6,7 @@ BreakoutWorld.js
 */
 import { clamp } from '/src/shared/utils/mathUtils.js';
 import { toObject } from '/src/shared/utils/objectUtils.js';
+import { toFiniteNumber } from '/src/shared/number/index.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 
@@ -34,11 +35,6 @@ const DEFAULT_BREAKOUT_SKIN = Object.freeze({
   }
 });
 
-function toFiniteNumber(value, fallback) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
 function sanitizeBreakoutWorldSkin(value) {
   const source = toObject(value);
   const colors = toObject(source.colors);

games/pong/game/PongScene.js

@@ -10,6 +10,7 @@ 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';
+import { toFiniteNumber } from '/src/shared/number/index.js';
 
 const COURT = {
   width: 960,
@@ -37,11 +38,6 @@ const DEFAULT_SIZING = {
   ballRadius: 8
 };
 
-function toFiniteNumber(value, fallback) {
-  const numeric = Number(value);
-  return Number.isFinite(numeric) ? numeric : fallback;
-}
-
 function sanitizePongSkin(skin) {
   const colors = toObject(skin?.colors);
   const sizing = toObject(skin?.sizing);

games/shared/gameManifestPreviewResolver.js

@@ -2,23 +2,13 @@ import {
   resolveManifestChromeAssetPaths,
   resolveRuntimeAssetUrl
 } from "/src/engine/runtime/gameImageConvention.js";
-
-function normalizeText(value) {
-  return typeof value === "string" ? value.trim() : "";
-}
-
-function normalizePath(value) {
-  return normalizeText(value).replace(/\\/g, "/");
-}
+import { normalizePathSeparators, normalizeText } from "../../src/shared/string/index.js";
+import { asArray } from "../../src/shared/utils/arrayUtils.js";
 
 function hasProtocol(value) {
   return /^[a-z][a-z0-9+.-]*:/i.test(value);
 }
 
-function asArray(value) {
-  return Array.isArray(value) ? value : [];
-}
-
 function documentRefOrNull(documentRef) {
   return documentRef || globalThis.document || null;
 }
@@ -33,7 +23,7 @@ async function waitForDocumentReady(documentRef) {
 }
 
 export function manifestPathFromGameHref(href) {
-  const normalized = normalizePath(href);
+  const normalized = normalizePathSeparators(href);
   if (!normalized || hasProtocol(normalized) || normalized.includes("..")) {
     return "";
   }
@@ -42,7 +32,7 @@ export function manifestPathFromGameHref(href) {
 }
 
 export function manifestPathForGame(game) {
-  const explicitPath = normalizePath(game?.manifestPath || game?.gameManifestPath);
+  const explicitPath = normalizePathSeparators(game?.manifestPath || game?.gameManifestPath);
   if (explicitPath && !hasProtocol(explicitPath) && !explicitPath.startsWith("//") && !explicitPath.includes("..")) {
     return explicitPath.startsWith("/") ? explicitPath : `/${explicitPath}`;
   }
@@ -51,7 +41,7 @@ export function manifestPathForGame(game) {
 
 export async function resolveGameManifestPreview(options = {}) {
   const documentRef = documentRefOrNull(options.documentRef);
-  const manifestPath = normalizePath(options.manifestPath);
+  const manifestPath = normalizePathSeparators(options.manifestPath);
   if (!manifestPath) {
     return {
       manifestPath: "",
@@ -65,7 +55,7 @@ export async function resolveGameManifestPreview(options = {}) {
     manifestPayload: options.manifestPayload,
     documentRef
   });
-  const previewPath = normalizePath(resolved.previewPath);
+  const previewPath = normalizePathSeparators(resolved.previewPath);
   return {
     manifestPath: resolved.manifestPath || manifestPath,
     previewPath,
@@ -112,7 +102,7 @@ export async function hydrateGameManifestPreviewImage(options = {}) {
   const gameId = normalizeText(options.gameId);
   const resolved = await resolveGameManifestPreview({
     gameId,
-    manifestPath: normalizePath(options.manifestPath) || (gameId ? `/games/${gameId}/game.manifest.json` : ""),
+    manifestPath: normalizePathSeparators(options.manifestPath) || (gameId ? `/games/${gameId}/game.manifest.json` : ""),
     documentRef
   });
   if (resolved.previewUrl) {

src/engine/collision/objectVector.js

@@ -15,6 +15,7 @@ import {
 } from '../rendering/OrientationTransform.js';
 import { isRecord } from '../../shared/types/typeGuards.js';
 import { deepClone as clone } from '../../shared/utils/jsonUtils.js';
+import { asFiniteNumber } from '../../shared/number/index.js';
 
 export const OBJECT_VECTOR_COLLISION_ENGINE_PATH = 'src/engine/collision/objectVector.js';
 export const OBJECT_VECTOR_COLLISION_MODES = Object.freeze(['bounds', 'vector', 'pixel-sprite', 'hybrid']);
@@ -32,15 +33,10 @@ const MODE_ALIASES = Object.freeze({
 const POLYGON_SAMPLE_COUNT = 28;
 const DEFAULT_MASK_CELL_SIZE = 4;
 
-function numberValue(value, fallback = 0) {
-  const parsed = Number(value);
-  return Number.isNaN(parsed) || Math.abs(parsed) === Infinity ? fallback : parsed;
-}
-
 function normalizePoint(point) {
   return {
-    x: numberValue(point?.x),
-    y: numberValue(point?.y),
+    x: asFiniteNumber(point?.x),
+    y: asFiniteNumber(point?.y),
   };
 }
 
@@ -63,12 +59,12 @@ function shapeTool(shape) {
 
 function sortedShapes(object) {
   return [...(Array.isArray(object?.shapes) ? object.shapes : [])]
-    .sort((left, right) => numberValue(left?.order) - numberValue(right?.order));
+    .sort((left, right) => asFiniteNumber(left?.order) - asFiniteNumber(right?.order));
 }
 
 function sortedFrames(state) {
   return [...(Array.isArray(state?.frames) ? state.frames : [])]
-    .sort((left, right) => numberValue(left?.order) - numberValue(right?.order));
+    .sort((left, right) => asFiniteNumber(left?.order) - asFiniteNumber(right?.order));
 }
 
 function firstObjectFrame(object, preferredStateIds = ['active', 'idle']) {
@@ -154,31 +150,31 @@ function shapeLocalPolygons(shape) {
   const geometry = isRecord(shape?.geometry) ? shape.geometry : {};
   const tool = shapeTool(shape);
   if (tool === 'rectangle') {
-    return [rectanglePoints(numberValue(geometry.x), numberValue(geometry.y), numberValue(geometry.width, 1), numberValue(geometry.height, 1))];
+    return [rectanglePoints(asFiniteNumber(geometry.x), asFiniteNumber(geometry.y), asFiniteNumber(geometry.width, 1), asFiniteNumber(geometry.height, 1))];
   }
   if (tool === 'polygon') {
     const points = normalizePoints(geometry.points);
     return points.length >= 3 ? [points] : [];
   }
   if (tool === 'polyline') {
     const points = normalizePoints(geometry.points);
-    const strokeWidth = Math.max(2, numberValue(shape?.style?.strokeWidth, 2));
+    const strokeWidth = Math.max(2, asFiniteNumber(shape?.style?.strokeWidth, 2));
     return points.slice(1).map((point, index) => segmentPolygon(points[index], point, strokeWidth));
   }
   if (tool === 'line') {
-    const strokeWidth = Math.max(2, numberValue(shape?.style?.strokeWidth, 2));
+    const strokeWidth = Math.max(2, asFiniteNumber(shape?.style?.strokeWidth, 2));
     return [segmentPolygon(
       normalizePoint(geometry.point1),
       normalizePoint(geometry.point2),
       strokeWidth
     )];
   }
   if (tool === 'circle') {
-    const radius = Math.max(1, numberValue(geometry.r, 1));
-    return [ellipsePoints(numberValue(geometry.cx), numberValue(geometry.cy), radius, radius)];
+    const radius = Math.max(1, asFiniteNumber(geometry.r, 1));
+    return [ellipsePoints(asFiniteNumber(geometry.cx), asFiniteNumber(geometry.cy), radius, radius)];
   }
   if (tool === 'ellipse') {
-    return [ellipsePoints(numberValue(geometry.cx), numberValue(geometry.cy), Math.max(1, numberValue(geometry.rx, 1)), Math.max(1, numberValue(geometry.ry, 1)))];
+    return [ellipsePoints(asFiniteNumber(geometry.cx), asFiniteNumber(geometry.cy), Math.max(1, asFiniteNumber(geometry.rx, 1)), Math.max(1, asFiniteNumber(geometry.ry, 1)))];
   }
   return [];
 }
@@ -285,7 +281,7 @@ export function createObjectVectorCollisionGeometry(object, instance = {}, optio
         .filter((polygon) => polygon.length >= 3);
     });
   const bounds = boundsFromPolygons(polygons);
-  const maskCellSize = Math.max(1, numberValue(options.maskCellSize, DEFAULT_MASK_CELL_SIZE));
+  const maskCellSize = Math.max(1, asFiniteNumber(options.maskCellSize, DEFAULT_MASK_CELL_SIZE));
   return {
     bounds,
     hasGeometry: polygons.length > 0,

src/engine/debug/network/shared/hostReadUtils.js

@@ -1,8 +1,4 @@
-function asObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? value
-    : {};
-}
+import { asObject } from "../../../../shared/utils/objectUtils.js";
 
 export function readHostStatus(host) {
   return host && typeof host.getStatus === "function"

src/engine/debug/panels/PromotionGatePanel.js

@@ -6,12 +6,7 @@ PromotionGatePanel.js
 */
 
 import { drawPanel } from '../DebugPanel.js';
-
-function asObject(value) {
-  return value && typeof value === 'object' && !Array.isArray(value) 
-  ? value 
-  : {};
-}
+import { asObject } from '../../../shared/utils/objectUtils.js';
 
 function resolvePromotionStatus(source) {
   const snapshot = asObject(source);

src/engine/debug/standard/threeD/shared/threeDDebugUtils.js

@@ -6,14 +6,9 @@ threeDDebugUtils.js
 */
 
 import { sanitizeText } from "../../../../../shared/string/index.js";
+import { asObject } from "../../../../../shared/utils/objectUtils.js";
 
-export { sanitizeText };
-
-export function asObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? value
-    : {};
-}
+export { asObject, sanitizeText };
 
 export function asArray(value) {
   return Array.isArray(value) ? value : [];