docker-dosbox-novnc/TODO.md

# TODO

- ~~Reduce image size of `jayfield/dosbox-novnc` (currently ~2.3GB).~~ Done in two steps:
  1. Merged the game download/extract steps and the unzip/smbclient install into a single
     layer (so the downloaded zips and the packages only needed to extract them no longer
     persist in the final image). 2.31GB -> 1.6GB.
  2. Stopped baking the games into the image at all (927MB of that was just t7g's two CD
     ISOs). `run.sh` mounts a named volume (`dosbox-games`) so installed games persist
     across `--rm` restarts. 1.6GB -> ~690MB. Container now needs network access to
     `vlda-01` at runtime (not just build time) to install games.
  3. Dropped the auto-download at container startup entirely. `scripts/setup_server.py` is
     a small stdlib-only HTTP server that serves an HTML page on `${SETUP_PORT}`
     (`70${DISPLAY_NUM}`, published as `7099` by `run.sh`) listing every `*.zip` on the SMB
     share with an Installed/Install status per game; the user clicks "Install" to
     fetch+extract a specific game into `${GAMES_HOME}` on demand.

- **Manifest-driven games + Start/Stop/Uninstall**: games are no longer discovered from raw
  `*.zip` files on the share. `setup_server.py` lists `*.json` manifests instead (one per
  game, in the `Games\dosbox\` catalog directory), each declaring
  `name`/`title`/`zip_path`/`start_cmd`. The web page grew Start/Stop/Uninstall buttons
  alongside Install, driven entirely by that manifest — nothing about a game's identity or
  how to run it is hardcoded in the image anymore. Started as a `stuntcar`-only pilot, now
  extended to 6 games (see the SCUMM item below). `t7g` still has no manifest and won't show
  up in the setup page until one is added (`t7g.json` with a `start_cmd` for its
  `dosbox-0.74-3.conf`). `game.sh`/`scripts/start_game.sh` (the old `docker exec`-based
  launch path, with its hardcoded `DOSBOX_VERSION`/`run.bat` convention) were intentionally
  left untouched during the pilot and still overlap with the new Start button — worth
  reconciling (or removing) once every remaining game has a manifest.

- ~~Create manifests for SCUMM engine games~~ Done: `scummvm` added to the Dockerfile
  (`/usr/games/scummvm`, not on `$PATH` by default under a non-login shell — manifests use
  the absolute path). Manifests live in the usual `Games\dosbox\*.json` catalog directory on
  the share, but their `zip_path` now points at wherever the game's zip actually already
  lived (`Games\Monkey Island\...`, `Games\Indiana Jones\...`, etc.) — this required
  generalizing the manifest schema from a bare `zip` filename (implicitly under
  `Games\dosbox\`) to a full `zip_path` relative to the share root, since these games weren't
  colocated with dosbox's. Added and verified end-to-end (install/start/stop/uninstall) via
  `monkey2`:
  - `monkey` — The Secret of Monkey Island
  - `monkey2` — Monkey Island 2: LeChuck's Revenge
  - `atlantis` — Indiana Jones and the Fate of Atlantis
  - `indy3` — Indiana Jones and the Last Crusade
  - `tentacle` — Day of the Tentacle

  Skipped the German CD release of Day of the Tentacle on the share (`Day Of The Tentacle
  (CD DOS, German).zip`) — unlike every other zip here, it doesn't wrap its contents in a
  single top-level folder (loose files at the zip root plus a stray `MANIAC/` dir for the
  embedded Maniac Mansion easter egg), so it doesn't fit the current "zip's top-level folder
  == install name" extraction convention. Also skipped Curse of Monkey Island (much larger,
  untested) — could be added the same way if wanted.

  ScummVM's own game-target IDs (`monkey`, `monkey2`, `atlantis`, `indy3`, `tentacle`)
  happened to exactly match each zip's existing top-level folder name, so no change was
  needed to the install/extraction logic itself, only to where zips are looked up from.

- ~~Handle multiple games running at once~~ Done: each running game now gets its own
  ephemeral X session (`Xvnc`+`fluxbox`+`websockify`, its own display `:90`-`:99` and noVNC
  port `8090`-`8099`) spun up by `start_game()` and torn down by `stop_game()` (or lazily on
  the next page load, if the game exited/crashed on its own) — instead of every game sharing
  one screen and fighting over focus/audio. Capped at `MAX_CONCURRENT_GAMES = 10`; starting
  an 11th game while all 10 slots are in use is refused with an error shown on its row rather
  than silently doing nothing. There is no more a single shared "default" desktop or global
  noVNC link — `server.sh` no longer starts Xvnc/fluxbox/websockify at container startup at
  all, only `setup_server.py` itself; each game's own "Open Screen" link appears on its row
  only while it's running, built with a little client-side JS (the noVNC port differs from
  the setup port and can't be known server-side without knowing which hostname the browser
  used to reach the container). `run.sh` publishes the whole `8090-8099` range up front,
  since Docker can't add port mappings to an already-running container. Verified end-to-end
  with two different games running concurrently (separate processes, separate displays,
  separate noVNC ports, independent stop/teardown) and the 10-slot cap logic.

- ~~Get game sound actually audible during play~~ Done: PulseAudio + a hand-rolled stdlib
  WebSocket bridge (`pcm_ws_bridge.py`, in `docker-common` — reusable, not dosbox-specific,
  per the earlier plan for this item) carries raw PCM to the browser, played back via a
  Web Audio `AudioWorkletNode` (`pcm-worklet.js`, also in `docker-common`). Verified real
  end-to-end audio: DOSBox → ALSA (default device, routed through Pulse via
  `/etc/asound.conf`) → PulseAudio's one default sink → `parec` → the bridge → a raw
  WebSocket client, measured RMS ≈9292 while `stuntcar` was actually playing (vs. silence
  before advancing past its title screen) — not just a plumbing check, actual game audio.

  **Audio is a single shared mix, not per-game** — deliberately simplified from an
  earlier per-slot-isolated design (considered and dropped as unnecessary complexity):
  every running game's audio mixes into Pulse's one default sink, and every `/screen/<name>`
  page connects to the same single `AUDIO_PORT` (`71${DISPLAY_NUM}`, `7199` by default).
  Trade-off: with more than one game running, you can't tell their audio apart.

  **Real bug found and fixed along the way**: `parec --device=@DEFAULT_SINK@.monitor`
  (the seemingly-obvious macro syntax) fails with "Stream error: Invalid argument" —
  PulseAudio has a *separate* single-token macro, `@DEFAULT_MONITOR@`, for exactly this;
  concatenating `@DEFAULT_SINK@` with a literal `.monitor` suffix isn't valid.

  `server.sh` now starts `pulseaudio --start --exit-idle-time=-1` and the bridge
  (`pcm_ws_bridge.py 7199 parec --device=@DEFAULT_MONITOR@ ...`) once, before `exec`-ing
  `setup_server.py` — both live for the container's whole lifetime, independent of any
  game's start/stop. `setup_server.py` gained `GET /screen/<name>` (an iframe onto the
  game's noVNC screen plus an "Enable Sound" button — browsers require a user gesture
  before audio can start) and `GET /pcm-worklet.js`; the "Open Screen" link is now a plain
  same-origin relative link (`/screen/<name>`) instead of the old client-side-JS-built
  cross-port link, since the wrapper page itself now handles connecting to the right ports
  (reading the actual host from the request's own `Host:` header server-side).