docs: add the phased GUI plan

1 files changed, 87 insertions, 0 deletions

diff --git a/docs/GUI-PLAN.md b/docs/GUI-PLAN.md
new file mode 100644
index 0000000..0285543
--- /dev/null
+++ b/docs/GUI-PLAN.md
@@ -0,0 +1,87 @@
+# GUI plan
+
+Decisions and rationale live in `docs/adr/0001-gui-frontend-architecture.md` and
+`0002-version-lockstep.md`. This file is the order of work.
+
+## Non-goals
+
+Audio, 3D, macOS, auto-update, a browser client, and pixel-golden tests in CI.
+
+## Phase 0 — version handshake (v4.0.0)
+
+Breaking wire change, released for client and server together.
+
+- `HELLO <version>` is the first line after TLS. The server answers
+  `HELLO <version> latest=<version> url=<download-url>` and rejects every other
+  message with `ERROR HELLO required` until it has seen one.
+- MAJOR.MINOR must match; PATCH may differ. A mismatch is refused before any
+  credentials are sent.
+- The client measures its connect latency with the `HELLO` round trip and
+  prints a notice when the server advertises a newer version.
+- `DOWNLOAD_URL` is read from the environment by the server, with the public
+  site as the fallback.
+
+**Gate:** mismatch refused in both directions, `HELLO` required before auth,
+existing game flows unchanged, new tests for version parsing and gating.
+
+## Phase 1 — core boundary and roulette
+
+- Introduce `Command` and `View`; move terminal-only concerns (prompt editing,
+  wheel animation, interactive prompts) into the TUI adapter.
+- App screens: `Connect`, `Trust`, `TrustMismatch`, `Login`, `Lobby`,
+  `History`, `Game`.
+- Port roulette first: `PlaceBet(BetTarget)`, `SetChip`, `ClearBets`, `Spin`,
+  and a `FeltView` carrying chips, cursor, and the last result.
+- Add `ForgetLogin` so "log out" and "forget saved login" are distinct in both
+  frontends.
+- Auto-login stays: a stored credential for the pinned fingerprint logs in
+  automatically after the trust check.
+
+**Gate:** the TUI behaves exactly as today, its tests now assert on `View`
+instead of text where practical, and `ClientCore` contains no terminal types.
+
+## Phase 2 — the other three games
+
+Slots, blackjack, crash ports with their own `GameView` variants and commands.
+Server push (`CRASH_BUSTED`) feeds the same `View`. The TUI keeps animating the
+crash board from its local clock.
+
+**Gate:** all four games playable in the TUI through `Command`/`View`.
+
+## Phase 3 — `gui/` skeleton and the style spike
+
+- Add the `gui/` workspace member (eframe), no game code yet.
+- Theme module with the agreed tokens, two fonts, spacing scale.
+- One reference screen: the roulette felt with chips, cursor, and a spinning
+  number, plus the persistent header (connection, balance, account).
+- Verify the Windows cross-compile with a hello-world before going further.
+
+**Gate:** your approval of the screenshot at 1080p; binary ≤ 40 MB, idle
+≤ 150 MB, cold start ≤ 1 s, 60 fps on integrated graphics.
+
+## Phase 4 — GUI wiring
+
+- Network thread with channels, request deadlines in the shared adapter.
+- Trust modal, version-mismatch screen, login/register, lobby, history panel.
+- All four games, per-frame painting and tier 1–2 effects.
+- Update notice from the handshake in the lobby.
+
+**Gate:** manual checklist per game at 60 fps, `egui_kittest` wiring tests,
+modem-throttled run.
+
+## Phase 5 — packaging
+
+- `publish.sh` emits `zagan-bet-gui-<version>-<platform>-<arch>[.exe]`.
+- Bash and PowerShell installers that verify the SHA-256, install to the user
+  directory, and create `.desktop`/Start-menu entries.
+- Download page lists raw binaries and installers; add the source-code link.
+
+**Gate:** `deploy.sh` verifies both artifact kinds; a clean machine installs
+from the page and launches.
+
+## Testing split
+
+- `View`/`Command` tests in the core: flows, gating, state. Always.
+- The TUI adapter remains the regression net through Phases 1–2.
+- `egui_kittest` for wiring that `View` cannot see; no pixel goldens in CI.
+- Manual for feel, animations, and layout at different window sizes.