Add 3D scene graph inspector panel

DavidQ · DavidQ · commit b5f6d38a4c75 · 2026-04-16T10:05:33.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,3 +1,3 @@
 MODEL: GPT-5.3-codex
 REASONING: high
-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
+COMMAND: Implement BUILD_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR as minimal provider + panel + wiring + tests. Package to <project folder>/tmp/BUILD_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR.zip
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-Add 3D collision overlay debug panel
+Add 3D scene graph inspector panel
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,3 +1,3 @@
-- [ ] overlay renders
+- [ ] hierarchy renders
 - [ ] no crashes
-- [ ] camera panel unaffected
+- [ ] prior panels unaffected
diff --git a/docs/pr/BUILD_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR.md b/docs/pr/BUILD_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR.md
@@ -0,0 +1,11 @@
+# BUILD_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR
+
+Implement:
+- provider: scene graph nodes
+- panel: hierarchy list/tree
+- minimal wiring
+- tests
+
+Constraints:
+- read-only
+- no engine changes beyond exposure
diff --git a/docs/pr/PLAN_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR.md b/docs/pr/PLAN_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR.md
@@ -0,0 +1,14 @@
+# PLAN_PR_LEVEL_17_20_SCENE_GRAPH_INSPECTOR
+
+Purpose:
+Add minimal 3D scene graph inspector panel.
+
+Scope:
+- provider (read-only)
+- panel (hierarchy view)
+- minimal wiring
+- testable
+
+Out of scope:
+- editing/mutation
+- performance optimization
diff --git a/src/engine/debug/standard/threeD/panels/panel3dSceneGraphInspector.js b/src/engine/debug/standard/threeD/panels/panel3dSceneGraphInspector.js
@@ -0,0 +1,52 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+panel3dSceneGraphInspector.js
+*/
+
+import {
+  createPanelDescriptor,
+  toLinePair
+} from "../shared/threeDDebugUtils.js";
+
+export const PANEL_3D_SCENE_GRAPH_INSPECTOR = "3d.sceneGraph";
+
+function toNodeLine(node, index) {
+  const indent = node.depth > 0 ? `${".".repeat(node.depth)} ` : "";
+  const label = `${indent}${node.nodeId}`;
+  return toLinePair(
+    `node.${index + 1}`,
+    `${label}|parent=${node.parentId}|children=${node.childCount}|active=${node.active === true}`
+  );
+}
+
+export function create3dSceneGraphInspectorPanel(provider, options = {}) {
+  return createPanelDescriptor({
+    id: PANEL_3D_SCENE_GRAPH_INSPECTOR,
+    title: "3D Scene Graph Inspector",
+    provider,
+    priority: options.priority ?? 1140,
+    enabled: options.enabled === true,
+    linesBuilder(snapshot = {}) {
+      const nodeRows = Array.isArray(snapshot.nodeRows) ? snapshot.nodeRows : [];
+      const baseLines = [
+        toLinePair("nodeCount", snapshot.nodeCount),
+        toLinePair("rootCount", snapshot.rootCount),
+        toLinePair("maxDepth", snapshot.maxDepth)
+      ];
+
+      if (nodeRows.length === 0) {
+        return [
+          ...baseLines,
+          toLinePair("nodes", "none")
+        ];
+      }
+
+      return [
+        ...baseLines,
+        ...nodeRows.map((node, index) => toNodeLine(node, index))
+      ];
+    }
+  });
+}
diff --git a/src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js b/src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js
@@ -8,12 +8,12 @@ registerStandard3dPanels.js
 import { PROVIDER_3D_CAMERA_SUMMARY } from "../providers/cameraSummaryProvider.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_SCENE_GRAPH_INSPECTOR } from "../providers/sceneGraphInspectorProvider.js";
 import { PROVIDER_3D_TRANSFORM_SUMMARY } from "../providers/transformSummaryProvider.js";
 import { create3dCameraPanel } from "./panel3dCamera.js";
 import { create3dCollisionOverlaysPanel } from "./panel3dCollisionOverlays.js";
 import { create3dRenderPipelineStagesPanel } from "./panel3dRenderPipelineStages.js";
