Skip to content

Commit 1aa90ea

Browse files
author
DavidQ
committed
relocate 1319 runtime mjs files to repo-level tests and add PowerShell runbook — BUILD_PR_LEVEL_12_13_SAMPLE_1319_ROOT_TESTS_AND_PS_RUNBOOK
1 parent 56e0d47 commit 1aa90ea

12 files changed

Lines changed: 291 additions & 24 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,28 @@
11
MODEL: GPT-5.4
22
REASONING: high
33
COMMAND:
4-
Move all .mjs runtime files for sample 1319 from server/ to tests/.
5-
Update all references accordingly.
6-
Do not change logic.
7-
Ensure server still runs and dashboard works.
8-
Validate sample 1319 connectivity.
9-
Update roadmap markers only if execution passes.
4+
Implement BUILD_PR_LEVEL_12_13_SAMPLE_1319_ROOT_TESTS_AND_PS_RUNBOOK exactly as defined.
5+
6+
Required changes:
7+
1. move executable runtime files:
8+
- tests/network-sample-1319/realNetworkServer.mjs
9+
- tests/network-sample-1319/realNetworkDashboard.mjs
10+
into:
11+
- tests/network-sample-1319/realNetworkServer.mjs
12+
- tests/network-sample-1319/realNetworkDashboard.mjs
13+
14+
2. keep samples/phase-13/1319/server/ for config/docs only
15+
3. update all references from sample-local tests path to repo-level tests path
16+
4. add a step-by-step PowerShell runbook for launching and validating sample 1319 from terminal
17+
5. keep docker-compose under samples/phase-13/1319/server/docker-compose.yml
18+
6. do not expand scope beyond relocation + runbook
19+
20+
Validation required:
21+
- no remaining references to sample-local runtime .mjs paths
22+
- node tests/network-sample-1319/realNetworkServer.mjs boots
23+
- sample 1319 launches from samples/index.html
24+
- dashboard loads and updates
25+
- no regressions to launcher/sample pathing
26+
27+
Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md by changing status markers only.
28+
Do not modify roadmap wording, structure, add content, or delete content.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
relocate 1319 server runtime files to tests directory — BUILD_PR_LEVEL_12_12_SAMPLE_1319_SERVER_TEST_RELOCATION
1+
relocate 1319 runtime mjs files to repo-level tests and add PowerShell runbook — BUILD_PR_LEVEL_12_13_SAMPLE_1319_ROOT_TESTS_AND_PS_RUNBOOK

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1-
- runtime files moved to tests/
2-
- references updated
3-
- no logic changes
1+
- confirmed current 1319 layout
2+
- executable runtime mjs files targeted for repo-level tests relocation
3+
- all old sample-local test references must be removed
4+
- PowerShell runbook required
5+
- launcher and dashboard validation required

‎docs/pr/BUILD_PR_LEVEL_12_10_REAL_NETWORK_SAMPLE_AND_DASHBOARD.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ This BUILD fixes that properly by requiring:
2727
- `samples/phase-13/1319/game/RealNetworkLaunchScene.js`
2828

2929
### Real Server + Dashboard
30-
- `samples/phase-13/1319/tests/realNetworkServer.mjs`
31-
- `samples/phase-13/1319/tests/realNetworkDashboard.mjs`
30+
- `tests/network-sample-1319/realNetworkServer.mjs`
31+
- `tests/network-sample-1319/realNetworkDashboard.mjs`
3232
- `samples/phase-13/1319/server/README.md`
3333
- `samples/phase-13/1319/server/docker-compose.yml`
3434

