Normalize vector rendering/math boundaries and close physics with real reusable helpers

DavidQ · DavidQ · commit 503615901453 · 2026-04-14T19:23:50.000-04:00
BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,8 +2,49 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-- Promote collision to its own boundary
-- Remove physics proxy
-- Normalize imports
-- Update roadmap status only
-- Output zip to <project>/tmp
+Create `BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT`.
+
+Implement this as one combined section-1 closeout PR.
+
+Boundary decisions:
+1. `VectorDrawing` belongs in rendering.
+2. `VectorMath` belongs in shared math/utility.
+3. `src/engine/physics` must contain real reusable physics helpers, not just placeholder/barrel status.
+
+Required work:
+1. Move/normalize vector drawing:
+   - place `VectorDrawing` under the appropriate rendering-owned path
+   - update imports/exports accordingly
+
+2. Move/normalize vector math:
+   - place `VectorMath` under the appropriate shared math/utility path
+   - update imports/exports accordingly
+
+3. Close physics truthfully:
+   - extract the smallest valid set of reusable physics-domain helpers from existing games/samples into `src/engine/physics`
+   - examples may include gravity, friction, drag, acceleration/integration, bounce/impulse if already stable
+   - do NOT promote game-specific behavior prematurely
+   - keep the extraction surgical
+
+4. Validate:
+   - imports remain green
+   - post-move validation remains green
+   - rendering no longer owns generic vector math
+   - shared math no longer depends on rendering
+   - `src/engine/physics` now contains real reusable physics helpers
+
+5. Roadmap:
+   - update status markers only
+   - no roadmap text rewrite
+   - mark `src/engine/rendering` and `src/engine/physics` complete only if truthfully supported
+   - leave `src/engine/scene` open if it still is not done
+
+6. Final packaging step is REQUIRED:
+   - package ALL changed files into this exact repo-structured ZIP:
+     `<project folder>/tmp/BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT.zip`
+
+Hard rules:
+- implementation by Codex
+- surgical changes only
+- no unrelated repo changes
+- no missing ZIP
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1,2 @@
-Collision boundary normalization
+Normalize vector rendering/math boundaries and close physics with real reusable helpers
+BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-BUILD_PR_LEVEL_01_SECTION_1_CLOSEOUT_RECHECK
+BUILD_PR_LEVEL_01_SECTION_1_CLOSEOUT_RECHECK
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1,4 @@
-Repack bundle
+- Combined vector boundary normalization with physics closeout to reduce PR count
+- Rendering now owns vector drawing concerns
+- Shared math/utils now owns generic vector math
+- Physics must be closed by extracting real reusable helpers from games/samples
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1 +1,8 @@
-Ensure collision != physics
+- VectorDrawing moved to rendering-owned path
+- VectorMath moved to shared math/utility path
+- imports/exports normalized and valid
+- src/engine/physics contains real reusable physics helpers
+- roadmap updated by status markers only
+- section 1 residue reduced or fully closed truthfully
+- output ZIP created at:
+  <project folder>/tmp/BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT.zip
diff --git a/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md b/docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
@@ -106,7 +106,7 @@
 - [x] duplicate-helper migration map defined
 - [x] ambiguous-name rename map defined
 - [x] legacy migration map defined
-- [.] implementation PRs executed
+- [x] implementation PRs executed
 - [x] imports normalized after moves
 - [x] post-move validation complete
 
@@ -115,7 +115,7 @@
 - [x] `src/engine/state`
 - [x] `src/engine/rendering`
 - [x] `src/engine/input`
-- [ ] `src/engine/physics`
+- [x] `src/engine/physics`
 - [x] `src/engine/audio`
 - [x] `src/engine/scene`
 - [x] `src/shared/utils`
