build(network-sample-b): implement host/client diagnostics sample with read-only debug panels and commands

DavidQ · DavidQ · commit 094aa7f5002e · 2026-04-06T11:43:23.000-04:00
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,8 +1,8 @@
 MODEL: GPT-5.4-codex
-REASONING: medium
+REASONING: high
 
 COMMAND:
-Create PR_DEBUG_SURFACES_NETWORK_SERVER_CONTAINER_FULL
+Create PR_DEBUG_SURFACES_NETWORK_SAMPLE_B_FULL
 
 PURPOSE:
-Implement Track U � Docker containerization for the network server and dashboard.
+Implement Sample B � Host / Client Diagnostics to simulate multi-role network behavior using the existing debug surface system.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1 +1 @@
-build(network-dashboard): implement Track U containerization for Sample A server dashboard
+build(network-sample-b): implement host/client diagnostics sample with read-only debug panels and commands
diff --git a/docs/dev/NETWORK_SAMPLES_PLAN.md b/docs/dev/NETWORK_SAMPLES_PLAN.md
@@ -25,12 +25,12 @@ Track the staged network sample journey for debug surface support using a strict
 
 # TRACK O — HOST / CLIENT SAMPLE
 
-- [ ] Sample B — Host / Client Diagnostics
-- [ ] Host status panel data
-- [ ] Client status panel data
-- [ ] Authority / ownership visibility
-- [ ] Replication snapshot visibility
-- [ ] Divergence warning surface
+- [x] Sample B — Host / Client Diagnostics
+- [x] Host status panel data
+- [x] Client status panel data
+- [x] Authority / ownership visibility
+- [x] Replication snapshot visibility
+- [x] Divergence warning surface
 
 ---
 
diff --git a/docs/dev/NEXT_COMMAND.txt b/docs/dev/NEXT_COMMAND.txt
@@ -1 +1 @@
-PR_DEBUG_SURFACES_NETWORK_SAMPLE_B_FULL
+PR_DEBUG_SURFACES_NETWORK_SERVER_OPS_FULL
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,16 +1,15 @@
-Implemented PR_DEBUG_SURFACES_NETWORK_SERVER_CONTAINER_FULL (Track U).
+Implemented PR_DEBUG_SURFACES_NETWORK_SAMPLE_B_FULL.
 
 Delivered:
-- Added container runtime artifacts for the Sample A dashboard server.
-- Added `games/network_sample_a/server/Dockerfile` with healthcheck and minimal runtime image.
-- Added `games/network_sample_a/.dockerignore` to keep context small and focused.
-- Added optional compose service at `games/network_sample_a/server/docker-compose.yml`.
-- Updated server access contract with opt-in `NETWORK_SAMPLE_A_ALLOW_REMOTE_WITH_KEY=1` for containerized browser access.
-- Updated server README with docker build/run, compose usage, env contract, port mapping, readiness, and logging expectations.
-- Updated Track U checklist to complete in `docs/dev/NETWORK_SAMPLES_PLAN.md`.
+- Added `games/network_sample_b` sample with host/client fake peer simulation.
+- Added read-only debug plugin panels for host status, client status, ownership/authority, and replication snapshots.
+- Added operator commands `network.connections` and `network.replication` (plus sample help listing).
+- Integrated Sample B into `games/index.html` under Level 11 with Debug Showcase consistency.
+- Added Sample B preview asset and standalone sample entry page.
+- Updated Track O checklist items to complete in `docs/dev/NETWORK_SAMPLES_PLAN.md`.
 
 Scope preserved:
 - no engine/core changes
-- no orchestration stack work
-- no dashboard feature expansion outside container access compatibility
-- BIG_PICTURE_ROADMAP not modified
+- no real networking transport implementation
+- no server/dashboard changes
+- no required edits to BIG_PICTURE_ROADMAP.md
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,15 +1,17 @@
-docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SERVER_CONTAINER.md
-docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SERVER_CONTAINER.md
-docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SERVER_CONTAINER.md
+docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
+docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
+docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
 docs/dev/CODEX_COMMANDS.md
 docs/dev/COMMIT_COMMENT.txt
 docs/dev/NEXT_COMMAND.txt
 docs/dev/NETWORK_SAMPLES_PLAN.md
 docs/dev/reports/change_summary.txt
 docs/dev/reports/file_tree.txt
 docs/dev/reports/validation_checklist.txt