‎docs/pr/BUILD_PR_LEVEL_12_12_SAMPLE_1319_SERVER_TEST_RELOCATION.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ From:
2020
- samples/phase-13/1319/server/*.mjs
2121

2222
To:
23-
- samples/phase-13/1319/tests/*.mjs
23+
- tests/network-sample-1319/*.mjs
2424

2525
### Update References
2626
- Update ALL references to new paths

‎docs/pr/BUILD_PR_LEVEL_12_13_SAMPLE_1319_ROOT_TESTS_AND_PS_RUNBOOK.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# BUILD_PR_LEVEL_12_13_SAMPLE_1319_ROOT_TESTS_AND_PS_RUNBOOK
2+
3+
## Purpose
4+
Normalize sample 1319 runtime test placement by moving executable `.mjs` files from the sample-local tests folder to repo-level `tests/`, and add a step-by-step PowerShell runbook for launching and validating sample 1319 from terminal.
5+
6+
## One PR Purpose Only
7+
1319 runtime test relocation + PowerShell runbook only.
8+
9+
## Current Confirmed Layout
10+
```text
11+
samples/phase-13/1319/
12+
index.html
13+
main.js
14+
game/
15+
RealNetworkLaunchScene.js
16+
server/
17+
docker-compose.yml
18+
README.md
19+
tests/
20+
realNetworkDashboard.mjs
21+
realNetworkServer.mjs
22+
```
23+
24+
## Required Fix
25+
26+
### A. Move Executable Runtime Files To Repo-Level tests/
27+
Move:
28+
- `tests/network-sample-1319/realNetworkServer.mjs`
29+
- `tests/network-sample-1319/realNetworkDashboard.mjs`
30+
31+
To repo-level tests home:
32+
- `tests/network-sample-1319/realNetworkServer.mjs`
33+
- `tests/network-sample-1319/realNetworkDashboard.mjs`
34+
35+
### B. Keep Sample Folder Clean
36+
After relocation:
37+
- `samples/phase-13/1319/server/` keeps config/docs only
38+
- sample-local tests folder should no longer contain executable runtime `.mjs` files
39+
- remove the sample-local tests folder if empty after move
40+
41+
### C. Update All References
42+
Update all affected references, including:
43+
- sample 1319 docs/readme
44+
- docker or launch references if needed
45+
- any validation scripts or helper docs
46+
- any launcher/admin links that mention old sample-local test paths
47+
48+
## Required Documentation Deliverable
49+
Add a step-by-step PowerShell runbook document for 1319.
50+
51+
### Required path
52+
One of these repo docs locations is acceptable, prefer the first:
53+
- `docs/pr/NETWORK_SAMPLE_1319_POWERSHELL_RUNBOOK.md`
54+
or
55+
- `samples/phase-13/1319/server/NETWORK_SAMPLE_1319_POWERSHELL_RUNBOOK.md`
56+
57+
Use the repo docs-first workflow and keep the runbook easy to follow.
58+
59+
## Required Runbook Content
60+
The PowerShell runbook must include:
61+
62+
### 1. Start the real server from repo root
63+
Use repo-level test path, not sample-local tests path.
64+
Example target command shape:
65+
- `node tests/network-sample-1319/realNetworkServer.mjs`
66+
67+
### 2. Start a local static file host for samples
68+
From repo root using PowerShell-friendly steps.
69+
Example:
70+
- `python -m http.server 8080`
71+
72+
### 3. Open sample launcher
73+
- `http://127.0.0.1:8080/samples/index.html`
74+
75+
### 4. Open sample 1319 directly
76+
- `http://127.0.0.1:8080/samples/phase-13/1319/index.html`
77+
78+
### 5. Open dashboard
79+
Document the dashboard URL backed by the real runtime.
80+
81+
### 6. Validation steps
82+
Step-by-step user actions:
83+
- start server
84+
- open client 1
85+
- open client 2
86+
- verify connect/session
87+
- verify authoritative updates
88+
- disconnect/reconnect one client
89+
- verify dashboard player/session/RTT/RX/TX updates
90+
91+
### 7. Docker section
92+
Keep docker-compose under:
93+
- `samples/phase-13/1319/server/docker-compose.yml`
94+
95+
Document PowerShell commands for:
96+
- up --build
97+
- down
98+
99+
### 8. Focused validation commands
100+
Document terminal commands from repo root for validation checks using the corrected repo-level runtime paths where needed.
101+
102+
## Important Path Correction
103+
The old command:
104+
- `node tests/network-sample-1319/realNetworkServer.mjs`
105+
106+
must be replaced with the new repo-level path.
107+
108+
## Scope Rules
109+
- no logic changes unless strictly required for moved path resolution
110+
- no runtime behavior changes
111+
- no feature expansion
112+
- no 3D work
113+
- no broad sample cleanup beyond this relocation/documentation slice
114+
115+
## Validation Requirements
116+
117+
### Path Validation
118+
- no remaining references to sample-local runtime `.mjs` paths
119+
- repo-level test paths resolve correctly
120+
121+
### Runtime Validation
122+
- `node tests/network-sample-1319/realNetworkServer.mjs` starts successfully
123+
- sample 1319 still connects correctly
124+
- dashboard still loads and updates
125+
126+
### Regression Validation
127+
- `samples/index.html` still launches 1319
128+
- no breakage to other samples from path/documentation changes
129+
130+
## Roadmap Rule
131+
Update:
132+
`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
133+
134+
Allowed:
135+
- status markers only: `[ ]` `[.]` `[x]`
136+
137+
Forbidden:
138+
- wording edits
139+
- structure edits
140+
- additions
141+
- deletions
142+
143+
## Acceptance Criteria
144+
- executable `.mjs` files moved to repo-level `tests/`
145+
- all references updated
146+
- PowerShell runbook added
147+
- sample 1319 still launches from `samples/index.html`
148+
- server and dashboard still run correctly
149+
- roadmap updated by marker only if execution-backed validation passes

‎docs/pr/NETWORK_SAMPLE_1319_POWERSHELL_RUNBOOK.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# NETWORK SAMPLE 1319 POWERSHELL RUNBOOK
2+
3+
## Scope
4+
Launch and validate sample 1319 real-network runtime from PowerShell using repo-level runtime paths.
5+
6+
## Preconditions
7+
- Run from repo root: `c:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming`
8+
- Node.js and Python are installed.
9+
10+
## 1) Start Real Server (Terminal A)
11+
```powershell
12+
cd c:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming
13+
node tests/network-sample-1319/realNetworkServer.mjs
14+
```
15+
16+
Expected startup output includes:
17+
- `NETWORK_SAMPLE_1319_SERVER_READY`
18+
- WebSocket URL
19+
- dashboard and health URLs
20+
21+
## 2) Start Static Sample Host (Terminal B)
22+
```powershell
23+
cd c:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming
24+
python -m http.server 8080
25+
```
26+
27+
## 3) Open Launcher
28+
- `http://127.0.0.1:8080/samples/index.html`
29+
30+
Confirm Sample 1319 appears in the launcher list.
31+
32+
## 4) Open Sample 1319 Directly
33+
- `http://127.0.0.1:8080/samples/phase-13/1319/index.html`
34+
35+
Keep endpoint as:
36+
- `ws://127.0.0.1:4320/ws`
37+
38+
## 5) Open Dashboard
39+
- `http://127.0.0.1:4320/admin/network-sample-1319/dashboard`
40+
41+
## 6) Step-by-Step Live Validation
42+
1. In sample tab 1, click `Connect`.
43+
2. Open a second 1319 tab and click `Connect`.
44+
3. Confirm both clients join the same live session.
45+
4. Move one client with `WASD` or arrow keys.
46+
5. Confirm authoritative state updates are visible on both tabs.
47+
6. Disconnect one client, then reconnect it.
48+
7. In dashboard, verify updates for:
49+
- active players
50+
- sessions
51+
- RTT
52+
- RX bytes
53+
- TX bytes
54+
- per-player status rows
55+
56+
## 7) Docker (Compose File Stays Under Sample Server Folder)
57+
Compose path:
58+
- `samples/phase-13/1319/server/docker-compose.yml`
59+
60+
Bring up:
61+
```powershell
62+
cd c:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming
63+
docker compose -f samples/phase-13/1319/server/docker-compose.yml up --build
64+
```
65+
66+
Bring down:
67+
```powershell
68+
cd c:\Users\davidq\Documents\GitHub\HTML-JavaScript-Gaming
69+
docker compose -f samples/phase-13/1319/server/docker-compose.yml down
70+
```
71+
72+
## 8) Focused Validation Commands
73+
From repo root:
74+
```powershell
75+
node tmp/validate_1319.mjs
76+
node tests/runtime/LaunchSmokeAllEntries.test.mjs
77+
node tests/final/MultiplayerNetworkingStack.test.mjs
78+
node tests/final/NetworkDebugAndServerDashboardCloseout.test.mjs
79+
node tests/core/Engine2DCapabilityCombinedFoundation.test.mjs
80+
node tests/core/EngineCoreBoundaryBaseline.test.mjs
81+
node tests/games/AsteroidsValidation.test.mjs
82+
```

‎samples/phase-13/1319/index.html‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
-->
77
<!DOCTYPE html>
88
<html lang="en">
9+
910
<head>
1011
<meta charset="UTF-8" />
1112
<title>Sample 1319 - Real Network + Live Dashboard</title>
@@ -18,6 +19,7 @@
1819
margin: 10px 0 12px;
1920
align-items: center;
2021
}
22+
2123
.network-controls input,
2224
.network-controls button {
2325
font: 14px/1.2 monospace;
@@ -27,16 +29,19 @@
2729
background: #0f172a;
2830
color: #e2e8f0;
2931
}
32+
3033
.network-controls button {
3134
cursor: pointer;
3235
border-color: #64748b;
3336
background: #13213a;
3437
}
38+
3539
.network-links {
3640
margin: 0 0 12px;
3741
color: #cbd5e1;
3842
font: 14px/1.3 monospace;
3943
}
44+
4045
.network-links code {
4146
color: #f8fafc;
4247
background: #0f172a;
@@ -46,10 +51,23 @@
4651
}
4752
</style>
4853
</head>
54+
4955
<body>
5056
<main>
5157
<h1>Sample 1319 - Real Network + Live Dashboard</h1>
52-
<p>Minimal authoritative real-network sample. The client connects over WebSocket to a live server endpoint and renders authoritative player snapshots.</p>
58+
<p>Minimal authoritative real-network sample. The client connects over WebSocket to a live server endpoint and
59+
renders authoritative player snapshots.</p>
60+
61+
62+
63+
<p class="network-links">
64+
For this to work, you need to have the server running locally. You can start the server with
65+
<code>node tests/network-sample-1319/realNetworkServer.mjs</code> from the root of the repository.<br />
66+
</p>
67+
<p class="network-links">
68+
Server health: <code>http://127.0.0.1:4320/admin/network-sample-1319/health</code><br />
69+
Live dashboard: <code>http://127.0.0.1:4320/admin/network-sample-1319/dashboard</code>
70+
</p>
5371

5472
<div class="network-controls">
5573
<input id="server-url" type="text" value="ws://127.0.0.1:4320/ws" aria-label="WebSocket endpoint" />
@@ -59,19 +77,16 @@ <h1>Sample 1319 - Real Network + Live Dashboard</h1>
5977
<button id="network-pulse" type="button">Send Pulse</button>
6078
</div>
6179

62-
<p class="network-links">
63-
Server health: <code>http://127.0.0.1:4320/admin/network-sample-1319/health</code><br />
64-
Live dashboard: <code>http://127.0.0.1:4320/admin/network-sample-1319/dashboard</code>
65-
</p>
66-
6780
<canvas id="game" width="960" height="540"></canvas>
6881

6982
<section>
7083
<h3>Controls</h3>
71-
<p>Move with <code>WASD</code> or arrow keys. Client sends input to the authoritative server and renders real replicated snapshots.</p>
84+
<p>Move with <code>WASD</code> or arrow keys. Client sends input to the authoritative server and renders real
85+
replicated snapshots.</p>
7286
</section>
7387
</main>
7488
<script type="module" src="/samples/shared/sampleDetailPageEnhancement.js"></script>
7589
<script type="module" src="./main.js"></script>
7690
</body>
77-
</html>
91+
92+
</html>

‎samples/phase-13/1319/server/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Run a real WebSocket authoritative server for sample 1319 and expose a live dash
77
From repo root:
88

99
```bash
10-
node samples/phase-13/1319/tests/realNetworkServer.mjs
10+
node tests/network-sample-1319/realNetworkServer.mjs
1111
```
1212

1313
## Serve Sample Launcher

0 commit comments

Comments
 (0)