@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/store/UIGuide_buyStoreItem.md

@@ -0,0 +1,133 @@
+# UI Guide — `buyStoreItem`
+
+## Overview
+Buy is a server round-trip with side effects (DB writes, balance
+deduction, reward issuance, optional CRM rules). Expected latency
+200–800ms depending on reward type. Always show an in-flight
+indicator on the Buy button and disable it for the duration of the
+call; never optimistically update the local balance / pool — wait
+for the auto-refresh.
+
+## Confirm modal (recommended)
+The typical UX shows a confirm modal between the item list and the
+Buy click: tapping a card opens the item detail modal which displays
+the item image, name, full description, price, the user's current
+balance, and the Buy button. The Buy button on the **card itself**
+is optional; many implementations only show it inside the detail
+modal. This serves both as a confirmation step and as the natural
+place to render insufficient-balance / locked / sold-out messages
+next to the action.
+
+## Buy button decision matrix
+
+Apply in priority order; **first match wins**. The state checks all
+derive from a single `TStoreItem` (from `getStoreItems()`) plus the
+user's current balance (from user properties).
+
+  1. `pool != null && pool <= 0` → **disabled "Sold Out" button** (or
+     hide the Buy button and show an out-of-stock badge). Auto-refresh
+     will update the state if stock is restored.
+  2. `active_till_date && Date.now() >= active_till_date` →
+     **disabled "Expired" button**. Show the formatted expiry date.
+  3. `can_buy === false` → **disabled Buy button**. Surface
+     `cant_buy_message` (operator-defined) if set; otherwise a
+     generic "Not available" caption. This catches segment locks
+     and operator-set restrictions.
+  4. User balance for the item's `purchase_type` is less than the
+     effective price (`discounted_price ?? price`) →
+     **disabled "Insufficient balance" button**. Show how many
+     units of the currency are missing (e.g. "120 points needed").
+     The button label can stay "Buy" but with a disabled visual.
+  5. A purchase is currently in flight for this item (local flag) →
+     **Buy button with loading indicator**; ignore additional clicks.
+  6. None of the above → **enabled Buy button** labelled e.g. "Buy"
+     with the price + currency icon (points / gems / diamonds) as a
+     stamp. On click: call `buyStoreItem(item.id)`; set the local
+     in-flight flag.
+
+Variants by `purchase_type`:
+- `'points'` — show the points icon next to the price.
+- `'gems'` — show the gems icon.
+- `'diamonds'` — show the diamonds icon.
+
+If `discounted_price` is set, render both prices: the original
+`price` with a strikethrough and the `discounted_price` highlighted.
+
+## In-flight UX
+- Replace the Buy button label with a loading dots / spinner
+  animation while the promise is pending. Keep the button visually
+  "pressed" / disabled.
+- Do NOT close the detail modal during the call — closing risks the
+  user double-clicking after re-opening.
+
+## Success UX
+On `err_code === 0`:
+- Close the detail modal.
+- Show a success toast (e.g. "Item purchased successfully"). The
+  toast is the primary feedback — there is no dedicated success
+  modal for the generic case.
+- Do NOT manually re-fetch `getStoreItems()` — the auto-refresh
+  fires.
+- Reward-type-specific celebrations (e.g. opening a mini-game spin
+  immediately after a `'minigamespin'` purchase, navigating to the
+  bonus screen after a bonus purchase) are application choices and
+  not enforced by the SDK.
+
+## Error UX per code
+- For `11006` (cap reached): prefer the item's `limit_message`
+  operator copy over `err_message`.
+- For `11014` (time-window): prefer the item's `purchase_limit_message`
+  operator copy over `err_message`. Both are localized, operator-tuned
+  strings meant for the user.
+- For `11009` (sold out): show a dedicated "sold out" message.
+- For `11004`: show a localized "try again later" / "not eligible"
+  message; the raw `err_message` is rarely user-friendly.
+- For all other non-zero codes: fall back to `err_message`, or to
+  a generic "Something went wrong. Try again later." if `err_message`
+  is empty.
+- Render the error in a dedicated error modal (closing the item
+  detail modal first) or as an inline message inside the detail
+  modal — both patterns are valid; the dedicated modal is the
+  reference implementation.
+
+## Status-specific visual treatments on the item card
+- `pool != null && pool <= 0` → grey-out overlay + "Out of Stock"
+  caption. When operator-enabled, unavailable items can be visually
+  greyed out entirely.
+- `can_buy === false` → optional "cant_buy" visual treatment
+  (border / icon) + tooltip showing `cant_buy_message`.
+- `active_till_date` set → live-updating countdown overlay,
+  format `DD:HH:MM:SS` (see below). Hide once expired and replace
+  with an "Expired" badge.
+- `discounted_price` set → discount ribbon (corner overlay) showing
+  the percent or a custom ribbon image.
+- `purchased_today` / `purchased_this_week` / `purchased_this_month`
+  true → optional "purchased recently" badge; useful for items
+  with a per-period cap, hints at why the Buy button might be
+  disabled.
+
+## Countdown format
+For items with `active_till_date`:
+  - Format `DD:HH:MM:SS`, each segment zero-padded to 2 digits.
+  - Update cadence: 1 second.
+  - Once `Date.now() >= active_till_date`, hide the countdown and
+    mark the item as expired (disabled Buy button, "Expired" badge).
+
+## Animations
+- In-flight: dots / spinner animation on the Buy button.
+- Success: a celebratory animation (confetti, coin shower) for
+  high-value items is a common pattern but not enforced by the SDK.
+  The default minimal UX is the success toast.
+
+## Mobile vs desktop
+The buy flow is identical on mobile and desktop; the layout
+differences live in the parent list view (see `getStoreItems` for
+grid / row variants). The detail modal and Buy button behaviour
+are the same on both.
+
+## Empty states
+Not applicable to this method (returns a single result). For the
+list-level empty / loading / error states, see the `getStoreItems`
+documentation.
+
+**Visitor mode**: not supported.

