Polish Collision Inspector V2 usability after template CSS alignment - PR_26139_010-collision-inspector-usability-polish

Author: DavidQ

docs/dev/reports/PR_26139_010-collision-inspector-usability-polish_report.md

@@ -0,0 +1,40 @@
+# PR_26139_010-collision-inspector-usability-polish
+
+## Scope
+- Continued Collision Inspector V2 polish on top of PR_26139_009.
+- Kept `../templates-v2/styles/toolStarter.css` as the visual source of truth.
+- Added a concise heading/orientation guide label:
+  - Canvas now references `collisionGuideNote` with `aria-describedby`.
+  - Heading legend item has a title explaining the guide.
+  - Visible note: `Heading guides show each object's rotation from its origin.`
+- Preserved A/B rotate inputs, fixed three-decimal Origins output, scale normalization, shared engine collision path, manifest-only geometry, and no fallback/default vector maps.
+
+## Usability Validation Added
+- Verifies left and right open accordion groups share vertical space evenly.
+- Verifies Live Result, Collision Summary, and Collision Logs each retain readable vertical space and scrollable output containers.
+- Verifies A and B rotate input changes recompute the shared engine collision summary.
+- Verifies A rotation changes transformed Object A points and the canvas preview pixels.
+- Verifies B rotation changes transformed Object B points.
+- Verifies zoom clamps to `5x` and preserves the manifest screen aspect ratio.
+- Verifies the heading/orientation guide is labeled and described.
+
+## Validation
+- PASS: `node --check tests/playwright/tools/CollisionInspectorV2.spec.mjs`
+- PASS: `npx playwright test tests/playwright/tools/CollisionInspectorV2.spec.mjs --project=playwright --workers=1 --reporter=list`
+  - `3 passed`
+  - Covers targeted Collision Inspector V2 usability/layout validation.
+  - Covers targeted A/B rotate and zoom validation.
+  - Covers targeted shared collision validation through `src/engine/collision/objectVector.js`.
+- PASS: `npm run build:manifest`
+  - This repo does not define a plain `npm run build`; `build:manifest` is the available build script.
+  - Removed generated `docs/build` output after validation.
+- PASS: `git diff --check`
+  - Only CRLF working-copy warnings were reported.
+
+## Full Samples Smoke Test
+- Skipped. This PR is limited to Collision Inspector V2 usability/layout polish and targeted validation.
+
+## Changed Files
+- `tools/collision-inspector-v2/index.html`
+- `tools/collision-inspector-v2/styles/collisionInspectorV2.css`
+- `tests/playwright/tools/CollisionInspectorV2.spec.mjs`

tests/playwright/tools/CollisionInspectorV2.spec.mjs

@@ -31,6 +31,22 @@ async function dragCanvasPoint(page, from, to) {
   }, { from, to });
 }
 
