Add 3D collision overlay debug panel

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-COMMAND: Create BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES as a docs-first, repo-structured delta. Use docs/pr/PLAN_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md and docs/pr/BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md as the source of truth. Implement the smallest valid read-only 3D render pipeline stages panel under src/engine/debug/standard/threeD by adding one provider, one panel, minimal registration wiring, and targeted test coverage only. Do not expand into collision overlays, scene graph inspection, transform inspector expansion, roadmap edits, start_of_day changes, or unrelated cleanup. Preserve existing camera debug panel behavior. Final step: package only this PR's created and modified files into <project folder>/tmp/BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.zip with exact repo-relative structure.
+COMMAND: Implement BUILD_PR_LEVEL_17_19_COLLISION_OVERLAYS with minimal provider + panel + wiring + tests. Package to <project folder>/tmp/BUILD_PR_LEVEL_17_19_COLLISION_OVERLAYS.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1 @@
-Add scoped 3D render-pipeline stages debug panel BUILD bundle
-
-- define the next Track H 3D debug-support step after camera debug panel
-- constrain implementation to a read-only provider + panel + minimal wiring + tests
-- preserve current 3D debug behavior while enabling the next validation-backed APPLY step
+Add 3D collision overlay debug panel

docs/dev/reports/validation_checklist.txt

@@ -1,16 +1,3 @@
-BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES VALIDATION CHECKLIST
-
-Automated
-- [ ] targeted test file passes
-- [ ] provider normalization test covers empty and populated input
-- [ ] panel render test covers fallback state
-- [ ] panel registration visibility is verified if applicable
-
-Manual
-- [ ] app launches without new console errors
-- [ ] existing 3D debug surface still opens
-- [ ] render pipeline stages panel is visible
-- [ ] stage rows display in deterministic order
-- [ ] empty/no-data state renders safely
-- [ ] camera debug panel still renders correctly
-- [ ] no collision overlay or scene graph UI appears from this PR
+- [ ] overlay renders
+- [ ] no crashes
+- [ ] camera panel unaffected

docs/pr/BUILD_PR_LEVEL_17_19_COLLISION_OVERLAYS.md

@@ -0,0 +1,11 @@
+# BUILD_PR_LEVEL_17_19_COLLISION_OVERLAYS
+
+Implement:
+- provider: collision overlay data
+- panel: render overlay
+- minimal wiring
+- tests
+
+Constraints:
+- read-only
+- no engine changes beyond exposure

docs/pr/PLAN_PR_LEVEL_17_19_COLLISION_OVERLAYS.md

@@ -0,0 +1,14 @@
+# PLAN_PR_LEVEL_17_19_COLLISION_OVERLAYS
+
+Purpose:
+Add minimal 3D collision overlay debug visualization.
+
+Scope:
+- one provider
+- one panel
+- minimal wiring
+- testable overlay rendering
+
+Out of scope:
+- physics rewrite
+- scene graph inspector

src/engine/debug/standard/threeD/panels/panel3dCollisionOverlays.js

@@ -0,0 +1,49 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+panel3dCollisionOverlays.js
+*/
+
+import {
+  createPanelDescriptor,
+  toLinePair
+} from "../shared/threeDDebugUtils.js";
+
+export const PANEL_3D_COLLISION_OVERLAYS = "3d.collision";
+
+function toOverlayLine(overlay, index) {
+  return toLinePair(
+    `overlay.${index + 1}`,
+    `${overlay.overlayId}|${overlay.kind}|${overlay.state}|enabled=${overlay.enabled === true}`
+  );
+}
+
+export function create3dCollisionOverlaysPanel(provider, options = {}) {
+  return createPanelDescriptor({
+    id: PANEL_3D_COLLISION_OVERLAYS,
+    title: "3D Collision Overlays",
+    provider,
+    priority: options.priority ?? 1130,
+    enabled: options.enabled === true,
+    linesBuilder(snapshot = {}) {
+      const overlayRows = Array.isArray(snapshot.overlayRows) ? snapshot.overlayRows : [];
+      const baseLines = [
+        toLinePair("overlayCount", snapshot.overlayCount),
+        toLinePair("activeCount", snapshot.activeCount)
+      ];
+
+      if (overlayRows.length === 0) {
+        return [
+          ...baseLines,
+          toLinePair("overlays", "none")
+        ];
+      }
+
+      return [
+        ...baseLines,
+        ...overlayRows.map((overlay, index) => toOverlayLine(overlay, index))
+      ];
+    }
+  });
+}

src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js