-games/network_sample_a/server/Dockerfile
-games/network_sample_a/.dockerignore
-games/network_sample_a/server/docker-compose.yml
-games/network_sample_a/server/networkSampleADashboardServer.mjs
-games/network_sample_a/server/README.md
+games/network_sample_b/index.html
+games/network_sample_b/main.js
+games/network_sample_b/game/FakeHostClientNetworkModel.js
+games/network_sample_b/game/NetworkSampleBScene.js
+games/network_sample_b/debug/networkSampleBDebug.js
+games/network_sample_b/assets/preview.svg
+games/index.html
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -3,26 +3,25 @@ Workflow
 - [x] BUILD created
 - [x] APPLY created
 
-Track U Implementation
-- [x] Dockerfile for server
-- [x] .dockerignore added for sample context
-- [x] Environment variable contract documented
-- [x] Local run command documented
-- [x] Compose-ready service definition added
-- [x] Port mapping rules documented
-- [x] Health/readiness check implemented
-- [x] Logging/output expectations documented
-- [x] Container debug notes documented
+Sample B Implementation
+- [x] host/client role simulation added
+- [x] multi-peer provider snapshot support added
+- [x] host status panel added
+- [x] client status panel added
+- [x] ownership/authority panel added
+- [x] replication snapshots panel added
+- [x] network.connections command added
+- [x] network.replication command added
+- [x] Sample B integrated in games/network_sample_b
+- [x] Sample B card added under Level 11 in games/index.html
 
-Safety
-- [x] no engine changes
-- [x] no orchestration scope expansion
-- [x] Sample A dashboard behavior preserved
-- [x] BIG_PICTURE_ROADMAP.md unchanged
+Roadmap/Docs
+- [x] Track O items updated to [x] in docs/dev/NETWORK_SAMPLES_PLAN.md
+- [x] BIG_PICTURE_ROADMAP.md not modified
 
 Validation Runs