diff --git a/docs/pr/BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT.md b/docs/pr/BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT.md
@@ -0,0 +1,62 @@
+# BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT
+
+## Purpose
+Close the combined section-1 residue for rendering/vector boundary placement and physics boundary truthfulness.
+
+## Applied Delta
+
+### 1) Vector drawing moved to rendering ownership
+- Added canonical rendering-owned module:
+  - `src/engine/rendering/VectorDrawing.js`
+- Updated rendering barrel:
+  - `src/engine/rendering/index.js` now exports `transformPoints` and `drawVectorShape`
+- Kept compatibility for legacy vector boundary imports:
+  - `src/engine/vector/VectorDrawing.js` re-exports from rendering
+  - `src/engine/vector/index.js` now resolves drawing exports from rendering path
+
+### 2) Vector math moved to shared math ownership
+- Added canonical shared math module:
+  - `src/shared/math/vectorMath.js`
+- Updated compatibility layer:
+  - `src/engine/vector/VectorMath.js` re-exports from shared math
+  - `src/engine/vector/index.js` resolves `vectorFromAngle` from shared math
+
+### 3) Physics boundary now contains real reusable helpers
+- Added reusable helpers under `src/engine/physics/`:
+  - `drag.js` (`applyDrag`)
+  - `arcadeBody.js` (`stepArcadeBody`)
+  - `integration.js` (`integrateVelocity2D`)
+  - `index.js` export surface
+- Normalized existing physics-system surface to use engine physics boundary:
+  - `src/engine/systems/PhysicsSystem.js` now re-exports from `src/engine/physics`
+
+### 4) Import normalization where touched
+- Updated representative runtime imports:
+  - `games/GravityWell/game/GravityWellWorld.js`
+  - `games/GravityWell/game/GravityWellScene.js`
+- Updated focused tests to canonical boundaries:
+  - `tests/vector/VectorMath.test.mjs`
+  - `tests/final/PrecisionCollisionSystems.test.mjs`
+  - `tests/core/Section1FinalResidueStructure.test.mjs`
+
+## Roadmap Status Marker Updates
+- `implementation PRs executed` -> `[x]`
+- `src/engine/physics` -> `[x]`
+
+No roadmap prose text was rewritten.
+
+## Validation
+- `node --check` on touched source/test files.
+- `node tests/core/Section1FinalResidueStructure.test.mjs`
+- `node tests/render/Renderer.test.mjs`
+- `node tests/scenes/SceneManager.test.mjs`
+- `node --input-type=module -e "import { run } from './tests/vector/VectorMath.test.mjs'; run();"`
+- `node --input-type=module -e "import { run } from './tests/final/PrecisionCollisionSystems.test.mjs'; run();"`
+- `rg -n "from '/src/engine/rendering/.*vectorMath|from '/src/shared/math/.*VectorDrawing" src shared` (boundary sanity check)
+
+## Result Summary
+- `VectorDrawing` now lives in rendering ownership.
+- `VectorMath` now lives in shared math ownership.
+- `src/engine/physics` now contains reusable physics-domain helpers, not proxy-only exports.
+- Section-1 rendering/physics markers are truthfully complete for this boundary slice.
+
diff --git a/games/GravityWell/game/GravityWellScene.js b/games/GravityWell/game/GravityWellScene.js
@@ -7,7 +7,7 @@ GravityWellScene.js
 import { Scene } from '/src/engine/scenes/index.js';
 import { Theme, ThemeTokens } from '/src/engine/theme/index.js';
 import { drawPanel } from '/src/engine/debug/index.js';
-import { drawVectorShape } from '/src/engine/vector/index.js';
+import { drawVectorShape } from '/src/engine/rendering/VectorDrawing.js';
 import { ReplaySystem } from '/src/engine/replay/index.js';
 import GravityWellWorld from './GravityWellWorld.js';
 
diff --git a/games/GravityWell/game/GravityWellWorld.js b/games/GravityWell/game/GravityWellWorld.js
@@ -5,7 +5,8 @@ David Quesenberry
 GravityWellWorld.js
 */
 import { clamp, distance } from '/src/engine/utils/index.js';