@@ -6,12 +6,12 @@ registerStandard3dPanels.js
 */
 
 import { PROVIDER_3D_CAMERA_SUMMARY } from "../providers/cameraSummaryProvider.js";
-import { PROVIDER_3D_COLLISION_SUMMARY } from "../providers/collisionSummaryProvider.js";
+import { PROVIDER_3D_COLLISION_OVERLAYS } from "../providers/collisionOverlaysProvider.js";
 import { PROVIDER_3D_RENDER_PIPELINE_STAGES } from "../providers/renderPipelineStagesProvider.js";
 import { PROVIDER_3D_SCENE_GRAPH_SUMMARY } from "../providers/sceneGraphSummaryProvider.js";
 import { PROVIDER_3D_TRANSFORM_SUMMARY } from "../providers/transformSummaryProvider.js";
 import { create3dCameraPanel } from "./panel3dCamera.js";
-import { create3dCollisionPanel } from "./panel3dCollision.js";
+import { create3dCollisionOverlaysPanel } from "./panel3dCollisionOverlays.js";
 import { create3dRenderPipelineStagesPanel } from "./panel3dRenderPipelineStages.js";
 import { create3dSceneGraphPanel } from "./panel3dSceneGraph.js";
 import { create3dTransformPanel } from "./panel3dTransform.js";
