# Lobby UI

The lobby is the first authenticated view; the user lands here after
the email-code login completes (see
[`docs/auth-flow.md`](auth-flow.md)). This doc captures the shared
shell, the Overview sections, the profile sub-screen, and the
defaults baked into the create-game form.

## Shell

Lobby and profile share a single chrome implemented in
`lib/screens/lobby-shell.svelte`. The chrome mirrors the project
site's VitePress layout: a left page-list sidebar (Overview /
Profile), a top identity strip on the right, and the page content in
the right-hand column. The shell uses `var(--font-mono)` so the
post-login pages adopt the "nerdy" type stack that the public site
already uses.

The identity strip reads the caller's account from
`lib/account-store.svelte.ts` — a session-wide cache that fetches
`user.account.get` once on first access and is written through after
every Profile save. Both `lobby-screen.svelte` and
`profile-screen.svelte` populate the same cache through
`account.ensure(client)`, so switching Overview ⇄ Profile never
re-issues `user.account.get` and the strip never flashes the
`lobby.account_loading` placeholder mid-navigation. The cache is
cleared by `session.signOut("user")` / `signOut("revoked")` so a
different user signing in on the same browser does not briefly see
the previous identity.

The strip falls back to `display_name` → immutable `user_name` →
`lobby.account_loading` while the first `ensure(...)` resolves. It
renders as a `data-testid="lobby-account-name"` button; clicking it
switches the top-level screen to `profile`
(`appScreen.go("profile")`). The e2e suites use that testid as their
lobby-loaded signal. The logout button sits next to it
(`session.signOut("user")`).

The sidebar always renders both pages; clicking the active page is a
no-op. The shell collapses to a horizontal scrolling strip below
640px.

## Overview sections

The Overview page renders one column of sections, top to bottom.
Cards inside each section take the full available width.

| Section              | Empty state           | Source                     | Action                                                    |
| -------------------- | --------------------- | -------------------------- | --------------------------------------------------------- |
| `create new game`    | (always visible)      | —                          | Opens the create screen (`appScreen.go("lobby-create")`)  |
| `my games`           | `no games yet`        | `lobby.my.games.list`      | Click → enters the game on the map view (`activeView.reset()` + `appScreen.go("game", { gameId })`) |
| `pending invitations`| `no invitations`      | `lobby.my.invites.list`    | Accept (`lobby.invite.redeem`) / Decline (`lobby.invite.decline`) |
| `my applications`    | `no applications`     | `lobby.my.applications.list` | Status badge (`pending` / `approved` / `rejected`)      |
| `public games`       | `no public games`     | `lobby.public.games.list`  | Submit application via inline race-name form (`lobby.application.submit`) |

## Profile sub-screen

`lib/screens/profile-screen.svelte` is a top-level `AppScreen` (peer of
`lobby` and `lobby-create`). The browser Back stack treats it the
same as the create screen — pushing a fresh history entry on entry,
falling back to lobby on Back/Forward (see
[`navigation.md`](navigation.md)).