+async function readCollisionSummary(page) {
+  return JSON.parse(await page.locator("#collisionSummary").textContent());
+}
+
+async function canvasSignature(page) {
+  return page.locator("#collisionCanvas").evaluate((canvas) => {
+    const context = canvas.getContext("2d");
+    const data = context.getImageData(0, 0, canvas.width, canvas.height).data;
+    let signature = 0;
+    for (let index = 0; index < data.length; index += 97) {
+      signature = (signature * 31 + data[index] * 3 + data[index + 1] * 5 + data[index + 2] * 7 + data[index + 3]) >>> 0;
+    }
+    return signature;
+  });
+}
+
 test.describe("Collision Inspector V2", () => {
   test("loads a game manifest and reports live vector, pixel, bounds, and hybrid collisions", async ({ page }) => {
     const server = await startRepoServer();
@@ -139,6 +155,9 @@ test.describe("Collision Inspector V2", () => {
       await expect(page.locator("#collisionSummaryContent #collisionSummary")).toBeVisible();
       await expect(page.locator("#resultContent")).not.toContainText("Mode");
       await expect(page.locator(".collision-inspector-v2__legend")).toContainText("Heading");
+      await expect(page.locator(".collision-inspector-v2__legend span").nth(3)).toHaveAttribute("title", "Heading guide shows object rotation from its origin.");
+      await expect(page.locator("#collisionCanvas")).toHaveAttribute("aria-describedby", "collisionGuideNote");
+      await expect(page.locator("#collisionGuideNote")).toHaveText("Heading guides show each object's rotation from its origin.");
       const summaryOverflow = await page.locator("#collisionSummaryContent").evaluate((element) => getComputedStyle(element).overflowY);
       expect(["auto", "scroll"]).toContain(summaryOverflow);
       const resultOverflow = await page.locator("#resultContent").evaluate((element) => getComputedStyle(element).overflowY);
@@ -151,15 +170,21 @@ test.describe("Collision Inspector V2", () => {
         const logs = document.querySelector(".collision-inspector-v2__accordion--logs").getBoundingClientRect();
         const heights = [result.height, summary.height, logs.height];
         return {
+          logContentHeight: document.querySelector("#collisionLogContent").getBoundingClientRect().height,
           inputMaxDelta: Math.abs(manifest.height - pair.height),
           maxDelta: Math.max(...heights) - Math.min(...heights),
+          resultContentHeight: document.querySelector("#resultContent").getBoundingClientRect().height,
           resultWidth: result.width,
+          summaryContentHeight: document.querySelector("#collisionSummaryContent").getBoundingClientRect().height,
           summaryWidth: summary.width,
           logsWidth: logs.width
         };
       });
       expect(outputLayout.inputMaxDelta).toBeLessThanOrEqual(6);
       expect(outputLayout.maxDelta).toBeLessThanOrEqual(6);
+      expect(outputLayout.resultContentHeight).toBeGreaterThan(80);
+      expect(outputLayout.summaryContentHeight).toBeGreaterThan(80);
+      expect(outputLayout.logContentHeight).toBeGreaterThan(80);
       expect(Math.abs(outputLayout.resultWidth - outputLayout.summaryWidth)).toBeLessThanOrEqual(1);
       expect(Math.abs(outputLayout.summaryWidth - outputLayout.logsWidth)).toBeLessThanOrEqual(1);
       await expect(page.locator("button[aria-controls='collisionLogContent']")).toBeVisible();
@@ -168,10 +193,23 @@ test.describe("Collision Inspector V2", () => {
       await page.locator("button[aria-controls='collisionLogContent']").click();
       await expect(page.locator("#collisionLogContent")).toBeVisible();
 
+      const initialSummary = await readCollisionSummary(page);
+      const initialSignature = await canvasSignature(page);
       await page.locator("#objectARotationInput").fill("45");
       await expect(page.locator("#rotationState")).toHaveText("A 45 / B 0");
+      const rotatedASummary = await readCollisionSummary(page);
+      expect(rotatedASummary.enginePath).toBe("src/engine/collision/objectVector.js");
+      expect(rotatedASummary.rotation.objectA).toBe(45);
+      expect(rotatedASummary.rotation.objectB).toBe(0);
+      expect(rotatedASummary.transformedPoints.objectA).not.toEqual(initialSummary.transformedPoints.objectA);
+      expect(await canvasSignature(page)).not.toBe(initialSignature);
       await page.locator("#objectBRotationInput").fill("180");
       await expect(page.locator("#rotationState")).toHaveText("A 45 / B 180");
+      const rotatedBSummary = await readCollisionSummary(page);
+      expect(rotatedBSummary.enginePath).toBe("src/engine/collision/objectVector.js");
+      expect(rotatedBSummary.rotation.objectA).toBe(45);
+      expect(rotatedBSummary.rotation.objectB).toBe(180);
+      expect(rotatedBSummary.transformedPoints.objectB).not.toEqual(initialSummary.transformedPoints.objectB);
       await page.locator("#objectARotationInput").fill("0");
       await expect(page.locator("#rotationState")).toHaveText("A 0 / B 180");
 
@@ -201,6 +239,11 @@ test.describe("Collision Inspector V2", () => {
       await page.locator("#collisionZoomInput").fill("5");
       await expect(page.locator("#zoomState")).toHaveText("5x");
       await expect(page.locator("#collisionSummary")).toContainText('"zoom": 5');
+      const zoomAspectRatio = await page.locator("#collisionCanvas").evaluate((canvas) => {
+        const rect = canvas.getBoundingClientRect();
+        return rect.width / rect.height;
+      });
+      expect(Math.abs(zoomAspectRatio - (960 / 720))).toBeLessThan(0.02);
       await page.evaluate(() => window.__collisionInspectorV2App.setZoom(8));
       await expect(page.locator("#zoomState")).toHaveText("5x");
       await expect(page.locator("#collisionSummary")).toContainText('"zoom": 5');

tools/collision-inspector-v2/index.html

@@ -113,14 +113,15 @@ <h2 class="tools-platform-frame__eyebrow">Shared Manifest Collision Tool</h2>
               <output id="zoomState" for="collisionZoomInput">1x</output>
             </div>
             <div class="collision-inspector-v2__canvas-viewport">
-              <canvas id="collisionCanvas" width="1" height="1" aria-label="Collision movement simulation"></canvas>
+              <canvas id="collisionCanvas" width="1" height="1" aria-label="Collision movement simulation" aria-describedby="collisionGuideNote"></canvas>
             </div>
             <div class="collision-inspector-v2__legend" aria-label="Collision overlay legend">
               <span>Object A</span>
               <span>Object B</span>
               <span>Overlap</span>
-              <span>Heading</span>
+              <span title="Heading guide shows object rotation from its origin.">Heading</span>
             </div>
+            <p id="collisionGuideNote" class="collision-inspector-v2__guide-note">Heading guides show each object's rotation from its origin.</p>
           </div>
         </section>
       </section>

tools/collision-inspector-v2/styles/collisionInspectorV2.css

@@ -127,6 +127,12 @@
   background: var(--tool-starter-text);
 }
 
+.collision-inspector-v2__guide-note {
+  margin: 0;
+  color: var(--tool-starter-muted);
+  font-size: 0.86rem;
+}
+
 .collision-inspector-v2__result {
   min-height: 48px;
   display: grid;