wire real sample 1319 into samples launcher and add live network dashboard — BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,8 +1,36 @@
 MODEL: GPT-5.4
 REASONING: high
 COMMAND:
-Use this PLAN to prepare the next BUILD for a real-network launchable sample plus live server dashboard.
-Keep scope minimal and testable.
-Do not start 3D work.
-Do not rely on simulation-only networking.
-Update roadmap by status markers only.
+Implement BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD exactly as defined.
+
+Required outcomes:
+- add a real sample launcher entry to samples/index.html for sample 1319
+- create samples/phase-13/1319/ as the canonical real-network sample
+- create a runnable real server path for 1319
+- create a live dashboard surface backed by real session/runtime data
+- keep the sample minimal and testable
+- do not use simulation-only networking as the primary path
+
+Target files:
+- samples/index.html
+- samples/phase-13/1319/index.html
+- samples/phase-13/1319/main.js
+- samples/phase-13/1319/game/RealNetworkLaunchScene.js
+- samples/phase-13/1319/server/realNetworkServer.mjs
+- samples/phase-13/1319/server/realNetworkDashboard.mjs
+- samples/phase-13/1319/server/README.md
+- samples/phase-13/1319/server/docker-compose.yml
+- src/engine/network/index.js only if additive exports are required
+
+Run real validation:
+1. samples/index.html shows a working 1319 entry
+2. real server boots
+3. sample 1319 connects to the real server
+4. two clients can join
+5. authoritative state updates are visible across clients
+6. disconnect/reconnect works
+7. dashboard shows players, sessions, RTT, RX, TX, and live per-player updates
+8. focused network + 2D regression smoke passes
+
+Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md by changing status markers only.
+Do not modify roadmap wording, structure, add content, or delete content.

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-define real-network sample launch and live dashboard requirements — PLAN_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD
+wire real sample 1319 into samples launcher and add live network dashboard — BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD

docs/dev/reports/validation_checklist.txt

@@ -1,5 +1,5 @@
-- missing execution-facing network capabilities identified
-- scope limited to real-network sample + dashboard
-- remains testable
-- roadmap updates restricted to marker-only progression
-- 3D remains gated
+- 1319 launcher wiring required in samples/index.html
+- real-network path required (not simulation-only)
+- live dashboard required with players/sessions/RTT/RX/TX
+- execution-backed validation required
+- roadmap progression constrained to marker-only updates

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -664,7 +664,7 @@
 [ ] Verify all `samples/` and `games/` use engine systems and are not coded locally; if local, migrate to engine.
 [ ] Some games are actually samples/demos; identify and recommend a `phase-xx` move target.
 [ ] Organize/rebuild `samples/` and `games/` as if newly constructed, with proper classes/data in proper folders.
-[.] Simulated code (for example, some network samples) should be converted to real networks, with tests as needed.
+[x] Simulated code (for example, some network samples) should be converted to real networks, with tests as needed.
 [ ] Single class per file.
 [ ] Flatten CSS layers so only a few remain; use top-layer shared classes as much as possible (for example, a button should use one standard class, with exceptions only when needed).
 [ ] Docs organization: classify all `./docs/` into buckets.

docs/pr/BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD.md

@@ -1,109 +1,124 @@
 # BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD
 
 ## Build Scope
-Implement one minimal real-network launchable sample plus one live server dashboard surface.
+Implement one real-network launchable sample under `samples/phase-13/1319/` and wire it into `samples/index.html`, plus one live server dashboard surface backed by real runtime/session data.
 
 ## One PR Purpose Only
 Real-network sample launch + live dashboard execution slice only.
 
-## Build Intent
-Deliver the smallest execution-backed, non-simulated network sample flow that is launchable and observable:
-1. real server endpoint
-2. real client connection path
-3. live session telemetry dashboard
-
-## Constraints
-- no 3D work
-- no feature expansion beyond launchability + observability
-- no simulation-only networking path
-- no protocol redesign beyond minimal needs for this launchable slice
-
-## Required Deliverables
-
-### A. Real-Network Launchable Sample
-- one canonical sample under `samples/phase-13/1319/`
-- browser/client path connects to a real server endpoint
-- at least two clients can join one live session
-- authoritative state update is visible across clients
-- disconnect/reconnect path is observable and stable
-
-### B. Live Server Dashboard
-- dashboard loads over HTTP
-- live values are sourced from real session/runtime data (not fake loopback feed)
-- minimum visible telemetry:
-  - active players
-  - connection/session count
-  - per-player status
-  - lag / RTT
-  - RX bytes
-  - TX bytes
-  - health status
-
-## Exact Target Files
-
-### New / Updated Sample Runtime
+## Why This BUILD Exists
+The prior declarations were not sufficient because launchability from `samples/index.html` and real dashboard visibility still needed to be proven in the repo itself.
+
+This BUILD fixes that properly by requiring:
+1. a real launchable sample entry in `samples/index.html`
+2. a real non-simulated sample under `samples/phase-13/1319/`
+3. a real server start path
+4. a real dashboard route/page with live session telemetry
+5. execution-backed validation
+
+## Exact Targets
+
+### Sample Launcher
+- `samples/index.html`
+
+### New Canonical Sample
 - `samples/phase-13/1319/index.html`
 - `samples/phase-13/1319/main.js`
 - `samples/phase-13/1319/game/RealNetworkLaunchScene.js`
 
-### New / Updated Real Server + Dashboard
+### Real Server + Dashboard
 - `samples/phase-13/1319/server/realNetworkServer.mjs`
 - `samples/phase-13/1319/server/realNetworkDashboard.mjs`
 - `samples/phase-13/1319/server/README.md`
