BUILD PR: centralize safeNormalize across exact AITargetDummy batch.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,11 +1,10 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_38_CODE_TO_LETTER_HIGHSCORE_BATCH.md exactly.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_39_SAFE_NORMALIZE_AITARGETDUMMY_BATCH.md exactly.
 Edit only these files:
-- src/shared/utils/initialsEntryUtils.js (new file)
-- games/Asteroids/systems/AsteroidsInitialsEntry.js
-- games/SpaceDuel/game/SpaceDuelInitialsEntry.js
-- games/SpaceInvaders/game/SpaceInvadersInitialsEntry.js
+- src/shared/math/vectorNormalizeUtils.js (new file)
+- games/AITargetDummy/game/AITargetDummyController.js
+- games/AITargetDummy/game/AITargetDummyWorld.js
 Do not expand scope.
-Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_38_CODE_TO_LETTER_HIGHSCORE_BATCH_delta.zip
+Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_39_SAFE_NORMALIZE_AITARGETDUMMY_BATCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: centralize codeToLetter across exact initials-entry batch.
+BUILD PR: centralize safeNormalize across exact AITargetDummy batch.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: continue duplicate-family extraction from the provided duplicate report.
+Next: run BUILD_PR_SHARED_EXTRACTION_40_CLONE_SNAPSHOT_NETWORK_SAMPLE_C_BATCH after this batch.

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Execution-grade batch for codeToLetter using the exact duplicate-report file list.
+Rebuilt 39 as an execution-grade batch using the exact duplicate-report file list for safeNormalize(x, y).

docs/dev/reports/validation_checklist.txt

@@ -1 +1 @@
-Exact file list present; one PR purpose only; no guessing.
+Exact file list present; exact helper list present; one PR purpose only.

docs/pr/BUILD_PR_SHARED_EXTRACTION_39_SAFE_NORMALIZE_AITARGETDUMMY_BATCH.md

@@ -0,0 +1,94 @@
+# BUILD_PR_SHARED_EXTRACTION_39_SAFE_NORMALIZE_AITARGETDUMMY_BATCH
+
+## Purpose
+Centralize duplicated `safeNormalize(x, y)` implementations across the exact AITargetDummy batch identified in the duplicate report.
+
+## Single PR Purpose
+Normalize ONLY this helper:
+
+- `safeNormalize(x, y)`
+
+## Exact Files Allowed
+
+### New shared file
+1. `src/shared/math/vectorNormalizeUtils.js`
+
+### Consumer files
+2. `games/AITargetDummy/game/AITargetDummyController.js`
+3. `games/AITargetDummy/game/AITargetDummyWorld.js`
+
+Do not edit any other file.
+
+## Source of Truth
+This exact scope comes from the provided duplicate report entry for:
+
+`function safeNormalize(x, y)`
+
+Only the 2 listed consumer files are in scope.
+
+## Exact Shared Helper Creation
+Create:
+
+`src/shared/math/vectorNormalizeUtils.js`
+
+Export exactly:
+
+```js
+export function safeNormalize(x, y) {
+  // copy one existing implementation exactly
+}
+```
+
+Implementation rules:
+- use ONE existing local implementation as source-of-truth
+- do NOT merge logic
+- do NOT generalize behavior
+- preserve the function signature exactly:
+  - `safeNormalize(x, y)`
+
+## Exact Consumer Changes
+For each of the 2 listed consumer files:
+
+If the file contains a local function definition matching:
+```js
+function safeNormalize(x, y)
+```
+then:
+- remove the local `safeNormalize(x, y)` function definition
+- import `safeNormalize` from the correct relative path to:
+  - `src/shared/math/vectorNormalizeUtils.js`
+- if the file already imports from that module, add `safeNormalize` with the minimum safe edit
+- do not duplicate imports
+- do not touch unrelated helpers
+- do not change logic
+
+If a listed file already imports and uses shared `safeNormalize`, leave it unchanged.
+
+## Relative Import Rule
+Use the correct relative path from each consumer file to:
+
+`src/shared/math/vectorNormalizeUtils.js`
+
+Do not use aliases.
+Do not change `.js` extension usage.
+
+## Hard Constraints
+- no engine changes
+- no game files outside the 2 listed consumers
+- no sample files
+- no repo-wide normalize/vector helper cleanup
+- no behavior changes
+- keep one PR purpose only
+
+## Validation Checklist
+1. Confirm no more than the 3 listed files changed
+2. Confirm `src/shared/math/vectorNormalizeUtils.js` exists and exports `safeNormalize`
+3. Confirm local `function safeNormalize(x, y)` definitions no longer exist in changed listed consumer files
+4. Confirm changed consumer files import `safeNormalize` from the correct relative path to `src/shared/math/vectorNormalizeUtils.js`
+5. Confirm no unrelated engine, game, or sample files changed
+6. Confirm no behavior changes were made
+
+## Non-Goals
+- no cleanup of other vector/math helpers
+- no cleanup outside the 2 listed consumer files
+- no refactor beyond this exact duplicate-removal batch

games/AITargetDummy/game/AITargetDummyController.js

@@ -7,14 +7,7 @@ AITargetDummyController.js
 import AITargetDummyConfig from './AITargetDummyConfig.js';
 import AITargetDummyStateMachine from './AITargetDummyStateMachine.js';
 import { clamp } from '../../../src/engine/utils/math.js';
-
-function safeNormalize(x, y) {
-  const length = Math.hypot(x, y);
-  if (length <= 1e-6) {
-    return { x: 0, y: 0, length: 0 };
-  }
-  return { x: x / length, y: y / length, length };
-}
+import { safeNormalize } from '../../../src/shared/math/vectorNormalizeUtils.js';
 
 export default class AITargetDummyController {
   constructor({ config = AITargetDummyConfig } = {}) {

games/AITargetDummy/game/AITargetDummyWorld.js

@@ -7,17 +7,10 @@ AITargetDummyWorld.js
 import AITargetDummyConfig from './AITargetDummyConfig.js';
 import AITargetDummyController from './AITargetDummyController.js';
 import { clamp } from '../../../src/engine/utils/math.js';
+import { safeNormalize } from '../../../src/shared/math/vectorNormalizeUtils.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 
-function safeNormalize(x, y) {
-  const length = Math.hypot(x, y);
-  if (length <= 1e-6) {
-    return { x: 0, y: 0, length: 0 };
-  }
-  return { x: x / length, y: y / length, length };
-}
-
 export default class AITargetDummyWorld {
   constructor({ width = 960, height = 720, config = AITargetDummyConfig } = {}) {
     this.width = width;

src/shared/math/vectorNormalizeUtils.js

@@ -0,0 +1,7 @@
+export function safeNormalize(x, y) {
+  const length = Math.hypot(x, y);
+  if (length <= 1e-6) {
+    return { x: 0, y: 0, length: 0 };
+  }
+  return { x: x / length, y: y / length, length };
+}