@smartico/public-api 0.0.379 → 0.0.381

package/docs/ui/avatars/UIGuide_setAvatar.md

@@ -0,0 +1,118 @@
+# UI Guide — `setAvatar`
+
+## Overview
+- Activates the chosen avatar as the user's profile avatar.
+- Confirmation-style mutation — user picks an avatar in
+  [`getAvatarsList`](../../api/classes/WSAPIAvatars.md#getavatarslist)
+  (or a variant from
+  [`getAvatarsCustomized`](../../api/classes/WSAPIAvatars.md#getavatarscustomized)),
+  then taps "Apply".
+- Server validates ownership — locked avatars are rejected.
+- The SDK clears both the catalog and the customized-variant caches on
+  return; re-call those methods to surface the new `is_in_use` state.
+
+## Loading state
+
+User taps "Apply" → the button enters an in-flight state (spinner +
+disabled). The default Smartico UI keeps the picker open during the
+call and closes it after the response lands.
+
+```ts
+const [applying, setApplying] = useState(false);
+
+const onApply = async (avatar: TAvatarDefinition) => {
+  if (applying) return;
+  setApplying(true);
+  const r = await window._smartico.api.setAvatar({
+    avatar_url:     avatar.avatar_url,
+    avatar_real_id: avatar.avatar_real_id,
+  });
+  setApplying(false);
+  handleResult(r);
+};
+```
+
+## Idempotency guard
+
+The SDK does NOT prevent double-clicks. Guard the call site as above.
+Re-applying the same avatar is safe server-side (returns `err_code: 0`,
+no double side-effects), but the redundant roundtrip wastes the user's
+time.
+
+## Action button decision matrix
+
+UI behavior per `err_code`:
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Close picker; refresh header avatar; show brief "Avatar updated" confirmation (optional). |
+| `1` (not in catalog) | Refresh catalog (operator may have removed the avatar); show "Avatar no longer available". |
+| `2` (inactive) | Show "This avatar is no longer available"; refresh catalog. |
+| `3` (outside time window) | Show "Available on {active_from_date} – {active_till_date}". |
+| `4` (not owned) | Show unlock requirement / "Earn this avatar first" — possible if the catalog was stale. Refresh and re-render lock states. |
+| Other non-zero | Show generic error toast. Surface `err_message` if present. Allow retry. |
+
+The default Smartico UI shows a hardcoded "Failed to apply avatar" toast
+on any non-zero code without branching. Custom UIs should branch on the
+code and prefer `err_message` when present.
+
+## Refresh after success
+
+- The SDK auto-clears the
+  [`getAvatarsList`](../../api/classes/WSAPIAvatars.md#getavatarslist)
+  and
+  [`getAvatarsCustomized`](../../api/classes/WSAPIAvatars.md#getavatarscustomized)
+  caches.
+- The user's stored avatar updates server-side; the next call to
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)
+  reflects the new `avatar_url`.
+- **No push to other open sessions.** A second device / tab the user is
+  logged in on will not see the change until it next calls
+  `getUserProfile()` or re-identifies. If you maintain a persistent
+  header avatar across tabs, plan a periodic refresh.
+
+## Selecting the right `avatar_url`
+
+| Source | Pass as `avatar_url` |
+|---|---|
+| Catalog avatar (from `getAvatarsList`) | `avatar.avatar_url` |
+| AI variant (from `getAvatarsCustomized`) | `variant.url` |
+
+For both, pass the base `avatar_real_id` — for an AI variant, that is
+the `avatar_real_id` of the base avatar the variant was derived from
+(it's already on the `TAvatarCustomized` record).
+
+## Animations / transitions
+
+Success sequence (default Smartico UI):
+
+1. Apply tap → spinner replaces button label.
+2. On `err_code === 0` → picker closes, header avatar fades to new
+   image.
+3. Optional: brief toast "Avatar updated" auto-dismissing after ~2 s.
+
+Failure sequence:
+
+1. Apply tap → spinner replaces button label.
+2. On non-zero `err_code` → spinner clears; error toast shown; picker
+   remains open so the user can pick a different avatar.
+
+## Mobile vs desktop
+
+- **Picker**: full-screen sheet on mobile; centered modal on desktop.
+- **Apply button**: bottom bar on mobile; bottom-right of modal on
+  desktop.
+- **Toast**: bottom-center on mobile; top-right on desktop.
+
+## Empty / no-selection state
+
+The "Apply" button should be disabled until the user selects an avatar.
+While selected avatar is the user's current one, the button label
+becomes "In Use" and stays disabled.
+
+## Performance
+
+- Single round-trip.
+- No optimistic update — wait for `err_code === 0` before flipping the
+  header avatar. Locked-avatar rejection is real and would otherwise
+  produce a visible flicker.

package/docs/ui/bonuses/UIGuide_claimBonus.md

@@ -0,0 +1,144 @@
+# UI Guide — `claimBonus`
+
+## Overview
+- Action-focused mutation. The user is on the bonuses screen, the
+  CTA is "Claim" on a pending bonus tile, and they click it.
+- Success (`err_code === 0`) means the operator's integration has
+  been called to credit the bonus to the player's account. The
+  status flips to `REDEEMED` and the bonuses list auto-refreshes
+  via [`getBonuses`](../../api/classes/WSAPIBonuses.md#getbonuses)'s
+  `onUpdate`.
+- Latency: typically 300 ms – 2 s — the server calls the operator's
+  bonus API synchronously inside the claim handler, so slow
+  operator endpoints translate to slow claim responses.
+- Balance updates do NOT arrive in the claim response — the
+  operator credits the player externally and the change surfaces
+  separately (typically via the SDK's user-properties channel).
+
+## Loading state
+
+- **Trigger**: set an in-flight flag (`claiming = true`) immediately
+  on click, BEFORE the call.
+- **Visual**: replace the button label with animated dots / spinner.
+  Disable the button. Keep the claim modal open during the call.
+- **Reset**: clear the flag on response — success or error.
+
+Latency can reach 1–2 s for slow operator integrations. Use a
+clearly-visible loading state (dots ≥ 3 frames, button width
+preserved to prevent layout jump).
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. Two simultaneous calls
+both reach the server. The first succeeds; the second returns
+`err_code = -1` (bonus already claimed). Guard the call site:
+
+```ts
+const [claiming, setClaiming] = useState(false);
+
+const onClaim = async () => {
+  if (claiming) return;                          // in-flight guard
+  if (!bonus.is_redeemable) return;              // not claimable
+  setClaiming(true);
+  const r = await window._smartico.api.claimBonus(bonus.bonus_id);
+  setClaiming(false);
+  handleResponse(r);
+};
+```
+
+Treat `err_code === -1` (already claimed) as **idempotent success**
+in the UI — close the modal, show the success toast, let the
+auto-refresh land. Don't show an error.
+
+## Action button decision matrix
+
+| `err_code` | Action |
+|---|---|
+| `0` (success) | Close the claim modal · Show a success toast (e.g. "Bonus claimed!") · The bonuses list auto-refreshes via `onUpdate`; the bonus moves from Pending to Redeemed tab on the next render — DON'T manually re-fetch. Balance credit arrives separately through the operator's integration. |
+| `-1` (not claimable / already claimed) | Same as success — treat as idempotent. Usually means another tab/session already claimed it (or the bonus expired between list fetch and click). |
+| `1` (generic server error) | Show a generic error toast. Allow retry — the bonus typically lands in `REDEEM_FAILED` and remains claimable. |
+| `9999` (uncaught exception) | Same as `1` — generic error toast, retry allowed. |
+| Other non-zero | Show a generic error toast with `err_message` if present. Allow retry. |
+
+The bonus's `bonus_status_id` after a failed claim is typically
+`REDEEM_FAILED (4)`. The default Smartico UI treats `REDEEM_FAILED`
+identically to `COUPON_ISSUED` — the user sees a normal Claim
+button on their next visit and can retry without any "previously
+failed" indicator.
+
+## `success` field — ignore it
+
+The wire response does NOT consistently carry a `success` boolean.
+The `TClaimBonusResult.success?: boolean` field will be `undefined`
+in practice. **Always branch on `err_code === 0`** for the success
+check, not on the `success` field.
+
+## Acknowledge message — pre-click
+
+`label_bonus_template_meta_map.acknowledge` is the operator-supplied
+text shown in the claim modal (wagering terms, expiry notice, etc.).
+It is **template-level and static** — shown regardless of whether
+the user has clicked Claim yet, and regardless of whether the
+claim eventually succeeds. Render it always in the modal body when
+present.
+
+## Optimistic update
+
+**Do NOT optimistically flip `bonus_status_id` to `REDEEMED`** before
+the response. The server can fail (operator integration timeout,
+business-rule rejection), and the failure state needs to surface as
+a real error. Keep the bonus in its prior state until the response
+lands.
+
+The in-flight `claiming` flag provides the visual feedback during
+the wait.
+
+## Refresh after response
+
+The SDK auto-refreshes the bonuses cache on every response (success
+OR error) via the same push that delivers the claim result. The
+`onUpdate` callback registered via `getBonuses({ onUpdate })` fires
+with the refreshed array shortly after — **don't manually call
+`getBonuses()` after a claim response**, the refresh is already
+happening.
+
+The user's balance update (after a successful claim) does NOT come
+through the bonuses channel. The operator's integration credits the
+player externally; balance updates surface via
+[`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+`props_change` push channel — subscribe there separately if your UI
+shows the balance.
+
+## Animations / transitions
+
+- **Loading dots**: 3-dot bouncing animation on the button while
+  the promise is in flight.
+- **Modal close on success**: animate the modal closure (~150 ms
+  ease-out).
+- **Card cross-tab transition**: when the bonus moves from Pending
+  to Redeemed (detected via diffing the prior + refreshed lists
+  inside `onUpdate`), the default Smartico UI does not animate the
+  move — it relies on the list-level fade-in for the new Redeemed
+  card.
+- **No celebration animation** (no confetti, no sound) — bonus claim
+  uses a plain success toast. Mission and store claims have
+  celebrations; bonuses don't.
+
+## 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.
+- **Modal style**: desktop centered with backdrop dim; mobile
+  full-screen slide-up sheet.
+
+## Performance
+
+- Single round-trip per click. The handler invokes the operator's
+  bonus API synchronously, so latency depends on the operator's
+  endpoint responsiveness.
+- The refresh after the response (server push → SDK cache write →
+  `onUpdate` fire) adds ~50–100 ms beyond the claim response —
+  fine for UI purposes.
+- Don't poll `getBonuses()` to detect claim completion — the
+  response promise is the authoritative signal.

package/docs/ui/bonuses/UIGuide_getBonuses.md

@@ -0,0 +1,176 @@
+# UI Guide — `getBonuses`
+
+## Overview
+- Returns the user's bonuses (pending claims, redeemed history, and —
+  rarely — internal statuses). Drive the rendering from
+  `bonus_status_id` ({@link BonusStatus}) and `is_redeemable`.
+- The list refreshes automatically only after
+  [`claimBonus`](../../api/classes/WSAPIBonuses.md#claimbonus). Server-
+  awarded bonuses (CRM, mission rewards, store redemptions) do NOT
+  push — poll on the 30 s cache TTL if you need near-live awareness.
+- Loading indicator: skip on cache hit; show a shimmer on cold fetch
+  (typically 100–500 ms).
+
+## List view organization
+
+The default Smartico UI splits bonuses into **two tabs**:
+
+| Tab | Bucket rule | Sort |
+|---|---|---|
+| **Pending** | `bonus_status_id === 2` (`COUPON_ISSUED`) OR `bonus_status_id === 4` (`REDEEM_FAILED`) | `create_date` DESC |
+| **Redeemed** | `bonus_status_id === 3` (`REDEEMED`) | `redeem_date` DESC |
+
+Status values `New (1)`, `COUPON_ISSUE_FAILED (5)`, `EXPIRED (6)` are
+typically filtered out by widget-level operator configuration. If they
+appear, the default UI does not surface them — drop them from your
+render.
+
+**Pending tab auto-hides**: when the Pending bucket is empty, the
+default Smartico UI removes the tab strip entirely and shows only the
+Redeemed list. Restore the tab strip when a fresh pending bonus
+appears (e.g. after a poll-driven refresh).
+
+**Bucketing helper** for custom UIs:
+
+```ts
+function bucket(bonus) {
+  if (bonus.bonus_status_id === 2 || bonus.bonus_status_id === 4) return 'pending';
+  if (bonus.bonus_status_id === 3) return 'redeemed';
+  return null;  // drop internal statuses from the UI
+}
+```
+
+## Bonus card / tile
+
+Fields rendered per tile:
+
+| Field | Source | Notes |
+|---|---|---|
+| Icon | `label_bonus_template_meta_map.image_url` | 1:1 aspect ratio. No SDK-provided fallback — supply a neutral placeholder if missing. |
+| Amount / title | Prefer `bonus_meta_map.uiAmount` (e.g. `"€50"`, `"100 free spins"`); fall back to `label_bonus_template_meta_map.description` | `description` may include HTML; sanitize before injecting. |
+| Date | `create_date` for pending bonuses; `redeem_date` for redeemed bonuses | ISO 8601 UTC; parse and format in user's local time (`new Date(create_date + 'Z')`). |
+| Redirect affordance | Small icon when `label_bonus_template_meta_map.redirect_url` is set | Separate click target from the card itself (don't open the claim modal on icon click). |
+
+**Whole-card click target** behavior depends on the bonus state:
+- Pending + `is_redeemable: true` → opens the claim modal (see "Action
+  button decision matrix").
+- All other states → card is non-interactive (apply a CSS class like
+  `hover-disable` and suppress the click handler).
+
+## Detail / claim modal
+
+When the user clicks a claimable card, open a modal showing:
+
+  1. Bonus icon (`label_bonus_template_meta_map.image_url`) at a
+     larger size.
+  2. Amount / title (same fields as the card).
+  3. Description (`label_bonus_template_meta_map.description`, HTML).
+  4. **Acknowledge message** —
+     `label_bonus_template_meta_map.acknowledge` — operator-supplied
+     text always shown when set (wagering terms, expiry notice,
+     etc.). May include deep-links — pass through the SDK's deep-link
+     handler for safe execution.
+  5. Claim button (see "Action button decision matrix").
+
+The acknowledge message is **template-level static text**, not a
+dynamic success message — it appears regardless of whether the
+claim succeeds.
+
+## Action button decision matrix
+
+Drive the Claim CTA from `bonus_status_id` + `is_redeemable`:
+
+| `bonus_status_id` | `is_redeemable` | UI state |
+|---|---|---|
+| `COUPON_ISSUED` (2) | `true` | Claim button enabled — primary CTA |
+| `REDEEM_FAILED` (4) | `true` | Claim button enabled — "Try again" label is appropriate; the default Smartico UI treats this identically to first-time claim |
+| `COUPON_ISSUED` / `REDEEM_FAILED` | `false` | Card is informational only; no Claim button (auto-redeemed integration) |
+| `REDEEMED` (3) | (irrelevant) | History row; no Claim button; show `redeem_date` |
+| `New` / `COUPON_ISSUE_FAILED` / `EXPIRED` | — | Drop from UI |
+
+Clicking the Claim button invokes
+[`claimBonus`](../../api/classes/WSAPIBonuses.md#claimbonus). See its
+own UI guide for the in-flight + per-error-code matrix.
+
+## Image / asset specs
+
+| Field | Aspect ratio | Notes |
+|---|---|---|
+| `label_bonus_template_meta_map.image_url` | 1:1 (square) | Operator-supplied; recommended ~256×256 px. Fallback: render a neutral bonus icon if missing. |
+
+## Status-specific visual treatments
+
+- **Pending (`COUPON_ISSUED` / `REDEEM_FAILED`)**: full-color card,
+  pointer cursor, clickable.
+- **Non-redeemable pending** (`is_redeemable: false`): identical
+  visual but `hover-disable` CSS class, no click handler.
+- **Redeemed**: same visual; appears in the Redeemed tab only; show
+  the redemption date.
+- **No status-specific colors / badges** in the default Smartico UI
+  — branding for "successfully redeemed" lives only in tab placement,
+  not in the card chrome.
+
+`REDEEM_FAILED` is visually identical to `COUPON_ISSUED` from the
+player's perspective. The "failed" state is a server-internal
+distinction that lets the integration record a prior failed attempt
+without losing the bonus. Don't surface "failed" in the UI copy —
+treat it as "claim available".
+
+## `redirect_url` handling
+
+When `label_bonus_template_meta_map.redirect_url` is set, render a
+small redirect icon on the card. Click behavior:
+
+- URL starts with `http` / `https` → open in a new browser tab
+  (`window.open(url, '_blank')`).
+- Anything else → treat as an internal deep-link; pass to the SDK's
+  deep-link handler (`_smartico.dp(url)`).
+
+The redirect click target is **separate from** the card's click
+target. Stop event propagation on the icon click so the claim modal
+does not open simultaneously.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton grid (3–6 placeholder
+  cards) matching the eventual layout.
+- **Loading (cache hit)**: do not render a loading state — the
+  promise resolves within a microtask.
+- **Empty list**: `[]` means no bonuses are visible. Show a neutral
+  empty-state illustration with copy like "No bonuses available".
+- **Empty Pending tab (but Redeemed has items)**: per the default
+  Smartico UI, hide the tab strip entirely and show only the
+  Redeemed list. Reverse when a poll-driven refresh restores
+  pending bonuses.
+- **Error**: keep the prior list visible if any; show a small
+  non-blocking error banner; retry on the next user-driven action.
+
+## Animations / transitions
+
+- **Card entry**: stagger fade-in (~30 ms per card) on first render.
+- **Card transition on claim success**: the redeemed bonus's card
+  fades out from the Pending tab and the Redeemed tab gains a new
+  card on its next render. The default Smartico UI does not animate
+  the cross-tab move — bonus rendering relies on the standard list
+  refresh.
+- **No celebration animation on claim success** — unlike mission /
+  store claim, bonuses use a plain success toast.
+
+## Mobile vs desktop
+
+- **Grid columns**: desktop typically 2–3 columns; mobile 1
+  (full-width cards).
+- **Tab strip**: identical on both; auto-hidden when Pending is
+  empty.
+- **Detail modal**: desktop centered with backdrop dim; mobile
+  full-screen slide-up.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches. A poll loop every
+  5 s effectively translates to one round-trip per 30 s.
+- Diff snapshots between fetches to detect status flips and animate
+  only the affected cards.
+- For very large bonus histories, virtualize the Redeemed tab with
+  `IntersectionObserver` — the default Smartico UI doesn't
+  paginate, so the full list is rendered.

package/docs/ui/clans/UIGuide_getClanInfo.md

@@ -0,0 +1,153 @@
+# UI Guide — `getClanInfo`
+
+## Overview
+- Powers the **clan detail modal / page** — the surface opened after a
+  user clicks a row in the clan list (see
+  [`getClans`](../../api/classes/WSAPIClans.md#getclans)).
+- One-shot fetch. No cache, no subscription, no push refresh. Re-call
+  to refresh.
+- Returns everything a `TClan` list entry has PLUS the ranked
+  `members[]` roster and a fresh `cooldown_until`.
+
+## Detail modal layout
+
+Top-to-bottom (single responsive component — same layout on mobile
+and desktop, just resized via the modal frame):
+
+  1. **Header** — close affordance, clan icon (`public_meta.image_url`
+     fallback to first-letter avatar), clan name, description.
+  2. **Metadata row** — entry fee (or "Free"),
+     `member_count / capacity_limit` text, rating position badge.
+  3. **Members list** — see "Members list".
+  4. **Sticky "my member" footer** — when `members.find(m => m.is_me)`
+     is non-null, pin a duplicate of the user's member row at the
+     bottom of the scroll area. No row-count threshold — fires
+     whenever the user is in the clan, regardless of total member
+     count.
+  5. **Join CTA** — see "Action button decision matrix" below.
+
+There is NO inline capacity progress bar in the detail modal (the
+progress bar appears only on the list-page row, not in detail).
+
+## Members list
+
+Sourced from `members[]`, server-ordered by `contribution_score` DESC
+(i.e. `position` ASC). No client-side re-sort required.
+
+Per-row columns:
+
+| Column | Source | Notes |
+|---|---|---|
+| Position | `member.position` | Plain text — no podium / top-3 styling in the detail modal. (The list page does apply podium styling to clan rows.) |
+| Avatar | `member.avatar_url` (or derived from `avatar_id` + brand avatar domain) | Square. Render as CSS `background-image` or `<img>`. Letter-avatar fallback if both are empty. |
+| Username | `member.public_username` | The default Smartico UI uses `public_username`; some sibling surfaces (tournament clan drill-down) prefer `member.clean_ext_user_id` as primary with `public_username` as fallback. Pick whichever matches your product's identity model. |
+| "You" badge | rendered when `member.is_me === true` | Small inline pill next to the username. |
+| Contribution | `member.contribution_score` | Format with `toLocaleString()` (locale-aware thousand separators). |
+
+**"Me" row highlight**: when `member.is_me === true`, apply a row CSS
+class (e.g. `is-me`) — background tint + inline "You" badge.
+
+## Sticky "my member" footer
+
+The default Smartico UI pins a duplicate of the user's member row at
+the bottom of the scrollable members list whenever the user is in this
+clan (i.e. `members.find(m => m.is_me)` returns a non-null value).
+Same visual treatment as the inline row, just pinned to the modal's
+footer area above the Join CTA.
+
+Skip the sticky footer when the user is not a member of this clan.
+
+## Action button decision matrix
+
+Same as the list-level CTA matrix — evaluate in priority order. The
+detail modal has the most accurate state because `cooldown_until` here
+is always fresh (vs the list's 30 s-cached value).
+
+| State | Condition | Button label | Enabled? |
+|---|---|---|---|
+| **Your clan** | `detail.clan_id === user_clan_id` | "Your clan" | No-op |
+| **Cooldown active** | `detail.cooldown_until !== null` | `"Cooldown until <local-date>"` | Disabled |
+| **Clan full** | `member_count >= capacity_limit` | "Clan is full" | Disabled |
+| **Insufficient balance** | `entry_fee_amount > 0` AND balance for `entry_fee_currency_type_id` < `entry_fee_amount` | `"Not enough {Points|Gems|Diamonds} (deficit)"` | Disabled |
+| **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 |
+
+Enabled Join click invokes
+[`joinClan(clan_id)`](../../api/classes/WSAPIClans.md#joinclan); see
+its own UI guide.
+
+**Note on cooldown freshness**: the detail's `cooldown_until` will
+reflect a just-expired cooldown 30 s sooner than the list's cached
+value. If your UI cares to surface a "you're now eligible" hint
+right when the cooldown ends, watch the detail's value rather than
+the list's.
+
+## Image / asset specs
+
+| Field | Aspect ratio | Used where | Fallback |
+|---|---|---|---|
+| `public_meta.image_url` | 1:1 (square) | Modal header icon | First character of `public_meta.name` rendered as a letter avatar |
+| `members[i].avatar_url` (or derived) | 1:1 | Member row avatars | Letter-avatar with the username's first character |
+
+CDN-resolved automatically by the SDK. The default Smartico UI
+re-derives member avatars from `avatar_id` + brand `avatarDomain`
+even though `avatar_url` is pre-populated — either works.
+
+## Empty / loading / error states
+
+- **Loading**: render the modal frame and header immediately
+  (driven by the caller-side `TClan` from the list); leave the
+  members list area as a shimmer skeleton until the detail
+  response lands.
+- **`members` empty**: render an empty-state placeholder (e.g.
+  "No members yet"). Rare — clans with `member_count === 0` are
+  unusual.
+- **Invalid `clanId` / network error**: the default Smartico UI
+  silently swallows the error and leaves the members list empty.
+  For better UX, attach a `.catch()` and surface "Failed to load
+  details — Try again".
+
+## Close affordance
+
+Three independent dismiss mechanisms:
+
+1. Close button (top-right).
+2. Click outside the modal card.
+3. `Escape` key.
+
+The default Smartico UI wires all three via a shared `useModalClose`
+hook.
+
+## Animations / transitions
+
+- **Modal entry**: fade-in + scale-up (~150 ms ease-out).
+- **Modal exit**: fade-out + scale-down (~120 ms).
+- **Member rows**: stagger fade-in (~20 ms per row) on first render.
+- **Join success celebration**: when the user successfully joins
+  THIS clan (detect by `joinClan` resolving with `errCode === 0`
+  for `detail.clan_id`), re-fetch `getClanInfo` and animate the
+  sticky-footer row sliding in.
+- **Rank changes between fetches**: if you poll the detail (uncommon
+  — typically only the list polls), use a FLIP animation when
+  `position` values shift between snapshots.
+
+## Mobile vs desktop
+
+- **Single component** — no separate mobile / desktop variants of
+  the detail modal. Layout adapts via the modal frame's responsive
+  sizing.
+- **Members list density**: identical on both. Rows are compact
+  enough to fit ~6–8 visible at once on a mobile sheet.
+- **Sticky footer**: same logic on both — no row-count threshold
+  (different from the list-page sticky footer which requires ≥ 7
+  rows).
+
+## Performance
+
+- Each call is a fresh network round-trip. Avoid auto-polling the
+  detail unless your UI explicitly needs live updates — the
+  default Smartico UI fetches once per modal mount.
+- If you do poll for live rank/score updates, use a 10–30 s
+  interval and diff snapshots to animate only the changed rows.
+- Member avatars use CDN-resized URLs; lazy-loading is usually
+  unnecessary for typical clan sizes (capacity_limit is the bound).