feat(games): add Doom dashboard widget (Chocolate Doom WASM)

Eighth Games widget: the real Doom running in a sandboxed iframe via
the cloudflare/doom-wasm Chocolate Doom build (vendored with sha256
provenance, GPL-2 license included). The IWAD is never embedded into
the binary: it is served from disk through the new read-only
/gamedata/ route (coordinator.http_server.gamedata_dir, empty =
disabled) and provisioned with scripts/fetch-doom-wad.sh. Widget
checks WAD availability with a ranged GET that validates IWAD/PWAD
magic and shows provisioning hints when missing.

Author: adubovikov

.gitignore

@@ -73,3 +73,8 @@ bundled_extensions/
 .cursor/*
 !.cursor/rules/
 !.cursor/rules/**
+
+# Doom widget IWAD — served from disk via gamedata_dir, never committed
+# nor embedded into the binary (see scripts/fetch-doom-wad.sh)
+gamedata/
+*.wad

docs/COORDINATOR.md

@@ -192,6 +192,7 @@ Authorization **code** flow (server exchanges `code`, loads userinfo, provisions
 | `read_timeout` | int | 30 | Read timeout in seconds |
 | `write_timeout` | int | 30 | Write timeout in seconds |
 | `static_path` | string | "" | Path to UI static files (optional) |
+| `gamedata_dir` | string | "" | On-disk directory served read-only at `/gamedata/` for large game assets (Doom widget IWAD). Empty disables the route. See `docs/VOIPGames.md`. |
 
 ### nodes
 

docs/VOIPGames.md

@@ -1,6 +1,6 @@
 # Games (Homer Next-Gen dashboard)
 
-The dashboard includes seven mini-games under the **Games** category. Widgets are added from the dashboard palette (`registry.ts`: `packet_defender`, `sip_dialog_master`, `jitter_buffer_hero`, `sipetris`, `netris`, `chess`, `netchess`). Five are educational (SIP/RTP-themed) and two are general-purpose chess games. The chess pair shares one rules engine (`chess.js` on the UI, `notnil/chess` on the server) and one presentational board component (`ChessBoard.tsx`).
+The dashboard includes eight mini-games under the **Games** category. Widgets are added from the dashboard palette (`registry.ts`: `packet_defender`, `sip_dialog_master`, `jitter_buffer_hero`, `sipetris`, `netris`, `chess`, `netchess`, `doom`). Five are educational (SIP/RTP-themed), two are general-purpose chess games, and one is the actual 1993 Doom compiled to WebAssembly. The chess pair shares one rules engine (`chess.js` on the UI, `notnil/chess` on the server) and one presentational board component (`ChessBoard.tsx`).
 
 ### Default dashboards
 
@@ -312,6 +312,62 @@ JSON envelope shared with the client; constants live in `src/coordinator/games/n
 
 ---
 
+## 8. Doom (`doom`)
+
+**Concept:** the real thing — Chocolate Doom compiled to WebAssembly (the
+[cloudflare/doom-wasm](https://github.com/cloudflare/doom-wasm) build, GPL-2)
+running inside the widget. No SIP theming, no excuses.
+
+### Architecture
+
+| Piece | Where | Shipped how |
+|-------|-------|-------------|
+| Engine (`websockets-doom.js` + `.wasm`, ~2.5 MB) | `src/ui/public/game/` | Committed + embedded with the UI bundle (provenance and sha256 in `public/game/README.md`) |
+| Host page | `src/ui/public/game/index.html` | Embedded; loaded by the widget in an `<iframe>` |
+| IWAD (`doom1.wad`, ~4 MB) | On-disk `gamedata_dir`, served at `/gamedata/` | **Never embedded** into the homer-core binary; provisioned manually |
+
+The engine runs in an iframe because Emscripten/SDL2 builds pollute window
+globals and cannot be torn down cleanly — removing the iframe (the Stop
+button or deleting the widget) is the teardown. Widget and host page talk
+over same-origin `postMessage` (`doomWad.ts` validates the frames).
+
+### WAD provisioning
+
+The shareware `doom1.wad` is freely distributable but deliberately kept out
+of the repo, the UI bundle, and the `go:embed` binary. On the coordinator
+host:
+
+```bash
+./scripts/fetch-doom-wad.sh /usr/local/homer-core/gamedata
+```
+
+then set the config and restart:
+
+```json
+{ "coordinator": { "http_server": { "gamedata_dir": "/usr/local/homer-core/gamedata" } } }
+```
+
+Any IWAD/PWAD named `doom1.wad` in that directory works (full Doom,
+Freedoom Phase 1 renamed — note vanilla visplane limits apply). If the WAD
+or the route is missing, the widget shows provisioning instructions instead
+of starting. The download happens once per page load with a progress bar;
+afterwards the browser HTTP cache applies.
+
+### Controls
+
+Standard Chocolate Doom bindings: arrows move, **Ctrl** fire, **Space**
+use, **ESC** in-game menu (which is also the pause). Click the game screen
+first so the iframe has keyboard focus. The header has **Fullscreen** and
+**Stop** buttons; music is disabled (`-nomusic`), sound effects work after
+the first user gesture (the Start click satisfies autoplay policy).
+
+### Dev mode
+
+`vite.config.ts` proxies `/gamedata` to the coordinator, mirroring `/api` —
+run a coordinator with `gamedata_dir` set, or expect the WAD-missing hint.
+
+---
+
 ## Source locations
 
 | Game | File |
@@ -323,6 +379,7 @@ JSON envelope shared with the client; constants live in `src/coordinator/games/n
 | Netris | `src/ui/src/dashboard/widgets/NetrisPanel.tsx` |
 | Chess | `src/ui/src/dashboard/widgets/ChessPanel.tsx` |
 | NetChess | `src/ui/src/dashboard/widgets/NetChessPanel.tsx` |
+| Doom | `src/ui/src/dashboard/widgets/DoomPanel.tsx`, `doomWad.ts`, `src/ui/public/game/` |
 | Widget registration | `src/ui/src/dashboard/widgets/registry.ts` |
 
-The single-player widgets (Packet Defender, SIP Dialog Master, Jitter Buffer Hero, SIPetris, Chess in bot mode) are **not** wired to live Homer capture; they are **local dashboard UI** only. **Netris** and **NetChess** talk to homer-core's coordinator over JWT-protected WebSockets (`/api/v4/games/netris`, `/api/v4/games/netchess`); the **Chess LLM mode** also relies on the coordinator (`/api/v4/games/chess/llm-{status,move}`). None of these endpoints consume captured traffic.
+The single-player widgets (Packet Defender, SIP Dialog Master, Jitter Buffer Hero, SIPetris, Chess in bot mode, Doom) are **not** wired to live Homer capture; they are **local dashboard UI** only. **Netris** and **NetChess** talk to homer-core's coordinator over JWT-protected WebSockets (`/api/v4/games/netris`, `/api/v4/games/netchess`); the **Chess LLM mode** also relies on the coordinator (`/api/v4/games/chess/llm-{status,move}`); **Doom** only fetches its IWAD from the static `/gamedata/` route. None of these endpoints consume captured traffic.

scripts/fetch-doom-wad.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Download the shareware doom1.wad for the dashboard Doom widget.
+#
+# The WAD is served at runtime by the coordinator's /gamedata/ route
+# (config key `gamedata_dir`) and is deliberately kept out of the UI
+# build so it never gets embedded into the homer-core binary.
+#
+# Usage: ./scripts/fetch-doom-wad.sh [target_dir]   (default: ./gamedata)
+set -euo pipefail
+
+TARGET_DIR="${1:-./gamedata}"
+WAD="${TARGET_DIR}/doom1.wad"
+
+# Shareware DOOM1.WAD v1.9 (freely distributable per the original
+# shareware license). Same copy the cloudflare/doom-wasm demo uses.
+URL="https://silentspacemarine.com/doom1.wad"
+SHA256="1d7d43be501e67d927e415e0b8f3e29c3bf33075e859721816f652a526cac771"
+
+if [ -f "${WAD}" ]; then
+    if echo "${SHA256}  ${WAD}" | sha256sum -c --quiet - 2>/dev/null; then
+        echo "OK: ${WAD} already present and checksum matches."
+        exit 0
+    fi
+    echo "WARN: ${WAD} exists but checksum differs (custom WAD?) — leaving it untouched."
+    exit 0
+fi
+
+mkdir -p "${TARGET_DIR}"
+echo "Downloading shareware doom1.wad -> ${WAD}"
+curl -fSL --max-time 300 "${URL}" -o "${WAD}.tmp"
+
+echo "${SHA256}  ${WAD}.tmp" | sha256sum -c --quiet - || {
+    echo "ERROR: checksum mismatch, removing download." >&2
+    rm -f "${WAD}.tmp"
+    exit 1
+}
+mv "${WAD}.tmp" "${WAD}"
+echo "OK: $(ls -la "${WAD}" | awk '{print $5}') bytes. Set coordinator gamedata_dir to $(cd "${TARGET_DIR}" && pwd)"

src/config/config.go

@@ -708,6 +708,10 @@ type CoordinatorHTTPServerConfig struct {
 	ReadTimeout  int    `json:"read_timeout" mapstructure:"read_timeout" default:"30"`
 	WriteTimeout int    `json:"write_timeout" mapstructure:"write_timeout" default:"30"`
 	StaticPath   string `json:"static_path" mapstructure:"static_path" default:""`
+	// GamedataDir is an on-disk directory served read-only at /gamedata/.
+	// Used for large game assets (e.g. the Doom widget IWAD) that must not
+	// be embedded into the binary via go:embed. Empty = route disabled.
+	GamedataDir string `json:"gamedata_dir" mapstructure:"gamedata_dir" default:""`
 }
 
 // NodeEndpoint defines a FlightSQL node to query

src/coordinator/coordinator.go

@@ -570,6 +570,15 @@ func mapNodeEndpoints(nodes []config.NodeEndpoint) []handlers.NodeInfo {
 func (c *Coordinator) setupStaticRoutes() {
 	staticPath := c.config.HTTPServer.StaticPath
 
+	// Large on-disk game assets (e.g. the Doom widget IWAD) are served from
+	// gamedata_dir and intentionally kept out of the embedded UI bundle so
+	// they never inflate the binary. Registered before the SPA handlers so
+	// /gamedata/* never falls through to index.html.
+	if dir := c.config.HTTPServer.GamedataDir; dir != "" {
+		logger.Info("Coordinator: Serving game data from filesystem", "path", dir)
+		c.echo.Static("/gamedata", dir)
+	}
+
 	// Serve from filesystem if static_path is configured
 	if staticPath != "" {
 		logger.Info("Coordinator: Serving UI from filesystem", "path", staticPath)

src/coordinator/gamedata_test.go

@@ -0,0 +1,77 @@
+package coordinator
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/labstack/echo/v4"
+	"github.com/sipcapture/homer-core/src/config"
+)
+
+// newStaticTestCoordinator builds the minimal Coordinator needed to
+// exercise setupStaticRoutes (no DB, no services).
+func newStaticTestCoordinator(httpCfg config.CoordinatorHTTPServerConfig) *Coordinator {
+	return &Coordinator{
+		config: &config.CoordinatorConfig{HTTPServer: httpCfg},
+		echo:   echo.New(),
+	}
+}
+
+func TestGamedataRouteServesWadFromDisk(t *testing.T) {
+	dir := t.TempDir()
+	wad := []byte("IWAD\x00\x00\x00\x00fake")
+	if err := os.WriteFile(filepath.Join(dir, "doom1.wad"), wad, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	c := newStaticTestCoordinator(config.CoordinatorHTTPServerConfig{GamedataDir: dir})
+	c.setupStaticRoutes()
+
+	rec := httptest.NewRecorder()
+	c.echo.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/gamedata/doom1.wad", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("expected 200 for existing wad, got %d", rec.Code)
+	}
+	if got := rec.Body.String(); got != string(wad) {
+		t.Fatalf("wad bytes mismatch: %q", got)
+	}
+
+	rec = httptest.NewRecorder()
+	c.echo.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/gamedata/missing.wad", nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("expected 404 for missing file, got %d", rec.Code)
+	}
+}
+
+func TestGamedataRouteDisabledWhenDirUnset(t *testing.T) {
+	c := newStaticTestCoordinator(config.CoordinatorHTTPServerConfig{})
+	c.setupStaticRoutes()
+
+	rec := httptest.NewRecorder()
+	c.echo.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/gamedata/doom1.wad", nil))
+	if rec.Code == http.StatusOK {
+		t.Fatalf("expected non-200 when gamedata_dir is unset, got %d", rec.Code)
+	}
+}
+
+func TestGamedataRouteRejectsPathTraversal(t *testing.T) {
+	dir := t.TempDir()
+	secret := filepath.Join(dir, "..", "secret.txt")
+	if err := os.WriteFile(secret, []byte("nope"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Remove(secret) })
+
+	c := newStaticTestCoordinator(config.CoordinatorHTTPServerConfig{GamedataDir: dir})
+	c.setupStaticRoutes()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/gamedata/../secret.txt", nil)
+	c.echo.ServeHTTP(rec, req)
+	if rec.Code == http.StatusOK && rec.Body.String() == "nope" {
+		t.Fatal("path traversal escaped gamedata_dir")
+	}
+}