Rewrite remaining engine utils references to shared utils - PR 11.78

Author: DavidQ

docs/archive/pr/legacy-pr-history/BUILD_PR_REPO_CLEANUP_PHASE_1B_ENGINE_BOUNDARY_AND_DUPLICATE_HELPER_SCAN.md

@@ -1,15 +1,15 @@
 # BUILD_PR: REPO_CLEANUP_PHASE_1B_ENGINE_BOUNDARY_AND_DUPLICATE_HELPER_SCAN
 
 ## Execution Summary
-- Docs-first scan completed across `src/engine/utils/**`, `src/engine/ui/**`, `games/**`, `tools/**`, and `samples/**`.
+- Docs-first scan completed across `src/shared/utils/**`, `src/engine/ui/**`, `games/**`, `tools/**`, and `samples/**`.
 - This phase made no runtime/helper consolidation changes.
 - Classification produced candidate groups for immediate low-risk cleanup and deferred manual review.
 
 ## Findings: Already in engine, local duplicate
 | path | responsibility | duplicate of | should be in engine | already in engine | canonical location | risk | recommendation |
 |---|---|---|---|---|---|---|---|
-| `games/Asteroids/utils/math.js` | wraps random/wrap helpers for Asteroids | `src/engine/utils/math.js` (`randomRange`, `wrap`) | no (wrapper can stay local) | yes | `src/engine/utils/math.js` | low | Keep only game-specific surface (`TAU`) or import engine helpers directly in consumers in a follow-up micro-PR. |
-| `games/*/game/*` local `function clamp(...)` cluster | scalar clamp utility repeated in multiple game modules | `src/engine/utils/math.js` (`clamp`) | no | yes | `src/engine/utils/math.js` | medium | Migrate in small batches (one game at a time) to reduce behavior/regression risk. |
+| `games/Asteroids/utils/math.js` | wraps random/wrap helpers for Asteroids | `src/shared/utils/math.js` (`randomRange`, `wrap`) | no (wrapper can stay local) | yes | `src/shared/utils/math.js` | low | Keep only game-specific surface (`TAU`) or import engine helpers directly in consumers in a follow-up micro-PR. |
+| `games/*/game/*` local `function clamp(...)` cluster | scalar clamp utility repeated in multiple game modules | `src/shared/utils/math.js` (`clamp`) | no | yes | `src/shared/utils/math.js` | medium | Migrate in small batches (one game at a time) to reduce behavior/regression risk. |
 | `tools/Vector Map Editor/editor/VectorMapFullscreenController.js` | fullscreen toggle + state sync | `src/engine/runtime/FullscreenService.js` | no | yes | `src/engine/runtime/FullscreenService.js` | low | Replace tool-local controller with engine runtime service adapter. |
 | `tools/Vector Map Editor/editor/VectorMapSerializer.js` + `tools/Vector Map Editor/editor/VectorMapRuntimeExporter.js` | blob download orchestration | `src/engine/runtime/BrowserDownloadService.js` | no | yes | `src/engine/runtime/BrowserDownloadService.js` | low | Route downloads through `BrowserDownloadService` and keep only payload-building logic local. |
 | `samples/_shared/platformerHelpers.js` (`overlap`) | AABB overlap predicate | `src/engine/collision/aabb.js` (`isColliding`) | no | yes | `src/engine/collision/index.js` | low | Import/alias `isColliding` in shared sample helper instead of redefining overlap math. |
@@ -39,9 +39,9 @@
 | path | responsibility | duplicate of | should be in engine | already in engine | canonical location | risk | recommendation |
 |---|---|---|---|---|---|---|---|
 | `games/SpaceInvaders/game/WaveController.js` naming | helper name implies simulation controller but currently HUD/banner presenter | `games/SpaceDuel/game/WaveController.js` (name only) | no | no | likely rename to `WaveHudPresenter`/`WaveStatusPresenter` | low | Rename in a doc-safe or tiny code-safe follow-up with import-site checks. |
