Continue Phase 4 shared utility normalization and duplicate cleanup - PR_26140_035-shared-utils-phase-4-finalization

Author: DavidQ

docs/dev/reports/PR_26140_035-shared-utils-phase-4-finalization_report.md

@@ -0,0 +1,74 @@
+# PR_26140_035 Shared Utils Phase 4 Finalization Report
+
+## Scope
+- Continued shared utility normalization cleanup from PR_26140_034.
+- Migrated only behavior-identical active helper implementations to shared utility modules.
+- Kept gameplay, schema behavior, manifest contracts, and public APIs intact.
+- Did not touch node_modules, tests/results, docs/dev/report snapshots, archived tools, generated bundles, or broad formatting-only files in the final content diff.
+
+## Implementation Summary
+- Reused shared `asArray` in `games/index.render.js`, tool pipeline helpers, `debugInspectorData`, and 3D debug utilities.
+- Reused shared object/record guards in active tool validators/loaders where local semantics matched non-array object checks.
+- Preserved stricter prototype-based `isPlainObject` checks in network contracts because their semantics differ.
+- Reused shared JSON `deepClone` for behavior-identical JSON clone wrappers in network, Asset Manager V2, Text to Speech V2, Workspace Manager V2, and Settings System code.
+- Reused shared finite-number coercion in 3D physics helpers.
+- Added shared `near(a, b, epsilon = 0.5)` and routed Pacman AI callers through it.
+- Re-exported Asteroids `randomRange` from the shared math utility while preserving its public game utility API.
+- Re-exported `isRecord` from the shared type guard in `GameManifestLoader` while preserving its public export.
+
+## Duplicate Scanner Results
+Source: `tools/shared/powerShell/find_dupes_called.ps1`, refreshed to `tmp/dupes_called.txt`.
+
+| Candidate | PR034 Count | PR035 Count | Notes |
+| --- | ---: | ---: | --- |
+| `function isPlainObject(value)` | 14 | 6 | Remaining active engine copies use stricter prototype checks; archive/sample hits are out of scope. |
+| `function asArray(value)` | 7 | 2 | Remaining hit is sample plus shared helper. |
+| `export function asArray(value)` | 2 | 0 | 3D debug utility now reuses shared export. |
+| `function clone(value)` | 19 | 2 | Remaining clones are Vector Map Editor files, left out because that tool is deprecated/out of scope. |
+| `function toFinite(value...)` | 3 | 0 | Consolidated active 3D physics helpers. |
+| `function near(a, b, epsilon = 0.5)` | 2 | 0 | Consolidated Pacman AI helpers into shared math. |
+| `export function asFinite(value, fallback = 0)` | 2 | 0 | 3D debug utility now reuses shared export. |
+| `function normalizeText(value)` | 4 | 4 | Remaining active helper lowercases or sits in stale/non-V2 tool scope; sample hits out of scope. |
+| `function normalizePath(value)` | 2 | 2 | Remaining helpers differ by fallback/trimming/slash-collapse behavior. |
+| `function normalizePoint(point)` | 2 | 2 | Kept local because invalid point handling differs. |
+| `function normalizePoints(points)` | 2 | 2 | Kept local because filtering/rounding semantics differ. |
+| `function toObject(value)` | 2 | 2 | Remaining duplicate includes old report snapshot plus shared utility. |
+| `node_modules` paths | not found | not found | Scanner stayed focused away from dependency tree. |
+
+## Remaining Repo-Owned Candidates
+- `src/engine/network/*Contract.js` strict `isPlainObject` helpers intentionally require `Object.getPrototypeOf(value) === Object.prototype`; shared non-array object guards would broaden accepted inputs.
+- `src/engine/runtime/fullscreenBezel.js` and `tools/preview-generator-v2/PreviewGeneratorV2RepoAccess.js` path helpers differ in coercion and slash normalization semantics.
+- `src/engine/collision/objectVector.js` and `tools/shared/vector/vectorAssetContract.js` point helpers differ in invalid point handling and precision behavior.
+- `src/engine/rendering/ObjectVectorRuntimeAssetService.js` and Object Vector Studio V2 shape helpers look similar but have different triangle/square normalization responsibilities.
+- Vector Map Editor clone helpers remain because the tool is deprecated/out of PR scope.
+- Sample-phase and report snapshot duplicates remain out of scope by request.
+
+## 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: duplicate scanner rerun and summarized above.
+- PASS: `git diff --check` (CRLF normalization warnings only; no whitespace errors).
+
+## Playwright Impact
+Playwright impacted: Yes. Shared runtime/tool imports changed across Workspace Manager V2, Object Vector Studio V2, Collision Inspector V2, and game/runtime code paths. Expected pass behavior is unchanged tool launch/load/collision/render behavior. Expected fail behavior would be import errors, page errors, failed tool launch, or schema/load regressions; none appeared in the final passing runs.
+
+## Coverage
+- Advisory Playwright V8 coverage artifacts were refreshed 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/refactor and was covered by 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, select the repo, and confirm game/tool loading still works.
+2. Launch Object Vector Studio V2 and Collision Inspector V2 from Workspace Manager V2.
+3. Launch Asteroids and confirm normal gameplay smoke behavior.
+4. Review `tmp/dupes_called.txt` for remaining out-of-scope duplicate helper candidates.

games/Asteroids/utils/math.js

@@ -4,14 +4,12 @@ David Quesenberry
 03/22/2026
 math.js
 */
-import { randomRange as sharedRandomRange, wrap as sharedWrap } from '../../../src/shared/utils/mathUtils.js';
+import { wrap as sharedWrap } from '../../../src/shared/utils/mathUtils.js';
+
+export { randomRange } from '../../../src/shared/utils/mathUtils.js';
 
 export const TAU = Math.PI * 2;
 
 export function wrap(value, max) {
   return sharedWrap(value, 0, max);
 }