@@ -37,7 +37,7 @@ export function createStandard3dPanels(options = {}) {
   const renderStages = create3dRenderPipelineStagesPanel(pickProvider(providerMap, PROVIDER_3D_RENDER_PIPELINE_STAGES), {
     enabled: options.enabled === true
   });
-  const collision = create3dCollisionPanel(pickProvider(providerMap, PROVIDER_3D_COLLISION_SUMMARY), {
+  const collision = create3dCollisionOverlaysPanel(pickProvider(providerMap, PROVIDER_3D_COLLISION_OVERLAYS), {
     enabled: options.enabled === true
   });
   const sceneGraph = create3dSceneGraphPanel(pickProvider(providerMap, PROVIDER_3D_SCENE_GRAPH_SUMMARY), {

src/engine/debug/standard/threeD/providers/collisionOverlaysProvider.js

@@ -0,0 +1,90 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+collisionOverlaysProvider.js
+*/
+
+import {
+  asArray,
+  asNonNegativeInteger,
+  asObject,
+  createProvider,
+  getAdapter,
+  sanitizeText
+} from "../shared/threeDDebugUtils.js";
+
+export const PROVIDER_3D_COLLISION_OVERLAYS = "provider.3d.collisionOverlays.snapshot";
+
+function toBoolean(value, fallback = false) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return fallback;
+}
+
+function toOverlayRow(rawOverlay, index) {
+  if (typeof rawOverlay === "string") {
+    const overlayId = sanitizeText(rawOverlay) || `overlay-${index + 1}`;
+    return {
+      overlayId,
+      kind: "bounds",
+      state: "active",
+      enabled: true,
+      order: index
+    };
+  }
+
+  const source = asObject(rawOverlay);
+  const overlayId = sanitizeText(source.overlayId) || sanitizeText(source.id) || `overlay-${index + 1}`;
+  const kind = sanitizeText(source.kind) || sanitizeText(source.type) || "bounds";
+  const state = sanitizeText(source.state) || sanitizeText(source.status) || "unknown";
+  const enabled = toBoolean(source.enabled, state === "active");
+  const order = asNonNegativeInteger(source.order, index);
+
+  return {
+    overlayId,
+    kind,
+    state,
+    enabled,
+    order
+  };
+}
+
+function byDeterministicOrder(left, right) {
+  if (left.order !== right.order) {
+    return left.order - right.order;
+  }
+  return left.overlayId.localeCompare(right.overlayId);
+}
+
+function readCollisionOverlays(raw) {
+  const source = asObject(raw);
+  const rawRows = Array.isArray(source.overlayRows)
+    ? source.overlayRows
+    : Array.isArray(source.overlays)
+      ? source.overlays
+      : asArray(source.activeOverlays);
+
+  const overlayRows = rawRows
+    .map((overlay, index) => toOverlayRow(overlay, index))
+    .sort(byDeterministicOrder);
+
+  return {
+    overlayRows,
+    overlayCount: overlayRows.length,
+    activeCount: overlayRows.filter((overlay) => overlay.enabled === true).length
+  };
+}
+
+export function createCollisionOverlaysProvider(adapters = {}) {
+  const adapter = getAdapter(adapters, "collisionOverlays");
+  return createProvider(
+    PROVIDER_3D_COLLISION_OVERLAYS,
+    "3D Collision Overlays",
+    (context = {}) => {
+      const source = adapter ? adapter(context) : asObject(context?.threeD?.collisionOverlays);
+      return readCollisionOverlays(source);
+    }
+  );
+}

src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js

@@ -6,7 +6,7 @@ registerStandard3dProviders.js
 */
 
 import { createCameraSummaryProvider } from "./cameraSummaryProvider.js";
-import { createCollisionSummaryProvider } from "./collisionSummaryProvider.js";
+import { createCollisionOverlaysProvider } from "./collisionOverlaysProvider.js";
 import { createRenderPipelineStagesProvider } from "./renderPipelineStagesProvider.js";
 import { createSceneGraphSummaryProvider } from "./sceneGraphSummaryProvider.js";
 import { createTransformSummaryProvider } from "./transformSummaryProvider.js";
@@ -17,7 +17,7 @@ export function createStandard3dProviders(options = {}) {
     createTransformSummaryProvider(adapters),
     createCameraSummaryProvider(adapters),
     createRenderPipelineStagesProvider(adapters),
-    createCollisionSummaryProvider(adapters),
+    createCollisionOverlaysProvider(adapters),
     createSceneGraphSummaryProvider(adapters)
   ];
 

tests/tools/CollisionOverlaysDebugPanel.test.mjs

@@ -0,0 +1,66 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+CollisionOverlaysDebugPanel.test.mjs
+*/
+import assert from "node:assert/strict";
+import { createStandard3dPanels } from "../../src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js";
+import { PANEL_3D_COLLISION_OVERLAYS, create3dCollisionOverlaysPanel } from "../../src/engine/debug/standard/threeD/panels/panel3dCollisionOverlays.js";
+import { createStandard3dProviders } from "../../src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js";
+import { PROVIDER_3D_COLLISION_OVERLAYS, createCollisionOverlaysProvider } from "../../src/engine/debug/standard/threeD/providers/collisionOverlaysProvider.js";
+
+export async function run() {
+  const provider = createCollisionOverlaysProvider({
+    collisionOverlays: () => ({
+      overlays: [
+        { overlayId: "contact-pairs", kind: "contacts", state: "active", enabled: true, order: 2 },
+        { overlayId: "aabb", kind: "bounds", state: "active", enabled: true, order: 1 },
+        "triggers",
+        { overlayId: "sleeping", kind: "bounds", state: "inactive", enabled: false, order: 4 }
+      ]
+    })
+  });
+
+  const snapshot = provider.getSnapshot({});
+  assert.equal(snapshot.overlayCount, 4);
+  assert.equal(snapshot.activeCount, 3);
+  assert.deepEqual(
+    snapshot.overlayRows.map((row) => row.overlayId),
+    ["aabb", "contact-pairs", "triggers", "sleeping"]
+  );
+  assert.deepEqual(
+    snapshot.overlayRows.map((row) => row.state),
+    ["active", "active", "active", "inactive"]
+  );
+
+  const panel = create3dCollisionOverlaysPanel(provider, { enabled: true });
+  const render = panel.render({}, {});
+  assert.equal(render.id, PANEL_3D_COLLISION_OVERLAYS);
+  assert.equal(render.title, "3D Collision Overlays");
+  assert.deepEqual(render.lines, [
+    "overlayCount=4",
+    "activeCount=3",
+    "overlay.1=aabb|bounds|active|enabled=true",
+    "overlay.2=contact-pairs|contacts|active|enabled=true",
+    "overlay.3=triggers|bounds|active|enabled=true",
+    "overlay.4=sleeping|bounds|inactive|enabled=false"
+  ]);
+
+  const fallbackProvider = createCollisionOverlaysProvider({
+    collisionOverlays: () => ({})
+  });
+  const fallbackPanel = create3dCollisionOverlaysPanel(fallbackProvider, { enabled: true });
+  const fallbackRender = fallbackPanel.render({}, {});
+  assert.deepEqual(fallbackRender.lines, [
+    "overlayCount=0",
+    "activeCount=0",
+    "overlays=none"
+  ]);
+
+  const { providerMap } = createStandard3dProviders();
+  assert.equal(providerMap.has(PROVIDER_3D_COLLISION_OVERLAYS), true);
+  const registeredPanels = createStandard3dPanels({ providerMap, enabled: false });
+  const panelIds = registeredPanels.map((entry) => entry.id);
+  assert.equal(panelIds.includes(PANEL_3D_COLLISION_OVERLAYS), true);
+}