-| `tools/SpriteEditor_old_keep/main.js` local `clamp` | overlaps engine clamp but file is a large patch/stabilization entrypoint | `src/engine/utils/math.js` (`clamp`) | uncertain | yes | evaluate per SpriteEditor stability plan | medium | Defer until SpriteEditor stabilization work is complete; avoid mixing concerns. |
-| `samples/sample003-mouse-input/MouseInputScene.js`, `samples/sample004-gamepad-input/GamepadScene.js` class-local clamp methods | duplicates engine clamp, but potentially intentional pedagogy | `src/engine/utils/math.js` (`clamp`) | uncertain | yes | sample-specific decision | low | Keep as-is unless sample docs explicitly prefer engine helper usage. |
-| Target path expectation: `src/engine/math/**` | scan target includes path that does not exist in repo (math lives under `src/engine/utils/math.js`) | N/A | N/A | N/A | `src/engine/utils/math.js` | low | Update future scan templates/docs to avoid path drift. |
+| `tools/SpriteEditor_old_keep/main.js` local `clamp` | overlaps engine clamp but file is a large patch/stabilization entrypoint | `src/shared/utils/math.js` (`clamp`) | uncertain | yes | evaluate per SpriteEditor stability plan | medium | Defer until SpriteEditor stabilization work is complete; avoid mixing concerns. |
+| `samples/sample003-mouse-input/MouseInputScene.js`, `samples/sample004-gamepad-input/GamepadScene.js` class-local clamp methods | duplicates engine clamp, but potentially intentional pedagogy | `src/shared/utils/math.js` (`clamp`) | uncertain | yes | sample-specific decision | low | Keep as-is unless sample docs explicitly prefer engine helper usage. |
+| Target path expectation: `src/engine/math/**` | scan target includes path that does not exist in repo (math lives under `src/shared/utils/math.js`) | N/A | N/A | N/A | `src/shared/utils/math.js` | low | Update future scan templates/docs to avoid path drift. |
 
 ## Explicit File Lists
 
@@ -114,7 +114,7 @@
    - Migrate `Asteroids`, `SpaceDuel`, `SpaceInvaders` services to thin adapters.
 4. `BUILD_PR: REPO_CLEANUP_PHASE_1F_NAMING_AND_TEMPLATE_ALIGNMENT`
    - Resolve `WaveController` naming ambiguity in Space Invaders.
-   - Update cleanup template path expectation from `src/engine/math/**` to `src/engine/utils/math.js`.
+   - Update cleanup template path expectation from `src/engine/math/**` to `src/shared/utils/math.js`.
 
 ## Phase Status
 - Classification and planning complete.

docs/archive/pr/legacy-pr-history/BUILD_PR_REPO_CLEANUP_PHASE_1G_ENGINE_PROMOTION_FROM_STRONG_CANDIDATES.md

@@ -22,7 +22,7 @@ Repo Cleanup Phase 1G - Engine Promotion From Strong Candidates
 - unrelated files outside this BUILD scope
 
 ## Full Repo-Relative Paths (Touched for This BUILD)
-- `src/engine/utils/fuzzyMatchScore.js`
+- `src/shared/utils/fuzzyMatchScore.js`
 - `tools/SpriteEditor_old_keep/shared/scoreCommandItem.js`
 - `tools/SpriteEditor_old_keep/shared/fuzzyMatchScore.js` (removed)
 - `docs/pr/PLAN_PR_REPO_CLEANUP_PHASE_1G_ENGINE_PROMOTION_FROM_STRONG_CANDIDATES.md`
@@ -35,19 +35,19 @@ Repo Cleanup Phase 1G - Engine Promotion From Strong Candidates
 ## Helper Ownership Before/After
 | helper | before owner | after owner | placement justification | behavior change |
 |---|---|---|---|---|
-| `fuzzyMatchScore(text, query)` | `tools/SpriteEditor_old_keep/shared/fuzzyMatchScore.js` | `src/engine/utils/fuzzyMatchScore.js` | Pure text scoring utility with zero UI/state coupling; best fit in engine utilities | none |
+| `fuzzyMatchScore(text, query)` | `tools/SpriteEditor_old_keep/shared/fuzzyMatchScore.js` | `src/shared/utils/fuzzyMatchScore.js` | Pure text scoring utility with zero UI/state coupling; best fit in engine utilities | none |
 
 ## Engine Placement Justification
 - The helper is deterministic and stateless.
 - It has no Sprite Editor data dependency and no UI coupling.
-- `src/engine/utils/` is the appropriate reusable utility domain.
+- `src/shared/utils/` is the appropriate reusable utility domain.
 
 ## Import Update
 - Updated `tools/SpriteEditor_old_keep/shared/scoreCommandItem.js` to import from:
-  - `../../../src/src/engine/utils/fuzzyMatchScore.js`
+  - `../../../src/src/shared/utils/fuzzyMatchScore.js`
 
 ## Validation
-- `node -c src/engine/utils/fuzzyMatchScore.js`
+- `node -c src/shared/utils/fuzzyMatchScore.js`
 - `node -c tools/SpriteEditor_old_keep/shared/scoreCommandItem.js`
 - `node -c tools/SpriteEditor_old_keep/shared/normalizeCommandText.js`
 - `node -c tools/SpriteEditor_old_keep/modules/appCommands.js`

docs/archive/pr/legacy-pr-history/BUILD_PR_REPO_CLEANUP_PHASE_1H_ENGINE_CONSOLIDATION_AND_EXPANSION.md

@@ -22,7 +22,7 @@ Repo Cleanup Phase 1H - Engine Consolidation and Controlled Expansion
 - unrelated files outside this BUILD scope
 
 ## Full Repo-Relative Paths (Touched for This BUILD)
-- `src/engine/utils/normalizeCommandText.js`
+- `src/shared/utils/normalizeCommandText.js`
 - `tools/SpriteEditor_old_keep/modules/appCommands.js`
 - `tools/SpriteEditor_old_keep/shared/scoreCommandItem.js`
 - `tools/SpriteEditor_old_keep/shared/normalizeCommandText.js` (removed)
@@ -36,11 +36,11 @@ Repo Cleanup Phase 1H - Engine Consolidation and Controlled Expansion
 ## Promoted Helpers (This Phase)
 | helper | before owner | after owner | engine domain | behavior change |
 |---|---|---|---|---|
-| `normalizeCommandText(input)` | `tools/SpriteEditor_old_keep/shared/normalizeCommandText.js` | `src/engine/utils/normalizeCommandText.js` | `src/engine/utils` (generic text normalization) | none |
+| `normalizeCommandText(input)` | `tools/SpriteEditor_old_keep/shared/normalizeCommandText.js` | `src/shared/utils/normalizeCommandText.js` | `src/engine/utils` (generic text normalization) | none |
 
 ## Consolidation Notes
 - Existing Phase 1G promotion remains in place:
-  - `src/engine/utils/fuzzyMatchScore.js`
+  - `src/shared/utils/fuzzyMatchScore.js`
 - Command ranking shared helper now depends on engine-owned generic helpers.
 - Sprite Editor module import updated to consume engine utility directly where used.
 
@@ -50,18 +50,18 @@ Repo Cleanup Phase 1H - Engine Consolidation and Controlled Expansion
 ## Updated Helper Inventory Snapshot
 | helper | owner after Phase 1H |
 |---|---|
-| `fuzzyMatchScore` | `src/engine/utils/fuzzyMatchScore.js` |
-| `normalizeCommandText` | `src/engine/utils/normalizeCommandText.js` |
+| `fuzzyMatchScore` | `src/shared/utils/fuzzyMatchScore.js` |
+| `normalizeCommandText` | `src/shared/utils/normalizeCommandText.js` |
 | `scoreCommandItem` | `tools/SpriteEditor_old_keep/shared/scoreCommandItem.js` |
 
 ## Import Updates
 - `tools/SpriteEditor_old_keep/shared/scoreCommandItem.js`
-  - `normalizeCommandText` import -> `../../../src/src/engine/utils/normalizeCommandText.js`
+  - `normalizeCommandText` import -> `../../../src/src/shared/utils/normalizeCommandText.js`
 - `tools/SpriteEditor_old_keep/modules/appCommands.js`
-  - `normalizeCommandText` import -> `../../../src/src/engine/utils/normalizeCommandText.js`
+  - `normalizeCommandText` import -> `../../../src/src/shared/utils/normalizeCommandText.js`
 
 ## Validation
-- `node -c src/engine/utils/normalizeCommandText.js`
+- `node -c src/shared/utils/normalizeCommandText.js`
 - `node -c tools/SpriteEditor_old_keep/shared/scoreCommandItem.js`
 - `node -c tools/SpriteEditor_old_keep/modules/appCommands.js`
 

docs/archive/tools/SpriteEditor_old_keep/modules/appCommands.js