-import { transformPoints, vectorFromAngle } from '/src/engine/vector/index.js';
+import { transformPoints } from '/src/engine/rendering/VectorDrawing.js';
+import { vectorFromAngle } from '/src/shared/math/vectorMath.js';
 
 const SHIP_SHAPE = [
   { x: 0, y: -16 },
diff --git a/src/engine/physics/arcadeBody.js b/src/engine/physics/arcadeBody.js
@@ -0,0 +1,31 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+arcadeBody.js
+*/
+import { clamp } from '../utils/math.js';
+import { applyDrag } from './drag.js';
+
+export function stepArcadeBody(body, dt) {
+  body.velocityX += (body.accelerationX ?? 0) * dt;
+  body.velocityY += (body.accelerationY ?? 0) * dt;
+
+  const dragX = body.dragX ?? 0;
+  const dragY = body.dragY ?? 0;
+
+  if (!body.accelerationX) {
+    body.velocityX = applyDrag(body.velocityX, dragX, dt);
+  }
+
+  if (!body.accelerationY) {
+    body.velocityY = applyDrag(body.velocityY, dragY, dt);
+  }
+
+  const maxSpeedX = body.maxSpeedX ?? Infinity;
+  const maxSpeedY = body.maxSpeedY ?? Infinity;
+  body.velocityX = clamp(body.velocityX, -maxSpeedX, maxSpeedX);
+  body.velocityY = clamp(body.velocityY, -maxSpeedY, maxSpeedY);
+  return body;
+}
+
diff --git a/src/engine/physics/drag.js b/src/engine/physics/drag.js
@@ -0,0 +1,22 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+drag.js
+*/
+export function applyDrag(value, drag, dt) {
+  if (!drag) {
+    return value;
+  }
+
+  if (value > 0) {
+    return Math.max(0, value - drag * dt);
+  }
+
+  if (value < 0) {
+    return Math.min(0, value + drag * dt);
+  }
+
+  return 0;
+}
+
diff --git a/src/engine/physics/index.js b/src/engine/physics/index.js
@@ -0,0 +1,10 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+index.js
+*/
+export { applyDrag } from './drag.js';
+export { stepArcadeBody } from './arcadeBody.js';
+export { integrateVelocity2D } from './integration.js';
+
diff --git a/src/engine/physics/integration.js b/src/engine/physics/integration.js
@@ -0,0 +1,12 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+integration.js
+*/
+export function integrateVelocity2D(body, dt) {
+  body.x += (body.velocityX ?? 0) * dt;
+  body.y += (body.velocityY ?? 0) * dt;
+  return body;
+}
+
diff --git a/src/engine/rendering/VectorDrawing.js b/src/engine/rendering/VectorDrawing.js
@@ -0,0 +1,25 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+VectorDrawing.js
+*/
+export function transformPoints(points, {
+  x = 0,
+  y = 0,
+  rotation = 0,
+  scale = 1,
+} = {}) {
+  const cos = Math.cos(rotation);
+  const sin = Math.sin(rotation);
+
+  return points.map((point) => ({
+    x: x + ((point.x * scale) * cos) - ((point.y * scale) * sin),
+    y: y + ((point.x * scale) * sin) + ((point.y * scale) * cos),
+  }));
+}
+
+export function drawVectorShape(renderer, points, options = {}) {
+  renderer.drawPolygon(points, options);
+}
+
diff --git a/src/engine/rendering/index.js b/src/engine/rendering/index.js
@@ -8,4 +8,4 @@ export { default as CanvasRenderer } from './CanvasRenderer.js';
 export { default as ResolutionScaler } from './ResolutionScaler.js';
 export { renderSpriteReadyEntities } from './SpriteRenderSystem.js';
 export { renderByLayers } from './LayeredRenderSystem.js';
-
+export { transformPoints, drawVectorShape } from './VectorDrawing.js';
diff --git a/src/engine/systems/PhysicsSystem.js b/src/engine/systems/PhysicsSystem.js
@@ -1,45 +1,7 @@
 /*
 Toolbox Aid
 David Quesenberry
-03/21/2026
+04/14/2026
 PhysicsSystem.js
 */
-import { clamp } from '../utils/math.js';
-
-export function stepArcadeBody(body, dt) {
-  body.velocityX += (body.accelerationX ?? 0) * dt;
-  body.velocityY += (body.accelerationY ?? 0) * dt;
-
-  const dragX = body.dragX ?? 0;
-  const dragY = body.dragY ?? 0;
-
-  if (!body.accelerationX) {
-    body.velocityX = applyDrag(body.velocityX, dragX, dt);
-  }
-
-  if (!body.accelerationY) {
-    body.velocityY = applyDrag(body.velocityY, dragY, dt);
-  }
-
-  const maxSpeedX = body.maxSpeedX ?? Infinity;
-  const maxSpeedY = body.maxSpeedY ?? Infinity;
-  body.velocityX = clamp(body.velocityX, -maxSpeedX, maxSpeedX);
-  body.velocityY = clamp(body.velocityY, -maxSpeedY, maxSpeedY);
-  return body;
-}
-
-export function applyDrag(value, drag, dt) {
-  if (!drag) {
-    return value;
-  }
-
-  if (value > 0) {
-    return Math.max(0, value - drag * dt);
-  }
-
-  if (value < 0) {
-    return Math.min(0, value + drag * dt);
-  }
-
-  return 0;
-}
+export { stepArcadeBody, applyDrag } from '../physics/index.js';
diff --git a/src/engine/vector/VectorDrawing.js b/src/engine/vector/VectorDrawing.js
@@ -1,24 +1,7 @@
 /*
 Toolbox Aid
 David Quesenberry
-03/22/2026
+04/14/2026
 VectorDrawing.js
 */
-export function transformPoints(points, {
-  x = 0,
-  y = 0,
-  rotation = 0,
-  scale = 1,
-} = {}) {
-  const cos = Math.cos(rotation);
-  const sin = Math.sin(rotation);
-
-  return points.map((point) => ({
-    x: x + ((point.x * scale) * cos) - ((point.y * scale) * sin),
-    y: y + ((point.x * scale) * sin) + ((point.y * scale) * cos),
-  }));
-}
-
-export function drawVectorShape(renderer, points, options = {}) {
-  renderer.drawPolygon(points, options);
-}
+export { transformPoints, drawVectorShape } from '../rendering/VectorDrawing.js';
diff --git a/src/engine/vector/VectorMath.js b/src/engine/vector/VectorMath.js
@@ -1,12 +1,7 @@
 /*
 Toolbox Aid
 David Quesenberry
-03/23/2026
+04/14/2026
 VectorMath.js
 */
-export function vectorFromAngle(angle, magnitude = 1) {
-  return {
-    x: Math.cos(angle) * magnitude,
-    y: Math.sin(angle) * magnitude,
-  };
-}
+export { vectorFromAngle } from '../../shared/math/vectorMath.js';
diff --git a/src/engine/vector/index.js b/src/engine/vector/index.js
@@ -4,5 +4,5 @@ David Quesenberry
 03/22/2026
 index.js
 */
-export { transformPoints, drawVectorShape } from './VectorDrawing.js';
-export { vectorFromAngle } from './VectorMath.js';
+export { transformPoints, drawVectorShape } from '../rendering/VectorDrawing.js';
+export { vectorFromAngle } from '../../shared/math/vectorMath.js';
diff --git a/src/shared/math/vectorMath.js b/src/shared/math/vectorMath.js
diff --git a/tests/core/Section1FinalResidueStructure.test.mjs b/tests/core/Section1FinalResidueStructure.test.mjs
diff --git a/tests/final/PrecisionCollisionSystems.test.mjs b/tests/final/PrecisionCollisionSystems.test.mjs
diff --git a/tests/vector/VectorMath.test.mjs b/tests/vector/VectorMath.test.mjs

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`		`-Collision boundary normalization`
	`1`	`+Normalize vector rendering/math boundaries and close physics with real reusable helpers`
	`2`	`+BUILD_PR_LEVEL_01_RENDERING_VECTOR_BOUNDARY_AND_PHYSICS_CLOSEOUT`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-BUILD_PR_LEVEL_01_SECTION_1_CLOSEOUT_RECHECK`
	`1`	`+BUILD_PR_LEVEL_01_SECTION_1_CLOSEOUT_RECHECK`