From dc8c03f265b7475cfc122a1221abf68f5d0a9ae9 Mon Sep 17 00:00:00 2001 From: salmonik Date: Sun, 1 Nov 2026 17:41:56 +0100 Subject: docs: add the phased GUI plan --- docs/GUI-PLAN.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/GUI-PLAN.md 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 ` is the first line after TLS. The server answers + `HELLO latest= 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---[.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. -- cgit v1.2.3