@@ -1,4 +1,4 @@
-import { normalizeCommandText } from "/src/engine/utils/normalizeCommandText.js";
+import { normalizeCommandText } from "/src/shared/utils/normalizeCommandText.js";
 import { scoreCommandItem } from "../shared/scoreCommandItem.js";
 
 function installSpriteEditorCommandMethods(SpriteEditorApp) {

docs/archive/tools/SpriteEditor_old_keep/modules/appPopups.js

@@ -1,4 +1,4 @@
-import { getCenteredRect } from "/src/engine/utils/index.js";
+import { getCenteredRect } from "/src/shared/utils/index.js";
 import {
   createCanvasPopupState,
   dismissCanvasPopup,

docs/archive/tools/SpriteEditor_old_keep/modules/appShell.js

@@ -3,7 +3,7 @@
   MACRO_DEFINITIONS_KEY,
   RECENT_ACTIONS_KEY,
 } from "./constants.js";
-import { pointInRect } from "/src/engine/utils/index.js";
+import { pointInRect } from "/src/shared/utils/index.js";
 
 function installSpriteEditorShellMethods(SpriteEditorApp) {
   Object.assign(SpriteEditorApp.prototype, {

docs/archive/tools/SpriteEditor_old_keep/modules/controlSurfaceCommandPalette.js

@@ -1,5 +1,5 @@
 import { LOGICAL_H, LOGICAL_W } from "./constants.js";
-import { xyInRect } from "/src/engine/utils/index.js";
+import { xyInRect } from "/src/shared/utils/index.js";
 
 function installControlSurfaceCommandPalette(SpriteEditorCanvasControlSurface) {
   SpriteEditorCanvasControlSurface.prototype.toggleFavoriteAt = function toggleFavoriteAt(x, y) {

docs/archive/tools/SpriteEditor_old_keep/modules/controlSurfaceInput.js

@@ -1,4 +1,4 @@
-import { xyInRect } from "/src/engine/utils/index.js";
+import { xyInRect } from "/src/shared/utils/index.js";
 
 function installControlSurfaceInput(SpriteEditorCanvasControlSurface) {
   SpriteEditorCanvasControlSurface.prototype.getControlAt = function getControlAt(x, y) {

docs/archive/tools/SpriteEditor_old_keep/shared/scoreCommandItem.js

@@ -1,5 +1,5 @@
-import { fuzzyMatchScore } from "/src/engine/utils/fuzzyMatchScore.js";
-import { normalizeCommandText } from "/src/engine/utils/normalizeCommandText.js";
+import { fuzzyMatchScore } from "/src/shared/utils/fuzzyMatchScore.js";
+import { normalizeCommandText } from "/src/shared/utils/normalizeCommandText.js";
 
 function scoreCommandItem(item, normalizedQuery) {
   if (!normalizedQuery) return 0;

docs/dev/codex_commands.md

@@ -1,18 +1,8 @@
-# Codex Commands — PR 11.76
+# Codex command - PR 11.78
 
 Model: GPT-5.4
-Reasoning: high
+Reasoning: medium
 
-```powershell
-codex exec --model gpt-5.4 --reasoning high "Apply PR 11.76. Move all utility files from src/engine/utils to src/shared/utils unless a file is proven to be engine-runtime code. Do not cherry-pick only duplicates. Update all imports. Do not create aliases or wrappers. Remove old duplicate files. Produce reports under docs/dev/reports and a ZIP artifact at tmp/PR_11_76_ENGINE_UTILS_TO_SHARED_UTILS.zip. Run targeted validation only."
-```
-
-## Required validation commands
-
-```powershell
-# find remaining old imports
-Select-String -Path .\src\*.js, .\src\**\*.js, .\samples\**\*.js, .\tools\**\*.js -Pattern "src/engine/utils|engine/utils|../engine/utils|../../engine/utils|../../../engine/utils" -ErrorAction SilentlyContinue
-
-# list remaining engine utils files
-Get-ChildItem .\src\engine\utils -Recurse -File -ErrorAction SilentlyContinue
+```text
+Run BUILD_PR_LEVEL_11_78_ENGINE_UTILS_REFERENCE_CLOSURE. Rewrite every remaining literal reference from src/engine/utils/ to src/shared/utils/, including leading-slash forms. Do not create aliases or shims. Fail the PR if any runtime/source references remain after verification.
 ```