Add scoped 3D render-pipeline stages debug panel BUILD bundle

DavidQ · DavidQ · commit 5c054f6b204b · 2026-04-16T09:54:13.000-04:00
- 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
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 camera debug panel
+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.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1,5 @@
-Add camera debug panel plan
+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
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-PLAN_PR_3D_LAYER_1_FOUNDATION
+NEXT => BUILD_PR_LEVEL_17_19_COLLISION_OVERLAYS
diff --git a/docs/dev/PROJECT_INSTRUCTIONS.md b/docs/dev/PROJECT_INSTRUCTIONS.md
@@ -119,3 +119,15 @@ ZIP STANDARD (ENFORCED)
 - Preserve wording unless the PR explicitly requires rewriting.
 - Keep roadmap handling status-only unless explicitly requested otherwise.
 - Do not delete roadmap content during cleanup work.
+
+## EXECUTION EFFICIENCY
+
+- Bundle PRs whenever it is safe and testable to reduce overall timeline and churn.
+- Codex must always return a ZIP artifact at:
+  <project folder>/tmp/<PR_NAME>.zip
+- Never ask whether to create the next ZIP for Codex; always assume it is required.
+- Default execution behavior:
+  - Choose the correct path automatically
+  - Reduce the number of options presented
+  - Do the right thing and complete the task fully and correctly
+
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1,4 @@
-Status-only sync for MASTER_ROADMAP_HIGH_LEVEL.md (Phase 16 markers updated to match current repo-backed progress and validation evidence).
+Summary
+- advances the 3D debug-support lane from camera debug panel to render pipeline stages
+- keeps scope to one provider, one panel, minimal wiring, and targeted validation
+- intentionally defers collision overlays and scene graph inspector to later PRs
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1 +1,16 @@
-Validate camera debug panel
+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
diff --git a/docs/pr/BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md b/docs/pr/BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md
@@ -0,0 +1,55 @@
+# BUILD_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES
+
+## Purpose
+Implement the next scoped Track H 3D debug-support item: render pipeline stages.
+
+## Source of Truth
+- `docs/pr/PLAN_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md`
+
+## Exact Build Target
+Add a read-only render-pipeline stages panel to the standard 3D debug surface using the smallest viable provider + panel pairing.
+
+## Required Outputs
+- `src/engine/debug/standard/threeD/providers/renderPipelineStagesProvider.js`
+- `src/engine/debug/standard/threeD/panels/panel3dRenderPipelineStages.js`
+- minimal updates to existing 3D panel registration/wiring only where required
+- targeted automated test coverage
+- no unrelated file edits
+
+## Functional Requirements
+1. Provider returns a normalized array of stage rows.
+2. Each row must use stable keys and safe fallback values.
+3. Panel renders the provider output in deterministic display order.
+4. Panel safely handles no-data and partial-data states.
+5. Panel is read-only and does not mutate render state.
+6. Existing 3D debug support remains functional after wiring.
+
+## Allowed Data Surface
+Use only already-available render/debug state that is reachable through existing public or local debug contracts. Do not introduce new engine-core behavior purely to make this panel richer.
+
+## Non-Goals
+- no collision overlays
+- no scene graph inspector
+- no transform inspector expansion
+- no engine rendering architecture rewrite
+- no broad UI cleanup
+- no roadmap edits in this PR
+
+## Implementation Notes
+- prefer the same naming/layout conventions already used by the camera debug panel
+- keep provider sanitization explicit and minimal
+- if a registration list exists, add one entry only for this panel
+- preserve current panel ordering unless a single adjacent insertion is required
+
+## Automated Validation
+Add or update targeted test(s) to verify:
+- provider normalization
+- panel render contract
+- safe fallback state
+- registration visibility if registration is file-driven
+
+## Manual Validation
+Follow `docs/dev/reports/validation_checklist.txt`.
+
+## Packaging Rule
+Package only files relevant to this PR into the final repo-structured ZIP.
diff --git a/docs/pr/PLAN_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md b/docs/pr/PLAN_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES.md
@@ -0,0 +1,52 @@
+# PLAN_PR_LEVEL_17_18_RENDER_PIPELINE_STAGES
+
+## Purpose
+Add the next smallest 3D debug-support capability after the camera debug panel by exposing render pipeline stage visibility in the standard 3D debug surface.
+
+## Why This PR Exists
+Track H in the master roadmap still lists Render pipeline stages as planned work in the 3D debug-support lane. This PR isolates that single capability so it can be implemented, tested, and validated without expanding into collision overlays or scene graph inspection.
+
+## Scope
+Implement a minimal, testable render-pipeline stages panel for 3D debug support.
+
+## In Scope
+- one new 3D render-pipeline provider for read-only stage data
+- one new standard 3D panel for render-pipeline stages
+- minimal panel registration/wiring needed for the panel to appear in the existing debug surface
+- test coverage for provider output and panel registration/render contract
+- validation checklist updates for manual smoke verification
+
+## Out of Scope
+- collision overlays
+- scene graph inspector
+- camera debug panel changes except integration compatibility
+- transform inspector expansion
+- render-engine behavior changes beyond read-only debug exposure
+- broad refactors or folder cleanup
+
+## Constraints
+- stay inside PLAN_PR -> BUILD_PR -> APPLY_PR workflow
+- one PR purpose only
+- smallest scoped valid change
+- no repo-wide scanning unless required
+- no start_of_day edits
+- no unrelated workspace cleanup
+
+## Target Shape
+- `src/engine/debug/standard/threeD/providers/renderPipelineStagesProvider.js`
+- `src/engine/debug/standard/threeD/panels/panel3dRenderPipelineStages.js`
+- minimal registry/wiring file updates only if required by the existing 3D debug panel system
+- targeted test file(s)
+
+## Acceptance Intent
+- panel appears in the existing 3D debug surface
+- panel shows a stable ordered list of pipeline stages or stage-state rows
+- panel remains read-only
+- no regression to the already-added camera debug panel
+- no regression to existing 3D support panels
+
+## Validation Focus
+- provider returns normalized stage rows
+- panel renders empty/fallback state safely
+- panel renders stage rows when provider returns data
+- 3D debug surface still loads without console errors
diff --git a/src/engine/debug/standard/threeD/panels/panel3dRenderPipelineStages.js b/src/engine/debug/standard/threeD/panels/panel3dRenderPipelineStages.js
@@ -0,0 +1,49 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+panel3dRenderPipelineStages.js
+*/
+
+import {
+  createPanelDescriptor,
+  toLinePair
+} from "../shared/threeDDebugUtils.js";
+
+export const PANEL_3D_RENDER_PIPELINE_STAGES = "3d.renderStages";
+
+function toStageLine(stage, index) {
+  return toLinePair(
+    `stage.${index + 1}`,
+    `${stage.stageId}|${stage.status}|enabled=${stage.enabled === true}`
+  );
+}
+
+export function create3dRenderPipelineStagesPanel(provider, options = {}) {
+  return createPanelDescriptor({
+    id: PANEL_3D_RENDER_PIPELINE_STAGES,
+    title: "3D Render Pipeline Stages",
+    provider,
+    priority: options.priority ?? 1120,
+    enabled: options.enabled === true,
+    linesBuilder(snapshot = {}) {
+      const stageRows = Array.isArray(snapshot.stageRows) ? snapshot.stageRows : [];
+      const baseLines = [
+        toLinePair("stageCount", snapshot.stageCount),
+        toLinePair("activeCount", snapshot.activeCount)
+      ];
+
+      if (stageRows.length === 0) {
+        return [
+          ...baseLines,
+          toLinePair("stages", "none")
+        ];
+      }
+
+      return [
+        ...baseLines,
+        ...stageRows.map((stage, index) => toStageLine(stage, index))
+      ];
+    }
+  });
+}
diff --git a/src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js b/src/engine/debug/standard/threeD/panels/registerStandard3dPanels.js
@@ -7,12 +7,12 @@ registerStandard3dPanels.js
 
 import { PROVIDER_3D_CAMERA_SUMMARY } from "../providers/cameraSummaryProvider.js";
 import { PROVIDER_3D_COLLISION_SUMMARY } from "../providers/collisionSummaryProvider.js";