-- [x] node --check games/network_sample_a/server/networkSampleADashboardServer.mjs
-- [x] local node server health endpoint returns 200
-- [x] local node server authorized metrics endpoint returns 200
-- [x] docker artifact syntax checked (Dockerfile + compose present)
-- [x] docker image build/run validation skipped in this environment (Docker CLI unavailable)
+- [x] node --check games/network_sample_b/main.js
+- [x] node --check games/network_sample_b/game/FakeHostClientNetworkModel.js
+- [x] node --check games/network_sample_b/game/NetworkSampleBScene.js
+- [x] node --check games/network_sample_b/debug/networkSampleBDebug.js
+- [x] static check of Level 11 card links for Sample B in games/index.html
diff --git a/docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md b/docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
@@ -0,0 +1,35 @@
+Toolbox Aid
+David Quesenberry
+04/06/2026
+APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
+
+# APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B
+
+## Apply Scope
+Apply Sample B host/client diagnostics implementation exactly as built.
+
+## In Scope Files
+- `games/network_sample_b/index.html`
+- `games/network_sample_b/main.js`
+- `games/network_sample_b/game/FakeHostClientNetworkModel.js`
+- `games/network_sample_b/game/NetworkSampleBScene.js`
+- `games/network_sample_b/debug/networkSampleBDebug.js`
+- `games/network_sample_b/assets/preview.svg`
+- `games/index.html` (Level 11 card/list integration)
+- `docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md`
+- `docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md`
+- `docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md`
+- `docs/dev/NETWORK_SAMPLES_PLAN.md` (Track O bracket updates)
+- docs/dev control/report files for this bundle
+
+## Validation
+- `node --check` passes for all new/changed Sample B JS files.
+- Sample B debug plugin commands return structured output:
+  - `network.connections`
+  - `network.replication`
+- Sample B card appears under Level 11 in `games/index.html` with Play/Debug links.
+- Track O checklist is updated to `[x]`.
+- `BIG_PICTURE_ROADMAP.md` remains unchanged unless explicitly validated and updated.
+
+## Output
+`<project folder>/tmp/PR_DEBUG_SURFACES_NETWORK_SAMPLE_B_FULL_bundle.zip`
diff --git a/docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md b/docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
@@ -0,0 +1,50 @@
+Toolbox Aid
+David Quesenberry
+04/06/2026
+BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
+
+# BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B
+
+## Build Summary
+Implemented Sample B host/client diagnostics using sample-owned fake peer simulation and existing debug surface infrastructure.
+
+## Implemented
+1. Sample B runtime and simulation
+- `games/network_sample_b/game/FakeHostClientNetworkModel.js`
+- `games/network_sample_b/game/NetworkSampleBScene.js`
+- simulates host/client peers with deterministic connection transitions
+- captures peer-level latency, replication, tx/rx bytes, and ownership context
+
+2. Debug plugin integration
+- `games/network_sample_b/debug/networkSampleBDebug.js`
+- read-only providers for peer, ownership, and replication snapshot data
+- panels:
+  - host status
+  - client status
+  - ownership / authority
+  - replication snapshots
+- commands:
+  - `network.connections`
+  - `network.replication`
+
+3. Sample B entrypoint and page
+- `games/network_sample_b/main.js`
+- `games/network_sample_b/index.html`
+- follows existing debug showcase behavior: overlay hidden by default, combo-key driven toggle
+
+4. Sample B preview asset
+- `games/network_sample_b/assets/preview.svg`
+
+5. Games hub integration
+- updated `games/index.html` Level 11 playable section with Sample B card and Play/Debug links
+- updated Level 11 progression list with Sample B Debug Showcase label
+
+6. Roadmap/checklist updates
+- updated Track O items in `docs/dev/NETWORK_SAMPLES_PLAN.md` to complete
+- no required changes to `docs/dev/BIG_PICTURE_ROADMAP.md`
+
+## Scope Safety
+- no engine/core changes
+- no real networking transport work
+- no server/dashboard expansion
+- sample-driven and read-only diagnostics only
diff --git a/docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md b/docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
@@ -0,0 +1,47 @@
+Toolbox Aid
+David Quesenberry
+04/06/2026
+PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B.md
+
+# PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_B
+
+## Goal
+Implement Sample B host/client diagnostics as a sample-driven, read-only debug surface integration with no real networking and no engine changes.
+
+## Workflow
+PLAN_PR -> BUILD_PR -> APPLY_PR
+
+## In Scope
+- simulate host/client roles with multiple peers
+- extend sample provider data for peer snapshots
+- overlay panels:
+  - host status
+  - client status
+  - ownership / authority
+  - replication snapshots
+- commands:
+  - network.connections
+  - network.replication
+- integrate under `games/network_sample_b`
+- add Sample B entry to `games/index.html` under Level 11
+- update Track O checklist in `docs/dev/NETWORK_SAMPLES_PLAN.md`
+
+## Out Of Scope
+- real networking sockets/WebRTC
+- engine/core API changes
+- server/dashboard changes
+
+## Contracts
+- sample-owned implementation only (`games/network_sample_b`)
+- debug surfaces remain read-only and diagnostic
+- command outputs are deterministic and operator-readable
+- Sample A patterns are reused for boot flow and plugin structure
+
+## Acceptance Criteria
+- Sample B opens and runs from `/games/network_sample_b/index.html`
+- host/client diagnostic panels render via existing debug surface runtime
+- `network.connections` command returns peer connection summary + per-peer lines
+- `network.replication` command returns host/client replication snapshot lines
+- Level 11 in `games/index.html` includes Sample B card and links
+- Track O items updated to `[.]` or `[x]`
+- `BIG_PICTURE_ROADMAP.md` unchanged unless explicitly validated for optional updates
diff --git a/games/index.html b/games/index.html
@@ -254,6 +254,17 @@ <h3>Level 11 - Network Games</h3>
         <div class="showcaseCardMeta">Onboarding: Open Play first to confirm baseline loopback behavior, then open Debug Mode to inspect connection state, RTT, and trace events intentionally.</div>
       </div>
     </div>
