ProLibertateGames/docs/UI-catan.md

# Katan UI — how it is built, and how to change it

The Katan screen (`app/src/main/java/org/prolibertate/games/ui/game/catan/`) is
built in layers so that **look, wording, layout and interaction can each be
changed on their own**. If you are an agent asked to restyle, retheme,
re-copy or re-lay-out Katan, start here and touch only the layer you were asked
about.

The rules live elsewhere and are not part of the UI: `game/catan/` is a pure
state machine (see [RULES-catan.md](RULES-catan.md)). **Nothing in `ui/game/catan/`
decides what is legal.** The engine's legal-move list is the single source of
truth, so the UI can only ever offer a move the rules would accept.

## The layers

| Layer | File | Owns | Change it to… |
| --- | --- | --- | --- |
| **Style** | `CatanStyle.kt` | Every colour, proportion and the light/dark palettes | Re-skin: new terrain colours, seat colours, piece sizes, token look |
| **Copy** | `CatanText.kt` | Every sentence, button label and name shown | Reword, localise, rename resources |
| **Geometry** | `CatanGeometry.kt` | Engine lattice → pixels, and pixel → nearest vertex/edge/hex | Change board scale, margin, harbour placement, tap reach (rarely) |
| **Interaction** | `CatanInteraction.kt` | What is tappable, what a tap means, which buttons are live | Change *how* something is selected (never *whether* it is legal) |
| **Board drawing** | `CatanBoardView.kt` | The `Canvas`: tiles, tokens, ports, robber, roads, pieces, highlights | Change how a piece is drawn (art, shapes, animation) |
| **Panels** | `CatanPanels.kt` | Resource tiles, hand, player cards, dice, action bar, log | Restyle or rearrange widgets |
| **Dialogs** | `CatanDialogs.kt` | Discard, robber victim, play card, trade, trade reply, game over | Change a dialog's flow or look |
| **Screen** | `CatanScreen.kt` | Wiring to `MatchController`, portrait/landscape layout, which dialog shows | Change the layout or add a new element |
| **Previews** | `CatanPreviews.kt` | Android Studio previews of real positions | Iterate on the look without a match |

Everything outside this folder that mentions Katan is one-line wiring:
`PlayScreen.kt` (builds the `MatchController`), `GameSetupScreen.kt` (players and
points-to-win options), `Catalog.kt` (the catalogue entry).

## Recipes

**Change colours or sizes.** Edit `CatanStyle.kt`. `LightStyle` is the reference
palette; `DarkStyle` is derived from it. Metrics (`roadWidth`, `settlementSize`,
`tokenRadius`, …) are fractions of the hex radius, so they scale with the screen.
To try a whole new theme, provide it at the root:
`CompositionLocalProvider(LocalCatanStyle provides myStyle) { … }`.

**Change wording or translate.** Edit `CatanText.kt`. Composables never build a
sentence themselves. `prompt(...)` is the one-line "what is happening / what do I
do" text; it is a pure function of the state, with tests in `CatanTextTest`.

**Redraw a piece** (settlement, road, robber, port, token). Edit the matching
`draw…` function in `CatanBoardView.kt`. Positions come from `BoardLayout`, so you
only decide the shape. Keep the hit target generous (see Accessibility).

**Rearrange the screen.** Edit `CatanScreen.kt`. It builds four independent
pieces (`board`, `players`, `promptRow`, `handAndActions`) and arranges them
differently in portrait and landscape. Moving or dropping a piece does not affect
the others.

**Add a widget.** Make it a stateless composable in `CatanPanels.kt` (values in,
lambdas out). Do not give it the `MatchController`.

**Change how a selection works** (for example a one-tap build instead of a
build-mode toggle). Edit `CatanInteraction.kt` and its tests, then adjust the
screen's UI state. The legal-move list stays the gate.

## Rules of the road

1. **Never put a rule in a composable.** If a button's enabled state or a tap's
   result depends on game logic, it goes in `CatanInteraction` (pure, tested) and
   is derived from the engine's `legal` list or `CatanRules`.
2. **Never hard-code a colour or a string** outside `CatanStyle` / `CatanText`.
3. **Stateless by default.** Panels and dialogs take values and report events. The
   only state they may own is the transient selection they are helping the player
   make (cards picked in a trade, for example).
4. **Hidden information.** The local view comes from `CatanRules.viewFor`: other
   players' development cards and the deck are empty on a client. Do not show the
   size of the deck; it is not known to a client. Card *counts* (`resourceCount`,
   `devHandCounts`) are public.
5. **The state is immutable.** Never mutate it; submit a move.
6. **The layout must not move.** Everything outside the board has a *fixed
   height*, and the board takes whatever is left, so the island's scale is the
   same all game. Concretely: a control is *enabled or disabled*, never
   *present or absent* (the action bar always shows every button); text that can
   vary in length is pinned to a fixed number of lines (`minLines = maxLines`);
   a line that is sometimes empty is still drawn (a non-breaking space), as the
   award line on a player card is. A change that makes any non-board element
   taller or shorter at runtime will rescale the board under the player's thumb.

