Skip to content

Commit e233a1d

Browse files
author
DavidQ
committed
Plan advanced inspectors as shared opt-in debug capability after rolling back the prior 3D apply.
1 parent c48e95b commit e233a1d

11 files changed

Lines changed: 254 additions & 26 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,18 @@
11
MODEL: GPT-5.4-codex
2-
COMMAND: APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
2+
REASONING: high
3+
4+
COMMAND:
5+
Follow PLAN_PR + BUILD_PR + APPLY_PR
6+
7+
Create PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS
8+
9+
Requirements:
10+
- Docs-first
11+
- No engine core changes
12+
- One PR per purpose
13+
- Build zip automatically to <project folder>/tmp/
14+
- Keep shared inspector capability opt-in only
15+
- No auto-injection into unrelated games/samples
16+
- No hidden 3D assumptions
17+
- Update roadmap trackers with bracket-only edits only
18+
- Roadmaps live under docs/roadmaps/

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Apply 3D debug surfaces
1+
Plan advanced inspector debug-surface contracts as a docs-first PLAN bundle with strict opt-in adoption, no engine-core changes, bracket-only roadmap tracker updates, and packaged delta zip output.

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
1+
BUILD_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS

‎docs/dev/reports/change_summary.txt‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,13 @@
1-
3D support bundle
1+
# Change Summary
2+
3+
## Bundle
4+
PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS_delta
5+
6+
## Included
7+
- PLAN / BUILD / APPLY docs for advanced inspectors
8+
- Codex command, commit comment, next command
9+
- Reports (change summary, file tree, validation checklist)
10+
- Roadmap tracker bracket-state updates under docs/roadmaps
11+
12+
## Intent
13+
Define the advanced inspector promotion path as opt-in shared debug capability with no engine-core changes, no forced sample adoption, and no hidden 3D assumptions.

‎docs/dev/reports/file_tree.txt‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,16 @@
1-
docs/pr docs/dev
1+
HTML-JavaScript-Gaming/
2+
docs/
3+
pr/
4+
PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
5+
BUILD_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
6+
APPLY_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
7+
dev/
8+
CODEX_COMMANDS.md
9+
COMMIT_COMMENT.txt
10+
NEXT_COMMAND.txt
11+
reports/
12+
change_summary.txt
13+
validation_checklist.txt
14+
file_tree.txt
15+
roadmaps/
16+
BIG_PICTURE_ROADMAP.md

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
1-
Validate 3D debug surfaces
1+
# Validation Checklist
2+
3+
- [x] PLAN doc present
4+
- [x] BUILD doc present
5+
- [x] APPLY doc present
6+
- [x] Docs-first scope preserved
7+
- [x] No engine-core changes
8+
- [x] Shared inspector capability marked opt-in
9+
- [x] No auto-injection requirement included
10+
- [x] No hidden 3D assumptions included
11+
- [x] Roadmap edits are bracket-only
12+
- [x] Zip built under <project folder>/tmp/

‎docs/pr/APPLY_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/06/2026
4+
APPLY_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
5+
6+
# APPLY_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS
7+
8+
## Apply Intent
9+
Implement advanced shared inspectors as an opt-in debug capability with read-only data flow and no engine core edits.
10+
11+
## Apply Rules
12+
- no engine core changes
13+
- no auto-injection into unrelated games/samples
14+
- no hidden 3D assumptions
15+
- no runtime mutation paths
16+
- use host/registry/command public APIs only
17+
18+
## Required Validation
19+
- imports pass for inspector modules
20+
- host + registry command flow works
21+
- inspector snapshots stay read-only and bounded
22+
- no forced sample/game adoption
23+
- roadmap edits remain bracket-only
24+
25+
## Roadmaps
26+
Roadmap edits (if needed) are limited to bracket states in:
27+
- docs/roadmaps/BIG_PICTURE_ROADMAP.md
28+
- docs/roadmaps/NETWORK_SAMPLES_PLAN.md
29+
- docs/roadmaps/PRODUCTIZATION_ROADMAP.md

‎docs/pr/BUILD_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/06/2026
4+
BUILD_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
5+
6+
# BUILD_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS
7+
8+
## Build Intent
9+
Prepare an implementation-ready BUILD follow-up for advanced inspector capabilities under debug layers only.
10+
11+
## Build Scope
12+
- finalize host/registry/command/view-model contract details
13+
- define bounded inspector data contracts (read-only)
14+
- define adapter seam contracts for project-owned target extraction
15+
- define APPLY slice order and validation gates
16+
17+
## Authoritative Target Structure
18+
```text
19+
engine/debug/inspectors/
20+
bootstrap/createInspectorSurfaceIntegration.js
21+
host/debugInspectorHost.js
22+
registry/debugInspectorRegistry.js
23+
commands/registerInspectorCommands.js
24+
viewModels/
25+
entityInspectorViewModel.js
26+
componentInspectorViewModel.js
27+
stateDiffInspectorViewModel.js
28+
timelineInspectorViewModel.js
29+
eventStreamInspectorViewModel.js
30+
```
31+
32+
## Guardrails
33+
- no engine core changes
34+
- no hidden 3D assumptions
35+
- no auto-injection into unrelated games/samples
36+
- opt-in wiring only
37+
- read-only inspector data flow only
38+
39+
## Ordered APPLY Steps
40+
1. Add inspector host + registry.
41+
2. Add inspector command bridge via public APIs.
42+
3. Add read-only inspector view-model modules.
43+
4. Add opt-in bootstrap helper.
44+
5. Wire only explicitly chosen sample/tool consumers.
45+
6. Run import/smoke/contract validation.
46+
7. Apply bracket-only roadmap state updates.
47+
48+
## Validation Targets
49+
- import health for inspector modules
50+
- command outputs deterministic and read-only
51+
- bounded history/timeline contracts
52+
- no engine core files touched
53+
- no forced adoption side effects
54+
55+
## Packaging
56+
`<project folder>/tmp/PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS_delta.zip`

