Align Collision Inspector V2 with shared engine collision and refactor tool structure - PR_26139_004-collision-inspector-engine-alignment

Author: DavidQ

docs/dev/reports/PR_26139_004-collision-inspector-engine-alignment_report.md

@@ -0,0 +1,70 @@
+# PR_26139_004-collision-inspector-engine-alignment Report
+
+## Summary
+
+Aligned Collision Inspector V2 with shared engine Object Vector collision logic and kept Asteroids collision consumers on the same manifest geometry path. The inspector now calls `src/engine/collision/objectVector.js` for bounds, vector, pixel/sprite, and hybrid checks instead of maintaining its own competing polygon/mask implementation.
+
+Playwright impacted: Yes.
+
+## Scope Completed
+
+- Added shared Object Vector collision support under `src/engine/collision/objectVector.js` and exported it through `src/engine/collision/index.js`.
+- Moved reusable Object Vector geometry normalization, transformed points, bounds, raster-mask, and collision-mode recommendation logic into the engine.
+- Updated Collision Inspector V2 to consume `evaluateObjectVectorCollisionPair(...)` and shared engine diagnostics only.
+- Refactored `CollisionInspectorV2App.js` into one-class files:
+  - `CollisionInspectorV2App.js`
+  - `CollisionInspectorV2Controls.js`
+  - `CollisionInspectorV2Logger.js`
+  - `CollisionInspectorV2ManifestLoader.js`
+  - `CollisionInspectorV2Renderer.js`
+- Kept `bootstrap.js` as a thin element/class wiring entry point.
+- Added inspector schema support with `tools/schemas/tools/collision-inspector-v2.schema.json` and wired it through `workspace.manifest.schema.json`.
+- Moved Collision Inspector V2 into the Workspace Manager V2 `Viewers` group and tools index viewer category.
+- Added object-pair collision-mode auto-selection with manual override.
+- Moved Collision Mode under Object B, moved Reset into the Collision Pair accordion, removed Copy Report, and added zoom.
+- Updated Asteroids entity/object-geometry collision transforms to use shared collision helpers while continuing to load manifest Object Vector Studio V2 objects only.
+
+## Guardrails
+
+- No hardcoded Asteroids object geometry was added.
+- No fallback/default vector maps were added.
+- Collision Inspector V2 uses manifest `objects[].shapes[]` geometry only.
+- Existing intentional ship flame flicker and asteroid scale tuning were preserved.
+
+## Validation
+
+PASS:
+
+- `node --check` on touched Collision Inspector V2 modules and touched Asteroids entity modules.
+- `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - 2 passed.
+- `node -e "import('./tests/final/PrecisionCollisionSystems.test.mjs').then(({ run }) => run())"`
+- `node -e "import('./tests/games/AsteroidsVectorTransforms.test.mjs').then(({ run }) => run())"`
+- `node -e "import('./tests/games/AsteroidsCollisionTimingStress.test.mjs').then(({ run }) => run())"`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list --grep "registers Workspace Manager V2 from the tools index"`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list --grep "uses header lifecycle controls and launches tools from fixed Workspace Manager V2 tiles"`
+- `npx playwright test tests/playwright/tools/WorkspaceManagerV2.spec.mjs --project=playwright --workers=1 --reporter=list --grep "loads Object Vector Studio V2 runtime assets into Asteroids gameplay rendering"`
+- `git diff --check`
+  - Passed with line-ending warnings only.
+
+FAIL, broader existing gate:
+
+- `npm test`
+  - Fails in `pretest` at `tools/dev/checkSharedExtractionGuard.mjs`.
+  - Reported `185 unexpected violation(s)`, `baseline_expected=609`, `baseline_resolved=6`, `total_violations=848`.
+  - The PR_003 Collision Inspector helper hits are removed; remaining failures are broad repository guard drift across existing game, sample, engine, and tool files.
+
+FAIL, broader existing Workspace V2 suite:
+
+- `npm run test:workspace-v2`
+  - 54 passed, 2 failed.
+  - Failing test: `validates optional Text to Speech V2 schema contract through Workspace Manager V2 schema`
+    - Expected `activeContext.tools` to include `text2speech-V2`; received false.
+  - Failing test: `tracks Object Vector Studio V2 dirty state through persisted edits and save outcomes`
+    - Expected generated manifest schema validation failure; save succeeded.
+  - Collision Inspector V2 category, schema, hydration, tile enablement, launch, and storage-session checks passed inside this run.
+
+## Notes
+
+- The targeted Asteroids collision stress fixture was adjusted to place the ship at the current manifest-accurate asteroid edge. The prior point was outside the restored Object Vector geometry and correctly produced no collision under the shared polygon path.
+- Full samples smoke test was not run; this PR is scoped to Collision Inspector V2, shared Object Vector collision, Asteroids targeted collision validation, and Workspace Manager launch wiring.

games/Asteroids/entities/Asteroid.js

@@ -5,7 +5,7 @@ David Quesenberry
 Asteroid.js
 */
 import { TAU, randomRange, wrap } from '../utils/math.js';
-import { transformPoints } from '../../../src/engine/rendering/index.js';
+import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
 
 const SIZE_PROFILES = {
   SML: { id: 1 },
@@ -57,10 +57,11 @@ export default class Asteroid {
     if (!this.collisionPoints.length) {
       return [];
     }
-    return transformPoints(this.collisionPoints, {
+    return transformCollisionPoints(this.collisionPoints, {
       x: this.x,
       y: this.y,
       rotation: this.angle,
+      rotationUnit: 'radians',
       scale: this.scale,
     });
   }

games/Asteroids/entities/Bullet.js

@@ -5,7 +5,7 @@ David Quesenberry
 Bullet.js
 */
 import { wrap } from '../utils/math.js';
-import { transformPoints } from '../../../src/engine/rendering/index.js';
+import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
 
 function normalizePoints(points) {
   return Array.isArray(points)
@@ -41,9 +41,11 @@ export default class Bullet {
   }
 
   getCollisionPolygon() {
-    return transformPoints(this.collisionPoints, {
+    return transformCollisionPoints(this.collisionPoints, {
       x: this.x,
       y: this.y,
+      rotation: this.angle,
+      rotationUnit: 'radians',
     });
   }
 }

games/Asteroids/entities/Ship.js

@@ -5,7 +5,7 @@ David Quesenberry
 Ship.js
 */
 import { wrap } from '../utils/math.js';
-import { transformPoints } from '../../../src/engine/rendering/index.js';
+import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
 
 function normalizePoints(points) {
   return Array.isArray(points)
@@ -56,10 +56,11 @@ export default class Ship {
   }
 
   getPoints() {
-    return transformPoints(this.collisionPoints, {
+    return transformCollisionPoints(this.collisionPoints, {
       x: this.x,
       y: this.y,
       rotation: this.angle,
+      rotationUnit: 'radians',
     });
   }
 }

games/Asteroids/entities/Ufo.js

@@ -6,7 +6,7 @@ Ufo.js
 */
 import Bullet from './Bullet.js';
 import { distance } from '../../../src/shared/utils/mathUtils.js';
-import { transformPoints } from '../../../src/engine/rendering/index.js';
+import { transformCollisionPoints } from '../../../src/engine/collision/index.js';
 import { randomRange } from '../utils/math.js';
 
 const UFO_PROFILES = {
@@ -110,7 +110,7 @@ export default class Ufo {
   }
 
   getCollisionPolygon() {
-    return transformPoints(this.collisionPoints, {
+    return transformCollisionPoints(this.collisionPoints, {
       x: this.x,
       y: this.y,
     });

games/Asteroids/game/asteroidObjectGeometry.js

@@ -1,6 +1,7 @@
 import {
   ASTEROIDS_ASTEROID_SIZE_OBJECT_IDS,
 } from './asteroidsObjectGeometryManifest.js';
+import { getObjectVectorCollisionOutlinePoints } from '../../../src/engine/collision/index.js';
 
 const ASTEROID_SIZE_LABELS = Object.freeze({
   1: 'SML',
@@ -12,18 +13,6 @@ function asArray(value) {
   return Array.isArray(value) ? value : [];
 }
 
-function toSafeNumber(value, fallback = 0) {
-  const numberValue = Number(value);
-  return Number.isNaN(numberValue) || Math.abs(numberValue) === Infinity ? fallback : numberValue;
-}
-
-function cleanPoint(point) {
-  return {
-    x: toSafeNumber(point?.x, 0),
-    y: toSafeNumber(point?.y, 0),
-  };
-}
-
 function centerPoints(points) {
   if (!points.length) {
     return [];
@@ -45,21 +34,6 @@ function maxRadius(points) {
   return Math.max(...points.map(({ x, y }) => Math.sqrt(x * x + y * y)));
 }
 
-function sortedShapes(object) {
-  return [...asArray(object?.shapes)].sort((left, right) => (
-    toSafeNumber(left?.order, 0) - toSafeNumber(right?.order, 0)
-  ));
-}
-
-function extractPrimaryPolygonPoints(object) {
-  const shape = sortedShapes(object).find((candidate) => (
-    candidate?.visible !== false
-    && candidate?.tool === 'polygon'
-    && asArray(candidate?.geometry?.points).length >= 3
-  ));
-  return asArray(shape?.geometry?.points).map(cleanPoint);
-}
-
 function logProfileFailure(logger, message, details = {}) {
   if (!logger) {
     return;
@@ -84,7 +58,7 @@ function createProfilesFromObjects(objects, options = {}) {
       });
       return;
     }
-    const points = centerPoints(extractPrimaryPolygonPoints(object));
+    const points = centerPoints(getObjectVectorCollisionOutlinePoints(object));
     if (points.length < 3) {
       logProfileFailure(options.logger, `Asteroids asteroid geometry profile ${objectId} must contain visible polygon geometry with at least 3 points.`, {
         objectId,

games/Asteroids/game/asteroidsObjectGeometryManifest.js

@@ -1,3 +1,5 @@
+import { getObjectVectorCollisionOutlinePoints } from '../../../src/engine/collision/index.js';
+
 const ASTEROIDS_OBJECT_VECTOR_TOOL_KEY = 'object-vector-studio-v2';
 const OBJECT_VECTOR_PAYLOAD_KEYS = new Set(['version', 'toolId', 'name', 'objects']);
 
@@ -57,47 +59,8 @@ function oldObjectSignal(object) {
   return /(^|[.\s_-])(old|legacy|deprecated|archive|archived|renamed|stale)($|[.\s_-])/.test(text);
 }
 
-function normalizePoint(point) {
-  return {
-    x: Number(point?.x ?? 0),
-    y: Number(point?.y ?? 0),
-  };
-}
-
-function normalizePoints(points) {
-  return Array.isArray(points)
-    ? points.map(normalizePoint).filter((point) => Number.isFinite(point.x) && Number.isFinite(point.y))
-    : [];
-}
-
-function shapeTool(shape) {
-  return normalizeString(shape?.tool).toLowerCase();
-}
-
-function sortedShapes(object) {
-  return Array.isArray(object?.shapes)
-    ? [...object.shapes].sort((left, right) => Number(left?.order ?? 0) - Number(right?.order ?? 0))
-    : [];
-}
-
-function shapeGeometryPoints(shape) {
-  const tool = shapeTool(shape);
-  if (tool === 'polygon' || tool === 'polyline') {
-    return normalizePoints(shape?.geometry?.points);
-  }
-  if (tool === 'line') {
-    return normalizePoints([shape?.geometry?.point1, shape?.geometry?.point2]);
-  }
-  return [];
-}
-
 function objectVectorGeometryPoints(object) {
-  const shapes = sortedShapes(object).filter((shape) => shape?.visible !== false);
-  const shape = shapes.find((candidate) => {
-    const tool = shapeTool(candidate);
-    return tool === 'polygon' || tool === 'polyline';
-  }) || shapes.find((candidate) => shapeTool(candidate) === 'line');
-  return shapeGeometryPoints(shape);
+  return getObjectVectorCollisionOutlinePoints(object);
 }
 
 function requiredObjectGeometryPointCount(objectId) {

src/engine/collision/index.js

@@ -8,3 +8,15 @@ export { isColliding } from './aabb.js';
 export { arePolygonsColliding, isPointInPolygon, getPolygonBounds } from './polygon.js';
 export { createRasterMask, areMasksColliding, isPointInMask, getMaskBounds } from './raster.js';
 export { runHybridCollision, getCollisionBoundsFromPolygon } from './hybrid.js';
+export {
+  createObjectVectorCollisionGeometry,
+  evaluateObjectVectorCollisionPair,
+  getObjectVectorCollisionOutlinePoints,
+  getObjectVectorOrigin,
+  normalizeObjectVectorCollisionMode,
+  OBJECT_VECTOR_COLLISION_ENGINE_PATH,
+  OBJECT_VECTOR_COLLISION_MODE_LABELS,
+  OBJECT_VECTOR_COLLISION_MODES,
+  recommendObjectVectorCollisionMode,
+  transformCollisionPoints,
+} from './objectVector.js';