trictrac/doc/client_web_overview.md

# client_web Crate Overview

A Leptos-based WASM frontend for trictrac. Builds to a single-page app served by Trunk on port 9092.

---

## File Structure

```
client_web/
├── Cargo.toml             # Dependencies and i18n locale config
├── Trunk.toml             # Serve port 9092
├── index.html             # Shell: mounts WASM + links CSS
├── assets/style.css       # All styles (~472 lines, no framework)
├── locales/
│   ├── en.json            # 52 English keys
│   └── fr.json            # 52 French keys
└── src/
    ├── main.rs            # load_locales!() macro + mount_to_body
    ├── app.rs             # Root App component, state, network loop (571 lines)
    ├── components/
    │   ├── mod.rs
    │   ├── game_screen.rs  # Main in-game UI, move staging (324 lines)
    │   ├── board.rs        # Board rendering and click handling (372 lines)
    │   ├── die.rs          # SVG die face
    │   ├── score_panel.rs  # Points/holes bar for one player
    │   ├── scoring.rs      # Jan-by-jan scoring notification panel
    │   ├── login_screen.rs # Room create/join
    │   └── connecting_screen.rs
    └── trictrac/
        ├── mod.rs
        ├── types.rs        # Protocol types: ViewState, JanEntry, PlayerAction, … (217 lines)
        ├── backend.rs      # BackEndArchitecture impl, engine bridge (332 lines)
        └── bot_local.rs    # Local bot: random moves, always Go (34 lines)
```

---

## Component Tree

```
App                          ← manages screen, pending queue, network task
└─ I18nContextProvider
   ├─ LoginScreen             ← room name input, create/join/bot buttons
   ├─ ConnectingScreen        ← spinner while connecting
   └─ GameScreen              ← in-game UI; receives GameUiState prop
      ├─ PlayerScorePanel     ← opponent score (above board)
      ├─ Board                ← 24 interactive fields; SVG arrow overlay
      ├─ side panel
      │  ├─ status bar        ← localised turn/action prompt
      │  ├─ dice bar          ← two Die components
      │  ├─ ScoringPanel (me)       ← my jans this turn, hold/go buttons
      │  ├─ ScoringPanel (opponent) ← opponent jans (shown during pause)
      │  └─ action buttons    ← Continue / Go / Empty Move
      └─ PlayerScorePanel     ← my score (below board)
      [game-over overlay modal]
```

---

## Screens and Transitions

```
Login ──(connect)──→ Connecting ──(game start)──→ Playing
                                    ↑                 │
                                    └──(reconnect)─────┘
Playing ──(disconnect / game over)──→ Login
```

`app.rs` drives transitions via `RwSignal<Screen>`.

---

## State Management

### Root signals (live in `App`, provided via Leptos context)

| Signal | Type | Purpose |
|--------|------|---------|
| `screen` | `RwSignal<Screen>` | Which screen is shown |
| `pending` | `RwSignal<VecDeque<GameUiState>>` | Buffered states awaiting "Continue" |
| `cmd_tx` | `UnboundedSender<NetCommand>` | UI → network command channel |

Both `pending` and `cmd_tx` are provided as context so any descendant can read/write them without prop-drilling.

### GameScreen-local signals

| Signal | Type | Purpose |
|--------|------|---------|
| `selected_origin` | `RwSignal<Option<u8>>` | First clicked field during move staging |
| `staged_moves` | `RwSignal<Vec<(u8, u8)>>` | Accumulated (origin, dest) pairs for this turn |
| `hovered_jan_moves` | `RwSignal<Vec<(CheckerMove, CheckerMove)>>` | Moves to draw arrows for on hover |

### Data flow

```
Network task (async in App)
    ↓  SessionEvent::Update
push_or_show() → pending queue or screen.set()
    ↓
GameScreen re-renders (GameUiState prop)
    ↓
User clicks field → staged_moves effect → NetCommand::Action(Move)
User clicks Go/Continue → cmd_tx.send or pending.pop_front()
```