-
-export function randomRange(min, max, rng = Math.random) {
-  return sharedRandomRange(min, max, rng);
-}

games/Pacman/game/PacmanFullAIGhostController.js

@@ -4,13 +4,11 @@ David Quesenberry
 03/25/2026
 PacmanFullAIGhostController.js
 */
+
+import { near } from '/src/shared/utils/mathUtils.js';
 import { chooseDirectionTowardTarget, DIRS, opposite } from './PacmanFullAINavigator.js';
 import { computeTargetTile } from './PacmanFullAITargeting.js';
 
-function near(a, b, epsilon = 0.5) {
-  return Math.abs(a - b) <= epsilon;
-}
-
 function speedForGhost(cfg, mode, ghost, tileX, tileY) {
   if (ghost.eaten) return cfg.ghostSpeedEaten;
   if (mode === 'frightened') return cfg.ghostSpeedFrightened;

games/Pacman/game/PacmanFullAIWorld.js

@@ -4,6 +4,8 @@ David Quesenberry
 03/25/2026
 PacmanFullAIWorld.js
 */
+
+import { near } from '/src/shared/utils/mathUtils.js';
 import PacmanFullAIConfig from './PacmanFullAIConfig.js';
 import PacmanFullAIGhostController from './PacmanFullAIGhostController.js';
 import PacmanFullAIGhostHouseController from './PacmanFullAIGhostHouseController.js';
@@ -14,10 +16,6 @@ import { oppositeCardinalDirection } from '/src/shared/utils/index.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 
-function near(a, b, epsilon = 0.5) {
-  return Math.abs(a - b) <= epsilon;
-}
-
 function isOppositePair(a, b) {
   return Boolean(a && b && oppositeCardinalDirection(a) === b);
 }

games/index.render.js

@@ -1,3 +1,4 @@
+import { asArray } from '../src/shared/utils/arrayUtils.js';
 import { getToolRegistry } from "../tools/toolRegistry.js";
 import { resolveGamePreviewMap } from "./shared/gameManifestPreviewResolver.js";
 import { normalizeText as normalize, normalizeToken } from "../src/shared/string/index.js";
@@ -52,10 +53,6 @@ function sortLevels(a, b) {
   return left.label.localeCompare(right.label, undefined, { sensitivity: "base" });
 }
 
-function asArray(value) {
-  return Array.isArray(value) ? value : [];
-}
-
 function escapeHtml(value) {
   return String(value)
     .replaceAll("&", "&")

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

@@ -6,17 +6,11 @@ threeDDebugUtils.js
 */
 
 import { sanitizeText } from "../../../../../shared/string/index.js";
+import { asFinite } from "../../../../../shared/math/numberNormalization.js";
+import { asArray } from "../../../../../shared/utils/arrayUtils.js";
 import { asObject } from "../../../../../shared/utils/objectUtils.js";
 
-export { asObject, sanitizeText };
-
-export function asArray(value) {
-  return Array.isArray(value) ? value : [];
-}
-
-export function asFinite(value, fallback = 0) {
-  return Number.isFinite(value) ? Number(value) : fallback;
-}
+export { asArray, asFinite, asObject, sanitizeText };
 
 export function asNonNegativeInteger(value, fallback = 0) {
   const normalized = Number.isFinite(value) ? Math.floor(Number(value)) : fallback;

src/engine/network/bootstrap/NetworkingLayer.js

@@ -4,13 +4,11 @@ David Quesenberry
 03/22/2026
 NetworkingLayer.js
 */
+
+import { deepClone as clone } from '../../../shared/utils/jsonUtils.js';
 import LoopbackTransport from '../transport/LoopbackTransport.js';
 import NetworkConditionSimulator from '../transport/NetworkConditionSimulator.js';
 
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
 export default class NetworkingLayer {
   constructor({
     playerId = 'player',

src/engine/network/client/ClientReplicationApplicationLayer.js

@@ -4,16 +4,14 @@ David Quesenberry
 04/15/2026
 ClientReplicationApplicationLayer.js
 */
+
+import { deepClone as clone } from '../../../shared/utils/jsonUtils.js';
 import ClientReconciliationStrategy, {
   REPLICATION_IGNORE_REASONS,
 } from './ClientReconciliationStrategy.js';
 import ReplicationMessageContract from '../replication/ReplicationMessageContract.js';
 import StateReplication from '../replication/StateReplication.js';
 
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
 export default class ClientReplicationApplicationLayer {
   constructor({
     sessionId = 'session',

src/engine/network/client/PredictionReconciler.js

@@ -4,10 +4,8 @@ David Quesenberry
 03/22/2026
 PredictionReconciler.js
 */
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
 
+import { deepClone as clone } from '../../../shared/utils/jsonUtils.js';
 function distance(a, b) {
   return Math.abs((a?.x ?? 0) - (b?.x ?? 0)) + Math.abs((a?.y ?? 0) - (b?.y ?? 0));
 }

src/engine/network/replication/ReplicationMessageContract.js

@@ -4,6 +4,8 @@ David Quesenberry
 04/15/2026
 ReplicationMessageContract.js
 */
+
+import { deepClone as clone } from '../../../shared/utils/jsonUtils.js';
 export const REPLICATION_SNAPSHOT_TYPES = Object.freeze({
   FULL: 'full',
   DELTA: 'delta',
@@ -29,10 +31,6 @@ const CLIENT_OWNED_METADATA_FIELDS = Object.freeze([
   'pendingEnvelopes',
 ]);
 
-function clone(value) {
-  return JSON.parse(JSON.stringify(value));
-}
-
 function isPlainObject(value) {
   return value !== null
     && typeof value === 'object'