@smartico/public-api 0.0.379 → 0.0.380

package/docs/api/interfaces/UserAchievement.md

@@ -214,4 +214,4 @@
 
 ### prize\_claim\_period\_type\_id?
 
-> `optional` **prize\_claim\_period\_type\_id?**: `AchievementClaimPeriodTypeId`
+> `optional` **prize\_claim\_period\_type\_id?**: [`AchievementClaimPeriodTypeId`](../enumerations/AchievementClaimPeriodTypeId.md)

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).

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/missions/UIGuide_getAchCategories.md

@@ -0,0 +1,17 @@
+# UI Guide — `getAchCategories`
+
+## UI guidance
+- Treat categories as relatively static. It is safe to fetch once on page load 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, generate one tab per category; "All" / "Other" tabs are
+  caller-provided (not returned by the server).
+- For section UIs (mission/badge listing grouped by category), iterate sorted
+  categories and render only those whose filtered item list is non-empty unless
+  you intentionally want empty sections.
+- Loading indicator: skip on cache hit; show a brief shimmer on cold fetch
+  (typically 100–300 ms).
+
+**Visitor mode**: supported. Use `_smartico.vapi(lang).getAchCategories()` to fetch
+categories with `name` translated to the given language without an authenticated user.