BUILD PR: centralize clamp(value,min,max) across core game batch.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,15 +1,10 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_27_AS_OBJECT_AS_ARRAY_DEBUG_BATCH.md exactly.
-Edit only these files:
-- src/engine/debug/inspectors/shared/inspectorUtils.js (only if minimum export fix is needed)
-- games/Asteroids/debug/asteroidsShowcaseDebug.js
-- games/network_sample_a/debug/networkSampleADebug.js
-- games/network_sample_b/debug/networkSampleBDebug.js
-- games/network_sample_c/debug/networkSampleCDebug.js
-- tools/dev/inspectors/inspectorStore.js
-- tools/dev/plugins/debugPluginSystem.js
-Fail fast unless src/engine/debug/inspectors/shared/inspectorUtils.js exists and exposes asObject and asArray, or can be fixed with a minimum export-only change.
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_28_CLAMP_CORE_BATCH.md exactly.
+Edit only:
+- src/engine/utils/math.js (export fix only if needed)
+- listed game files
+Fail fast if clamp is not available.
 Do not expand scope.
-Package the delta output to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_27_AS_OBJECT_AS_ARRAY_DEBUG_BATCH_delta.zip
+Package to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_28_CLAMP_CORE_BATCH_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: centralize asObject/asArray across debug batch to inspectorUtils shared helper.
+BUILD PR: centralize clamp(value,min,max) across core game batch.

docs/dev/NEXT_COMMAND.txt

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

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Batch extraction for asObject/asArray across selected debug consumers only.
+clamp core batch extraction

docs/dev/reports/validation_checklist.txt

@@ -1 +1 @@
-asObject/asArray batch moved to shared helper with consumer imports updated.
+clamp centralized

docs/pr/BUILD_PR_SHARED_EXTRACTION_28_CLAMP_CORE_BATCH.md

@@ -0,0 +1,92 @@
+# BUILD_PR_SHARED_EXTRACTION_28_CLAMP_CORE_BATCH
+
+## Purpose
+Centralize duplicated `clamp(value, min, max)` implementations across core/game usage into the engine math utility.
+
+## Single PR Purpose
+Normalize ONLY this helper:
+
+- clamp(value, min, max)
+
+Target batch (core + games using identical signature):
+
+1. games/AITargetDummy/game/AITargetDummyController.js
+2. games/AITargetDummy/game/AITargetDummyInputController.js
+3. games/AITargetDummy/game/AITargetDummyWorld.js
+4. games/Asteroids/game/AsteroidsAttractAdapter.js
+5. games/Bouncing-ball/game/BouncingBallWorld.js
+6. games/Breakout/game/BreakoutWorld.js
+7. games/Gravity/game/GravityInputController.js
+8. games/Gravity/game/GravityWorld.js
+9. games/MultiBallChaos/game/MultiBallChaosWorld.js
+10. games/network_sample_a/game/FakeLoopbackNetworkModel.js
+11. games/network_sample_a/game/NetworkSampleAScene.js
+12. games/network_sample_b/game/FakeHostClientNetworkModel.js
+13. games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js
+14. games/PacmanLite/game/PacmanLitePlayerController.js
+15. games/PaddleIntercept/game/PaddleInterceptWorld.js
+16. games/Pong/game/PongWorld.js
+17. games/SpaceDuel/game/SpaceDuelAttractAdapter.js
+18. games/SpaceInvaders/game/SpaceInvadersInputController.js
+19. games/SpaceInvaders/game/SpaceInvadersWorld.js
+20. games/Thruster/game/ThrusterInputController.js
+21. games/Thruster/game/ThrusterWorld.js
+
+## Exact Files Allowed
+
+### Canonical shared source
+1. src/engine/utils/math.js
+
+### Consumers
+(only the 21 listed files)
+
+## Shared Helper
+Use:
+- src/engine/utils/math.js
+
+Fail fast unless it exports:
+- clamp
+
+If present but not exported correctly → minimal export fix only.
+
+## Change Rules
+
+### Shared file
+Allowed:
+- ensure clamp exists
+- ensure clamp is exported
+
+Not allowed:
+- no behavior change
+
+### Consumer files
+If local:
+```js
+function clamp(value, min, max)
+```
+
+Then:
+- remove local definition
+- import clamp from src/engine/utils/math.js
+- merge into existing import if present
+
+Do NOT touch:
+- clamp with fallback param
+- clamp variants with different signatures
+
+## Constraints
+- no tools
+- no debug
+- no samples
+- no behavior change
+- exact batch only
+
+## Validation
+- only listed files changed
+- no local clamp definitions remain in listed files
+- imports added correctly
+- no signature mismatch introduced
+
+## Non-Goals
+- no clamp(fallback) variants
+- no tools clamp cleanup

games/AITargetDummy/game/AITargetDummyController.js

@@ -6,10 +6,7 @@ AITargetDummyController.js
 */
 import AITargetDummyConfig from './AITargetDummyConfig.js';
 import AITargetDummyStateMachine from './AITargetDummyStateMachine.js';
-
-function clamp(value, min, max) {
-  return Math.max(min, Math.min(max, value));
-}
+import { clamp } from '../../../src/engine/utils/math.js';
 
 function safeNormalize(x, y) {
   const length = Math.hypot(x, y);

games/AITargetDummy/game/AITargetDummyInputController.js

@@ -5,10 +5,7 @@ David Quesenberry
 AITargetDummyInputController.js
 */
 import { GamepadInputAdapter } from '../../../src/engine/input/index.js';
-
-function clamp(value, min, max) {
-  return Math.max(min, Math.min(max, value));
-}
+import { clamp } from '../../../src/engine/utils/math.js';
 
 export default class AITargetDummyInputController {
   constructor(input) {

games/AITargetDummy/game/AITargetDummyWorld.js

@@ -6,13 +6,10 @@ AITargetDummyWorld.js
 */
 import AITargetDummyConfig from './AITargetDummyConfig.js';
 import AITargetDummyController from './AITargetDummyController.js';
+import { clamp } from '../../../src/engine/utils/math.js';
 
 const MAX_STEP_SECONDS = 1 / 120;
 
-function clamp(value, min, max) {
-  return Math.max(min, Math.min(max, value));
-}
-
 function safeNormalize(x, y) {
   const length = Math.hypot(x, y);
   if (length <= 1e-6) {

games/Asteroids/game/AsteroidsAttractAdapter.js

@@ -4,9 +4,7 @@ David Quesenberry
 03/25/2026
 AsteroidsAttractAdapter.js
 */
-function clamp(value, min, max) {
-  return Math.max(min, Math.min(max, value));
-}
+import { clamp } from '../../../src/engine/utils/math.js';
 
 function estimateTextWidth(text, fontPx) {
   return String(text ?? '').length * (fontPx * 0.62);