## Interaction model (what the player actually does)

| Phase | The player… |
| --- | --- |
| Setup | taps a highlighted crossing (settlement), then a highlighted edge beside it (road). *Cancel* re-picks the settlement |
| Roll | presses **Roll dice** |
| Seven | **Discard** dialog (forced); then taps a hex to move the robber; a victim dialog appears only if more than one player can be robbed |
| Main turn | arms **Road / Settlement / City** and taps a highlighted spot; **Buy card**; **Play card**; **Trade**; **End turn** |
| Road Building | taps highlighted edges, or **Done with roads** |
| Offered a trade | **Accept / Decline / Counter…** dialog (forced); *Counter…* opens a picker pre-filled with the mirror of the offer |
| Counter-offers received | **Counter-offers** dialog: *Accept* beside the one to take, or *No deal* |
| Game over | result dialog |

Trade offers are free-form (two card multisets), so they are validated with
`CatanRules.isLegalMove`, not looked up in the legal list.

## Testing

Gradle does not run in the agent sandbox; **CI is the compile and test check**
(dispatch `ci.yml` on your branch). What is covered:

- `CatanGeometryTest` — the island fits any box, edges and corners are one radius,
  hit-testing finds the right vertex/edge/hex.
- `CatanInteractionTest` — targets and tap outcomes for setup, building, free
  roads, the robber (including the victim choice), discards, bank trades, offers,
  development cards and trade replies, all against real engine states.
- `CatanTextTest` — the prompts and tallies.

Drawing and dialogs are not unit-tested; use the previews in `CatanPreviews.kt`
and play a game on a dev build.

## Accessibility notes

- Tap targets: vertices and edges accept a tap within `tapReach` (0.7) hex radii,
  about 23 dp on a phone. If you shrink the board, keep that physical size.
- Seat colours are blue, orange, white and purple, each outlined in near-black so
  they read on any terrain. Colour is the only piece identity today; adding a
  shape or letter per seat would help colour-blind players (a good first task).
- The board has a content description but no per-hex semantics; a screen-reader
  mode would need one.

## Cities & Knights on the screen

The same layers carry the expansion; the screen only adds pieces, and **none of them
decides what is legal** — each reads the engine's legal-move list.

| Layer | What it adds |
| --- | --- |
| `CatanStyle.kt` | commodity colours, a colour per improvement track, the wall and barbarian colours, the awake-knight halo |
| `CatanText.kt` | goods, track, knight and progress-card names and help text; the prompts for every chore |
| `CatanInteraction.kt` | `BuildKind.WALL` / `KNIGHT`; chore taps; the moving-knight and armed-card modes; `knightActions`, `progressHand`, `goodsBankTrades` |
| `CatanBoardView.kt` | shields for knights (strength dots; faded when asleep, white halo when awake), dashed walls, a pennant for each metropolis, the merchant coin, a faint robber until the first attack |
| `CatanPanels.kt` | commodity tiles in the hand, the barbarian strip, the yellow / red / event dice, the extra player-card lines, the Improve and Progress buttons |
| `CatanCkDialogs.kt` | goods picker (discard, wedding, harbour), improvements, progress cards, the knight menu, deck / aqueduct / spy / drop choices, goods trade |
| `CatanScreen.kt` | the visual state: knight menu, moving knight, armed card, and which chore dialog shows |

**Interaction model.** Tap one of your own knights (it gets a yellow ring when it can do
something) for its menu: wake, promote, move or chase the robber. *Move* arms the board
with the crossings the knight can reach. A progress card that needs a place on the board
(Engineer, Medicine, Merchant, Diplomat, Intrigue, Inventor) closes the dialog and
**arms** the board; the next tap plays it. Chores that are answered with a place — a city
to lose, a metropolis site, a driven knight's refuge, a free knight — light the crossings
on the board and the prompt line says what to tap; the others open a dialog that cannot
be dismissed, because the game is waiting on it.

**Testing.** `CatanCkInteractionTest` plays whole games and checks that for *every* legal
move at *every* position some control (a tap, a button or a dialog choice) produces it, so
a legal move with no way to make it — a stuck phone — fails the build.

## Status and known gaps

The screen is **playable and feature-complete for the engine's rules**, but is
**unverified on two real devices**, so the catalogue entry is `devPreview`
(openable on a dev build, hidden from production). To release it: verify
two-device play, then in `Catalog.kt` set `available = true` and remove
`devPreview = true`, and update `CatalogTest`.

Not done yet, in rough priority order:

1. Two-device verification (host + guest over the LAN) and a full game on a phone
   and a tablet.
2. Feedback on events: dice-roll animation, a highlight on hexes that produced,
   resource-gain flourishes, haptics. The state carries the dice and a text log;
   it does not say which hexes paid out, so that needs either a diff of two states
   or an engine addition.
3. Art: terrain textures, resource and harbour icons, a real robber pawn.
4. A timer or cancel button on offers (the engine has neither).
5. A board that shows the *last* move (a faint highlight of what just changed).
6. Landscape polish on large tablets; the right-hand panel scrolls but is plain.