+    <div class="card">
+      <img class="thumb" src="/games/network_sample_b/assets/preview.svg" alt="Network Sample B gameplay preview" />
+      <div class="cardBody">
+        <div class="tagRow"><span class="badge playable">Playable Now</span><span class="badge debug-showcase">Debug Showcase</span></div>
+        <div class="cardTitle">Network Sample B - Host / Client Diagnostics</div>
+        <div class="cardDesc">Host/client diagnostics simulation with multi-peer provider snapshots, ownership/authority visibility, and replication-focused debug command surfaces.</div>
+        <div class="showcaseCardMeta">Play: <a href="/games/network_sample_b/index.html">/games/network_sample_b/index.html</a> | Debug Mode: <a href="/games/network_sample_b/index.html?debug=1">/games/network_sample_b/index.html?debug=1</a></div>
+        <div class="showcaseCardMeta">Docs: <a href="/docs/release/debug_showcase_tour.md">Debug Tour</a>, <a href="/docs/release/debug_showcase_getting_started.md">Getting Started</a>.</div>
+        <div class="showcaseCardMeta">Onboarding: Start in Play to verify host/client baseline flow, then open Debug Mode for peer connection, authority, and replication inspection.</div>
+      </div>
+    </div>
   </div>
 </section>
     </section>
@@ -380,7 +391,8 @@ <h3>Level 10 - Full Systems</h3>
           <h3>Level 11 - Network Games</h3>
           <p></p>
           <ul>
-                        <li>Network Sample A <span class="inline-status">(Debug Showcase)</span></li>
+            <li>Network Sample A <span class="inline-status">(Debug Showcase)</span></li>
+            <li>Network Sample B <span class="inline-status">(Debug Showcase)</span></li>
 <li>Tic Tac Toe</li>
             <li>Connect Four</li>
             <li>Othello</li>