-import { create3dSceneGraphPanel } from "./panel3dSceneGraph.js";
+import { create3dSceneGraphInspectorPanel } from "./panel3dSceneGraphInspector.js";
 import { create3dTransformPanel } from "./panel3dTransform.js";
 
 function pickProvider(providerMap, providerId) {
@@ -40,7 +40,7 @@ export function createStandard3dPanels(options = {}) {
   const collision = create3dCollisionOverlaysPanel(pickProvider(providerMap, PROVIDER_3D_COLLISION_OVERLAYS), {
     enabled: options.enabled === true
   });
-  const sceneGraph = create3dSceneGraphPanel(pickProvider(providerMap, PROVIDER_3D_SCENE_GRAPH_SUMMARY), {
+  const sceneGraph = create3dSceneGraphInspectorPanel(pickProvider(providerMap, PROVIDER_3D_SCENE_GRAPH_INSPECTOR), {
     enabled: options.enabled === true
   });
 
diff --git a/src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js b/src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js
@@ -8,7 +8,7 @@ registerStandard3dProviders.js
 import { createCameraSummaryProvider } from "./cameraSummaryProvider.js";
 import { createCollisionOverlaysProvider } from "./collisionOverlaysProvider.js";
 import { createRenderPipelineStagesProvider } from "./renderPipelineStagesProvider.js";
-import { createSceneGraphSummaryProvider } from "./sceneGraphSummaryProvider.js";
+import { createSceneGraphInspectorProvider } from "./sceneGraphInspectorProvider.js";
 import { createTransformSummaryProvider } from "./transformSummaryProvider.js";
 
 export function createStandard3dProviders(options = {}) {
@@ -18,7 +18,7 @@ export function createStandard3dProviders(options = {}) {
     createCameraSummaryProvider(adapters),
     createRenderPipelineStagesProvider(adapters),
     createCollisionOverlaysProvider(adapters),
-    createSceneGraphSummaryProvider(adapters)
+    createSceneGraphInspectorProvider(adapters)
   ];
 
   return {
diff --git a/src/engine/debug/standard/threeD/providers/sceneGraphInspectorProvider.js b/src/engine/debug/standard/threeD/providers/sceneGraphInspectorProvider.js
@@ -0,0 +1,98 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+sceneGraphInspectorProvider.js
+*/
+
+import {
+  asArray,
+  asNonNegativeInteger,
+  asObject,
+  createProvider,
+  getAdapter,
+  sanitizeText
+} from "../shared/threeDDebugUtils.js";
+
+export const PROVIDER_3D_SCENE_GRAPH_INSPECTOR = "provider.3d.sceneGraphInspector.snapshot";
+
+function toBoolean(value, fallback = false) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return fallback;
+}
+
+function toNodeRow(rawNode, index) {
+  if (typeof rawNode === "string") {
+    const nodeId = sanitizeText(rawNode) || `node-${index + 1}`;
+    return {
+      nodeId,
+      parentId: "none",
+      depth: 0,
+      childCount: 0,
+      active: true,
+      order: index
+    };
+  }
+
+  const source = asObject(rawNode);
+  const nodeId = sanitizeText(source.nodeId) || sanitizeText(source.id) || `node-${index + 1}`;
+  const parentId = sanitizeText(source.parentId) || sanitizeText(source.parent) || "none";
+  const depth = asNonNegativeInteger(source.depth, 0);
+  const children = asArray(source.children);
+  const childCount = asNonNegativeInteger(source.childCount, children.length);
+  const active = toBoolean(source.active, true);
+  const order = asNonNegativeInteger(source.order, index);
+
+  return {
+    nodeId,
+    parentId,
+    depth,
+    childCount,
+    active,
+    order
+  };
+}
+
+function byDeterministicOrder(left, right) {
+  if (left.order !== right.order) {
+    return left.order - right.order;
+  }
+  if (left.depth !== right.depth) {
+    return left.depth - right.depth;
+  }
+  return left.nodeId.localeCompare(right.nodeId);
+}
+
+function readSceneGraphInspector(raw) {
+  const source = asObject(raw);
+  const rawRows = Array.isArray(source.nodeRows)
+    ? source.nodeRows
+    : Array.isArray(source.nodes)
+      ? source.nodes
+      : asArray(source.rootNodeIds);
+
+  const nodeRows = rawRows
+    .map((node, index) => toNodeRow(node, index))
+    .sort(byDeterministicOrder);
+
+  return {
+    nodeRows,
+    nodeCount: nodeRows.length,
+    rootCount: nodeRows.filter((node) => node.depth === 0 || node.parentId === "none").length,
+    maxDepth: nodeRows.reduce((maxDepth, node) => Math.max(maxDepth, node.depth), 0)
+  };
+}
+
+export function createSceneGraphInspectorProvider(adapters = {}) {
+  const adapter = getAdapter(adapters, "sceneGraphInspector");
+  return createProvider(
+    PROVIDER_3D_SCENE_GRAPH_INSPECTOR,
+    "3D Scene Graph Inspector",
+    (context = {}) => {
+      const source = adapter ? adapter(context) : asObject(context?.threeD?.sceneGraphInspector);
+      return readSceneGraphInspector(source);
+    }
+  );
+}
diff --git a/tests/tools/SceneGraphInspectorDebugPanel.test.mjs b/tests/tools/SceneGraphInspectorDebugPanel.test.mjs
@@ -0,0 +1,65 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+SceneGraphInspectorDebugPanel.test.mjs
+*/
+import assert from "node:assert/strict";
+import { createStandard3dPanels } from "../../src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js";
+import { PANEL_3D_SCENE_GRAPH_INSPECTOR, create3dSceneGraphInspectorPanel } from "../../src/engine/debug/standard/threeD/panels/panel3dSceneGraphInspector.js";
+import { createStandard3dProviders } from "../../src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js";
+import { PROVIDER_3D_SCENE_GRAPH_INSPECTOR, createSceneGraphInspectorProvider } from "../../src/engine/debug/standard/threeD/providers/sceneGraphInspectorProvider.js";
+
+export async function run() {
+  const provider = createSceneGraphInspectorProvider({
+    sceneGraphInspector: () => ({
+      nodes: [
+        { nodeId: "player", parentId: "worldRoot", depth: 1, childCount: 2, active: true, order: 2 },
+        { nodeId: "worldRoot", depth: 0, childCount: 3, active: true, order: 0 },
+        { nodeId: "uiRoot", depth: 0, childCount: 1, active: true, order: 1 },
+        { nodeId: "pauseMenu", parentId: "uiRoot", depth: 1, childCount: 0, active: false, order: 3 }
+      ]
+    })
+  });
+
+  const snapshot = provider.getSnapshot({});
+  assert.equal(snapshot.nodeCount, 4);
+  assert.equal(snapshot.rootCount, 2);
+  assert.equal(snapshot.maxDepth, 1);
+  assert.deepEqual(
+    snapshot.nodeRows.map((row) => row.nodeId),
+    ["worldRoot", "uiRoot", "player", "pauseMenu"]
+  );
+
+  const panel = create3dSceneGraphInspectorPanel(provider, { enabled: true });
+  const render = panel.render({}, {});
+  assert.equal(render.id, PANEL_3D_SCENE_GRAPH_INSPECTOR);
+  assert.equal(render.title, "3D Scene Graph Inspector");
+  assert.deepEqual(render.lines, [
+    "nodeCount=4",
+    "rootCount=2",
+    "maxDepth=1",
+    "node.1=worldRoot|parent=none|children=3|active=true",
+    "node.2=uiRoot|parent=none|children=1|active=true",
+    "node.3=. player|parent=worldRoot|children=2|active=true",
+    "node.4=. pauseMenu|parent=uiRoot|children=0|active=false"
+  ]);
+
+  const fallbackProvider = createSceneGraphInspectorProvider({
+    sceneGraphInspector: () => ({})
+  });
+  const fallbackPanel = create3dSceneGraphInspectorPanel(fallbackProvider, { enabled: true });
+  const fallbackRender = fallbackPanel.render({}, {});
+  assert.deepEqual(fallbackRender.lines, [
+    "nodeCount=0",
+    "rootCount=0",
+    "maxDepth=0",
+    "nodes=none"
+  ]);
+
+  const { providerMap } = createStandard3dProviders();
+  assert.equal(providerMap.has(PROVIDER_3D_SCENE_GRAPH_INSPECTOR), true);
+  const registeredPanels = createStandard3dPanels({ providerMap, enabled: false });
+  const panelIds = registeredPanels.map((entry) => entry.id);
+  assert.equal(panelIds.includes(PANEL_3D_SCENE_GRAPH_INSPECTOR), true);
+}

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Add 3D collision overlay debug panel`
	`1`	`+Add 3D scene graph inspector panel`