Move engine utilities into shared utils and update imports - PR 11.76. Rewire moved utility imports from engine utils to shared utils - PR 11.77

Author: DavidQ

docs/dev/codex_commands.md

@@ -1,8 +1,18 @@
-# Codex Commands — PR 11.75
+# Codex Commands — PR 11.76
 
 Model: GPT-5.4
 Reasoning: high
 
 ```powershell
-codex --model gpt-5.4 --reasoning high "Run PR 11.75 utils consolidation. Read docs/pr/PR_11_75_UTILS_CONSOLIDATION.md. Inventory src/engine/utils and src/shared/utils at file and exported-method level. Consolidate only true shared-safe duplicates into src/shared/utils, keep engine-bound utilities in src/engine/utils, update imports, remove duplicate implementation files only after imports are updated, and write reports under docs/dev/reports. Do not create wrappers, alias files, bridge exports, pass-through variables, or broad refactors. Run targeted syntax/import validation only."
+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
 ```

docs/dev/commit_comment.txt

@@ -1 +1 @@
-Consolidate shared utilities and remove duplicate engine utility implementations - PR 11.75
+Move engine utilities into shared utils and update imports - PR 11.76

docs/dev/reports/PR_11_76_ACCEPTANCE_CHECKLIST.md

@@ -0,0 +1,12 @@
+# PR 11.76 Acceptance Checklist
+
+- [ ] All files under `src/engine/utils/*` inventoried.
+- [ ] All utility files moved to `src/shared/utils/*`.
+- [ ] Any remaining `src/engine/utils/*` file has a documented engine-runtime dependency.
+- [ ] No wrapper or alias files created.
+- [ ] No duplicate utility implementations remain.
+- [ ] All repo imports updated to new shared utility paths.
+- [ ] Search for old engine utility imports returns zero, except documented exceptions.
+- [ ] Workspace Manager opens.
+- [ ] Affected tools open without console import errors.
+- [ ] Full samples test skipped because this is targeted utility/import consolidation; run only if broad loader/runtime issues appear.

docs/dev/reports/PR_11_76_ENGINE_UTILS_TO_SHARED_UTILS_report.md

@@ -0,0 +1,39 @@
+# PR 11.76 — Engine Utils to Shared Utils
+
+## Scope Executed
+- Moved all files from `src/engine/utils/` into `src/shared/utils/`.
+- Removed old `src/engine/utils/index.js`.
+- Updated `src/shared/utils/index.js` exports for moved utilities.
+- No engine-runtime exceptions were found.
+
+## Files Moved
+- `src/engine/utils/fuzzyMatchScore.js` -> `src/shared/utils/fuzzyMatchScore.js`
+- `src/engine/utils/geometry.js` -> `src/shared/utils/geometryUtils.js`
+- `src/engine/utils/invariant.js` -> `src/shared/utils/invariantUtils.js`
+- `src/engine/utils/normalizeCommandText.js` -> `src/shared/utils/normalizeCommandTextUtils.js`
+
+## Files Updated
+- `src/shared/utils/index.js`
+
+## Files Removed
+- `src/engine/utils/index.js`
+
+## Validation
+- Required import scan command:
+  - `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`
+  - Result: no matches
+- Required engine utils directory check:
+  - `Get-ChildItem .\src\engine\utils -Recurse -File -ErrorAction SilentlyContinue`
+  - Result: no files
+- Targeted syntax checks:
+  - `node --check src/shared/utils/index.js`
+  - `node --check src/shared/utils/geometryUtils.js`
+  - `node --check src/shared/utils/invariantUtils.js`
+  - `node --check src/shared/utils/normalizeCommandTextUtils.js`
+  - `node --check src/shared/utils/fuzzyMatchScore.js`
+  - Result: all passed
+
+## Acceptance Summary
+- `src/engine/utils/*` now contains no files.
+- Moved utilities are under `src/shared/utils/*`.
+- No active imports remain in `src/`, `samples/`, or `tools/` for `engine/utils` paths.

docs/pr/PR_11_76_ENGINE_UTILS_TO_SHARED_UTILS.md

@@ -0,0 +1,40 @@
+# PR 11.76 — Engine Utils to Shared Utils Consolidation
+
+## Purpose
+Move the complete utility layer currently under `src/engine/utils/*` into `src/shared/utils/*` because these files are utilities, not engine runtime code.
+
+## Scope
+- Inventory every file under `src/engine/utils/*`.
+- Move all utility files to `src/shared/utils/*`.
+- Preserve folder structure where it helps clarity.
+- Merge only when the target shared file is the same utility contract.
+- Update all imports across the repo.
+- Remove emptied `src/engine/utils` files/folders after import updates.
+
+## Important Correction
+Do not cherry-pick only exact duplicates. The default action is move to shared.
+
+Only keep a file under `src/engine/utils/*` if it is proven to be engine runtime code, meaning it directly depends on engine runtime systems such as:
+- render loop ownership
+- engine state lifecycle
+- engine-specific service registry
+- runtime scene/game object orchestration
+- engine-only loader internals
+
+Canvas helpers, math helpers, path helpers, DOM helpers, JSON helpers, color helpers, id helpers, validation helpers, formatting helpers, and similar utilities belong in `src/shared/utils/*`.
+
+## Rules
+- No pass-through aliases.
+- No wrapper files that re-export moved utilities from the old path.
+- No duplicate utility implementations left behind.
+- No broad refactor beyond import path updates required by the move.
+- No unrelated changes.
+- If two files conflict, keep the shared destination as source of truth and merge useful exported functions into one shared file.
+- If a file must remain in engine, document the exact engine runtime dependency in the report.
+
+## Acceptance
+- `src/engine/utils/*` is empty or contains only documented engine-runtime exceptions.
+- All moved utilities live under `src/shared/utils/*`.
+- All imports resolve to the new shared paths.
+- No old `src/engine/utils/*` imports remain except documented exceptions.
+- Workspace Manager and affected tools load without import errors.

src/engine/utils/index.js

@@ -28,3 +28,7 @@ export { stringifyValue } from "./stringifyValueUtils.js";
 export { oppositeCardinalDirection } from "./directionUtils.js";
 export { wrapTextByCharacterCount } from "./textWrapUtils.js";
 export { clamp, distance, wrap, randomRange } from "./mathUtils.js";
+export { pointInRect, xyInRect, getCenteredRect } from "./geometryUtils.js";
+export { invariant } from "./invariantUtils.js";
+export { normalizeCommandText } from "./normalizeCommandTextUtils.js";
+export { fuzzyMatchScore } from "./fuzzyMatchScore.js";