# 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)). Phase 8 introduced the live
lobby with five sections, the create-game form, and the TS-side
FlatBuffers integration the rest of the client builds on. This doc
captures the sections, the application / invite lifecycle the user
sees, and the defaults baked into the create-game form.

## Sections

The lobby renders one column of sections, top to bottom, with the
common content max-width capped at `32rem` (same convention as the
login page). Cards inside each section take the full available
width.

| Section              | Empty state           | Source                     | Action                                                    |
| -------------------- | --------------------- | -------------------------- | --------------------------------------------------------- |
| `create new game`    | (always visible)      | —                          | Navigates to `/lobby/create`                              |
| `my games`           | `no games yet`        | `lobby.my.games.list`      | Click → `/games/:id/map` (placeholder until Phase 10)     |
| `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`) |

The header preserves the device-session-id `<code>` block from the
Phase 7 placeholder (kept as a debug affordance) plus a greeting if
the gateway returns a `display_name` for the caller.

## 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 page navigates back to `/lobby` and the new game shows
up in `my games` once the lobby's onMount has had a chance to refresh
the list.

## 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. Phase 8 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.

Phase 7's `user.account.get` decode previously used
`JSON.parse(TextDecoder)`; that path was rewritten in Phase 8 to use
the same generated `AccountResponse` table, so the lobby greeting now
works against a real local stack as well as the mocked Playwright
fixtures.