---

## Network and Session

The multiplayer layer is provided by `backbone-lib` (local fork at `../../forks/multiplayer/`). `App` spawns an async task (via `spawn_local`) that multiplexes:
- `cmd_rx`: commands from UI components
- `session.next_event()`: updates from the server

### StoredSession (localStorage key: `"trictrac_session"`)

```rust
struct StoredSession {
    relay_url: String,
    game_id: String,
    room_id: String,
    token: u64,          // reconnect token issued by server
    is_host: bool,
    view_state: Option<ViewState>,  // host saves last known state; guest saves None
}
```

On page load, if a stored session exists, App goes directly to Connecting and sends `NetCommand::Reconnect`. Failed reconnects clear the session and return to Login.

---

## Pause / Confirmation Flow

Certain opponent events are paused so the local player can see what happened before their turn starts.

Pause triggers (`infer_pause_reason()` in `app.rs`):

| Reason | Condition |
|--------|-----------|
| `AfterOpponentRoll` | Opponent is active; dice values changed |
| `AfterOpponentGo` | Opponent chose Go (HoldOrGoChoice→Move transition) |
| `AfterOpponentMove` | Turn switched to us |

While a state is in the pending queue, `GameScreen` shows a "Continue" button. Clicking it calls `pending.pop_front()`; if the queue empties, the live state is displayed.

---

## Game Engine Integration

**File**: `src/trictrac/backend.rs`

`TrictracBackend` implements the `BackEndArchitecture` trait. It owns a `GameState` from `trictrac-store` and translates between the UI protocol and the engine's event model.

### PlayerAction → GameEvent mapping

| PlayerAction | GameEvents emitted |
|---|---|
| `Roll` | `GameEvent::Roll`, `GameEvent::RollResult(d1, d2)` |
| `Move(m1, m2)` | `GameEvent::Move` (after validation) |
| `Go` | `GameEvent::Go` |
| `Mark` | internal; drives `MarkPoints`/`MarkAdvPoints` loop automatically |

`drive_automatic_stages()` loops through scoring stages without waiting for player input — these are not interactive in the current implementation (schools are not implemented).

### ViewState construction

`ViewState::from_game_state()` in `types.rs` converts the engine state to the serialisable snapshot sent to clients:
- `board: [i8; 24]` — direct copy of `Board::positions`
- `dice: [u8; 2]` — current dice values
- `stage / turn_stage` — serialisable enums (`SerStage`, `SerTurnStage`)
- `scores: [PlayerScore; 2]` — points, holes, `can_bredouille`
- `dice_jans: Vec<JanEntry>` — scoring events for the current turn, sorted descending by points
- `active_player_index: usize` — 0 = host, 1 = guest

### Bot

`bot_local.rs` runs in the browser (no server call). It inspects `GameState` directly and returns a `PlayerAction`:
- **RollDice**: always Roll
- **HoldOrGoChoice**: always Go
- **Move**: picks a random legal sequence from `MoveRules::get_possible_moves_sequences()`; mirrors moves because Black's board is mirrored

---

## Board Rendering (`board.rs`)

### Layout

The 24 fields are split into 4 quarters of 6. Each player sees the board from their own perspective:

```
White's view:
  TOP-LEFT  [13–18]  |  TOP-RIGHT  [19–24]
  ─────────────────────────────────────────
  BOT-LEFT  [12–7]   |  BOT-RIGHT  [6–1]

Black's view (mirror):
  TOP-LEFT  [1–6]    |  TOP-RIGHT  [7–12]
  ─────────────────────────────────────────
  BOT-LEFT  [24–19]  |  BOT-RIGHT  [18–13]
```

Fields are 60 × 180 px, alternating gold (`#d4a843` / `#c49030`). Checkers are 40 px SVG circles (radial gradient). Up to 4 are stacked visually; a text label is shown when count > 4.

### Highlighting