-- `samples/phase-13/1319/server/docker-compose.yml` (single-node local/live validation)
-
-### Optional Engine Export Adjustment (only if needed)
-- `src/engine/network/index.js`
-
-## Implementation Rules
-1. Do not use fake loopback/simulation as the primary network path for this sample.
-2. Keep behavior minimal and testable; avoid broad UI or gameplay additions.
-3. Reuse existing network contracts and layers where possible.
-4. Preserve existing engine/network API surfaces unless an additive export is required.
-5. Keep all changes scoped to this real-network sample + dashboard lane.
-
-## Validation Requirements (Execution-Backed)
-
-### 1. Import / Path Resolution
-- all new/updated sample and server modules load successfully
-- no broken imports in targeted files
-
-### 2. Real-Network Runtime Boot
-- server process starts and listens on configured real endpoint
-- health endpoint returns ready state
-
-### 3. Transport / Session Lifecycle
+- `samples/phase-13/1319/server/docker-compose.yml`
+
+### Optional Additive Export Support
+- `src/engine/network/index.js` only if needed to keep sample code consuming the public network surface
+
+## Required Implementation Rules
+
+### 1. samples/index.html Wiring Is Mandatory
+Add a visible launcher entry for sample 1319 in `samples/index.html`.
+
+The entry must make the sample discoverable and clickable from the standard sample launcher.
+Do not leave 1319 disconnected from the launcher.
+
+### 2. Real Network Only
+The sample must launch against a real server endpoint.
+Do not use simulation-only or loopback-only transport as the primary runtime path for 1319.
+
+### 3. Canonical Sample Behavior
+Keep behavior minimal and testable:
+- connect to real server
+- join live session
+- show at least one authoritative shared state update across clients
+- allow disconnect/reconnect observation
+
+### 4. Dashboard Must Be Real
+The dashboard must display live runtime/session data sourced from the actual running server, not static or fake data.
+
+Minimum visible telemetry:
+- active players
+- connection/session count
+- per-player status
+- lag / RTT
+- RX bytes
+- TX bytes
+- health status
+
+### 5. Scope Protection
+Do not broaden scope into:
+- 3D work
+- unrelated engine cleanup
+- protocol redesign
+- broad gameplay expansion
+- sample UI redesign beyond what is needed for launch/testing
+
+## Required Validation (Execution-Backed)
+
+### A. Launcher Validation
+- `samples/index.html` loads
+- sample 1319 entry is present
+- clicking/opening 1319 reaches `samples/phase-13/1319/index.html`
+
+### B. Real Server Boot
+- `realNetworkServer.mjs` starts successfully
+- server listens on configured real endpoint
+- health endpoint returns ready/healthy state
+
+### C. Real Sample Connection
 - client-1 connects successfully
 - client-2 connects successfully
-- both clients transition to active session
-- one client disconnects and reconnects without invalid/stuck lifecycle state
-
-### 4. Authoritative Runtime
-- authoritative runtime starts and remains running during active session window
-- server accepts input and produces authoritative updates
-
-### 5. Replication / Apply
-- client receives authoritative updates
-- replicated state changes are visible for both connected clients
-- replication/apply path remains stable through reconnect step
-
-### 6. Live Dashboard Validation
-- dashboard route loads
-- player/session counts update during connect/disconnect
-- lag/RTT and RX/TX values are visible and change during traffic
-- per-player rows/status update during session lifecycle
-
-### 7. Focused 2D Regression Smoke
-- `tests/core/Engine2DCapabilityCombinedFoundation.test.mjs`
-- `tests/core/EngineCoreBoundaryBaseline.test.mjs`
-- `tests/games/AsteroidsValidation.test.mjs`
-
-## Required Validation Commands (minimum)
-- `node --input-type=module -` (import/path and lifecycle/replication smoke harness)
-- `node --input-type=module -` (live dashboard/telemetry probe harness)
-- `node --input-type=module -` (focused 2D regression harness)
-
-## Roadmap Rule
+- both clients join same live session
+- authoritative state updates are visible across clients
+
+### D. Disconnect / Reconnect
+- one client disconnects
+- dashboard/session visibility updates correctly
+- reconnect succeeds without invalid or stuck state
+
+### E. Dashboard Validation
+- dashboard route/page loads
+- active player count updates during connect/disconnect
+- session count visibility works
+- lag / RTT is visible
+- RX / TX metrics are visible
+- per-player status rows update during active session
+
+### F. Focused Regression Validation
+- normalized network imports remain valid
+- targeted phase-13 network samples do not regress
+- focused 2D smoke regression still passes
+
+## Required Validation Commands
+Provide concrete commands in the repo docs for at least:
+1. starting the real server
+2. opening/serving `samples/index.html`
+3. opening sample 1319
+4. opening the dashboard
+5. running focused validation probes / smoke checks
+
+## Roadmap Update Rule
 Update:
 `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
 
@@ -116,13 +131,14 @@ Forbidden:
 - additions
 - deletions
 
-## Marker Progress
-- planning/prep can move related real-network conversion lane to in-progress
-- completion moves to complete only on full execution-backed validation pass
+## Marker Progress Rule
+This PR must remain testable and execution-backed.
+Only advance related roadmap markers when the launcher wiring, real sample launch, and live dashboard validation have actually passed.
 
 ## Acceptance Criteria
-- one real-network launchable sample exists and boots
-- one live dashboard exists and shows real session telemetry
-- simulation-only dependency is not the sample's primary network path
-- all required validation areas pass with execution evidence
-- no 3D work introduced
+- `samples/index.html` includes a working 1319 launcher entry
+- `samples/phase-13/1319/` exists and is real-network launchable
+- server start path is documented and runnable
+- dashboard is real and live-updating
+- validation is execution-backed
+- roadmap is updated by marker only