package/docs/ui/store/UIGuide_getStoreCategories.md

@@ -0,0 +1,19 @@
+# UI Guide — `getStoreCategories`
+
+## UI guidance
+- Treat categories as relatively static. Safe to fetch once on store-page entry and
+  reuse for the lifetime of the view; the SDK's 30 s cache handles short-term re-calls.
+- Sort by `order` ascending before rendering. Items with the same `order` should fall
+  back to `name` or `id` for stable ordering.
+- For tab UIs (the common store layout), generate one tab per non-empty category.
+  The reference UI also appends the count of items in parentheses on each tab label
+  (e.g. `Bonuses (12)`) — compute the count by intersecting `getStoreItems()` with
+  each category id.
+- If you want an "All items" tab, generate it client-side; the server does not return one.
+- Loading indicator: skip on cache hit; show a brief shimmer on cold fetch (typically
+  100–300 ms).
+- Empty state: when this method returns `[]`, render the store as a flat grid (no tabs,
+  no section headers) over `getStoreItems()`.
+
+**Visitor mode**: supported. Use `_smartico.vapi(lang).getStoreCategories()` to fetch
+categories with `name` translated to the given language without an authenticated user.

package/docs/ui/store/UIGuide_getStoreItems.md

@@ -0,0 +1,264 @@
+# UI Guide — `getStoreItems`
+
+## Overview
+- Register `onUpdate` on first render and treat each invocation as
+  "discard prior list, re-render from this array". Do not merge.
+- Loading indicator: the first `getStoreItems()` is a server round-trip
+  (typically 100–500 ms); subsequent calls within the 30 s cache window
+  resolve effectively synchronously.
+- The SDK returns a flat array; tabs/sections/filters are applied
+  client-side using `category_ids`, `custom_section_id`, and
+  `only_in_custom_section`.
+- The catalog card UI is the SAME for all `type` values. Type-specific
+  behavior (lootbox reveal, bonus activation toast, SAW redirect) is
+  the consumer's responsibility AFTER the purchase succeeds, not on
+  the catalog tile itself.
+
+## List view organization
+- **Categories**: render `getStoreCategories()` as tabs/chips. For each
+  tab, filter the catalog to items whose `category_ids` includes the
+  active category id. An item present in multiple categories appears
+  under each.
+- **Custom sections**: the operator can group items into
+  custom_section_id buckets that live on a separate route from the main
+  store. Items with `only_in_custom_section: true` MUST be hidden from
+  the main store and appear only inside their `custom_section_id`.
+  Items WITHOUT that flag (but with a `custom_section_id`) appear in
+  both places.
+- **Sorting** (within a category): three modes, operator-configurable
+  default order:
+    1. "Natural" — a composite sort string from operator config
+       (commonly `canbuy desc, priority asc, price asc`). Sorts buyable
+       items above non-buyable, then by `priority` (lower first),
+       breaking ties by `price`.
+    2. "Price" — by numeric `price`, ASC or DESC.
+    3. "Name" — alphabetic by `name`, ASC or DESC.
+  Default is "Natural". Consumers may expose toggles.
+- **No status bucketing** (unlike missions). Sold-out / can't-buy
+  items are intermixed with buyable items; the "Natural" sort just
+  pushes them lower. Render them with a status overlay (see status
+  treatments below) rather than putting them in a separate tab.
+- **Search**: optional client-side substring match on `name`
+  (case-insensitive). The SDK does not paginate.
+- **No pagination**: the SDK returns the full visible catalog in one
+  response. For very large catalogs (50+ items), consider client-side
+  virtualization. The default Smartico UI does NOT virtualize.
+
+## Item card / tile (list view)
+
+Fields to render on the card:
+- `image` — documented source size **256×256 px**, 1:1 aspect ratio.
+  CSS `background-image` or `<img>` is conventional.
+- `name` — the title. Pre-translated server-side. Safe to render as
+  HTML if the consumer sanitizes first.
+- Price block — `price` rendered alongside a currency icon driven by
+  `purchase_type` (`'points'` / `'gems'` / `'diamonds'`). When
+  `discounted_price` is set, render `discounted_price` as the active
+  price and strike-through `price`.
+- Ribbon overlay (`ribbon` field) — presets `'sale'`, `'hot'`, `'new'`,
+  `'vip'` use built-in styling; any other string is a custom URL
+  (250×300 px). Position: top-left corner overlay.
+- Discount ribbon (`discount_price_ribbon`) — only when set. Presets
+  `'10' | '15' | '20' | '25' | '50'` use built-in percent-styled
+  ribbons; the literal `'custom'` uses `custom_ribbon_image` (250×300 px)
+  as the artwork. Position: top-right corner overlay (or opposite the
+  item ribbon).
+- Stock indicator — when `pool !== null`:
+    - `pool > 0`: render "In stock — N left" (using
+      `pool` as the count).
+    - `pool === 0`: render "Out of stock" / "Sold out" overlay
+      and grey-out the card if the operator enabled the
+      `grey_out_unavailable_items` config flag.
+  When `pool === null`, render no stock indicator (unlimited supply).
+- Countdown timer — render only when `active_till_date` is set AND the
+  operator enabled the per-item `show_timer` flag. Format below.
+- Buy button — labeled with the "Buy Now" CTA, the price, and the
+  currency icon. Disabled / greyed when `can_buy === false`, when the
+  user can't afford the item (live balance < `price`), or when
+  `pool === 0`.
+
+Fields NOT shown on the card (detail popup only):
+- Full `description` HTML (cards typically show just the title)
+- `hint_text` (T&C)
+- `related_games`
+- `related_item_ids`
+- `cant_buy_message` (the verbose explanation; show on the popup or as
+  a toast when the Buy button is clicked while disabled)
+- `limit_message` / `purchase_limit_message` (surfaced post-attempt via
+  the buy error toast, not pre-emptively on the card)
+
+Click target: the **whole card** opens the detail popup. The Buy button
+inside the popup is where the purchase is actually dispatched — there
+is no inline buy from the card in the default Smartico UI.
+
+## Detail popup
+
+Top-to-bottom structure (omit sections whose source field is empty):
+  1. Close button.
+  2. Item ribbon overlay (same as card).
+  3. Discount ribbon overlay (same as card).
+  4. Title (`name`).
+  5. Countdown timer (when `active_till_date && show_timer`).
+  6. Stock indicator ("In stock — N left" / "Out of stock"), with
+     grey-out applied to the image when the item is unbuyable AND the
+     operator enabled `grey_out_unavailable_items`.
+  7. Image (`image`) — render larger than the card variant.
+  8. Full `description` (HTML).
+  9. Insufficient-balance line — when the live balance for
+     `purchase_type` is less than `price`, render a localized
+     "You're short by N {points|gems|diamonds}" copy with the deficit
+     computed client-side (`price − balance`).
+  10. `cant_buy_message` — when `can_buy === false` and there's a
+      reason string (e.g. "VIP only").
+  11. Buy button block. Disabled state combines the three conditions
+      above. While the purchase RPC is in flight, replace the inner
+      price/CTA with a loading dots animation.
+  12. T&C `hint_text` — surfaced as an info-icon tooltip below the
+      Buy button (tap to expand). Not inline.
+  13. Related items / related games carousel (collapsed by default,
+      expandable). `related_item_ids` resolves against the main
+      catalog; `related_games` filtered to those with
+      `game_public_meta.enabled === true`. Show navigation arrows when
+      5+ items on desktop, 4+ on mobile.
+
+## Action button decision matrix
+
+*(Buy button)*
+
+Apply in priority order; first match wins:
+
+  1. **Purchase RPC in flight** — show loading dots over the price/CTA,
+     keep the button disabled until the response arrives. Guard
+     double-clicks at the UI layer.
+  2. `pool === 0` → **"Sold out"** state; button disabled. The card and
+     image may be greyed (operator config).
+  3. `can_buy === false` → button disabled. Surface `cant_buy_message`
+     (or `limit_message`) on the popup as the explanation.
+  4. Balance < `price` for the relevant `purchase_type` → button
+     disabled. Surface a localized insufficient-balance line with the
+     deficit.
+  5. All clear → **"Buy Now"** button enabled. On click: call
+     [buyStoreItem](../../api/classes/WSAPIStore.md#buystoreitem)(`id`) and show loading dots until the
+     response arrives.
+
+After a successful purchase ([buyStoreItem](../../api/classes/WSAPIStore.md#buystoreitem) `err_code === 0`):
+- Close the popup, show a success toast.
+- The SDK auto-fires `onUpdate` with the refreshed catalog — re-render
+  from that array, do NOT manually decrement the local `pool`.
+
+On a failed purchase, branch on `err_code` (see [buyStoreItem](../../api/classes/WSAPIStore.md#buystoreitem)
+for the full error code table — codes `11000` / `11011` / `11012` for
+insufficient balance per currency, `11006` for per-period cap reached,
+`11009` for pool emptied between catalog fetch and buy, `11014` for
+purchase-limit hit, etc.). Surface `purchase_limit_message` for the
+limit-hit case, `limit_message` for the cap-reached case; fall back to
+`err_message` otherwise.
+
+## Price rendering per `purchase_type`
+- **`'points'`**: render `price` with a "points" currency glyph; compare
+  against the user's `ach_points_balance`.
+- **`'gems'`**: render with a "gems" glyph; compare against
+  `ach_gems_balance`.
+- **`'diamonds'`**: render with a "diamonds" glyph; compare against
+  `ach_diamonds_balance`.
+- When `discounted_price` is set: the **discounted** value is the
+  active price (used for affordability checks); `price` becomes the
+  strikethrough "before" value.
+- All three balances update server-side as the user plays and arrive
+  on the user's gamification profile asynchronously — keep them live
+  without polling.
+
+## Image / asset specs
+- `image` (item icon): **256×256 px**, 1:1 aspect ratio.
+- `ribbon` (when a URL): **250×300 px** custom artwork.
+- `custom_ribbon_image` (discount ribbon when `discount_price_ribbon === 'custom'`):
+  **250×300 px**.
+- Related game thumbnails: **1:1 aspect ratio** per
+  `game_public_meta.image`.
+- No built-in fallback placeholders — consumers should provide one when
+  source fields are empty.
+
+## Status-specific visual treatments
+- **Sold out** (`pool === 0`): "Out of stock" badge on the card; image
+  greyscaled when the operator enabled `grey_out_unavailable_items`.
+  Buy button disabled.
+- **Cannot afford** (balance < `price` for `purchase_type`): Buy button
+  disabled (greyed); the rest of the card is full-color. Detail popup
+  adds the deficit line. The card image is greyscaled only when the
+  operator enabled `grey_out_unavailable_items`.
+- **Not eligible** (`can_buy === false`): same as cannot-afford
+  visually; the explanation source is `cant_buy_message` (popup) /
+  `limit_message` (post-buy-attempt).
+- **Discount active** (`discounted_price` set): show the discount
+  ribbon overlay and the strikethrough+new-price treatment.
+- **New item** (operator marked `ribbon === 'new'` OR client-side
+  tracking of newly-added ids in localStorage): "New" ribbon preset.
+  The SDK does not track "newness" — the operator's `ribbon` field is
+  the source of truth.
+- **Flash sale** (`active_till_date && show_timer`): countdown timer
+  on the card and popup.
+
+## Countdown / timing format
+
+*(for `active_till_date`)*
+
+Convention used by the default Smartico UI:
+- `DD:HH:MM:SS` (zero-padded to 2 digits each) when the timer is set.
+- Update the displayed text every **1 second**.
+- When the timer reaches 0, the item disappears from the catalog on
+  the next refresh (server filters it out). The consumer should NOT
+  need a separate "expired" state for catalog items.
+
+## Empty / loading / error states
+- **Empty catalog**: "No store items" message + illustration.
+- **Empty category** (after filter): same copy or a category-scoped
+  variant.
+- **Empty search**: no-results state with the search term.
+- **Loading**: spinner / skeleton until the first response. Subsequent
+  `onUpdate` refreshes are fast enough to render in-place without a
+  skeleton.
+- **Buy error**: surface `purchase_limit_message` (for
+  `err_code === 11014`), `limit_message` (for `err_code === 11006`), or
+  the server `err_message` as a modal/toast.
+
+## Animations / transitions
+- List entry: stagger-fade-in per card (the default Smartico UI uses a
+  ~100 ms stagger per index).
+- Popup open: bounce + fade-in on title/image; fade-in on description,
+  stock line, and balance line.
+- Buy button in flight: loading dots overlay; disable underlying CTA.
+- Purchase success: close popup, show success toast; the auto-refresh
+  re-renders the catalog (pool decrements, `can_buy` re-evaluates).
+- Card hover (desktop): optional scale/shadow per consumer's design.
+
+## Mobile vs desktop
+- Mobile: vertical scroll; the default Smartico UI uses a 2-column grid
+  for the main store and a list layout for purchase history.
+- Desktop: wider multi-column grid. Related-items carousel shows
+  navigation arrows at 5+ items on desktop vs 4+ on mobile.
+- The detail popup is structurally identical on both; only sizing
+  differs.
+
+## Performance
+- No pagination. The SDK returns the full visible catalog in one
+  response.
+- For very large catalogs (50+ items) consider client-side
+  virtualization. The default Smartico UI does NOT virtualize.
+- The 30-second SDK cache makes intra-session re-renders free; do NOT
+  poll `getStoreItems()`.
+
+**Cache TTL**: the SDK caches the response for 30 seconds. The cache is
+invalidated and re-fetched automatically after every `buyStoreItem(...)`
+call resolves for the current user. It is NOT invalidated by other
+users' purchases, by operator BO edits, or by `active_till_date`
+elapsing while the page is open.
+
+**Visitor mode**: supported, with caveats.
+- The catalog reflects the brand's proxy "visitor" user, not the actual
+  anonymous viewer. Per-user fields (`can_buy`, `pool` decrements,
+  `purchased_*` flags) reflect the proxy user's state and are not
+  meaningful for display.
+- `onUpdate` is accepted but NEVER fires in visitor mode — there is no
+  live channel, so push events are not delivered.
+- [buyStoreItem](../../api/classes/WSAPIStore.md#buystoreitem) is not supported in visitor mode; the Buy button
+  should deep-link to a login/registration flow instead.

package/docs/ui/store/UIGuide_getStorePurchasedItems.md

@@ -0,0 +1,122 @@
+# UI Guide — `getStorePurchasedItems`
+
+## Overview
+Loading indicator recommended on cold fetch (no cache hit, typical
+100–500 ms latency). The default Smartico UI renders a full-screen spinner
+while the first page is in flight, then a fade-in on the list. On load-
+more pagination, the recommended pattern is to hide the "Load more"
+button while the next page is fetching rather than showing a separate
+spinner.
+
+## List view
+- Flat newest-first list. The default Smartico UI does NOT group by date
+  (no "Today" / "This Week" / "Older" headers) and does NOT offer
+  category / type / status filter chips. If your design needs date
+  bucketing, use the SDK-provided `purchased_today` /
+  `purchased_this_week` / `purchased_this_month` booleans for grouping.
+- Pagination UI: render a "Load more" button below the list when the
+  previous page returned exactly `limit` items. Hide it once a page
+  returns fewer than `limit` rows. The default Smartico UI uses an explicit
+  button; infinite scroll is a valid alternative but not the reference
+  pattern.
+- Stagger animation: the default Smartico UI fades each row in with a
+  100 ms incremental `animationDelay` (row 0 at 0 ms, row 1 at 100 ms,
+  etc.) for a cascade effect on the first page. Optional.
+
+## Item card (history row)
+Two-column desktop / single-column-with-footer mobile layout. Rendered
+fields, top-to-bottom:
+  1. Item image (`image`) on the left, 1:1 aspect (256×256 source spec,
+     typically rendered ~64–96 px on screen via CSS).
+  2. Stock indicator — only when `pool !== null`. `pool > 0` shows
+     "In stock — N left"; `pool === 0` shows "Out of stock".
+     (This reflects CURRENT stock for "Buy Again" context, not stock at
+     purchase time.)
+  3. Item name (`name`) — HTML, sanitize to plain text or render with
+     `dangerouslySetInnerHTML` after trusted sanitization.
+  4. Price stamp — `purchase_points_amount` paired with the currency
+     icon implied by `purchase_type`. This is the historical amount
+     paid, NOT the current item `price`.
+  5. Purchase date — `purchase_ts` formatted via
+     `toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'medium' })`
+     and prefixed with a "Purchased:" label.
+  6. **"Buy Again" button** — opens the standard buy modal for the
+     same item. Disabled when:
+       - `can_buy === false` (server says the user cannot purchase it
+         right now), OR
+       - the user's current balance is below the item's CURRENT
+         `price` (not `purchase_points_amount`), OR
+       - `pool === 0` (out of stock).
+     Layout: inline on desktop (right column), in a bottom footer strip
+     on mobile.
+
+## Fields explicitly NOT rendered on the row
+- `description`, `ribbon`, `hint_text`, `custom_data`, `type`,
+  `related_games`, `category_ids`, `discounted_price`,
+  `discount_price_ribbon`, `custom_ribbon_image`, `active_till_date`,
+  `cant_buy_message` — the default Smartico UI omits these on the history
+  row.
+
+## Detail view
+No tap-to-expand inline detail view exists for history rows. "Buy
+Again" is the only action; it routes through the standard
+[getStoreItems](../../api/classes/WSAPIStore.md#getstoreitems) buy modal (full description, related games, etc.
+are surfaced there).
+
+## Status-specific treatments
+- No fulfillment status field; rows have no delivered/pending/cancelled
+  visual variants.
+- Stock-based modifier: when `pool === 0`, grey out / disable the "Buy
+  Again" button and show the "Out of stock" label in the info area.
+  This is a CURRENT availability signal, not a status on the past
+  purchase itself.
+
+## Image / asset specs
+- `image`: documented source size **256×256 px**, 1:1 aspect ratio.
+- Typically rendered via `<img>` (the default Smartico UI uses an `<img>`,
+  not CSS background-image, for history rows).
+- No built-in fallback placeholder — provide one when `image` is empty.
+
+## Date formatting
+- Format `purchase_ts` with `toLocaleString(undefined, ...)` to render
+  in the user's OS locale and timezone. Do NOT assume UTC display — the
+  stored timestamp is UTC milliseconds but humans read it locally.
+- For relative formatting ("3 hours ago", "Yesterday"), use
+  `purchased_today` / `purchased_this_week` / `purchased_this_month`
+  as buckets or compute deltas client-side.
+
+## Empty state
+When the first page returns an empty array, render a "No purchases yet"
+empty state (icon + copy). Do NOT distinguish "no purchases at all"
+from "no purchases in selected period" — this method has no period
+filter, so any empty response means the user has zero history entries
+total.
+
+## Error handling
+On a network or server failure the Promise rejects. The SDK does not
+surface an `err_code`/`err_message` shape on this method (the array
+either resolves or the call throws). Wrap in `try { ... } catch` and
+either retry with backoff or surface a generic "Couldn't load purchase
+history" message — the default Smartico UI's behavior is to silently clear
+the loading state, which leaves the previous list visible.
+
+## Mobile vs desktop
+- Desktop: two-column row (image left, info+actions right). "Buy Again"
+  and purchase-date inline in the info column.
+- Mobile: single-column with a bottom footer strip carrying the
+  purchase-date and the "Buy Again" button.
+- No CSS-breakpoint magic in the default Smartico UI — the layout toggle
+  is a runtime `isMobile` boolean.
+
+## Performance
+- 20 rows per page is small enough that virtualization is not needed
+  under typical history sizes.
+- Cache (30 s) is fine for in-screen re-renders. Do not call this on
+  every render — fetch once on screen mount and on demand for "Load
+  more" / `onUpdate` triggers.
+- Polling is unnecessary — the `onUpdate` callback delivers fresh data
+  automatically when the user makes another purchase. For background
+  activity (purchases made on other surfaces), the cache TTL gives
+  eventual consistency within 30 seconds of the next call.
+
+**Visitor mode**: not supported.

package/docs/ui/tournaments/UIGuide_getClanTournamentPlayers.md

@@ -0,0 +1,140 @@
+# UI Guide — `getClanTournamentPlayers`
+
+## Overview
+- Powers the clan drill-down modal opened from a clan row on the
+  tournament detail's clan leaderboard tab (see
+  [`getTournamentInstanceInfo`](../../api/classes/WSAPITournaments.md#gettournamentinstanceinfo)).
+- One-shot fetch. No cache, no polling, no subscription. Re-call to
+  refresh.
+- Returns up to ~20 players, server-sorted by score DESC. Client-side
+  re-sort is unnecessary.
+
+## Modal / drawer layout
+
+Top-to-bottom layout (centered modal on desktop, full-screen
+slide-up sheet on mobile):
+
+  1. **Close affordance** — explicit close button (top-right);
+     click-outside dismiss; Escape key dismiss.
+  2. **Clan header** — clan image (1:1 aspect ratio, fallback to
+     first-letter avatar with the clan's name), clan name, total
+     score, contributing-members count, and a rank badge (1/2/3) if
+     applicable.
+
+     The default Smartico UI populates this header from the **caller-side**
+     `ClanLeaderboardEntry` object (the row the user clicked) rather
+     than from the response's `clan_public_meta` and `clan_id` — they
+     contain the same identity but the parent context already has
+     richer data (total_score, contributing_members, position) that the
+     response doesn't carry. The response's `clan_id` and
+     `clan_public_meta.name`/`image_url` are still available for
+     consumers that need them.
+
+  3. **Table header row** — three columns: `#` (rank) · Player
+     (avatar + name) · Score.
+  4. **Player list** — one row per `players[i]`. See "Player row".
+  5. **Empty state** (when `players.length === 0`) — "No leaders" text.
+     Shown both during the loading round-trip AND when the result is
+     empty.
+
+## Player row
+
+Three columns:
+
+| Column | Source | Notes |
+|---|---|---|
+| `#` (rank) | `position ?? 0` | Plain text. Server-side rank within this clan. |
+| Player (avatar + name) | `avatar_url` (or derived from `avatar_id` + label `avatarDomain`) + `clean_ext_user_id ?? public_username` | Username prefers `clean_ext_user_id` over `public_username`; if both empty, the avatar fallback letter is also blank. |
+| Score | `scores ?? 0` | Format with space-thousands ("1 234 567") + "pts" suffix. |
+
+**"Me" row highlight**: when `is_me === true`, add a distinct
+background (CSS class `is-me` in the default Smartico UI). There is no
+sticky "me" footer in this modal — the user's row scrolls with the
+list. If your UI has many players (rare — server caps at ~20), you may
+want to auto-scroll the "me" row into view on first render.
+
+**Avatar resolution**: if `avatar_url` is already populated by the SDK,
+use it directly. Otherwise, derive a CDN URL from `avatar_id` and the
+brand's avatar domain — the SDK's `CoreUtils.avatarUrl()` does this for
+you on the response.
+
+**Top-3 styling**: optional — apply podium accent (gold/silver/bronze)
+to rows where `position <= 3`. The default Smartico UI applies the
+podium treatment only on the clan header rank badge, not on individual
+player rows.
+
+## Empty / loading / error states
+
+- **Loading**: render the modal frame and clan header immediately
+  (driven by caller-side data); render an "empty state" placeholder
+  in the player list area while the call is in flight. **Or** render a
+  skeleton rows (3–5 grey bars) — typically friendlier than the
+  empty-state text appearing then disappearing.
+- **Empty (no players)**: render the "No leaders" text. This can mean:
+  - no one in the clan has scored yet,
+  - the call failed (network / server error — the default UI silently
+    swallows the error),
+  - the `(tournamentInstanceId, clanId)` combination is invalid.
+
+  These three are not distinguishable in the response itself. The
+  default UI treats them identically. If your UI cares to distinguish,
+  attach a `.catch()` to surface a transient-error toast.
+- **Error**: not surfaced by default. Add explicit error handling if
+  needed — wrap the call in try/catch and show a "Failed to load — Try
+  again" affordance.
+
+## Close affordance
+
+Three independent dismiss mechanisms (all dispatch the same close
+action):
+
+1. Close button (top-right of modal).
+2. Click outside the modal card.
+3. `Escape` key.
+
+The default Smartico UI wires all three via a shared `useModalClose`
+hook. Mirror this pattern for parity.
+
+## Refresh
+
+- **Don't poll inside this modal**. The default Smartico UI doesn't
+  poll — the clan-leaderboard tab (parent) does poll via
+  `getTournamentInstanceInfo` and refreshes the visible clan rankings
+  when the modal closes. Live updates inside the modal are not part
+  of the default UX.
+- If your product requires live updates inside this modal, call
+  `getClanTournamentPlayers` again on a 3 s interval. Be cautious —
+  each call is a fresh network round-trip (no cache).
+
+## Pagination
+
+None at the SDK level. The server returns up to ~20 players (configured
+per tournament). There is no "load more" affordance in the default UI.
+
+## Animations / transitions
+
+- **Modal entry**: fade-in + scale (~150 ms ease-out).
+- **Modal exit**: fade-out + scale-down (~120 ms).
+- **List entry**: cards/rows fade-in staggered ~20 ms per row on
+  first render. No skeleton-to-data crossfade (the list is small
+  enough to render instantly once data arrives).
+- **Rank change between calls** (if you implement live polling): FLIP
+  animation to reorder rows.
+
+## Mobile vs desktop
+
+- **Modal style**: centered overlay on desktop with backdrop dim;
+  full-screen slide-up sheet on mobile (with a swipe-down dismiss
+  gesture).
+- **Header layout**: image left, identity right on desktop; stacked
+  (image above identity) on mobile.
+- **Row density**: identical on both — the row is already compact.
+
+## Performance
+
+- Each call is a fresh network round-trip. The page typically has at
+  most one of these in flight at a time (driven by user clicks),
+  so cost is minimal.
+- If your UI offers a "view all clans" affordance that pre-fetches
+  player lists for many clans, throttle the fetches — don't fan out
+  20 simultaneous round-trips.