Field CSS classes are computed reactively inside the `view!` macro closure:

| Class | Meaning |
|-------|---------|
| `.clickable` | Valid origin during Move stage (lime green) |
| `.selected` | Currently selected origin (darker green + outline) |
| `.dest` | Valid destination for the selected origin |

`valid_sequences` (from `MoveRules`) is computed once per render and used to derive `valid_origins_for()` and `valid_dests_for()`. The displayed checker count (`displayed_value()`) accounts for staged-but-not-yet-sent moves so the board previews the move visually.

### SVG arrow overlay

When the player hovers a row in the ScoringPanel, the corresponding checker moves are drawn as gold arrows over the board. `field_center()` maps field numbers to pixel coordinates; `arrow_svg()` renders the path with a drop-shadow.

---

## Scoring Display (`scoring.rs`, `score_panel.rs`)

`compute_scored_event()` in `app.rs` diffs consecutive `ViewState` snapshots to produce a `ScoredEvent`:
- `points_earned: i32`
- `holes_gained: u8`
- `jans: Vec<JanEntry>` — only events relevant to the beneficiary

`ScoringPanel` renders one `JanEntry` per row. Hovering a row writes that entry's moves into `hovered_jan_moves`, triggering the arrow overlay on the board.

`PlayerScorePanel` shows a colour-filled bar (animated via CSS `transition: width 0.3s`) for points (0–12) and holes (0–12). Bredouille state is shown with a small indicator.

---

## Internationalisation

`leptos_i18n::load_locales!()` is a compile-time macro that reads `locales/en.json` and `locales/fr.json` and generates a typed `i18n` module. There are 52 keys covering UI labels, game-state prompts, jan names, and status messages.

Usage in components:
```rust
let i18n = use_i18n();
t!(i18n, your_turn_roll)                       // → reactive View
t_string!(i18n, scored_pts, pts = 4)           // → String with interpolation
```

The language switcher (top bar and login screen) calls `i18n.set_locale(Locale::en | Locale::fr)`, which triggers a full reactive re-render.

---

## Styling

`assets/style.css` is a single hand-written stylesheet (~472 lines). No CSS framework.

Key design tokens:
- Body background: `#c8b084` (tan)
- Board background: `#2e6b2e` (dark green)
- Fields: `#d4a843` / `#c49030` (gold alternating)
- Interactive fields: `#aad060` (lime, clickable) / `#709a20` (darker, selected)
- UI panels: `#f5edd8` (cream)

Layout uses Flexbox and CSS Grid throughout. Score bars animate with `transition: width 0.3s`. Field clicks give immediate feedback via `transition: background 0.1s`. No media queries — the layout is designed for desktop/tablet.

---

## Protocol Types (`types.rs`)

| Type | Role |
|------|------|
| `PlayerAction` | `Roll \| Move(CheckerMove, CheckerMove) \| Go \| Mark` — UI → backend |
| `GameDelta` | `{ state: ViewState }` — broadcast to all clients on every change |
| `ViewState` | Full serialisable snapshot of engine state |
| `JanEntry` | One scoring event: jan type, points, ways, moves, is_double |
| `ScoredEvent` | Points/holes delta + jan list for one player in one turn |
| `PlayerScore` | name, points (0–11), holes (0–12), can_bredouille |
| `SerStage` | `PreGame \| InGame \| Ended` |
| `SerTurnStage` | `RollDice \| RollWaiting \| MarkPoints \| HoldOrGoChoice \| Move \| MarkAdvPoints` |

`CheckerMove` comes directly from `trictrac-store`; fields are 1-indexed (0 = stack/exit).

---

## Build

```bash
trunk serve          # dev server at http://localhost:9092
trunk build --release  # WASM release bundle
```

`index.html` uses Trunk's `data-trunk` attributes: `rel="rust"` compiles `src/main.rs` to WASM; `rel="css"` copies `assets/style.css`. The WASM binary and generated JS glue land in `dist/`.