diff --git a/games/network_sample_a/server/DOCKER_SETUP.md b/games/network_sample_a/server/DOCKER_SETUP.md
@@ -0,0 +1,46 @@
+# Setting Up Docker via VS Code Extensions
+
+This guide covers how to install, configure, and manage Docker entirely through the Visual Studio Code interface.
+
+## 1. Install the Official Extension
+1. Open **VS Code**.
+2. Go to the **Extensions** view (`Ctrl+Shift+X`).
+3. Search for **"Docker"** (published by Microsoft).
+4. Click **Install**.
+
+## 2. System Installation via VS Code
+If Docker is not yet installed on your computer, the extension provides shortcuts:
+* **The Whale Icon:** Click the Docker icon in the Activity Bar. If Docker isn't found, it will display a button: **"Get Docker Desktop"**.
+* **Command Palette:** Press `Ctrl+Shift+P` and type `Docker: Help`. This will lead you to official documentation for your specific OS.
+
+> **Note:** You must still run the Docker Desktop installer once it downloads to enable the background engine.
+
+## 3. Configure Your Project
+You don't need to write a `Dockerfile` manually. The extension can do it for you:
+1. Open your project folder in VS Code.
+2. Press `Ctrl+Shift+P` and type **"Docker: Add Docker Files to Workspace"**.
+3. Select your application platform (Node.js, Python, Go, etc.).
+4. Choose the port your app uses.
+5. The extension will automatically generate:
+   - `Dockerfile`
+   - `.dockerignore`
+   - `docker-compose.yml` (optional)
+
+## 4. Managing Containers (No Terminal Required)
+Use the **Docker Tab** (Whale Icon) in the sidebar to manage your workflow visually:
+
+
+| Task | Action in VS Code |
+| :--- | :--- |
+| **Build Image** | Right-click your `Dockerfile` in the Explorer -> **Build Image**. |
+| **Run Container** | In the **Images** pane, right-click an image -> **Run**. |
+| **Stop/Restart** | In the **Containers** pane, right-click a running container -> **Stop** or **Restart**. |
+| **View Logs** | Right-click a container -> **View Logs** (opens a dedicated output window). |
+| **Enter Terminal** | Right-click a container -> **Attach Shell** (opens a terminal *inside* the container). |
+
+## 5. Pro Tip: Dev Containers
+For a "Zero-Install" local setup, install the **Dev Containers** extension.
+1. Press `Ctrl+Shift+P` -> **Dev Containers: Add Dev Container Configuration Files...**
+2. Choose your tech stack.
+3. VS Code will prompt you to **"Reopen in Container"**. 
+4. Your entire VS Code environment (extensions, themes, and tools) will now run inside Docker.
diff --git a/games/network_sample_b/assets/preview.svg b/games/network_sample_b/assets/preview.svg
@@ -0,0 +1,42 @@
+<!--
+Toolbox Aid
+David Quesenberry
+04/06/2026
+preview.svg
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 540" role="img" aria-labelledby="title desc">
+  <title id="title">Network Sample B Debug Showcase</title>
+  <desc id="desc">Host and client diagnostics preview with ownership and replication status.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0%" stop-color="#09142a" />
+      <stop offset="100%" stop-color="#12355a" />
+    </linearGradient>
+  </defs>
+
+  <rect width="960" height="540" fill="url(#bg)" />
+  <rect x="40" y="40" width="880" height="460" rx="16" fill="#0d1f35" stroke="#4a7bb0" stroke-width="2" />
+
+  <text x="72" y="92" fill="#e6f3ff" font-size="34" font-family="monospace" font-weight="700">NETWORK SAMPLE B</text>
+  <text x="72" y="124" fill="#9fc7eb" font-size="18" font-family="monospace">Host / Client Diagnostics</text>
+
+  <rect x="72" y="154" width="390" height="148" rx="10" fill="#0f2238" stroke="#4e78a4" />
+  <text x="92" y="184" fill="#d4edff" font-size="17" font-family="monospace">Host: connected</text>
+  <text x="92" y="212" fill="#d4edff" font-size="17" font-family="monospace">Client A: connected</text>
+  <text x="92" y="240" fill="#f9c74f" font-size="17" font-family="monospace">Client B: synchronizing</text>
+  <text x="92" y="268" fill="#d4edff" font-size="17" font-family="monospace">Connections: 3 peers</text>
+
+  <rect x="496" y="154" width="392" height="148" rx="10" fill="#0f2238" stroke="#4e78a4" />
+  <text x="516" y="184" fill="#d4edff" font-size="17" font-family="monospace">Authority</text>
+  <text x="516" y="212" fill="#9fc7eb" font-size="15" font-family="monospace">world-clock -&gt; host-1</text>
+  <text x="516" y="236" fill="#9fc7eb" font-size="15" font-family="monospace">ship-alpha -&gt; client-a</text>
+  <text x="516" y="260" fill="#9fc7eb" font-size="15" font-family="monospace">ship-bravo -&gt; client-b</text>
+
+  <rect x="72" y="336" width="816" height="126" rx="10" fill="#0f2238" stroke="#4e78a4" />
+  <text x="92" y="372" fill="#b6defe" font-size="16" font-family="monospace">network.connections | network.replication</text>
+  <text x="92" y="398" fill="#b6defe" font-size="16" font-family="monospace">Shift + ` : Console | Ctrl + Shift + ` : Overlay</text>
+  <text x="92" y="424" fill="#b6defe" font-size="16" font-family="monospace">Level 11 Network host/client simulation</text>
+
+  <circle cx="840" cy="86" r="14" fill="#14b8a6" />
+  <text x="72" y="496" fill="#7fa9d0" font-size="14" font-family="monospace">/games/network_sample_b/index.html</text>
+</svg>
diff --git a/games/network_sample_b/debug/networkSampleBDebug.js b/games/network_sample_b/debug/networkSampleBDebug.js
diff --git a/games/network_sample_b/game/FakeHostClientNetworkModel.js b/games/network_sample_b/game/FakeHostClientNetworkModel.js
diff --git a/games/network_sample_b/game/NetworkSampleBScene.js b/games/network_sample_b/game/NetworkSampleBScene.js
diff --git a/games/network_sample_b/index.html b/games/network_sample_b/index.html
diff --git a/games/network_sample_b/main.js b/games/network_sample_b/main.js

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-build(network-dashboard): implement Track U containerization for Sample A server dashboard`
	`1`	`+build(network-sample-b): implement host/client diagnostics sample with read-only debug panels and commands`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-PR_DEBUG_SURFACES_NETWORK_SAMPLE_B_FULL`
	`1`	`+PR_DEBUG_SURFACES_NETWORK_SERVER_OPS_FULL`