@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/clans/UIGuide_getClans.md

@@ -0,0 +1,172 @@
+# UI Guide — `getClans`
+
+## Overview
+- Powers the **clan-browser screen** (and the clan-pick modal during
+  tournament registration via
+  [`registerInTournament`](../../api/classes/WSAPITournaments.md#registerintournament)).
+- Returned `clans[]` is already server-sorted by `rating_position` ASC
+  (1 = best). The default Smartico UI re-sorts on the same key as a
+  defensive measure but no client-side ordering work is required.
+- Loading indicator: the first call is a server round-trip
+  (typically 100–500 ms); subsequent calls within the 30 s cache
+  window resolve effectively synchronously.
+- `onUpdate` is poll-driven (no server push). For near-live state, the
+  consumer must poll on an interval — the default Smartico UI polls
+  every 30 s while the clan screen is open.
+
+## List view organization
+
+A single flat ranked list — no tabs. Render `clans[]` in the order
+returned (already sorted by `rating_position`).
+
+**Client-side search filter**: filter `clan.public_meta.name` against
+the user's typed query (case-insensitive). No server round-trip.
+
+**Sticky "my clan" footer**: when the user is in a clan and the
+visible list is long enough (the default Smartico UI uses ≥ 7 visible
+items), pin a duplicate of the user's clan row at the bottom of the
+scroll area so it remains visible while the user scrolls. Skip this
+when the user is clanless or the list is short.
+
+No dedicated "My Clan" panel at the top of the list — the user's clan
+appears at its natural `rating_position`, just highlighted in place.
+
+## Item card / row
+
+Fields rendered (column structure for desktop; mobile may collapse):
+
+| Column | Source | Notes |
+|---|---|---|
+| Rank | `rating_position` | Display as `#N`. Apply `.top-1` / `.top-2` / `.top-3` styling for positions 1–3. |
+| Icon / image | `public_meta.image_url` | Square. Fallback: first character of `public_meta.name` rendered as a letter avatar. |
+| Name | `public_meta.name` | Translated server-side. Add "Your clan" badge next to the name if `clan.clan_id === user_clan_id`. |
+| Rating score | `rating_score` | Numeric; the higher, the better. |
+| Members | `member_count` / `capacity_limit` | Desktop: render a progress bar at `member_count / capacity_limit * 100%` with a label `N / M`. Mobile: text-only `N / M`. |
+| Entry fee | `entry_fee_amount` + `entry_fee_currency_type_id` | "Free" when `entry_fee_amount === 0` or `entry_fee_currency_type_id === 3`. Otherwise `"{amount} {Points|Gems|Diamonds}"`. |
+
+**Whole-row click target**: opens the detail modal (via
+[`getClanInfo`](../../api/classes/WSAPIClans.md#getclaninfo) to load
+members on demand). The row itself has no inline Join CTA — joining
+happens from inside the detail modal (see "Action button decision
+matrix" below).
+
+**Detail-only fields** (not on row): `description`, full `members[]`
+list (from `getClanInfo`), full progress bar styling on desktop.
+
+## Action button decision matrix
+
+The Join CTA lives in the detail modal (or the clan-pick modal during
+tournament registration). Evaluate in priority order — first match
+wins.
+
+| State | Condition | Button label | Enabled? | Notes |
+|---|---|---|---|---|
+| **Your clan** | `clan.clan_id === user_clan_id` | "Your clan" | No-op | Highlight; no join action. |
+| **Cooldown active** | `cooldown_until !== null` | `"Cooldown until <local-date>"` | Disabled | Affects ALL clans — the cooldown is user-level, not per-clan. Format `cooldown_until` from UTC to local time (`DD-MM-YYYY HH:mm` style). |
+| **Clan full** | `member_count >= capacity_limit` | "Clan is full" | Disabled | |
+| **Insufficient balance** | `entry_fee_amount > 0` AND user's balance for `entry_fee_currency_type_id` < `entry_fee_amount` | `"Not enough {Points|Gems|Diamonds} (deficit)"` | Disabled | Cross-check against {@link getUserProfile} balance for the currency. |
+| **Joinable — free** | `entry_fee_amount === 0` OR `entry_fee_currency_type_id === 3` | "Join free" | Enabled | |
+| **Joinable — paid** | default | `"Join ({amount} {Points|Gems|Diamonds})"` | Enabled | |
+
+The enabled Join click invokes
+[`joinClan(clan_id)`](../../api/classes/WSAPIClans.md#joinclan). See
+its own UI guide for the in-flight + error-code matrix.
+
+**Picker mode (`registerInTournament` clan-pick modal)**: when the
+user is in cooldown, the default Smartico UI disables every row in the
+picker (not just the buttons) — `onClick` is suppressed entirely.
+
+## Cooldown rendering
+
+- The cooldown is **user-level**, not per-clan. While
+  `cooldown_until !== null`, the user cannot join any clan.
+- Format: `cooldown_until` is an ISO 8601 UTC string
+  (`"YYYY-MM-DDTHH:MM:SS"`, no timezone suffix). Parse as UTC, display
+  in user-local time. The default Smartico UI shows
+  `DD-MM-YYYY HH:mm` (e.g. `"01-06-2026 16:30"`).
+- No "X days remaining" countdown — show the absolute expiry datetime.
+  If your product surface justifies a countdown, render one yourself.
+
+## Image / asset specs
+
+| Field | Aspect ratio | Notes |
+|---|---|---|
+| `public_meta.image_url` | 1:1 (square) | Recommended source size not strictly enforced; the default Smartico UI sizes via CSS. Provide a square image for best results. |
+
+**Fallback**: when `image_url` is missing or fails to load, render
+the first character of `public_meta.name` as a letter avatar in the
+icon container.
+
+## Status-specific visual treatments
+
+- **Your clan**: row gets a `.highlight` background tint + "Your clan"
+  badge next to the name.
+- **Top-3 rank**: rows for `rating_position` 1–3 get podium accents
+  (gold/silver/bronze).
+- **Full clan**: no row-level treatment — only the detail-modal button
+  shows the disabled state.
+- **Cooldown active**: only the detail-modal button is disabled (or
+  in the picker, the whole row is dimmed).
+- **Insufficient balance**: only the detail-modal button is disabled.
+
+## Empty / loading / error states
+
+- **Loading (first fetch)**: render a spinner / shimmer skeleton of
+  rows.
+- **Empty list (no clans configured)**: render a neutral empty-state
+  illustration with copy like "No clans available".
+- **Empty search results**: same empty-state illustration with
+  query-aware copy (e.g. "No clans matching '<query>'").
+- **Error**: the default Smartico UI keeps the spinner visible
+  indefinitely on fetch failure (no error boundary). For a better UX,
+  catch the rejected promise and render a "Failed to load — Try again"
+  affordance.
+
+## Refresh
+
+`onUpdate` is poll-driven only. Two ways to keep the list fresh:
+
+1. **Poll**: re-call `getClans()` on a 30-second interval while the
+   clan screen is visible. The cache deduplicates rapid refetches.
+2. **Re-call after mutations**: after a successful
+   [`joinClan`](../../api/classes/WSAPIClans.md#joinclan), re-call
+   `getClans()` immediately to pick up the new `user_clan_id` and any
+   refreshed `member_count` / `cooldown_until` fields.
+
+There is no server push that refreshes the clans list automatically
+— another user joining your clan, an operator kicking you, or a clan
+being archived will all only surface on the next consumer-driven
+fetch.
+
+## Animations / transitions
+
+- **List entry**: rows fade-in with a ~30 ms stagger on first render.
+- **Rank reorder between polls**: if you implement live updates,
+  detect `rating_position` changes by diffing the previous and
+  current arrays, and animate rows to their new position (FLIP
+  animation). Don't full-re-render the list.
+- **Join success celebration**: when `user_clan_id` flips between
+  polls (detect by comparing pre- and post-refresh values), play a
+  brief "Welcome to {clan name}" toast and animate the now-highlighted
+  row.
+
+## Mobile vs desktop
+
+- **Member fill**: desktop renders a progress bar; mobile renders
+  text-only (`N / M`).
+- **Columns**: desktop shows `#`, Clan, Rating, Members, Entry;
+  mobile drops Members (entry fee inlines below the name).
+- **Sticky my-clan footer**: same threshold on both (≥ 7 visible
+  rows).
+- **Search**: same client-side filter; desktop typically has a
+  search input at the top; mobile may use a dedicated search sheet.
+
+## Performance
+
+- 30 s polling on the clans surface is fine for typical clan
+  catalogs (< 200 clans). For very large catalogs, consider polling
+  only while the surface is in the viewport.
+- Use keyed per-row rendering — celebration / rank-reorder animations
+  break if the DOM nodes are recreated on every poll tick.
+- Image lazy-loading is safe; clans below the fold rarely need
+  immediate paint.

package/docs/ui/clans/UIGuide_joinClan.md

@@ -0,0 +1,196 @@
+# UI Guide — `joinClan`
+
+## Overview
+- Action-focused mutation. The user is on the clans browser or the
+  detail modal, the CTA is "Join (...)", and they click it.
+- A successful response (`errCode === 0`) means: membership persisted,
+  entry fee (if any) already debited, cooldown restarted, CRM events
+  fired. The SDK has done all of this server-side by the time the
+  promise resolves.
+- The SDK does NOT auto-refresh `getClans` after success. The
+  consumer must re-call manually.
+- Latency: typically 200–800 ms for a healthy WebSocket connection
+  (the server performs balance checks + atomic DB writes
+  synchronously).
+
+## Loading state
+
+- **Trigger**: set an in-flight flag (`joining = true`) immediately
+  on click, BEFORE the call. This is the consumer's responsibility
+  — the SDK has no in-flight guard.
+- **Visual**: replace the button label with animated dots / spinner.
+  Disable the button. Keep the modal open.
+- **Reset**: clear the in-flight flag on response — success or error.
+
+## Idempotency UI guard
+
+**Two distinct hazards** the consumer must guard against:
+
+1. **Double-click during in-flight**: the SDK does NOT prevent two
+   simultaneous `joinClan` calls. If the user clicks twice before the
+   first response arrives, both requests reach the server. If the
+   first succeeds, the second behaves as a clan-switch to the same
+   clan — which, on labels with `CLAN_COOLDOWN_DAYS = 0`, will
+   **deduct the entry fee a second time**. Guard with an in-flight
+   flag (see "Loading state").
+
+2. **Same-clan re-click**: the SDK does NOT short-circuit when the
+   user clicks Join on the clan they're already in. The server
+   treats it as a clan-switch to the same clan, and on labels with
+   cooldown=0 will re-deduct the fee. The Join button MUST be
+   disabled (or show "Your clan") whenever
+   `target.clan_id === user_clan_id`. Don't rely on the server to
+   silently no-op.
+
+Recommended pattern:
+
+```ts
+const [joining, setJoining] = useState(false);
+
+const onJoin = async () => {
+  if (joining) return;                           // in-flight guard
+  if (target.clan_id === userClanId) return;     // same-clan guard
+  if (cooldownUntil) return;                     // cooldown guard
+  if (target.member_count >= target.capacity_limit) return;
+  // (also: balance guard — handled by the pre-render CTA state matrix)
+
+  setJoining(true);
+  const r = await window._smartico.api.joinClan(target.clan_id);
+  setJoining(false);
+  handleResponse(r);
+  if (r.errCode === 0) await window._smartico.api.getClans();
+};
+```
+
+## Action button decision matrix
+
+`errCode` branch behavior. Refer to the `joinClan` TSDoc for the full
+table of codes; UI handling per code:
+
+| `errCode` | Action |
+|---|---|
+| `0` (success) | Show success toast (e.g. `"Joined {clan.name}"`). Close modal (or transition it to the "Your clan" state). Call `getClans()` to refresh `user_clan_id`, `member_count`, and `cooldown_until`. The default Smartico UI also dispatches an optimistic local state update so the Join button instantly flips to "Your clan" before the refresh lands. |
+| `1000` (invalid parameters) | Programming error from SDK consumer side — should not occur. Show a generic error toast. |
+| `1001` (not found / archived) | Refresh `getClans()`; the clan should disappear from the list. Show a brief "clan no longer available" toast. |
+| `1002` (full) | Show "Clan is full". Refresh `getClans()`; the now-full clan's button will pre-disable to "Clan is full". |
+| `1003` (insufficient funds) | Show insufficient-balance UI naming the currency (`['points','gems','diamonds'][entry_fee_currency_type_id]`) and the deficit (`entry_fee_amount`). Optional: deep-link to a currency-earning surface. |
+| `1004` (segment mismatch) | Show a gating message — operator-supplied copy if the clan exposes one; otherwise a generic "Not eligible for this clan". Don't retry. |
+| `1005` | `joinClan` does NOT return `1005`. If you see it in this method's response, treat as a generic error. |
+| `1006` (cooldown active) | Show "Cooldown until {cooldown_until local-formatted}". Disable the Join CTA across ALL clans until cooldown expires. |
+| `1007` (archived) | Defined in the public enum but the server emits `1001` instead. Handle as a synonym for `1001` defensively. |
+| `1011` | `joinClan` does NOT return `1011`. If you see it in this method's response, treat as a generic error. |
+| Other | Generic error toast with `errMsg` if any. |
+
+## Per-error-code message strategy
+
+| `errCode` | `errMsg` usable? | Operator-supplied copy | Best source |
+|---|---|---|---|
+| `0` (success) | — | — | Localized `"Joined {clan.name}"` |
+| `1003` (insufficient funds) | Fallback | — | Localized `"Insufficient {currency}"` + deficit derived from `entry_fee_amount` and the user's balance |
+| `1004` (segment mismatch) | Fallback | If the clan has an operator-supplied entry-conditions message, prefer it | Otherwise localized "Not eligible for this clan" |
+| `1006` (cooldown) | Fallback | — | Localized "Cooldown until {date}" — format `cooldown_until` from UTC to local |
+| `1002` (full) | Fallback | — | Localized "Clan is full" |
+| All others | Use `errMsg` as a fallback when no specific localized copy is available | — | Localized error per code |
+
+## Optimistic update
+
+The default Smartico UI optimistically flips the user's clan
+membership state on `errCode === 0` (before `getClans()` refreshes).
+This is **safe** for this method because:
+
+- The server has already committed the membership row when the
+  response returns.
+- The fee is already debited.
+- If the optimistic update sets `user_clan_id` to the new clan, the
+  refresh from `getClans()` will confirm the same value.
+
+You can mirror this pattern: on `errCode === 0`, immediately update
+the UI to show the user in the new clan, then re-fetch in the
+background. If the refresh disagrees (very unlikely), reconcile.
+
+Do NOT optimistically update on any non-zero `errCode` — those are
+real failures.
+
+## Success celebration
+
+The default Smartico UI does not play a dedicated celebration
+animation (no confetti, no full-screen overlay). The button flips
+to "Your clan" immediately via optimistic update, and the modal
+re-renders with refreshed member data once `getClans()` returns.
+
+If your product surface justifies a celebration, drive it from the
+`onUpdate` detection: when `result.user_clan_id` flips between
+pre-join and post-join fetches, play your celebration.
+
+## Refresh after response
+
+The SDK does NOT auto-refresh the `getClans` cache. After a
+successful join, manually call `getClans()` to pick up:
+
+- The new `user_clan_id`
+- The new `cooldown_until` (cooldown restarts at join time)
+- The updated `member_count` on the joined clan
+- The decremented `member_count` on any previously-joined clan
+  (clan-switch case)
+
+The user's balance update from the entry-fee debit arrives via the
+SDK's user-properties update channel — subscribe separately to
+{@link getUserProfile} if your UI shows the balance.
+
+## Clan-switch semantics
+
+When the user is in clan A and successfully joins clan B, the
+server performs an **atomic transition**: deactivate A membership,
+insert B membership, debit fee — all in one transaction. The user
+is never observably clanless during the switch.
+
+From the UI's perspective, this is identical to a fresh join. No
+special handling required — the response is the same `errCode === 0`,
+and `getClans()` refresh will show the user in clan B with a fresh
+cooldown.
+
+## Special case — tournament clan-pick flow
+
+When `registerInTournament(tournamentId)` returns `1005` (user has
+no clan and the tournament is clan-based), the default UI typically:
+
+1. Opens a clan-picker driven by `getClans`.
+2. User picks a clan → call `joinClan(clanId)`.
+3. On `errCode === 0`, automatically retry
+   `registerInTournament(tournamentId)`.
+4. Handle `1011` on the retry: user joined the clan but joined
+   after this tournament started (and has prior tournament scores)
+   — show an explanatory message; the user is in the clan but
+   blocked from this specific tournament run.
+
+The SDK does NOT chain these calls automatically. Each step is the
+consumer's responsibility. See the
+[UI Guide for `registerInTournament`](../tournaments/UIGuide_registerInTournament.md)
+for the recommended sequence.
+
+## Animations / transitions
+
+- **Loading dots**: 3-dot bouncing animation on the button while the
+  promise is in flight.
+- **Button state flip**: when the response arrives, animate the
+  button label transition (~150 ms ease-out).
+- **Member list refresh**: after `getClans()` re-fetch, the affected
+  clan rows (`member_count` change, your clan now highlighted) get a
+  brief highlight pulse on update.
+
+## Mobile vs desktop
+
+- **Loading state**: identical (dots on the button).
+- **Error surfacing**: desktop typically uses a toast/snackbar;
+  mobile may use a centered modal with a clear "OK" affordance.
+- **Cooldown / insufficient-balance disabled states**: rendered the
+  same way on both — the disabled button shows the constraint text.
+
+## Performance
+
+- Single round-trip per click. No batching needed.
+- The `getClans()` refresh after success adds ~50–500 ms (cache miss
+  → fresh fetch). Treat as fire-and-forget; the optimistic UI flip
+  has already happened.
+- Don't poll `getClans()` to detect join completion — the response
+  promise is the authoritative signal.

package/docs/ui/gamepick/UIGuide_gamePickGetActiveRound.md

@@ -0,0 +1,99 @@
+# UI Guide — `gamePickGetActiveRound`
+
+## Overview
+- Returns a single round with its events, user selections, scoring rules.
+- Powers the round-detail / prediction-input screen.
+- No cache; no push subscription.
+
+## Detail view layout
+
+Top-to-bottom sections in the default Smartico UI:
+
+1. **Header**: round name + description + status pill (see
+   [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds)
+   for status mapping).
+2. **Timer / deadline**: countdown to `last_bet_date` ("Bets close in 2h 15m").
+3. **Score recap (if scored)**: `user_score`, full/partial/lost counts.
+4. **Event list**: one row per event in `events[]`.
+
+## Event row layout
+
+Each event row carries:
+
+| Field | Source | Notes |
+|---|---|---|
+| Teams / question | `event_meta.team1_name`, `event_meta.team2_name` (MatchX) or `event_meta.text` (Quiz) | Heading |
+| Team images | `event_meta.team1_img`, `event_meta.team2_img` | 32×32 px (1:1) |
+| Match date | `match_date` | "Sat 25 May · 16:00" |
+| Sport | `event_meta.sport` | Small chip |
+| Odds | `odds_details` | Optional display |
+| User selection input | based on `market_type_id` | Score pickers (MatchX) / radio (Quiz) |
+| Resolution badge | `resolution_type_id` (`GamePickResolutionType`) | Only after resolution |
+| `is_open_for_bets` | boolean | Disable input when false |
+
+## Prediction input by `market_type_id`
+
+| Market | Input type |
+|---|---|
+| MatchX Goals / Winner | Two numeric pickers (team1 score / team2 score) |
+| Quiz 1×2 | Three buttons (1 / X / 2) |
+| Quiz Yes / No | Two buttons (Yes / No) |
+| Quiz custom | Operator-defined buttons |
+
+## Action button decision matrix
+
+Bottom CTA per round state:
+
+| State | CTA |
+|---|---|
+| `is_active_now && has_open_for_bet_events && !user_placed_bet` | "Submit predictions" (primary) |
+| `is_active_now && has_open_for_bet_events && user_placed_bet` (and edits made) | "Update predictions" (primary) |
+| `is_active_now && user_placed_bet` (no pending changes) | Disabled "Predictions submitted" |
+| `!has_open_for_bet_events` | Hidden / "View only" message |
+| `is_resolved` | "View results" — links to history |
+
+## Resolution badges (`GamePickResolutionType`)
+
+| Value | Badge |
+|---|---|
+| `None` (0) | No badge (event not yet resolved) |
+| `Lost` (2) | Red X icon |
+| `PartialWin` (3) | Amber half-star |
+| `FullWin` (4) | Green checkmark |
+
+## Edits and `allow_edit_answers`
+
+When the round is open and an event's `is_open_for_bets` is true, the user
+can edit predictions for that event. The `allow_edit_answers` flag on the
+round controls whether edits are accepted; the server enforces this and
+returns `errCode: 3` (no-op) if submits happen after the deadline.
+
+## Error states
+
+| `errCode` | Treatment |
+|---|---|
+| `4` (round / event not found) | Refresh active rounds and bounce back to lobby |
+| `100002` (template not found) | Bounce back to lobby |
+| `100000` (auth) | Re-init session |
+
+## Refresh
+
+- No SDK cache.
+- Re-call after a submit to surface the persisted predictions and updated
+  state.
+- Poll every 30–60 s while the user is on the screen if event resolution
+  updates matter.
+
+## Mobile vs desktop
+
+- **Mobile**: event rows stack full-width with score pickers below the
+  teams.
+- **Desktop**: 2-column event grid; score pickers inline with teams.
+
+## Performance
+
+- Single round-trip. The full event list ships in one payload.
+- For lobby views with many rounds, prefer
+  [`gamePickGetGameInfo`](../../api/classes/WSAPIGamePick.md#gamepickgetgameinfo)
+  for a metadata-only round list and only call this method when the user
+  opens a specific round.

package/docs/ui/gamepick/UIGuide_gamePickGetActiveRounds.md

@@ -0,0 +1,76 @@
+# UI Guide — `gamePickGetActiveRounds`
+
+## Overview
+- Returns every open round for a MatchX or Quiz game template, with full
+  event lists and the user's selections per event.
+- Powers the rounds-lobby screen.
+- No SDK cache; every call is a live HTTP roundtrip to the Game Pick games
+  server.
+- No push subscription — poll if you need live status updates.
+
+## List view organization
+
+Single flat list of round cards. The default Smartico UI sorts by `open_date`
+ascending (closest-opening or already-open first). Rounds with status
+`NoEventsDefined` (1) are filtered out server-side and never appear.
+
+## Item card / tile
+
+Fields rendered per round card:
+
+| Field | Source | Notes |
+|---|---|---|
+| Round name | `round_name` | Title |
+| Description | `round_description` | Subtitle (truncated) |
+| Open / close window | `open_date`, `last_bet_date` | "Bets close in 2h 15m" |
+| Event count | `events.length` | "5 matches" / "10 questions" |
+| User progress | `user_placed_bet` | "Predictions submitted" badge or "Make your picks" CTA |
+| Score so far | `user_score` | Visible after resolution |
+| Status pill | `round_status_id` | See mapping below |
+
+## Status pill mapping (`GPRoundStatus`)
+
+| Value | Label / treatment |
+|---|---|
+| `Other` (-1) | Active — green pill "Open" |
+| `NoMoreBetsAllowed` (2) | Amber pill "Bets closed" |
+| `AllEventsResolved_ButNotRound` (3) | Blue pill "Awaiting resolution" |
+| `RoundResolved` (4) | Gray pill "Resolved" |
+
+(Status 1 `NoEventsDefined` never appears here.)
+
+## Click target
+
+Single tap opens the round-detail view (calls
+[`gamePickGetActiveRound`](../../api/classes/WSAPIGamePick.md#gamepickgetactiveround)
+for that round).
+
+## Empty / loading / error states
+
+- **Empty (`errCode: 100003`)**: "No open rounds right now — check back later."
+- **Loading**: skeleton card list (2–3 placeholders).
+- **Error (`errCode: 100002`)**: "Game not found" — likely template ID is
+  wrong; bounce back to the lobby.
+- **Error (`errCode: 100000`)**: "Session expired — please log in again" —
+  hash auth failure.
+
+## Refresh
+
+- No SDK cache.
+- Poll every 30–60 s while the user is on the lobby screen to catch
+  status changes (events going from open to closed).
+- Re-call after any submit ([`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection)
+  or [`gamePickSubmitSelectionQuiz`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselectionquiz))
+  to reflect the new `user_placed_bet` state on the relevant round card.
+
+## Mobile vs desktop
+
+- **Mobile**: full-width round cards stacked vertically.
+- **Desktop**: 2- or 3-column grid of round cards.
+
+## Performance
+
+- Each call ships the full event list. For lobbies with many rounds, prefer
+  [`gamePickGetGameInfo`](../../api/classes/WSAPIGamePick.md#gamepickgetgameinfo)
+  which returns round metadata only (no events), then call this method only
+  when the user wants to see prediction-able rounds in detail.

package/docs/ui/gamepick/UIGuide_gamePickGetBoard.md

@@ -0,0 +1,81 @@
+# UI Guide — `gamePickGetBoard`
+
+## Overview
+- Returns a leaderboard scoped to one round, OR (with `round_id: -1`) the
+  season / overall leaderboard for the template.
+- Powers leaderboard screens within the Game Pick experience.
+- No cache; no push subscription.
+
+## List view organization
+
+Server-ranked. `users[]` is the public top list; `my_user` carries the
+current user's row separately (renders as a sticky "you are here" footer).
+
+## Row layout
+
+Each leaderboard row shows:
+
+| Field | Source | Notes |
+|---|---|---|
+| Rank | `gp_position` | Big number or "—" when null (not yet ranked) |
+| Avatar | `avatar_url` | 32×32 px (1:1) |
+| Username | `public_username` | May be masked / anonymized by label settings — see below |
+| Score | `resolution_score` | Total score in the scoped period |
+| Stats (full / part / lost) | `full_wins_count`, `part_wins_count`, `lost_count` | Optional inline pills |
+
+### Username masking
+
+Label settings can anonymize `public_username` for other players. Pair the
+username with the avatar so the user can still recognize themselves visually
+even when usernames are masked.
+
+## "You are here" footer (`my_user`)
+
+When the response includes `my_user`, render it as a sticky footer always
+visible at the bottom of the leaderboard. This gives the user a fixed
+anchor regardless of scroll position. When `my_user` is `null` (user
+hasn't predicted in this scope), render a CTA: "Play a round to join the
+leaderboard."
+
+## `round_id` modes
+
+| `round_id` | Returns |
+|---|---|
+| Positive | Per-round leaderboard (only scores from that round's events) |
+| `-1` | Season / overall leaderboard (aggregated across all rounds of the template) |
+
+Use a top tab or segmented control to let the user switch between per-round
+and season views.
+
+## Empty / loading / error states
+
+- **Empty**: "No players ranked yet — be the first!"
+- **Loading**: skeleton row list (5–10 placeholders).
+- **Error (`errCode: 100002`)**: "Game not found" — bounce back.
+- **Error (`errCode: 100000`)**: "Session expired" — re-init.
+
+## Refresh
+
+- No SDK cache.
+- Poll every 30–60 s while the leaderboard is on screen to surface rank
+  changes after events resolve.
+- Re-call after every successful round resolution (status transitions to
+  `RoundResolved` (4)).
+
+## Click-through (view another player's picks)
+
+From a leaderboard row, allow the user to tap-through to
+[`gamePickGetRoundInfoForUser`](../../api/classes/WSAPIGamePick.md#gamepickgetroundinfoforuser)
+using `users[].int_user_id` to inspect that player's predictions. The default
+Smartico UI opens this in a modal / sheet over the leaderboard.
+
+## Mobile vs desktop
+
+- **Mobile**: full-width rows; sticky footer for `my_user`.
+- **Desktop**: full-width rows centered with max-width; sticky footer.
+
+## Performance
+
+- Server-paginated implicitly — typical responses are top 20–100 players
+  plus the user's row.
+- No virtualization needed unless the response is >200 rows.