-import { PROVIDER_3D_RENDER_STAGE_SUMMARY } from "../providers/renderStageSummaryProvider.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 { create3dRenderStagesPanel } from "./panel3dRenderStages.js";
+import { create3dRenderPipelineStagesPanel } from "./panel3dRenderPipelineStages.js";
 import { create3dSceneGraphPanel } from "./panel3dSceneGraph.js";
 import { create3dTransformPanel } from "./panel3dTransform.js";
 
@@ -34,7 +34,7 @@ export function createStandard3dPanels(options = {}) {
   const camera = create3dCameraPanel(pickProvider(providerMap, PROVIDER_3D_CAMERA_SUMMARY), {
     enabled: options.enabled === true
   });
-  const renderStages = create3dRenderStagesPanel(pickProvider(providerMap, PROVIDER_3D_RENDER_STAGE_SUMMARY), {
+  const renderStages = create3dRenderPipelineStagesPanel(pickProvider(providerMap, PROVIDER_3D_RENDER_PIPELINE_STAGES), {
     enabled: options.enabled === true
   });
   const collision = create3dCollisionPanel(pickProvider(providerMap, PROVIDER_3D_COLLISION_SUMMARY), {
diff --git a/src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js b/src/engine/debug/standard/threeD/providers/registerStandard3dProviders.js
@@ -7,7 +7,7 @@ registerStandard3dProviders.js
 
 import { createCameraSummaryProvider } from "./cameraSummaryProvider.js";
 import { createCollisionSummaryProvider } from "./collisionSummaryProvider.js";
-import { createRenderStageSummaryProvider } from "./renderStageSummaryProvider.js";
+import { createRenderPipelineStagesProvider } from "./renderPipelineStagesProvider.js";
 import { createSceneGraphSummaryProvider } from "./sceneGraphSummaryProvider.js";
 import { createTransformSummaryProvider } from "./transformSummaryProvider.js";
 
@@ -16,7 +16,7 @@ export function createStandard3dProviders(options = {}) {
   const providers = [
     createTransformSummaryProvider(adapters),
     createCameraSummaryProvider(adapters),
-    createRenderStageSummaryProvider(adapters),
+    createRenderPipelineStagesProvider(adapters),
     createCollisionSummaryProvider(adapters),
     createSceneGraphSummaryProvider(adapters)
   ];
diff --git a/src/engine/debug/standard/threeD/providers/renderPipelineStagesProvider.js b/src/engine/debug/standard/threeD/providers/renderPipelineStagesProvider.js
@@ -0,0 +1,90 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/16/2026
+renderPipelineStagesProvider.js
+*/
+
+import {
+  asArray,
+  asNonNegativeInteger,
+  asObject,
+  createProvider,
+  getAdapter,
+  sanitizeText
+} from "../shared/threeDDebugUtils.js";
+
+export const PROVIDER_3D_RENDER_PIPELINE_STAGES = "provider.3d.renderPipelineStages.snapshot";
+
+function toBoolean(value, fallback = false) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  return fallback;
+}
+
+function toStageRow(rawStage, index) {
+  if (typeof rawStage === "string") {
+    const stageId = sanitizeText(rawStage) || `stage-${index + 1}`;
+    return {
+      stageId,
+      label: stageId,
+      status: "enabled",
+      enabled: true,
+      order: index
+    };
+  }
+
+  const source = asObject(rawStage);
+  const stageId = sanitizeText(source.stageId) || sanitizeText(source.id) || `stage-${index + 1}`;
+  const label = sanitizeText(source.label) || sanitizeText(source.title) || stageId;
+  const status = sanitizeText(source.status) || "unknown";
+  const enabled = toBoolean(source.enabled, status === "enabled");
+  const order = asNonNegativeInteger(source.order, index);
+
+  return {
+    stageId,
+    label,
+    status,
+    enabled,
+    order
+  };
+}
+
+function byDeterministicOrder(left, right) {
+  if (left.order !== right.order) {
+    return left.order - right.order;
+  }
+  return left.stageId.localeCompare(right.stageId);
+}
+
+function readRenderPipelineStages(raw) {
+  const source = asObject(raw);
+  const rawStages = Array.isArray(source.stageRows)
+    ? source.stageRows
+    : Array.isArray(source.stages)
+      ? source.stages
+      : asArray(source.enabledStages);
+
+  const stageRows = rawStages
+    .map((stage, index) => toStageRow(stage, index))
+    .sort(byDeterministicOrder);
+
+  return {
+    stageRows,
+    stageCount: stageRows.length,
+    activeCount: stageRows.filter((stage) => stage.enabled === true).length
+  };
+}
+
+export function createRenderPipelineStagesProvider(adapters = {}) {
+  const adapter = getAdapter(adapters, "renderPipelineStages");
+  return createProvider(
+    PROVIDER_3D_RENDER_PIPELINE_STAGES,
+    "3D Render Pipeline Stages",
+    (context = {}) => {
+      const source = adapter ? adapter(context) : asObject(context?.threeD?.renderPipelineStages);
+      return readRenderPipelineStages(source);
+    }
+  );
+}
diff --git a/tests/tools/RenderPipelineStagesDebugPanel.test.mjs b/tests/tools/RenderPipelineStagesDebugPanel.test.mjs

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-PLAN_PR_3D_LAYER_1_FOUNDATION`
	`1`	`+NEXT => BUILD_PR_LEVEL_17_19_COLLISION_OVERLAYS`