Skip to content

Commit 0c1cc2b

Browse files
author
DavidQ
committed
Build BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION docs bundle for a read-only sample-level server dashboard surface under tools/dev/server-dashboard.
1 parent aa39b68 commit 0c1cc2b

12 files changed

Lines changed: 500 additions & 23 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
⚠️ RULE:
2+
This file is a status tracker only.
3+
ONLY modify bracket states [ ] [.] [x].
4+
Do NOT change structure or wording.
5+
6+
---
7+
8+
# 🧭 Debug Platform & Ecosystem Roadmap
9+
10+
## Status Legend
11+
- [ ] Todo
12+
- [.] In Progress
13+
- [x] Complete
14+
15+
---
16+
17+
# 🧱 TRACK A — DEBUG FOUNDATION (COMPLETE)
18+
19+
- [x] Dev Console (input + command execution)
20+
- [x] Debug Overlay (visual panels)
21+
- [x] Console ↔ Overlay Boundary
22+
- [x] Panel Registry
23+
- [x] Data Providers (read-only model)
24+
- [x] Operator Commands (control surface)
25+
- [x] Panel Persistence
26+
27+
---
28+
29+
# 🚀 TRACK B — PROMOTION TO ENGINE LAYER
30+
31+
- [x] PLAN_PR_DEBUG_SURFACES_PROMOTION
32+
- [x] BUILD_PR_DEBUG_SURFACES_PROMOTION
33+
- [x] APPLY_PR_DEBUG_SURFACES_PROMOTION
34+
35+
---
36+
37+
# 📦 TRACK C — STANDARD DEBUG LIBRARY
38+
39+
- [x] PLAN_PR_DEBUG_SURFACES_STANDARD_LIBRARY
40+
- [x] BUILD_PR_DEBUG_SURFACES_STANDARD_LIBRARY
41+
- [x] APPLY_PR_DEBUG_SURFACES_STANDARD_LIBRARY
42+
43+
---
44+
45+
# 🎛️ TRACK D — DEBUG PRESETS
46+
47+
- [x] PLAN_PR_DEBUG_SURFACES_PRESETS
48+
- [x] BUILD_PR_DEBUG_SURFACES_PRESETS
49+
- [x] APPLY_PR_DEBUG_SURFACES_PRESETS
50+
51+
---
52+
53+
# 🧰 TRACK E — ADVANCED DEBUG UX
54+
55+
- [x] PLAN_PR_DEBUG_SURFACES_ADVANCED_UX
56+
- [x] BUILD_PR_DEBUG_SURFACES_ADVANCED_UX
57+
- [x] APPLY_PR_DEBUG_SURFACES_ADVANCED_UX
58+
59+
---
60+
61+
# 🎮 TRACK F — GAME INTEGRATION
62+
63+
- [x] PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION
64+
- [x] BUILD_PR_DEBUG_SURFACES_GAME_INTEGRATION
65+
- [x] APPLY_PR_DEBUG_SURFACES_GAME_INTEGRATION
66+
- [x] Sample game uses full debug platform
67+
- [x] Toggle debug in production-safe mode
68+
- [x] Performance-safe overlays
69+
- [x] Build-time debug flags
70+
71+
---
72+
73+
# 🌐 TRACK G — NETWORK / MULTIPLAYER DEBUG
74+
75+
- [x] Connection status panel
76+
- [.] Latency / RTT panel
77+
- [ ] Replication state viewer
78+
- [ ] Client/server divergence inspector
79+
- [.] Event tracing
80+
- [.] PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT
81+
- [x] BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT
82+
- [x] APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT
83+
84+
---
85+
86+
# 🧊 TRACK H — 3D DEBUG SUPPORT
87+
88+
- [.] Transform inspector
89+
- [x] BUILD_PR_DEBUG_SURFACES_3D_SUPPORT
90+
- [x] APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
91+
- [ ] Camera debug panel
92+
- [ ] Render pipeline stages
93+
- [ ] Collision overlays
94+
- [ ] Scene graph inspector
95+
96+
---
97+
98+
# 🔬 TRACK I — INSPECTORS & TOOLING
99+
100+
- [x] Entity inspector
101+
- [x] Component inspector
102+
- [x] State diff viewer
103+
- [x] Timeline debugger
104+
- [x] Event stream viewer
105+
106+
---
107+
108+
# 🧠 TRACK J — ENGINE MATURITY
109+
110+
- [x] Stable debug API
111+
- [x] Plugin system
112+
- [x] External documentation
113+
- [x] Versioned contracts
114+
- [x] Performance benchmarks
115+
116+
---
117+
118+
# 🏁 END STATE
119+
120+
A complete system:
121+
122+
- Engine Core → minimal contracts
123+
- Engine Debug → reusable platform
124+
- Standard Library → shared baseline
125+
- Presets → usability layer
126+
- Extensions → 3D, network, inspectors

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
1-
MODEL: GPT-5.3-codex
1+
MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Validate multi-entity implementation in network_sample_c.
5+
Create BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION
66

