apply: shared 3D debug support layer

Author: DavidQ

docs/dev/3D_SAMPLE_ADAPTER_HARNESS.md

@@ -0,0 +1,16 @@
+# 3D Sample Adapter Harness Notes
+
+## Purpose
+Provide a low-risk validation path for shared 3D debug support without hard-coding a specific renderer into the shared layer.
+
+## Harness Responsibilities
+- expose transform summaries
+- expose camera summaries
+- expose render stage summaries
+- expose collision/debug volume summaries
+- expose scene graph summaries
+
+## Harness Rules
+- adapter remains project-local
+- shared 3D panels/providers stay generic
+- no renderer internals in shared layer

docs/dev/BIG_PICTURE_ROADMAP.md

@@ -81,7 +81,7 @@ Do NOT change structure or wording.
 
 - [.] Transform inspector
 - [x] BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
-- [ ] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
+- [x] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
 - [ ] Camera debug panel
 - [ ] Render pipeline stages
 - [ ] Collision overlays

docs/dev/CODEX_COMMANDS.md

@@ -2,10 +2,15 @@ MODEL: GPT-5.4-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
+Apply APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
 
 Requirements:
-- Docs-only
-- Include guardrails file
-- Update BIG_PICTURE_ROADMAP.md (brackets only)
-- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip
+- Execute the 3D support APPLY step only
+- Create summary-level shared 3D providers, shared 3D panels, and optional shared 3D presets
+- Keep renderer-specific adapters and scene extraction outside the shared layer
+- Preserve existing provider/panel/preset conventions
+- Do not add deep inspectors, renderer-specific implementations, or network support
+- Validate with a 3D sample or local adapter harness
+- Update BIG_PICTURE_ROADMAP.md by changing bracket states only
+- Include ROADMAP_GUARDRAILS.md unchanged
+- Package to <project folder>/tmp/APPLY_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: build 3D support layer and define guardrails for apply readiness
+apply: shared 3D debug support layer

docs/dev/NEXT_COMMAND.txt

@@ -1,2 +1,2 @@
 Next:
-APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
+PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT

docs/dev/ROADMAP_GUARDRAILS.md

@@ -1,14 +1,27 @@
 # 🛡️ Roadmap Guardrails
 
-## RULE
-docs/dev/BIG_PICTURE_ROADMAP.md is a status tracker.
+## Purpose
+Prevent accidental corruption of BIG_PICTURE_ROADMAP.md by enforcing strict update rules.
 
-Allowed:
-- Change [ ] [.] [x] only
+## RULE: TRACKER FILE PROTECTION
+The file `docs/dev/BIG_PICTURE_ROADMAP.md` is a status tracker only.
 
-Forbidden:
-- Any wording/structure change
+### Allowed Changes
+- Change ONLY:
+  - [ ] → [.] → [x]
 
-## Validation
+### Forbidden Changes
+- Adding/removing sections
+- Rewriting text
+- Reordering items
+- Renaming tracks
+- Collapsing or expanding content
+
+## VALIDATION CHECK
+Any change to BIG_PICTURE_ROADMAP.md must pass:
 - Headings unchanged
-- Only bracket diffs
+- No text modified outside brackets
+- Only bracket states updated
+
+## CODEX RULE
+Codex must treat this file as immutable structure and perform surgical edits only.

docs/dev/reports/change_summary.txt

@@ -1,12 +1,13 @@
-Created docs-only BUILD bundle for `BUILD_PR_DEBUG_SURFACES_3D_SUPPORT`.
+Created APPLY bundle for shared 3D debug support.
 
 Included:
-- refreshed BUILD doc for 3D support contracts
-- new dedicated guardrails file
-- bracket-only roadmap state update
-- refreshed reports and packaging metadata
+- apply PR doc
+- codex command
+- roadmap guardrails
+- updated BIG_PICTURE_ROADMAP.md (brackets only)
+- 3D sample adapter harness notes
+- reports
 
-Scope controls maintained:
-- docs-only
-- no implementation code changes
-- renderer-specific/deep-inspector/network scope excluded
+Primary intent:
+- add summary-level, renderer-agnostic shared 3D support
+- keep adapters local

