@smartico/public-api 0.0.379 → 0.0.380

package/docs/ui/tournaments/UIGuide_getTournamentInstanceInfo.md

@@ -0,0 +1,265 @@
+# UI Guide — `getTournamentInstanceInfo`
+
+## Overview
+- Powers the **tournament detail / lobby screen** — the surface a user
+  lands on after picking an item from
+  [`getTournamentsList`](../../api/classes/WSAPITournaments.md#gettournamentslist).
+- One-shot fetch. There is no subscription and no client cache.
+  Re-call to refresh; the default Smartico UI polls every 3 s while
+  the detail view is open.
+- For a clan tournament (`is_clan_based === true`), the response also
+  carries clan-level data (`clan_leaderboard[]`,
+  `clan_prize_structure[]`, `user_clan_id`).
+
+## Detail view layout
+
+Top-to-bottom layout (desktop):
+
+  1. **Header image** — `image2` (920×200 px) rendered as
+     `background-image` on the header block; falls back to `image1` if
+     missing.
+  2. **Tournament name + back affordance** — above the image (desktop)
+     or overlaid (mobile).
+  3. **Countdown ticker** — `DD:HH:MM:SS` live ticker. Counts to
+     `end_time` while `is_in_progress`; to `start_time` while
+     `is_upcoming`. Hidden when `is_finished` / `is_cancelled`.
+     Updates every 1 second.
+  4. **Info row** — date range, buy-in, registration count
+     (`registration_count / players_max_count`), duration. On desktop,
+     this lives inside the header image; on mobile it sits below.
+  5. **Registration CTA** — see "Registration CTA" below.
+  6. **Tab strip** — General · Players (or ClanBoard) · Prizes ·
+     RelatedGames (when non-empty).
+  7. **Active tab content** — see per-tab sections below.
+  8. **Sidebar (desktop only)** — if `related_games?.length > 0`,
+     render the related-games list; otherwise render a "Prizes
+     overview" panel.
+
+Mobile layout collapses the sidebar into a tab (`RelatedGames`) and
+moves the tournament name into the header overlay.
+
+## Header image specs
+
+| Field | Source size | Used where | Fallback |
+|---|---|---|---|
+| `image2` | 920×200 px | Desktop header background | Falls back to `image1` (544×216 px) |
+| `image2_mobile` | 720×400 px | Mobile header background | Falls back to `image1` |
+
+Render as CSS `background-image`, not `<img>`. No built-in placeholder
+— provide a neutral fallback color/illustration if all three are
+missing.
+
+## Registration CTA
+
+Same rules as the card-level CTA in
+[`UIGuide_getTournamentsList`](./UIGuide_getTournamentsList.md), but
+this time clicking it actually **invokes registration** via
+[`registerInTournament`](../../api/classes/WSAPITournaments.md#registerintournament)
+rather than opening the detail view (you're already in it).
+
+| Condition | CTA label | Action |
+|---|---|---|
+| `is_can_register === true` (no clan constraint) | "Join tournament" | Call `registerInTournament(instance_id)`; show loading state while the promise is pending |
+| `is_can_register === true` AND `is_clan_based === true` AND `user_clan_id` is null | "Join tournament" | First prompt the user to pick a clan ([`joinClan`](../../api/classes/WSAPIClans.md#joinclan)), then call `registerInTournament` |
+| `registration_status === 'REGISTERED'` (before start) | "You are registered" | Disabled / informational |
+| `registration_status === 'REGISTERED'` AND `is_finished` | "You are registered" | Disabled / informational |
+| `registration_status === 'PENDING'` | "Pending approval" | Disabled |
+| `registration_status === 'REGISTERED_PENDING_QUALIFICATION'` | "Pending qualification" | Disabled |
+| `registration_type === 'AUTO'` AND active | "Automatic registration" | Disabled / informational |
+| Cancelled / expired / segment-blocked | "Registration closed" | Disabled |
+
+For segment-blocked tournaments where the user fails entry conditions,
+surface `segment_dont_match_message` (operator-supplied) below the
+CTA or in a tooltip on hover.
+
+## Tabs
+
+| Tab | When shown | Content source |
+|---|---|---|
+| **General / Info** | Always | `description` HTML (sanitize before injecting) + optional `hint_text` (T&C) |
+| **Players** | `is_clan_based === false` | `players[]` — individual leaderboard |
+| **ClanBoard** | `is_clan_based === true` (replaces Players) | `clan_leaderboard[]` — clan leaderboard |
+| **Prizes** | Always | `prizes[]` (non-clan) or `clan_prize_structure[]` (clan) |
+| **Related games** | `related_games?.length > 0` AND mobile (desktop renders this in the sidebar) | `related_games[]` |
+
+Default selected tab: General.
+
+## Player leaderboard (non-clan)
+
+Sourced from `players[]`. Columns:
+
+| Column | Source | Notes |
+|---|---|---|
+| Position | `player.position`, zero-padded (`01`, `09`, `10`, …) | Show `'-'` when tournament status is REGISTER (no one has scored yet) OR `player.position === null` |
+| Avatar | `player.avatar_url` (CDN-resized; 128×128 typical) | Operator setting `config.hide_avatars_leaderboards` may suppress |
+| Username | `player.public_username` | |
+| Score | `player.scores` | Hidden on rows where `is_me === false` if operator setting `show_other_users_score === false`. Always shown for `me`. |
+
+**Top-3 styling**: rows where `position <= 3` get optional podium
+treatment (gold / silver / bronze background or accent). CSS classes
+in the default Smartico UI: `place-1`, `place-2`, `place-3`.
+
+**"Me" row**: when `player.is_me === true`, highlight the row (e.g.
+`place-my` class — background tint, slightly larger font). The user's
+position is also surfaced separately in the dedicated "me" panel
+below the leaderboard (see "`me` panel").
+
+**Empty state**: when `players[]` is empty (e.g. tournament hasn't
+started yet, no scores recorded), render an empty-state illustration
+with copy like "No players yet" or "Be the first to register".
+
+## Clan leaderboard (clan tournaments)
+
+Sourced from `clan_leaderboard[]`, filtered to entries where
+`contributing_members > 0`. Each row:
+
+| Element | Source |
+|---|---|
+| Position badge | `clan.position` — podium styling for 1/2/3 |
+| Clan image | `clan.public_meta.image_url`; fallback to first-letter avatar |
+| Clan name | `clan.public_meta.name` |
+| "Your clan" badge | If `clan.clan_id === user_clan_id`, add a "Your clan" pill |
+| Contributing members | `clan.contributing_members` |
+| Total score | `clan.total_score`, space-formatted (`1 234 567`) + "pts" suffix |
+
+**User's clan highlight**: row gets a distinct background when
+`clan.clan_id === user_clan_id`.
+
+**Sticky "my clan" footer**: when `clan_leaderboard.length >= 5` and
+`user_clan_id` is set, pin the user's clan row at the bottom of the
+scrollable list as a sticky footer.
+
+**Clan row click** opens a modal showing that clan's individual
+player breakdown via
+[`getClanTournamentPlayers`](../../api/classes/WSAPITournaments.md#getclantournamentplayers).
+
+**Empty state**: render a Lottie animation (or static illustration) +
+"No leaders" copy.
+
+## `me` panel
+
+When `detail.me` is populated, render a **sticky "me" panel** below
+(or alongside) the leaderboard with:
+
+- Rank badge — `me.position` (or `'-'` if not yet ranked)
+- Avatar — `me.avatar_url`
+- Username — `me.public_username`
+- Score — `me.scores` (always shown, regardless of
+  `show_other_users_score`)
+
+This panel is **not** rendered when `me` is undefined (visitor mode,
+unregistered users, or registered users with no recorded score yet).
+
+The `user_position_in_clan` and `user_score_in_clan` fields on the
+response are not rendered by the default Smartico UI but are
+available on `TTournamentDetailed` if your custom UI needs them.
+
+## Prize structure
+
+### Non-clan tournaments — `prizes[]`
+
+Render as a ranked table. Each row:
+
+- **Place range**: `place_from` – `place_to`; if equal, render the
+  single value (e.g. `1st place`); otherwise a range (e.g.
+  `2nd–5th place`).
+- **Prize image**: `prizes[i].image_url` (1:1 aspect ratio).
+- **Prize description**: derived from `type` + `points`:
+  - `'POINTS_ADD'` → "{points} pts"
+  - `'TANGIBLE'` / `'BONUS'` / `'MINI_GAME_ATTEMPT'` → `name`
+  - Other types → `name` fallback
+
+### Clan tournaments — `clan_prize_structure[]`
+
+More complex — render as accordions, one per `clan_place` entry:
+
+- **Group header**: `<ordinal> Place` for clan placement (e.g.
+  `1st place`, `2nd place`). Overridable by
+  `clan_place_entry.public_meta.prize_name`.
+- **Prize type label**:
+  - `prize_type_id === 1` (Fixed) → "Fixed prizes"
+  - `prize_type_id === 2` (Dynamic) → "Dynamic prizes" (uses
+    `prize_pool_amount`)
+- **Per-tier rows** (from `tiers[]` inside each clan_place):
+  - Player place range (`player_place_from` – `player_place_to`)
+  - Tier image — `tier.public_meta.image_url` (optional)
+  - Prize amount derived from `prize_type_id` + `distribution_type`:
+    - Fixed → render `public_meta.name` (or points / gems / diamonds
+      from `details_json`)
+    - Dynamic + `distribution_type === 1` (ScoreWeighted) → render
+      `pool_amount` as "total pool" with "Score-weighted split"
+      secondary label
+    - Dynamic + `distribution_type === 2` (EqualSplit) → render
+      `pool_amount / range_size` as "avg per player" with "equal
+      split" secondary label
+
+The default Smartico UI uses a `compact` variant for mobile that
+collapses each clan_place group into a single line.
+
+## Countdown ticker
+
+`DD:HH:MM:SS` exact-digit format with 1-second tick. Each segment
+in its own `<span>` for styling; RTL-aware (segment order reverses
+in right-to-left locales).
+
+Timing source:
+- `is_upcoming` → counts down to `start_time`
+- `is_in_progress` → counts down to `end_time`
+- `is_finished` / `is_cancelled` → ticker hidden
+
+When the countdown reaches zero, don't auto-flip the UI state — wait
+for the next poll-driven refresh to pick up the lifecycle transition.
+(The detail-info call doesn't push; lifecycle reads come from polling.)
+
+## Empty / loading / error states
+
+- **Loading (first fetch)**: render a skeleton layout — header
+  placeholder, blank tab strip, shimmer rows in the active tab area.
+  Don't render `null` (avoid a layout jump when data arrives).
+- **Loading (poll refresh)**: keep the prior snapshot visible; do not
+  blank the UI. Stale state for ≤3 s is fine.
+- **`players[]` empty**: empty-state illustration with copy like
+  "No players yet". Common when the tournament is upcoming and no
+  one has registered yet.
+- **`clan_leaderboard[]` empty**: Lottie animation + "No leaders"
+  text.
+- **Error**: keep last snapshot, show a small non-blocking error
+  banner, retry on next poll tick. If the first fetch fails, show a
+  full-screen "Failed to load — Try again" with a retry button.
+
+## Animations / transitions
+
+- **Tab switch**: cross-fade content (~150 ms).
+- **Leaderboard position change**: when a player's `position` shifts
+  between polls (detect by diffing the prior snapshot), animate the
+  row to its new position (slide / FLIP animation). Helps users see
+  live movement.
+- **Countdown final 10 s**: optional pulse / color change on the
+  countdown digits.
+
+## Mobile vs desktop
+
+- **Header**: desktop renders tournament name above the image and
+  info blocks (buy-in / registration / duration) inside the image;
+  mobile overlays name inside the image and moves info blocks below.
+- **Image source**: desktop uses `image2`, mobile uses
+  `image2_mobile`; both fall back to `image1`.
+- **Tab strip**: desktop shows all 3–4 tabs; mobile drops the
+  RelatedGames tab if there are no related games (and the sidebar
+  becomes an in-tab section on mobile).
+- **Clan prize structure**: desktop uses the full accordion; mobile
+  uses a compact variant.
+- **Leaderboard**: desktop shows full 4-column rows; mobile may
+  collapse avatar + username into a single column to save horizontal
+  space.
+
+## Performance
+
+- Diff snapshots between polls to detect position changes and animate
+  only the affected rows. Avoid full re-renders of the leaderboard
+  table on every poll tick.
+- Virtualize the player list if `players.length > 100` (uncommon —
+  the server usually returns a top-N slice).
+- Stop polling when the detail view is no longer visible
+  (`IntersectionObserver` or your router-driven unmount). Each poll
+  is a real network round-trip.

package/docs/ui/tournaments/UIGuide_getTournamentsList.md

@@ -0,0 +1,236 @@
+# UI Guide — `getTournamentsList`
+
+## Overview
+- The list is the lobby surface — designed for a tabbed grid where each
+  card opens a detail view (powered by
+  [`getTournamentInstanceInfo`](../../api/classes/WSAPITournaments.md#gettournamentinstanceinfo)).
+- Register `onUpdate` on first render; treat each invocation as
+  "discard prior list, re-render from this array". `onUpdate` fires
+  only after `registerInTournament` resolves — lifecycle transitions
+  (start/finish/cancel) don't push.
+- 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.
+
+## List view organization
+
+The default Smartico UI groups tournaments into category tabs. A single
+tournament can appear in multiple tabs simultaneously.
+
+| Tab | Assignment rule | Sort |
+|---|---|---|
+| **Overview** (default) | `is_in_progress` OR `is_user_registered` OR `is_can_register` OR `is_upcoming` — i.e. anything not finished/cancelled | Featured pinned first; then by `start_time` ASC for upcoming, registered/registrable next |
+| **MyTournaments** | `is_user_registered === true` | Insertion order |
+| **InProgress** | `is_in_progress === true` | Insertion order |
+| **Upcoming** | `is_upcoming === true` | `start_time` ASC |
+| **Finished** | `is_finished === true` | Insertion order (server returns newest finished first) |
+| **Top** | `is_can_register === true` | Featured pinned first |
+
+**Featured pinning**: tournaments with `is_featured === true` AND
+`is_cancelled === false` get moved to index 0 in the Overview and Top
+tabs only. No visual difference on the card itself — just position.
+
+**Default visible tabs**:
+- Desktop: Overview · MyTournaments · InProgress · Finished
+- Mobile: Overview · MyTournaments · InProgress
+
+**Custom section filtering**: if your UI scopes the lobby to a
+specific custom section (e.g. a deep-link `?custom_section_id=42`),
+filter to tournaments whose `custom_section_id` matches; the SDK does
+not filter for you.
+
+**Bucketing helper** (raw-state to bucket — for reference):
+
+```ts
+function bucket(t: TTournament) {
+  if (t.is_in_progress) return 'live';
+  if (t.is_user_registered && !t.is_finished) return 'mine';
+  if (t.is_can_register) return 'available';
+  if (t.is_upcoming) return 'upcoming';
+  if (t.is_finished) return 'finished';
+  if (t.is_cancelled) return 'cancelled';
+  return 'other';
+}
+```
+
+Drive UI tabs from the boolean flags directly. Avoid recomputing
+state from `start_time` / `end_time` / `registration_status` — the
+SDK already encodes the canonical lifecycle.
+
+## Tournament card / tile
+
+Fields rendered on the card (top-to-bottom):
+
+- **Background image** — `image1`, documented source 544×216 px.
+  Render at a 16:9-ish aspect ratio with `background-image`. No
+  built-in placeholder — provide a neutral fallback if missing.
+- **Status badge** — top-left, color-coded by lifecycle state.
+  See "Status-specific visual treatments" below.
+- **Clan badge** — appended to the status block when
+  `is_clan_based === true`.
+- **Countdown line** — relative time string driven by `start_time`
+  (upcoming) or `end_time` (in-progress / finished). See "Countdown
+  / timing format".
+- **Tournament name** — `name`, prominent.
+- **Ribbon** — `ribbon` field. Presets (`'sale'`, `'hot'`, `'new'`,
+  `'vip'`) are CSS classes; a custom URL (250×300 px) renders as an
+  image overlay top-right.
+- **Footer row** (3 columns on desktop, may collapse on mobile):
+  - Registration count: `registration_count` / `players_max_count`
+  - Buy-in: derived from `registration_cost_points` /
+    `registration_cost_gems` / `registration_cost_diamonds` (only
+    one is set per tournament) — show "Free" if all are falsy.
+    `custom_price_text` (operator-supplied string) overrides if set.
+  - Prize pool: `prize_pool_short` if set, else a derived label
+    from `prizes[]` (or "Mixed" / "—" as fallback).
+- **CTA button** — see "Action button decision matrix".
+
+**Mobile card variant**: ribbon renders ABOVE the image (not as an
+overlay); footer typically collapses to inline buy-in/prize line.
+
+**Whole-card click** opens the detail view via
+[`getTournamentInstanceInfo`](../../api/classes/WSAPITournaments.md#gettournamentinstanceinfo);
+the CTA button click triggers the same detail-view open (it does NOT
+invoke `registerInTournament` from the card — registration is always
+performed from inside the detail view).
+
+**Fields NOT on the card** (detail-view-only):
+- `description` (HTML), full `prizes[]` table, `me` block, full player
+  leaderboard (via `getTournamentInstanceInfo`), clan leaderboard,
+  `related_games`, `min_scores_win`.
+
+## Action button decision matrix
+
+CTA label is driven by `is_can_register`, then by
+`registration_status`. Resolve in priority order — first match wins.
+
+| Condition | CTA label | Enabled? |
+|---|---|---|
+| `is_can_register === true` | "Join tournament" | Enabled — opens detail view |
+| `registration_status === 'REGISTERED'` AND not yet started | "You are registered" | Disabled (informational) |
+| `registration_status === 'REGISTERED'` AND `is_finished` | "You are registered" | Disabled (informational) |
+| `registration_status === 'PENDING'` | "Pending approval" | Disabled |
+| `registration_status === 'REGISTERED_PENDING_QUALIFICATION'` | "Pending qualification" | Disabled |
+| `registration_type === 'AUTO'` AND tournament active | "Automatic registration" | Disabled (informational) |
+| `is_clan_based` AND user has no clan | "Registration closed" | Disabled |
+| Everything else (cancelled, expired, segment-blocked, max reached, etc.) | "Registration closed" | Disabled |
+
+When CTA is "Registration closed" and the user fails segment
+conditions, surface `segment_dont_match_message` (operator-supplied)
+inside the detail view, not on the card.
+
+The CTA button is also part of the card click target — clicking it
+opens the detail view rather than invoking registration directly.
+Registration only happens from the detail-view CTA.
+
+## Image / asset specs
+
+| Field | Documented source | Aspect ratio | Used where | Fallback |
+|---|---|---|---|---|
+| `image1` | 544×216 px | ~5:2 (landscape banner) | Card grid background | Neutral placeholder if missing |
+| `image2` | 920×200 px | ~4.6:1 | Desktop lobby-detail header (rendered by detail view, not card) | Falls back to `image1` |
+| `image2_mobile` | 720×400 px | 9:5 | Mobile lobby-detail header | Falls back to `image1` |
+| `ribbon` (custom URL) | 250×300 px | 5:6 (portrait) | Card overlay | Hide ribbon if URL fails |
+| `prizes[].image_url` | 1:1 square | 1:1 | Detail-view prize table only | Hide image if missing |
+
+Do not render `image2` / `image2_mobile` on the card — they're sized
+for the detail-view header.
+
+## Status-specific visual treatments
+
+Drive from the lifecycle booleans and `registration_status`. Recommended
+treatments:
+
+| State | Card visual | Badge text |
+|---|---|---|
+| `is_upcoming` (PUBLISHED) | Full-color card | "New" |
+| `is_upcoming` (REGISTER — accepting registrations) | Full-color card, "live registration" pulse on the CTA | "Gathering" |
+| `is_in_progress` | Full-color card, optional shimmer/glow accent | "Started" / "Live" |
+| `is_finished` | Subtle desaturation (e.g. 80% opacity), no shimmer | "Finished" |
+| `is_cancelled` | Status badge collapses / hidden; card itself may be hidden by the consumer's tab logic | (none — badge hidden) |
+| `is_user_registered && !is_finished` | Color-restored card, add a "Registered" check-mark overlay | derived from `registration_status` |
+
+The default Smartico UI collapses the cancelled card's status block to
+`height: 10 px` to keep layout consistent without surfacing the
+"Cancelled" label prominently — many consumers prefer to hide cancelled
+items entirely.
+
+**Clan tournaments**: append a "Clan" pill next to the status badge
+when `is_clan_based === true`. No other structural change on the card.
+
+## Countdown / timing format
+
+The default Smartico UI uses moment.js-style relative formatting
+(`"in 3 days"`, `"in 2 hours"`, `"a few seconds ago"`) with a status
+prefix:
+
+| State | Prefix | Time source |
+|---|---|---|
+| `is_upcoming` | "Starts in" | `start_time` |
+| `is_in_progress` | "Ends in" | `end_time` |
+| `is_finished` | "Finished" | (no relative time, or `end_time` past-tense) |
+| `is_cancelled` | "Cancelled" | (no time) |
+
+Suggested format tiers (compact):
+- > 7 days → `"Starts <date>"` (e.g. `"Starts 12 Jun"`)
+- 1–7 days → `"in N days"`
+- 1–24 h → `"in Hh Mm"`
+- < 1 h → `"in Mm Ss"`, update every second
+- Within 60 s → exact seconds with 1-second tick
+
+The detail view uses a more precise `DD:HH:MM:SS` ticker; the card
+uses the compact relative form.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a shimmer grid (skeleton cards) at
+  the eventual grid layout. The first call is a network round-trip.
+- **Loading (cache hit)**: do not render a loading state — the promise
+  resolves within a microtask.
+- **Empty list**: `[]` means the user has no visible tournaments.
+  Show an empty-state illustration; copy varies by tab:
+  - Finished tab: "No tournaments finished yet"
+  - MyTournaments tab: "You haven't joined any tournaments yet"
+  - All other tabs: "No tournaments available"
+- **Error**: keep the prior list visible if any, show a small
+  non-blocking error banner, retry on the next user-driven action.
+
+## Animations / transitions
+
+- **List entry**: cards fade-in with a ~30 ms stagger on first render.
+- **Registration success celebration**: when `is_user_registered` flips
+  from `false` to `true` between fetches (detect by diffing prior list
+  in your `onUpdate` handler), play a check-mark scale-in on the
+  registered card. The default Smartico UI also briefly highlights the
+  whole card.
+- **Countdown ticker**: update once per second when remaining time is
+  under 1 hour; once per minute otherwise.
+- **Status badge transitions**: when a tournament moves from
+  `is_upcoming` to `is_in_progress` mid-render, animate the badge
+  recolor over ~300 ms. This transition happens only on cache miss /
+  refresh — not pushed live.
+
+## Mobile vs desktop
+
+- **Grid columns**: desktop 2–3, tablet 2, mobile 1 (full-width cards
+  due to the landscape image aspect ratio).
+- **Tab strip**: desktop shows Overview · MyTournaments · InProgress ·
+  Finished; mobile drops Finished to reduce horizontal scroll.
+- **Card footer**: desktop renders 3-column footer (registrations /
+  buy-in / prize pool); mobile collapses to a single-line summary.
+- **Ribbon position**: desktop overlays on the image (top-right);
+  mobile renders above the image to avoid overlap on small cards.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches; a poll loop hitting
+  `getTournamentsList` every 5 s effectively translates to one
+  network round-trip per 30 s.
+- Diff lists between fetches to detect lifecycle transitions
+  (`is_upcoming → is_in_progress`, registration flips). Avoid full
+  re-renders on every poll tick if you animate the card transitions —
+  keyed per-card rendering matters because the celebration animations
+  break if the DOM nodes are recreated.
+- The hardest perf hit is the countdown ticker. Consider rendering the
+  full countdown only on currently-visible cards (use
+  `IntersectionObserver` for off-screen virtualization on long lists).

package/docs/ui/tournaments/UIGuide_registerInTournament.md

@@ -0,0 +1,156 @@
+# UI Guide — `registerInTournament`
+
+## Overview
+- Action-focused mutation. The user is on a tournament card or detail
+  view, the CTA is "Join tournament", and they click it.
+- A successful response (`err_code === 0`) means: registration row
+  exists, buy-in already debited, lobby refresh fired. The SDK has
+  already updated the cache by the time you receive the response — the
+  `onUpdate` callback on `getTournamentsList` fires shortly after.
+- Latency: typically 100–500 ms for a healthy WebSocket connection.
+
+## Loading state
+
+- **Trigger**: set an in-flight flag (`registering = true`) immediately
+  on click, BEFORE the call. This is the consumer's responsibility —
+  the SDK does NOT have an in-flight guard.
+- **Visual**: replace the button label with animated dots (or a
+  spinner). Disable the button. Keep the modal / panel open.
+- **Reset**: clear the in-flight flag on response — success or error.
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. Two simultaneous calls both
+send to the server; both responses resolve. The first will succeed
+(`err_code = 0`); the second usually returns `30004`
+(already-registered) but may also succeed if the race is exactly tied.
+
+**Two practical guards**:
+
+```ts
+// 1. Component-local in-flight flag (simple)
+const [registering, setRegistering] = useState(false);
+
+const onJoin = async () => {
+  if (registering) return;
+  setRegistering(true);
+  const r = await window._smartico.api.registerInTournament(tournament.instance_id);
+  setRegistering(false);
+  handleResponse(r);
+};
+
+// 2. Disable the button while is_user_registered hasn't flipped yet
+const disabled = registering || tournament.is_user_registered;
+```
+
+Treat `err_code = 30004` as **idempotent success** in the UI — hide
+the Register button and show "Registered". Don't show an error.
+
+## Action button decision matrix
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Close any registration modal · Show a success toast · Refresh the detail view if open (call `getTournamentInstanceInfo` again) · The lobby list auto-refreshes via `onUpdate` — DON'T manually re-fetch `getTournamentsList` |
+| `30004` (already registered) | Same as success — treat as idempotent success |
+| `1010` (no clan) | Open a clan-pick modal driven by [`getClans`](../../api/classes/WSAPIClans.md#getclans) and [`joinClan`](../../api/classes/WSAPIClans.md#joinclan); after the clan-join resolves, call `registerInTournament` again. Don't show an error |
+| `30002` (insufficient points) | Show insufficient-points UI: `"You need X more points to join"`. Optional: deep-link to a points-earning surface. |
+| `300010` (insufficient gems) | Show insufficient-gems UI (analogous to `30002` but for gems currency). NOT in the public enum — branch on the literal numeric value. |
+| `300011` (insufficient diamonds) | Show insufficient-diamonds UI (analogous, for diamonds). NOT in the public enum — branch on the literal. |
+| `30001` (instance not found) | Refresh the lobby; the tournament is gone. Show a brief "no longer available" toast. |
+| `30003` (not in registerable state) | Refresh the lobby; the button should disappear. |
+| `30005` (segment mismatch) | Show the operator-supplied `tournament.segment_dont_match_message` if set; fall back to `err_message`. Don't retry. |
+| `30006` (anomalous "not registered") | Show generic error toast with `err_message`. Allow retry. |
+| `30007` (status-change blocked) | Show generic error toast. Don't retry. |
+| `30008` (tournament full) | Show "Tournament is full" message; the lobby auto-refresh will hide the button on the refreshed item. |
+| Other non-zero / unknown | Show generic error toast with `err_message` if any. |
+
+## Per-code error message strategy
+
+| `err_code` | Use `err_message`? | Use operator copy? | Best UX text source |
+|---|---|---|---|
+| `0` (success) | — | — | `"You're registered in {tournament.name}"` (localized) |
+| `30005` (segment mismatch) | Fallback only | **Preferred** | `tournament.segment_dont_match_message` → `err_message` → localized generic |
+| `30002` / `300010` / `300011` (no balance) | Fallback | — | Localized `"Insufficient {currency}"` with deficit amount derived from `tournament.registration_cost_*` and the user's profile balance |
+| `30008` (full) | Fallback | — | Localized `"Tournament is full"` |
+| All other `3000x` | Fallback | — | Localized error string for the code → fall back to `err_message` |
+
+`segment_dont_match_message` is a field on the root `TTournament`
+object — read it directly as `tournament.segment_dont_match_message`.
+
+## Clan tournament gating
+
+When `tournament.is_clan_based === true`, the user must already be in
+a clan before calling `registerInTournament`. Two paths:
+
+1. **Pre-call check** (recommended): in the click handler, read the
+   user's clan membership (e.g. via {@link getUserProfile}). If they
+   have no clan, open a clan-pick modal (driven by
+   [`getClans`](../../api/classes/WSAPIClans.md#getclans) +
+   [`joinClan`](../../api/classes/WSAPIClans.md#joinclan)). After
+   `joinClan` resolves, call `registerInTournament` — typically
+   automatically, without requiring a second click.
+2. **Server-side safety net**: if a race occurs (e.g. the user leaves
+   their clan between the pre-check and the server-side check), the
+   server returns `err_code = 1010`. Handle this the same way —
+   re-open the clan-pick flow, then retry.
+
+The default Smartico UI uses approach 1 with 2 as a fallback.
+
+## Optimistic update
+
+**Do NOT optimistically flip `is_user_registered`** before the
+response. The local tournament object should only update when the
+auto-refreshed lobby array arrives via `getTournamentsList`'s
+`onUpdate` callback. The `registering` in-flight flag provides
+sufficient visual feedback during the wait.
+
+If you DO use an optimistic state (for instant UI feedback), reconcile
+on the response: if `err_code !== 0` AND `err_code !== 30004`, revert
+the optimistic flip. Most consumers should skip optimistic UI for
+this mutation — the latency is short enough that a loading spinner
+suffices.
+
+## Refresh after response
+
+The SDK auto-refreshes `getTournamentsList` after every response
+(success or error) via a server push. The `onUpdate` callback on
+`getTournamentsList({ onUpdate })` fires with the refreshed array
+shortly after `registerInTournament` resolves. **Don't manually call
+`getTournamentsList()` after a register response — the cache is
+already being refreshed.**
+
+The detail view (`getTournamentInstanceInfo`) is NOT auto-refreshed.
+If the detail screen is open, call it again to get the updated
+leaderboard, registration count, and `me` block.
+
+The user's balance (after a buy-in deduction) updates via the
+SDK's user-properties channel — subscribe to user-property
+changes separately if your UI shows the balance.
+
+## Animations / transitions
+
+- **Loading dots**: 3-dot bouncing animation on the button while the
+  call is in flight.
+- **Success celebration**: when `is_user_registered` flips from
+  `false` to `true` on the refreshed lobby item, play a
+  check-mark scale-in on the registered card. The default Smartico UI
+  also fires a success toast with the tournament name.
+- **Error modal**: dismissable; auto-close after ~5 s for
+  recoverable errors (`30002`, `300010`, `300011`); persistent for
+  `30005` (operator-supplied message is usually important).
+
+## Mobile vs desktop
+
+- **Loading state**: identical (dots animation on the button).
+- **Error surfacing**: desktop typically uses a toast/snackbar;
+  mobile may use a centered modal with a clear "OK" affordance.
+- **Clan-pick flow**: full-screen slide-up sheet on mobile;
+  centered modal on desktop.
+
+## Performance
+
+- Single round-trip per click. No batching needed.
+- The lobby refresh (server push + SDK cache write + `onUpdate` fire)
+  adds ~50–100 ms after the response — fine for UI purposes.
+- Don't poll `getTournamentsList` after a register response — the
+  refresh is already happening.