7-
- Verify per-entity timelines
8-
- Verify selective rewind correctness
9-
- Verify debug outputs
10-
11-
DO NOT:
12-
- modify docs
13-
- expand scope
7+
Requirements:
8+
- Follow PLAN_PR + BUILD_PR + APPLY_PR discipline
9+
- Docs-first for this bundle
10+
- No engine core changes
11+
- One PR per purpose
12+
- Keep integration sample-level
13+
- Implement docs for a read-only server dashboard foundation under tools/dev/server-dashboard
14+
- Include host, registry, providers, renderer responsibilities
15+
- Keep console and overlay decoupled from dashboard internals
16+
- Keep combo keys unchanged
17+
- Write outputs under docs/pr and docs/dev/reports
18+
- Update tracker files only by changing bracket states
19+
- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Validate multi-entity rewind support
1+
Build BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION as a docs-first, sample-level, read-only server-dashboard foundation bundle with explicit host/registry/providers/renderer boundaries and bracket-only tracker state updates.

‎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_SERVER_DASHBOARD_FOUNDATION
1+
APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION

‎docs/dev/reports/change_summary.txt‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
1-
multi-entity update
1+
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION
2+
3+
Summary:
4+
- Refined the BUILD_PR doc as docs-first execution guidance for a read-only server dashboard foundation.
5+
- Added server-dashboard local documentation under `tools/dev/server-dashboard/README.md`.
6+
- Captured host, registry, providers, and renderer ownership boundaries.
7+
- Explicitly documented console/overlay decoupling and combo-key non-change requirements.
8+
- Updated tracker status using bracket-only edits in `docs/roadmaps/NETWORK_SAMPLES_PLAN.md` (Track T moved further into in-progress states).
9+
- Refreshed report artifacts and commit comment for this BUILD bundle.
10+
11+
Guardrails respected:
12+
- no engine core changes
13+
- one PR purpose only (server dashboard foundation docs)
14+
- sample-level integration rule preserved
15+
- no server-dashboard runtime implementation code in this bundle

‎docs/dev/reports/file_tree.txt‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,18 @@
1-
updated
1+
HTML-JavaScript-Gaming/
2+
docs/
3+
pr/
4+
PLAN_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION.md
5+
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION.md
6+
APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION.md
7+
dev/
8+
commit_comment.txt
9+
reports/
10+
change_summary.txt
11+
file_tree.txt
12+
validation_checklist.txt
13+
roadmaps/
14+
NETWORK_SAMPLES_PLAN.md
15+
tools/
16+
dev/
17+
server-dashboard/
18+
README.md

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,14 @@
1-
ok
1+
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION validation checklist
2+
3+
[x] PLAN/BUILD/APPLY discipline is preserved in docs set
4+
[x] BUILD doc is docs-first and one-purpose
5+
[x] Host responsibility documented
6+
[x] Registry responsibility documented
7+
[x] Providers responsibility documented
8+
[x] Renderer responsibility documented
9+
[x] Console/overlay decoupling explicitly documented
10+
[x] Combo keys explicitly unchanged by contract
11+
[x] No engine-core changes included
12+
[x] Tracker update performed via bracket-only edits
13+
[x] Reports updated under docs/dev/reports
14+
[x] Bundle package target set to tmp/BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION_delta.zip