docs/dev/reports/file_tree.txt

@@ -1,9 +1,15 @@
-BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip
-- docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT.md
-- docs/pr/BUILD_PR_DEBUG_SURFACES_3D_SUPPORT_GUARDRAILS.md
-- docs/dev/codex_commands.md
-- docs/dev/commit_comment.txt
-- docs/dev/BIG_PICTURE_ROADMAP.md
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/reports/file_tree.txt
+APPLY_PR_DEBUG_SURFACES_3D_SUPPORT_delta/
+└── docs/
+    ├── dev/
+    │   ├── BIG_PICTURE_ROADMAP.md
+    │   ├── ROADMAP_GUARDRAILS.md
+    │   ├── codex_commands.md
+    │   ├── commit_comment.txt
+    │   ├── next_command.txt
+    │   ├── 3D_SAMPLE_ADAPTER_HARNESS.md
+    │   └── reports/
+    │       ├── change_summary.txt
+    │       ├── validation_checklist.txt
+    │       └── file_tree.txt
+    └── pr/
+        └── APPLY_PR_DEBUG_SURFACES_3D_SUPPORT.md

docs/dev/reports/validation_checklist.txt

@@ -1,14 +1,10 @@
 Validation Checklist
 
-[x] BUILD bundle is docs-only
-[x] Guardrails file is included
-[x] One PR purpose only (3D support BUILD)
-[x] Shared 3D panel inventory is present
-[x] Shared 3D provider inventory is present
-[x] Optional 3D presets are present
-[x] Adapter boundaries are explicit
-[x] Renderer-specific implementation scope excluded
-[x] Deep inspector scope excluded
-[x] Network scope excluded
-[x] BIG_PICTURE_ROADMAP.md updated by bracket changes only
-[x] Delta ZIP contains only BUILD-relevant docs
+[ ] Shared 3D providers created
+[ ] Shared 3D panels consume provider data only
+[ ] Optional shared 3D presets created
+[ ] Renderer-specific adapters remain local
+[ ] No deep inspectors added
+[ ] No renderer-specific logic added to shared layer
+[ ] BIG_PICTURE_ROADMAP.md changed by brackets only
+[ ] 3D sample/adapters validate successfully

docs/pr/APPLY_PR_DEBUG_SURFACES_3D_SUPPORT.md

@@ -1,12 +1,51 @@
 # APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
 
-## Steps
-1. Create shared 3D providers (summary)
-2. Create panels consuming providers
-3. Register optional 3D presets
-4. Keep adapters local to project
-5. Validate with a 3D sample/adapters
+## Purpose
+
+Apply the approved 3D support plan by creating the first shared 3D panels, providers, and optional presets for the debug surfaces platform.
+
+## Apply Scope
+
+### Create Shared 3D Providers
+- `transformSummary`
+- `cameraSummary`
+- `renderStageSummary`
+- `collisionSummary`
+- `sceneGraphSummary`
+
+### Create Shared 3D Panels
+- `3d.transform`
+- `3d.camera`
+- `3d.renderStages`
+- `3d.collision`
+- `3d.sceneGraph`
+
+### Create Optional Shared 3D Presets
+- `preset.3d.inspect`
+- `preset.3d.render`
+- `preset.3d.camera`
+
+### Keep Local
+- renderer-specific adapters
+- scene-specific extraction
+- project-specific debug visuals
+- engine-specific stage mappings
+
+## Execution Order
+
+1. Create summary-level 3D providers
+2. Create shared 3D panels consuming providers only
+3. Create optional shared 3D presets
+4. Add registration entry points
+5. Wire a sample adapter harness or 3D-capable sample integration
+6. Validate renderer-agnostic behavior and adapter boundaries
 
 ## Rules
-- Use public APIs only
+
+- Keep adoption opt-in
+- Preserve existing provider/panel/preset conventions
+- Shared layer must stay renderer-agnostic
+- Panels must consume provider data only
+- No deep inspectors in this PR
 - No renderer-specific logic in shared layer
+- No network support in this PR