‎docs/pr/PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/06/2026
4+
PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
5+
6+
# PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS
7+
8+
## Workflow Discipline
9+
PLAN_PR -> BUILD_PR -> APPLY_PR
10+
11+
## Purpose
12+
Define a docs-first plan for advanced shared inspector capabilities under debug surfaces while preserving strict opt-in adoption and no engine core changes.
13+
14+
## Requirements Alignment
15+
- docs-first
16+
- no engine core changes
17+
- one PR per purpose
18+
- shared inspector capability opt-in only
19+
- no auto-injection into unrelated games/samples
20+
- no hidden 3D assumptions
21+
- roadmap updates by bracket-only edits only
22+
23+
## In Scope
24+
- shared inspector host contract
25+
- shared inspector registry contract
26+
- inspector command bridge contract
27+
- inspector view-model boundary contract
28+
- ownership split: shared contracts vs project/sample adapters
29+
- rollout/validation strategy for opt-in adoption
30+
31+
## Out Of Scope
32+
- engine core API changes
33+
- forced integration into all games/samples/tools
34+
- default-on behavior for inspector plugins
35+
- transport/persistence redesign
36+
- 3D-specific assumptions as required inputs
37+
38+
## Ownership Model
39+
### Shared (`engine/debug/inspectors`)
40+
- host + registry contracts
41+
- command-surface contracts
42+
- read-only inspector view-model contracts
43+
- explicit adapter seams
44+
45+
### Project/Sample/Tool Layer
46+
- domain-specific target resolvers
47+
- local data extractors/adapters
48+
- local labeling and projection rules
49+
- local opt-in wiring
50+
51+
### Engine Core
52+
- no changes in this PLAN PR
53+
54+
## Candidate Shared Structure
55+
```text
56+
engine/debug/inspectors/
57+
bootstrap/
58+
host/
59+
registry/
60+
commands/
61+
viewModels/
62+
adapters/
63+
```
64+
65+
## Candidate Inspector Commands
66+
- inspector.help
67+
- inspector.status
68+
- inspector.open <inspectorId>
69+
- inspector.close <inspectorId>
70+
- inspector.focus <targetId>
71+
- inspector.snapshot
72+
73+
## Validation Goals
74+
- no engine core diffs required
75+
- inspector capability remains opt-in
76+
- no hidden 3D assumptions in shared contracts
77+
- no auto-wiring to unrelated games/samples
78+
- command paths flow through host/registry APIs only
79+
80+
## Deliverables
81+
- docs/pr/PLAN_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
82+
- docs/pr/BUILD_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
83+
- docs/pr/APPLY_PR_DEBUG_SURFACES_ADVANCED_INSPECTORS.md
84+
- docs/dev/CODEX_COMMANDS.md
85+
- docs/dev/COMMIT_COMMENT.txt
86+
- docs/dev/NEXT_COMMAND.txt
87+
- docs/dev/reports/change_summary.txt
88+
- docs/dev/reports/file_tree.txt
89+
- docs/dev/reports/validation_checklist.txt

‎docs/roadmaps/BIG_PICTURE_ROADMAP.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -78,23 +78,23 @@
7878

7979
# 🧊 TRACK H — 3D DEBUG SUPPORT
8080

81-
- [x] Transform inspector
82-
- [x] BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
83-
- [x] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
84-
- [x] Camera debug panel
85-
- [x] Render pipeline stages
86-
- [x] Collision overlays
87-
- [x] Scene graph inspector
81+
- [ ] Transform inspector
82+
- [ ] BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
83+
- [ ] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
84+
- [ ] Camera debug panel
85+
- [ ] Render pipeline stages
86+
- [ ] Collision overlays
87+
- [ ] Scene graph inspector
8888

8989
---
9090

9191
# 🔬 TRACK I — INSPECTORS & TOOLING
9292

93-
- [x] Entity inspector
94-
- [x] Component inspector
95-
- [x] State diff viewer
96-
- [x] Timeline debugger
97-
- [x] Event stream viewer
93+
- [.] Entity inspector
94+
- [.] Component inspector
95+
- [.] State diff viewer
96+
- [.] Timeline debugger
97+
- [.] Event stream viewer
9898

9999
---
100100

0 commit comments

Comments
 (0)