@smartico/public-api 0.0.380 → 0.0.382

package/docs/ui/gamepick/UIGuide_gamePickGetBoard.md

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

package/docs/ui/gamepick/UIGuide_gamePickGetGameInfo.md

@@ -0,0 +1,78 @@
+# UI Guide — `gamePickGetGameInfo`
+
+## Overview
+- Returns the game template configuration + metadata for every round
+  (without events).
+- Powers the game welcome / lobby screen.
+- Lighter than
+  [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds)
+  because it omits the per-round event payload.
+- No cache; no push subscription.
+
+## Welcome / lobby layout
+
+The default Smartico UI uses this for the top-level Game Pick screen:
+
+| Section | Source |
+|---|---|
+| Game title | `sawTemplate.saw_template_ui_definition.name` |
+| Branding image | `sawTemplate.saw_template_ui_definition` (theme-dependent) |
+| Buy-in chip | `saw_buyin_type_id` + `buyin_cost_*` (see table below) |
+| Attempts counter | `spin_count` (visible when `saw_buyin_type_id` is Spins) |
+| Rounds list | `allRounds[]` |
+
+## Buy-in chip mapping (`saw_buyin_type_id`)
+
+| Value | Display |
+|---|---|
+| Free (0) | "Free to play" pill |
+| Points (1) | "100 points" with points icon |
+| Gems (2) | "10 gems" with gems icon |
+| Diamonds (3) | "1 diamond" with diamonds icon |
+| Spins (4) | "X attempts left" using `spin_count` |
+
+## Rounds metadata list
+
+Each row in `allRounds[]` carries:
+
+| Field | Source | Notes |
+|---|---|---|
+| Round name | `round_name` | Title |
+| Description | `round_description` | Subtitle |
+| Window | `open_date`, `last_bet_date` | "Open • Bets close in 2h" |
+| Status pill | `round_status_id` | Same mapping as [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds) |
+
+Click a row → fetch
+[`gamePickGetActiveRound`](../../api/classes/WSAPIGamePick.md#gamepickgetactiveround)
+for that `round_id` (events are not in this response).
+
+## When to use this vs `gamePickGetActiveRounds`
+
+| Use this method | Use `gamePickGetActiveRounds` |
+|---|---|
+| Welcome / lobby screen showing all rounds (open + closed + resolved) | Only open rounds with their event lists |
+| When you only need round metadata (titles, windows) | When you want to render prediction inputs inline |
+| Lighter payload — skips events | Heavier — full event payload |
+
+## Refresh
+
+- No cache.
+- Re-call after a successful submit to refresh `spin_count`.
+- Otherwise re-call on screen mount.
+
+## Error states
+
+| `errCode` | Treatment |
+|---|---|
+| `100002` (template not found) | Show "Game not available" |
+| `100000` (auth) | Re-init session |
+
+## Mobile vs desktop
+
+- **Mobile**: header + rounds stacked vertically.
+- **Desktop**: header on top, rounds in a 2-column grid below.
+
+## Performance
+
+- Single round-trip with no event payload — much smaller than
+  [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds).

package/docs/ui/gamepick/UIGuide_gamePickGetHistory.md

@@ -0,0 +1,55 @@
+# UI Guide — `gamePickGetHistory`
+
+## Overview
+- Returns the full round history (active + resolved) for a MatchX or Quiz
+  game template, newest-first.
+- Powers the "Past predictions" / history tab.
+- No cache; no push subscription.
+
+## List view organization
+
+Server-sorted newest-first. No client-side sort needed. Optionally tab by:
+
+- "Resolved" — filter to `is_resolved === true`.
+- "Awaiting resolution" — filter to `round_status_id ===
+  AllEventsResolved_ButNotRound` (3).
+- "Open" — same content as
+  [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds);
+  the history endpoint includes these too but the default Smartico UI keeps
+  them in the lobby instead.
+
+## Item card / row
+
+Each row shows:
+
+| Field | Source | Notes |
+|---|---|---|
+| Round name | `round_name` | Title |
+| Resolved on | `resolution_date` or `last_bet_date` | "Resolved 22 May" |
+| User score | `user_score` | Right-aligned |
+| Full / partial / lost counts | `events` aggregated by `resolution_type_id` | Optional summary |
+| Status pill | `round_status_id` | Same mapping as [`gamePickGetActiveRounds`](../../api/classes/WSAPIGamePick.md#gamepickgetactiverounds) |
+
+**Click target**: open the round detail (typically a read-only view showing
+the user's picks plus event resolution badges).
+
+## Empty / loading / error states
+
+- **Empty**: "No past predictions yet — play a round to see your history."
+- **Loading**: skeleton list (3–5 placeholders).
+- **Error**: keep prior list if any; non-blocking banner.
+
+## Refresh
+
+- No cache.
+- Re-call when the user opens the history tab. No need to poll — resolved
+  rounds don't change once `round_status_id` reaches `RoundResolved` (4).
+
+## Mobile vs desktop
+
+- Identical row density on both.
+
+## Performance
+
+- The history endpoint can return a long list for active games. Consider
+  client-side pagination or virtualization if rendering 100+ rows.

package/docs/ui/gamepick/UIGuide_gamePickGetRoundInfoForUser.md

@@ -0,0 +1,71 @@
+# UI Guide — `gamePickGetRoundInfoForUser`
+
+## Overview
+- Returns a round with another player's predictions instead of the
+  current user's.
+- Use to power "view this player's picks" modals opened from leaderboard
+  rows.
+- The `int_user_id` comes from
+  [`gamePickGetBoard`](../../api/classes/WSAPIGamePick.md#gamepickgetboard)
+  (`users[].int_user_id`).
+- No cache.
+
+## Modal layout
+
+Open as a modal / sheet over the leaderboard. Top-to-bottom sections:
+
+1. **Header**: target player's avatar + username + rank ("Rank #3 · 240
+   pts").
+2. **Round summary**: round name + final score line.
+3. **Event list**: one row per event with the target user's pick + the
+   resolution result.
+
+## Event row layout
+
+Same as
+[`gamePickGetActiveRound`](../../api/classes/WSAPIGamePick.md#gamepickgetactiveround)
+but with two key differences:
+
+| Field | Difference |
+|---|---|
+| `user_selection` / `team{1,2}_user_selection` | Shows the TARGET user's picks, not the current user's |
+| Input | Read-only — no edit affordance |
+| Resolution badge | `resolution_type_id` ({@link GamePickResolutionType}) drives the badge — same mapping as the active round detail |
+
+## Stable `int_user_id` semantics
+
+`int_user_id` is stable within a single game template but NOT portable
+across templates. Always source it fresh from
+[`gamePickGetBoard`](../../api/classes/WSAPIGamePick.md#gamepickgetboard)
+in the current template — don't cache across template boundaries.
+
+## Empty / error states
+
+| `errCode` | Treatment |
+|---|---|
+| `4` (round / event / user not found) | Show "This player has no predictions for this round" — close the modal |
+| `100002` (template not found) | Bounce back |
+| `100000` (auth) | Re-init session |
+
+When the target user has no picks (rare — every leaderboard entry has at
+least one pick), the response succeeds with all events showing empty
+selection fields. Render as "No picks recorded for this round".
+
+## Refresh
+
+- No cache.
+- Re-fetch on modal open. Don't poll — another player's predictions are
+  fixed once they submit.
+
+## Mobile vs desktop
+
+- **Mobile**: full-screen modal sheet sliding up from the bottom.
+- **Desktop**: centered modal with backdrop.
+
+## Performance
+
+- Single round-trip. Same payload size as
+  [`gamePickGetActiveRound`](../../api/classes/WSAPIGamePick.md#gamepickgetactiveround)
+  (full event list).
+- Lazy-load — don't fetch until the user explicitly opens a leaderboard
+  row.

package/docs/ui/gamepick/UIGuide_gamePickGetUserInfo.md

@@ -0,0 +1,64 @@
+# UI Guide — `gamePickGetUserInfo`
+
+## Overview
+- Returns the user's profile within the Game Pick games server — display
+  name, avatar, mirrored balances, last sync timestamp.
+- Used for the in-game profile header. NOT a source of truth for the
+  user's live Smartico balance — use
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile) for
+  that.
+- No cache; no push subscription.
+
+## Render layout
+
+The default Smartico UI uses this in the Game Pick header / profile panel:
+
+| Element | Source |
+|---|---|
+| Avatar | `avatar_url` (40–64 px square) |
+| Username | `public_username` |
+| "Set custom username" CTA | shown when `pubic_username_set === false` |
+| Points balance | `ach_points_balance` |
+| Gems balance | `ach_gems_balance` |
+| Diamonds balance | `ach_diamonds_balance` |
+| Last sync hint | `last_wallet_sync_time` (small text "Synced 30s ago") |
+
+## Balance freshness caveat
+
+The balances here are a server-side mirror, updated at most every ~60 s
+from the user's true Smartico balance. For widget components outside the
+Game Pick context, or for affordability gating, prefer
+[`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile) — it
+reflects the live balance with push subscription updates.
+
+Within Game Pick itself, the mirrored balance is what the games server
+uses to enforce buy-ins, so it's the correct value to display alongside
+"Cost: 100 points" affordances.
+
+## First-call lazy provisioning
+
+On the user's very first call for a given template, the games server
+lazily creates their record. The call may take an extra ~200 ms on first
+call as a result. Subsequent calls are normal latency.
+
+## Refresh
+
+- No SDK cache.
+- Re-call after every successful submit
+  ([`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection)
+  or
+  [`gamePickSubmitSelectionQuiz`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselectionquiz))
+  to refresh the mirrored balances.
+- Don't poll faster than every 60 s — the server-side mirror only
+  refreshes that often.
+
+## Mobile vs desktop
+
+- **Mobile**: condensed avatar + username; balances in a row underneath.
+- **Desktop**: avatar + name on the left, balances aligned right.
+
+## Performance
+
+- Single round-trip.
+- For multi-balance display elsewhere, prefer `getUserProfile` to avoid
+  the ~1-minute staleness of the mirror.

package/docs/ui/gamepick/UIGuide_gamePickSubmitSelection.md

@@ -0,0 +1,103 @@
+# UI Guide — `gamePickSubmitSelection` (MatchX)
+
+## Overview
+- Submits all MatchX score predictions for a round in one shot.
+- First successful submit charges one buy-in (per `saw_buyin_type_id`);
+  subsequent edits within the same round are free.
+- Server hard-rejects submits after `last_bet_date` with `errCode: 3` (no
+  buy-in consumed).
+
+## Loading state
+
+User taps "Submit" → enter in-flight state (spinner + disabled button).
+Server typically responds in 200–600 ms.
+
+```ts
+const [submitting, setSubmitting] = useState(false);
+
+const onSubmit = async () => {
+  if (submitting) return;
+  setSubmitting(true);
+  const r = await window._smartico.api.gamePickSubmitSelection({
+    saw_template_id,
+    round,
+  });
+  setSubmitting(false);
+  handleResult(r);
+};
+```
+
+## Idempotency guard
+
+Re-submit is safe (returns `errCode: 3` and never double-charges) but the
+double-roundtrip wastes time. Guard the call site as above.
+
+## Action button decision matrix
+
+UI behavior per `errCode`:
+
+| `errCode` | Action |
+|---|---|
+| `0` (success) | Show "Predictions saved" toast; refresh round to surface persisted picks; offer link to leaderboard |
+| `3` (no changes / all events closed) | Silent — assume user clicked Submit with no edits |
+| `4` (round / event not found) | Refresh active rounds; show "Round no longer available" |
+| `40001` (no spins left) | Disable Submit; show "Out of attempts" + top-up CTA |
+| `40003` (insufficient points) | Disable Submit; show insufficient-points message naming the deficit |
+| `40004` (max spins cap hit) | Show "Daily limit reached — try again tomorrow" |
+| `40007` (template not active) | Show "Game not currently available"; bounce back to lobby |
+| `40009` (segment mismatch) | Show "This game isn't available to you" |
+| `40011` / `40012` (gems / diamonds) | Same as `40003` for the matching currency |
+| `100002` (template not found) | Show "Game not found"; bounce back |
+| `100000` (auth) | Re-init session |
+| Other non-zero | Generic error toast; allow retry |
+
+## Buy-in feedback
+
+On the FIRST successful submit, the server deducts the buy-in. The default
+Smartico UI shows a confirmation toast naming the cost ("100 points
+deducted — good luck!"). The user's balance updates via
+[`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+`props_change` channel — re-render any balance widgets.
+
+## Refresh after success
+
+- Re-call
+  [`gamePickGetActiveRound`](../../api/classes/WSAPIGamePick.md#gamepickgetactiveround)
+  for this round to surface `user_placed_bet === true` and
+  `has_not_submitted_changes === false`.
+- The user's balance updates push automatically via the user-properties
+  channel.
+- Score is awarded later, after the operator resolves the round (status
+  transitions to `RoundResolved` (4)).
+
+## Selection format
+
+Each event must include:
+
+```ts
+{
+  gp_event_id:          number,
+  team1_user_selection: number,  // predicted score for team 1
+  team2_user_selection: number,  // predicted score for team 2
+}
+```
+
+Events not included in the submit are treated as "no change".
+
+## Mobile vs desktop
+
+- **Mobile**: full-width Submit button anchored to bottom of viewport.
+- **Desktop**: Submit button bottom-right of the round detail card.
+
+## Animations / transitions
+
+- Submit tap → button morphs to spinner.
+- On success → green checkmark briefly replaces the spinner; then toast
+  fades in.
+- On error → spinner clears; error toast slides in; button re-enables.
+
+## Performance
+
+- Single round-trip per submit.
+- Server only writes events whose selections changed (delta UPSERT),
+  so submitting the full event list is efficient.

package/docs/ui/gamepick/UIGuide_gamePickSubmitSelectionQuiz.md

@@ -0,0 +1,67 @@
+# UI Guide — `gamePickSubmitSelectionQuiz` (Quiz)
+
+## Overview
+- Submits all Quiz answers for a round in one shot.
+- First successful submit charges one buy-in (per `saw_buyin_type_id`).
+- Same error-handling matrix as
+  [`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection).
+
+## Loading state and idempotency guard
+
+Identical to
+[`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection)
+— spinner on click, guard against double-tap, single round-trip.
+
+## Action button decision matrix
+
+Identical to
+[`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection)
+— see that UI guide for the full per-`errCode` table. The codes returned
+are the same set.
+
+The reported analytics event differs: this method emits
+`minigame_quiz_prediction` instead of `minigame_matchx_prediction`.
+
+## Selection format
+
+Each event must include:
+
+```ts
+{
+  gp_event_id:    number,
+  user_selection: string,  // e.g. '1' / '2' / 'x' (1×2 market)
+                           //  or  'yes' / 'no'   (binary market)
+                           //  or  operator-defined string (custom)
+}
+```
+
+The accepted `user_selection` values depend on `market_type_id` on the event:
+
+| Market | Valid `user_selection` values |
+|---|---|
+| 1×2 | `'1'`, `'x'`, `'2'` |
+| Yes / No | `'yes'`, `'no'` |
+| Custom | Operator-defined; check the event's `event_meta` for allowed values |
+
+## Quiz UI patterns
+
+- **Radio button set** per event row — exactly one answer selectable.
+- **Locked after deadline**: when `is_open_for_bets === false`, render the
+  user's prior selection as read-only and disable the input.
+
+## Refresh after success
+
+Same as
+[`gamePickSubmitSelection`](../../api/classes/WSAPIGamePick.md#gamepicksubmitselection):
+re-fetch the active round to surface persisted state; balance updates push
+via the user-properties channel; score is awarded after operator
+resolution.
+
+## Mobile vs desktop
+
+- **Mobile**: vertical radio button list.
+- **Desktop**: horizontal button group per event.
+
+## Performance
+
+- Single round-trip; delta UPSERT — only changed selections are written.

package/docs/ui/general/UIGuide_getCustomSections.md

@@ -0,0 +1,137 @@
+# UI Guide — `getCustomSections`
+
+## Overview
+- Returns the user-eligible custom sections that the operator configured in the
+  BO. Each section is a nav-level entry the consumer renders in a side menu /
+  bottom-bar / desktop sidebar.
+- `section_type_id` (see `AchCustomSectionType`) is the dispatch key — it tells
+  the consumer which page component to mount when the user opens the section.
+- 30 s cache; no push subscription.
+
+## Nav layout
+
+Render sections in the order returned — do NOT re-sort client-side. The operator
+chose the order; preserve it.
+
+| Surface | Default Smartico UI behavior |
+|---|---|
+| Mobile hamburger menu | `menu_img` (left) + `menu_name` (label) |
+| Desktop sidebar / new navbar | `menu_img` + `menu_name` row |
+| Home bottom tab bar | `menu_img` as the icon for each tab |
+
+## Section type → page mapping
+
+`section_type_id` drives the component to mount:
+
+| `AchCustomSectionType` | Page behavior |
+|---|---|
+| `HTML_PAGE` (1) | Render `body` as raw HTML in a sandboxed container |
+| `MISSIONS_CATEGORY` (2) | Mount the missions page; filter to missions in this section |
+| `TOURNAMENTS_CATEGORY` (3) | Mount the tournaments page; filter to tournaments in this section |
+| `LEVELS` (4) | Liquid-template page; render `body` inside an iframe with the data context selected via `liquid_entity_data` |
+| `MINI_GAMES` (5) | Mount the SAW page; filter mini-games to this section |
+| `MISSION_CUSTOM_LAYOUT` (6) | Themed card-grid mission view; apply `theme` + optional `custom_skin_images` + `generic_custom_css` |
+| `MATCH_X_AND_QUIZ` (7) | Mount the SAW page; filter to MatchX / Quiz games only |
+| `REDIRECT_LINK` (9) | Do NOT mount a page; on click resolve `url_or_dp` (Smartico DP string or external URL) |
+| `LOOTBOX_WEEKLY` (10) | Mount the SAW page; filter to weekly lootbox templates |
+| `LOOTBOX_CALENDAR_DAYS` (11) | Mount the SAW page; filter to calendar-day lootbox templates |
+| `STORE` (12) | Mount the store page; filter items by `shop_category_ids` |
+| `RAFFLE` (13) | Mount the raffle page; show the raffle referenced by `raffle_id` |
+| `BADGES` (14) | Mount the badges page; filter to `ach_category_ids` |
+
+If a `section_type_id` value is not in this map, skip the section silently —
+the operator might have configured a type the consumer doesn't yet support.
+
+## Item card / nav row
+
+Fields rendered per section in the nav:
+
+| Field | Source | Notes |
+|---|---|---|
+| Icon | `menu_img` | 64 × 64 px (1:1). Fallback chain: `.webp → .png` |
+| Label | `menu_name` | Server-pre-translated |
+| Notification badge | derived (see below) | Per-section unread count |
+
+**Notification badges** — the default Smartico UI shows an unread count for
+sections of these types:
+
+- `MISSIONS_CATEGORY`: count of new missions
+- `BADGES`: count of new badges
+- `TOURNAMENTS_CATEGORY`: count of new tournaments
+- `MINI_GAMES`: count of spinnable templates
+- `LOOTBOX_WEEKLY` / `LOOTBOX_CALENDAR_DAYS`: count of spinnable lootboxes
+- `MATCH_X_AND_QUIZ`: count of unfinished MatchX / Quiz games
+
+Other types (`HTML_PAGE`, `LEVELS`, `STORE`, `RAFFLE`, `REDIRECT_LINK`) don't
+typically need a badge — the default UI omits them.
+
+## Theming (`MISSION_CUSTOM_LAYOUT` only)
+
+The `theme` field applies only to `MISSION_CUSTOM_LAYOUT` sections — it does
+not override the global widget theme for other types. The default Smartico UI
+maps `GENERIC` to a configurable layout (using `custom_skin_images` +
+`generic_custom_css`) and other values (`valentines-light`, `valentines-dark`,
+`euro-2024`) to fixed seasonal layouts.
+
+## Liquid templates (`LEVELS` type)
+
+For `section_type_id === LEVELS`, render `body` (the operator-authored Liquid
+template) inside a sandboxed iframe. Inject the data context selected by
+`liquid_entity_data` — each ID names one entity collection the consumer
+should pass into the template:
+
+| `LiquidEntityData` ID | Context name |
+|---|---|
+| `Missions` (1) | `missions` |
+| `Store` (2) | `items` + `storeItems` |
+| `Tournaments` (3) | `tournaments` |
+| `MiniGames` (4) | `miniGames` |
+| `Levels` (5) | `levels` |
+| `Jackpots` (6) | `jackpots` |
+| `Bonus` (7) | `bonuses` |
+| `Badges` (9) | `badges` + `badgeCategories` |
+| `Tournament` (10) | `singleTournament` (from `ach_tournament_id`) |
+| `Raffles` (11) | `raffles` |
+| `SingleRaffle` (12) | `singleRaffle` (from `raffle_id`) |
+
+Also always inject `userInfo`, `liquidParams` (URL params), `storeCategories`,
+`badgeCategories` for any Liquid section.
+
+Provide a `_smartico` proxy so inner template JS can call public SDK methods
+(`openMission()`, `openTournament()`, etc.) back to the parent frame via
+postMessage.
+
+## Image / asset specs
+
+- **Nav icon (`menu_img`)**: 64 × 64 px (1:1).
+- **Format**: WebP when supported; PNG fallback.
+- **Fallback chain**: `.webp → .png → default placeholder`.
+
+## Empty / loading / error states
+
+- **Empty (no sections)**: render the built-in pages only (Missions /
+  Tournaments / Store / etc.) — no custom-section additions.
+- **Loading (cold fetch)**: skeleton nav placeholders (3–5 rows).
+- **Error**: keep prior nav state if any; non-blocking banner.
+
+## Refresh
+
+- 30 s SDK cache absorbs nav re-mounts.
+- No push subscription. Sections become eligible (or ineligible) when the
+  user's segments / level change server-side; the next call after the cache
+  window expires picks the new set up.
+
+## Mobile vs desktop
+
+- **Mobile**: hamburger menu OR bottom tab bar (depending on the consumer's
+  shell).
+- **Desktop**: persistent sidebar with icon + label.
+- **Tab bar overflow**: when sections exceed the tab bar capacity (default 5),
+  the default Smartico UI moves overflow into a "More" menu.
+
+## Performance
+
+- Cache for 30 s; fetch once at app boot.
+- Pre-load `menu_img` icons at first nav render.
+- For Liquid sections (`LEVELS`), lazy-load the iframe — don't mount it until
+  the user navigates to the section.