‎docs/pr/APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION
2+
3+
## Purpose
4+
Apply the approved server dashboard foundation with surgical sample-level changes only.
5+
6+
## Apply Rules
7+
- Preserve existing console behavior
8+
- Preserve existing overlay behavior
9+
- Preserve existing combo keys
10+
- Do not refactor unrelated network code
11+
- Do not introduce new feature scope
12+
- Keep all work under `tools/dev` plus sample wiring
13+
14+
## Ordered Apply Sequence
15+
1. Add `serverDashboardProviders.js`
16+
2. Add `serverDashboardRegistry.js`
17+
3. Add `serverDashboardRenderer.js`
18+
4. Add `serverDashboardHost.js`
19+
5. Wire sample-level dashboard bootstrap in `MultiSystemDemoScene.js`
20+
6. Run validation
21+
7. Package delta ZIP
22+
23+
## Provider Contract
24+
Providers must return normalized read-only snapshots such as:
25+
- connection/session counts
26+
- player rows
27+
- latency summary
28+
- rx/tx summaries
29+
- timestamp
30+
31+
Providers must not:
32+
- mutate runtime
33+
- register commands
34+
- write persistence
35+
- depend on overlay render state
36+
37+
## Renderer Contract
38+
Renderer must:
39+
- render summary + player rows
40+
- tolerate empty datasets
41+
- remain visually simple
42+
- avoid advanced UX controls
43+
44+
Renderer must not:
45+
- execute operator commands
46+
- mutate runtime state
47+
- own refresh logic
48+
49+
## Validation
50+
- Dashboard host starts and stops cleanly
51+
- Snapshot refresh works at the chosen interval
52+
- Renderer shows stable rows for sample data
53+
- Empty state is safe
54+
- Existing debug surfaces still work
55+
- No engine-core files changed
56+
57+
## Package Output
58+
`<project folder>/tmp/BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION_delta.zip`
59+
60+
## Next Recommended Command
61+
`APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION`

‎docs/pr/BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/06/2026
4+
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION.md
5+
6+
# BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION
7+
8+
## Build Summary
9+
Prepared a docs-first foundation bundle for a read-only server dashboard surface scoped to `tools/dev/server-dashboard`. This BUILD_PR remains one-purpose, sample-level, and does not modify engine core APIs or behavior.
10+
11+
## Workflow Discipline
12+
PLAN_PR -> BUILD_PR -> APPLY_PR
13+
14+
## Scope and Boundaries
15+
- docs-first only in this bundle
16+
- no engine core changes
17+
- no server mutation controls
18+
- no containerization/docker work
19+
- no transport implementation work
20+
- keep console and overlay decoupled from dashboard internals
21+
- keep combo keys unchanged
22+
23+
## Server Dashboard Foundation Surface
24+
### Target folder
25+
`tools/dev/server-dashboard/`
26+
27+
### Planned implementation units
28+
- `serverDashboardHost.js`
29+
- `serverDashboardRegistry.js`
30+
- `serverDashboardProviders.js`
31+
- `serverDashboardRenderer.js`
32+
33+
## Responsibility Contract
34+
### Host responsibility (`serverDashboardHost`)
35+
- own start/stop lifecycle
36+
- own refresh cadence and polling schedule
37+
- request normalized snapshots from providers
38+
- coordinate registry + renderer handoff
39+
- remain debug-only and read-only from the dashboard perspective
40+
41+
### Registry responsibility (`serverDashboardRegistry`)
42+
- register known dashboard sections
43+
- enforce deterministic section ordering
44+
- return immutable section descriptors for rendering
45+
- isolate dashboard section metadata from console/overlay plugin internals
46+
47+
### Provider responsibility (`serverDashboardProviders`)
48+
- collect read-only sample-facing telemetry snapshots
49+
- normalize connection/session/player/network summaries
50+
- expose stable payload shape for renderer consumption
51+
- forbid runtime mutation and transport write actions
52+
53+
### Renderer responsibility (`serverDashboardRenderer`)
54+
- render shell + summary rows + player rows
55+
- tolerate empty/partial datasets safely
56+
- avoid ownership of refresh, polling, or provider logic
57+
- avoid coupling to console renderer and overlay renderer internals
58+
59+
## Decoupling Rules
60+
- console and overlay remain independent debug surfaces
61+
- dashboard host must not require console open state
62+
- dashboard host must not require overlay visibility
63+
- dashboard internals are not managed by combo key handlers
64+
- existing combo key behavior stays unchanged
65+
66+
## Sample-Level Integration Rule
67+
- integration remains sample-level only
68+
- no engine-level promotion in this BUILD_PR
69+
- initial consumer/proving surface remains sample-owned wiring
70+
71+
## Validation Targets (Docs-First)
72+
- host/registry/providers/renderer ownership is explicit and non-overlapping
73+
- provider payloads are read-only by contract
74+
- dashboard flow is deterministic and polling-based
75+
- decoupling from console and overlay is explicit
76+
- combo key behavior is explicitly unchanged
77+
- no engine-core work is requested
78+
79+
## Apply Gate for Next PR
80+
APPLY_PR should only implement the documented foundation surface under `tools/dev/server-dashboard` plus sample wiring, with no scope expansion.
81+
82+
## Packaging Target
83+
`<project folder>/tmp/BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_FOUNDATION_delta.zip`

0 commit comments

Comments
 (0)