On mount it reads the caller's account through `account.ensure(...)`
(see [Shell](#shell)) — the first visit issues `user.account.get`,
subsequent visits resolve from the session-wide cache without a
gateway round-trip. The form renders an identity read-out (immutable
`user_name`, `email`) plus three editable fields:

| Field                 | Endpoint              | Notes                                                          |
| --------------------- | --------------------- | -------------------------------------------------------------- |
| `display_name`        | `user.profile.update` | Trimmed; empty value clears the stored name (backend PATCH semantics). |
| `preferred_language`  | `user.settings.update`| `<select>` over `SUPPORTED_LOCALES`; if the stored value is unsupported the option is preserved verbatim so a round-trip save does not silently switch it. |
| `time_zone`           | `user.settings.update`| `<select>` of every IANA zone the browser knows (`Intl.supportedValuesOf("timeZone")`), grouped by leading slash segment (Africa / America / …; singletons like `UTC` collapse into a trailing "Other" optgroup). When the form opens with no stored zone, the picker is pre-selected to `Intl.DateTimeFormat().resolvedOptions().timeZone`. A stored value the runtime no longer advertises is added as an extra "Other" entry so the round-trip never silently drops it. Browsers that lack `supportedValuesOf` fall back to a free-text input; the backend validates with `time.LoadLocation` in every shape. |

Save fires `user.profile.update` and/or `user.settings.update`
conditionally on which fields actually changed, then **stays on the
profile** and surfaces a transient `profile-saved-notice` line
(`data-testid="profile-saved-notice"`). Editing any field clears the
notice. Only the explicit `cancel` button navigates back to the lobby
(`appScreen.go("lobby")`). When the saved `preferred_language` is one
the UI also ships translations for, the active i18n locale switches
in-place so the rest of the session matches the new preference. The
write-through is also pushed into the shared `account` store so the
shell identity strip picks up the new `display_name` without a second
`user.account.get`.

`GameSummary` carries a `current_turn` field that the lobby UI does
not display directly — the in-game shell reads it from the same
payload to load the matching `user.games.report` for the map view
without an additional gateway call. See
[`game-state.md`](game-state.md) for the consumer's view.

## Application lifecycle

`Submit application` on a public-game card toggles an inline race-name
form on the same card (no overlay/modal infrastructure yet — the
in-game shell that introduces overlays lands later). On submit:

1. The page calls `submitApplication(client, gameId, raceName)` from
   `src/api/lobby.ts`.
2. The wrapper builds an `ApplicationSubmitRequest` FlatBuffers
   payload, posts it through `GalaxyClient.executeCommand`, decodes
   the `ApplicationSubmitResponse`, and returns an
   `ApplicationSummary` plain object.
3. The lobby page prepends the new application to the
   `my applications` list and collapses the inline form. The page
   does not refresh the public-games list — backend semantics are
   that the public game still exists and is still in
   `enrollment_open`.
4. Status starts as `pending`. When the owner approves, backend
   creates a membership and the next refresh of `lobby.my.games.list`
   surfaces the game in `my games`. When the owner rejects, the
   application stays terminal in `my applications` with status
   `rejected`.

## Invite lifecycle

A pending invite arrives in `pending invitations` either when the
inviter targets the user by id (`invited_user_id` is set) or when the
user redeems a code-based invite from somewhere outside the lobby.
The user can accept (`lobby.invite.redeem`) or decline
(`lobby.invite.decline`):

- **Accept** — the invite card disappears, the page refreshes
  `my games`, and the freshly-joined game appears there.
- **Decline** — the invite card disappears. No membership is
  created.

## Create-game form

The form posts `lobby.game.create` through the gateway with
`visibility="private"` hard-coded; the user surface never produces a
public game (FUNCTIONAL.md §3.3). Fields:

| Field                 | Visibility       | Default | Notes                                                  |
| --------------------- | ---------------- | ------- | ------------------------------------------------------ |
| `game_name`           | always           | `""`    | Non-empty client-side check                            |
| `description`         | always           | `""`    |                                                        |
| `turn_schedule`       | always           | `0 0 * * *` | Plain text input, hint says "five-field cron"      |
| `enrollment_ends_at`  | always           | `""`    | `<input type="datetime-local">`, RFC 3339 on submit    |
| `min_players`         | Advanced toggle  | `2`     | `<details>` block                                      |
| `max_players`         | Advanced toggle  | `8`     |                                                        |
| `start_gap_hours`     | Advanced toggle  | `24`    |                                                        |
| `start_gap_players`   | Advanced toggle  | `2`     |                                                        |
| `target_engine_version` | Advanced toggle | `v1`   | Falls back to `v1` if blank                           |

On success the create screen returns to the lobby
(`appScreen.go("lobby")`) and the new game shows up in `my games`
once the lobby's onMount has had a chance to refresh the list (the
lobby screen remounts on return, so its onMount re-fires).

## Errors

Lobby errors raised by the gateway carry a canonical code
(`invalid_request`, `subject_not_found`, `forbidden`, `conflict`,
`internal_error`). The `LobbyError` thrown by `lobby.ts` exposes the
code; the page maps it to the matching `lobby.error.<code>` i18n key
and falls back to the gateway-supplied message via
`lobby.error.unknown` for any unknown code.

## Why FlatBuffers on the TS side

The gateway encodes lobby payloads through `pkg/transcoder/lobby.go`
into FlatBuffers bytes; the browser must decode them with the same
schema. The TS integration ships:

- `flatbuffers` runtime dependency in `ui/frontend/package.json`;
- `make -C ui fbs-ts` driving `flatc --ts` to regenerate the bindings
  from `pkg/schema/fbs/*.fbs` into `ui/frontend/src/proto/galaxy/fbs/`;
- a Vitest round-trip suite (`tests/lobby-fbs.test.ts`) that catches
  binding drift in CI.

`user.account.get` decodes through the generated `AccountResponse`
table, so the lobby greeting works against a real local stack as well
as the mocked Playwright fixtures.