@smartico/public-api 0.0.380 → 0.0.382

package/docs/ui/raffles/UIGuide_claimRafflePrize.md

@@ -0,0 +1,99 @@
+# UI Guide — `claimRafflePrize`
+
+## Overview
+- Action-focused mutation. The user has a winning row from a raffle
+  draw (visible via
+  [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+  with `should_claim === true` or via
+  [`getRaffleDrawRunsHistory`](../../api/classes/WSAPIRaffles.md#getraffledrawrunshistory)
+  with `has_unclaimed_prize === true`), and they click Claim.
+- Success (`errorCode === 0`) means the claim is recorded and prize
+  delivery is queued server-side. The actual delivery (wallet
+  credit, free spins, etc.) happens through the operator's
+  integration outside the SDK's response cycle.
+- Latency: typically 200 ms – 1 s for a healthy WebSocket.
+- Balance updates do NOT arrive in this response. Subscribe to
+  [`getUserProfile`](../../api/classes/WSAPIUser.md#getuserprofile)'s
+  `props_change` channel to observe credits.
+
+## Result shape note
+
+This method returns `{ errorCode, errorMessage? }` (camelCase
+full-word) — **different** from most other SDK result types that
+use `{ err_code, err_message }` (snake_case). Branch on the
+camelCase keys.
+
+## 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 detail / history view open.
+- **Reset**: clear the flag on response — success or error.
+
+## Idempotency UI guard
+
+The SDK does NOT prevent double-clicks. A second call on the same
+`won_id` returns `errorCode === 1` with `errorMessage` indicating
+the prize has already been claimed. Guard the call site:
+
+```ts
+const [claiming, setClaiming] = useState(false);
+
+const onClaim = async (won_id: number) => {
+  if (claiming) return;                     // in-flight guard
+  setClaiming(true);
+  const r = await window._smartico.api.claimRafflePrize({ won_id });
+  setClaiming(false);
+  handleResponse(r);
+};
+```
+
+Treat `errorCode === 1` with an "already claimed" message as
+**idempotent success** in the UI — the underlying state is what
+the consumer wants.
+
+## Action button decision matrix
+
+| Condition | Action |
+|---|---|
+| `errorCode === 0` (success) | Show a success toast ("Prize claimed!"). The raffles list auto-refreshes via [`getRaffles`](../../api/classes/WSAPIRaffles.md#getraffles)'s `onUpdate`; the winner row's `claimed_date` populates on the next refresh. Don't manually re-fetch. |
+| `errorCode === 1` + `errorMessage` mentions "already claimed" | Treat as success — same UI as above. Surface a brief "Already claimed" toast for clarity if you prefer. |
+| `errorCode === 1` + any other `errorMessage` (control group, mismatch) | Show a generic error toast with the operator message. Allow retry only if the message suggests transient failure. |
+| Other non-zero | Show a generic error toast. Allow retry. |
+
+## Refresh after response
+
+The SDK auto-refreshes the raffles cache on every claim response
+(success OR failure) via the same push that delivers the result.
+The `onUpdate` callback registered via `getRaffles({ onUpdate })`
+fires with the refreshed list. **Don't manually call `getRaffles()`
+after a claim** — the refresh is already happening.
+
+The winner row in the active detail view (`getRaffleDrawRun`) is
+NOT auto-refreshed — call that separately if the detail screen is
+open and you want to see `claimed_date` immediately. The default
+Smartico UI re-fetches the draw detail after a successful claim.
+
+## No celebration animation
+
+Unlike mission / SAW celebrations, the default Smartico UI does
+NOT play a confetti or full-screen animation on raffle claim. The
+winner row updates in-place with the claimed timestamp; a
+success toast is the primary visual feedback. Add a celebration
+in your own UI if your product surface calls for it.
+
+## Mobile vs desktop
+
+- **Error surfacing**: desktop snackbar / toast; mobile centered
+  modal.
+- **Modal style**: desktop centered; mobile full-screen sheet.
+- **Loading state**: identical (dots animation on the button).
+
+## Performance
+
+- Single round-trip per click.
+- Prize delivery through the operator's integration is async
+  and out-of-band — the SDK consumer doesn't observe it directly.
+- Don't poll for delivery confirmation — trust the success
+  response.

package/docs/ui/raffles/UIGuide_getRaffleDrawRun.md

@@ -0,0 +1,117 @@
+# UI Guide — `getRaffleDrawRun`
+
+## Overview
+- Powers the **draw detail / winners screen** for a single raffle
+  draw run. Adds paginated `prizes[].winners[]` rows (usernames +
+  avatars) to the same `TRaffleDraw` shape already embedded in
+  [`getRaffles`](../../api/classes/WSAPIRaffles.md#getraffles).
+- One-shot fetch. No cache, no subscription. Re-call to refresh —
+  the default Smartico UI polls on a variable cadence depending on
+  the draw's `current_state`.
+
+## Detail view layout
+
+Top-to-bottom layout:
+
+  1. **Header** — `image_url` / `image_url_mobile` as background.
+  2. **Title + state chip** — `name` + a chip driven by
+     `current_state` (Open / Drawing / Finished).
+  3. **Countdown ticker** — `DD : HH : MM : SS` to `execution_ts`
+     while Open; not rendered during WinnerSelection or after
+     Executed (replaced by drawing animation / winner list).
+  4. **Prize cards** — one per `prizes[]` entry. Each shows
+     `name`, `description`, `image_url`, `prizes_per_run_actual`,
+     and (if `current_state === Executed`) the paginated
+     `winners[]` rows.
+  5. **My tickets** — `my_tickets_count` / `my_last_tickets` for
+     Open draws.
+  6. **Opt-in / claim CTAs** — see the
+     [`requestRaffleOptin`](../../api/classes/WSAPIRaffles.md#requestraffleoptin)
+     and [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)
+     UI guides.
+
+## Winners list (paginated)
+
+When `current_state === Executed`, each prize card carries a
+`winners[]` array (type `TRafflePrizeWinner`). Render as a table:
+
+| Column | Source |
+|---|---|
+| Position | Computed from list order (the server-sorted result places the current user's wins at the top). |
+| Avatar | `winner.avatar_url`. Fallback to a letter avatar when missing. |
+| Username | `winner.username`. Fallback to "Anonymous" if empty. |
+| Ticket | `winner.ticket.ticket_id_string` (use the string form for display). |
+| Claimed | If `winner.claimed_date` is set, show "Claimed"; otherwise show "Pending" (or a Claim CTA if `should_claim === true` and the row matches the current user). |
+
+**Pagination** via `winners_from` / `winners_to`:
+
+- Default window per call: `0 – 20`.
+- Server cap per call: 50 rows. Passing a larger window silently
+  truncates.
+- Total count: `winners_total` on the returned `TRaffleDraw`.
+- The default Smartico UI uses page size 7 internally with a
+  custom pagination component — your UI can choose any size up to
+  50.
+
+For load-more pagination: advance `winners_from` by the prior page
+size on each subsequent call; reuse the same response transform.
+
+## Refresh / polling
+
+`getRaffleDrawRun` has no cache and no push refresh. Poll manually
+when the consumer is viewing a live draw. Recommended cadence
+keyed to `current_state` + remaining time:
+
+| State / Time | Poll interval |
+|---|---|
+| `WinnerSelection` (drawing) | 3 s |
+| `Open`, `< 5 minutes` to execution | 10 s |
+| `Open`, `> 5 minutes` to execution | 30 s |
+| `Executed` | No polling needed (state is terminal) |
+
+Stop polling when the detail view unmounts.
+
+## Image / asset specs
+
+Inherits from [`getRaffles`](./UIGuide_getRaffles.md#image--asset-specs):
+
+- Draw promo: 365×175 px (desktop), 300×145 px (mobile)
+- Background image: 900×85 px (desktop), 1328×240 px (mobile)
+- Prize image: 256×256 px (1:1 square)
+- Avatar: serve via CDN; letter-avatar fallback when empty
+
+## Empty / loading / error states
+
+- **Loading**: render the modal frame + countdown immediately
+  (driven by the caller-side `TRaffleDraw` from `getRaffles`);
+  show a winners-list skeleton while the call is in flight.
+- **`winners[]` empty** (Executed draw with no winners): render
+  "No winners yet" placeholder. Rare — the server should have
+  selected at least one winner per `prizes_per_run_actual`.
+- **Error**: keep the prior snapshot if any; show a non-blocking
+  error banner; retry on next poll tick.
+
+## Animations / transitions
+
+- **WinnerSelection**: full-screen Lottie drawing animation; the
+  winners list area is hidden until state transitions to Executed.
+- **Winners-list page change**: cross-fade rows on pagination.
+- **No confetti / celebration animation** on the user's win row —
+  surface a "You won!" pill on rows where `should_claim` is true
+  for the current user.
+
+## Mobile vs desktop
+
+- **Modal style**: desktop centered with backdrop dim; mobile
+  full-screen slide-up sheet.
+- **Image source**: desktop fields vs `*_mobile` fields.
+- **Winners-list layout**: desktop 4 columns; mobile may collapse
+  the position column or compact the row.
+
+## Performance
+
+- Each call is a fresh network round-trip. During live drawing
+  (3 s polling), this is the active surface; `getRaffles` is not
+  polled in parallel.
+- Pagination is server-side — don't over-fetch by passing a large
+  window; reuse smaller windows.

package/docs/ui/raffles/UIGuide_getRaffleDrawRunsHistory.md

@@ -0,0 +1,92 @@
+# UI Guide — `getRaffleDrawRunsHistory`
+
+## Overview
+- Powers a **draw-history modal / page** showing past-executed runs
+  for a raffle (optionally scoped to a single recurring draw
+  schedule).
+- Use to surface unclaimed-prize CTAs across the user's history,
+  let the user revisit completed draws, or build a "my wins"
+  surface.
+- One-shot fetch, no cache. Re-call to refresh — typically only
+  needed after a new execution lands or after a
+  [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)
+  call resolves.
+
+## List view organization
+
+Server-sorted by `execution_ts` DESC (newest first). No client-side
+sort required.
+
+If `props.draw_id` is omitted, the list interleaves history across
+all draws of the raffle. The default Smartico UI shows them in
+their server order — no per-draw grouping. To group by draw, key on
+`row.id` (the schedule_id) client-side.
+
+If `props.draw_id` is set, the list scopes to one draw's recurring
+history.
+
+## Item row
+
+Fields rendered per row:
+
+| Field | Source | Notes |
+|---|---|---|
+| Image | `image_url` (or `image_url_mobile` on mobile); fallback to `icon_url` | Same specs as in `getRaffles` UI guide. |
+| Name | `name` | |
+| Description | `description` | Optional; the default UI may omit it on dense lists. |
+| Grand badge | If `is_grand === true`, render a "Grand" pill | |
+| Scheduled date | `execution_ts` formatted as user-local date/time | |
+| Actual date | `actual_execution_ts` — typically same as scheduled, but may differ slightly on recovery paths | |
+| User won? | If `is_winner === true`, surface a "You won!" pill | |
+| Claim CTA | If `has_unclaimed_prize === true`, show a "Claim" button that opens the prize detail via [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun) | |
+
+Row click target: opens the executed draw's detail view (winner
+list) by calling `getRaffleDrawRun({ raffle_id, run_id })`.
+
+## Claim CTA on history rows
+
+When `row.has_unclaimed_prize === true`, surface a Claim button.
+Clicking it should:
+
+1. Fetch the run detail via
+   [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+   to locate the user's winning row(s).
+2. Pass each winner row's `raf_won_id` to
+   [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize).
+
+The default Smartico UI renders the Claim button inline on the
+history row and opens a confirmation flow when clicked.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton list (3–5
+  placeholder rows) sized to the eventual layout.
+- **Empty result**: `[]` means no executed runs yet. Render a
+  neutral empty-state ("No history yet").
+- **Error**: keep prior state if any; show a non-blocking error
+  banner; retry on next user-driven action.
+
+## Refresh
+
+No subscription, no cache, no push. Call manually:
+
+- After a `claimRafflePrize` resolves (to refresh
+  `has_unclaimed_prize`).
+- After a new run executes on the server side (the user observes
+  the new history row).
+- On a periodic poll if your UI wants to show new executions
+  promptly — typically not necessary for history surfaces.
+
+## Mobile vs desktop
+
+- **Image source**: `image_url_mobile` / `background_image_url_mobile`
+  on mobile.
+- **Row density**: mobile may collapse description and date columns
+  to save horizontal space.
+
+## Performance
+
+- Each call is a fresh network round-trip. Scope with `draw_id` when
+  possible to keep response size manageable.
+- Don't poll the history surface in real time — re-fetch
+  on user-initiated actions only.

package/docs/ui/raffles/UIGuide_getRaffleWonPrizes.md

@@ -0,0 +1,120 @@
+# UI Guide — `getRaffleWonPrizes`
+
+## Overview
+- Powers a **"my prizes" screen** for a single raffle — the flat list of
+  every prize the current user has won across all of that raffle's draws,
+  newest-won first.
+- One-shot, paginated fetch. No cache, no subscription. Re-call to refresh
+  (e.g. after a [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)).
+- Each row already carries `public_meta.name` + `public_meta.image_url`, so
+  you can render full prize cards without a follow-up
+  [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun) call.
+
+## List view organization
+
+- Single flat list (no per-draw grouping), ordered newest-win first.
+- There is **no** server-side "unclaimed first" ordering. If your design
+  surfaces actionable prizes at the top, sort client-side by
+  `requires_claim && !claimed_date`, then keep the server order within each
+  group.
+- Drive "load more" off `total` (the full win count across all draws), not
+  off the page length:
+
+```ts
+const hasMore = page.offset + page.won_prizes.length < page.total;
+console.log('[smartico] more pages?', hasMore);
+```
+
+## Item card / tile
+
+One card per `won_prizes[]` row:
+
+| Element | Source | Notes |
+|---|---|---|
+| Prize image | `public_meta.name` → `public_meta.image_url` | Square artwork; the default Smartico UI renders it as a circular icon. |
+| Prize name | `public_meta.name` | Localised. Truncate long names (~30 chars) with an ellipsis. |
+| Claimed / Claim CTA | `requires_claim` + `claimed_date` | See the action matrix below. |
+| Won-by attribution | `user.public_username` / `user.avatar_id` | The list belongs to one user; usually shown once in the header, not per card. |
+
+## Action button decision matrix
+
+Per row:
+
+| `requires_claim` | `claimed_date` | Render |
+|---|---|---|
+| `false` | (any) | No CTA — prize was auto-delivered. Optionally show a "Delivered" tag. |
+| `true` | `null` | **Claim** button. On click call `claimRafflePrize({ won_id: prize.raf_won_id })` — `raf_won_id` IS the `won_id`. |
+| `true` | epoch ms | No CTA — show a "Claimed" tag (optionally with the claimed date). |
+
+```ts
+const canClaim = prize.requires_claim && !prize.claimed_date;
+if (canClaim) {
+  console.log('[smartico] show Claim — on click: claimRafflePrize({ won_id:', prize.raf_won_id, '})');
+}
+```
+
+Guard the Claim button against double-clicks (set an in-flight flag on click).
+A second claim of an already-claimed prize is rejected server-side. After a
+successful claim, re-call `getRaffleWonPrizes` to pick up the new
+`claimed_date` (this method has no `onUpdate`).
+
+## User attribution (avatar + username)
+
+The `user` object describes whose prizes these are.
+
+- **Null-check `user` first** — it is `null` when `won_prizes` is empty.
+- **Avatar**: use `user.avatar_id`. If it already starts with `http`, use it
+  directly as the `<img src>`. Otherwise it is an avatar token — prepend the
+  widget's configured avatar domain (`{avatarDomain}/avatar/{avatar_id}`).
+  `user.avatar_url` is always `null`; ignore it. `user.avatar_real_id`
+  identifies the avatar definition internally and is not used for rendering.
+- **Username**: `user.public_username` is server-masked for privacy (e.g.
+  `"32:r*****"`). Render it verbatim. For the current user, show a localised
+  "You" label instead of the masked string.
+
+## Image / asset specs
+
+- Prize image (`public_meta.image_url`): square (1:1) CDN artwork. The default
+  Smartico UI renders it at 40×40 px with `border-radius: 50%`.
+- Provide a letter/placeholder fallback when `image_url` is empty.
+
+## Empty / loading / error states
+
+- **Loading**: show a card skeleton grid while the call is in flight.
+- **Empty** (`errCode === 0` and `won_prizes.length === 0`): render an empty
+  state ("No prizes won yet"). Note this is *also* the response when the user
+  is not eligible to see the raffle — the two are indistinguishable, so keep
+  the copy neutral.
+- **Error** (`errCode !== 0`): keep any prior snapshot; show a non-blocking
+  error banner with a retry. `errCode` is `1` for all server errors —
+  surface `errMsg` if present.
+
+## Refresh / polling
+
+- One-shot promise; no client cache; no push refresh.
+- Re-call on screen open, on explicit "load more", and after a successful
+  `claimRafflePrize`.
+- **Do not poll on a timer** — the server rate-limits this call (~30/min, with
+  a ~5 s minimum gap between calls). Tight polling will start failing.
+
+## Pagination
+
+- `offset` / `limit` page the rows; the SDK defaults to `0` / `20`.
+- The server does **not** clamp `limit` — pass an explicit, sane page size.
+- An `offset` past the end returns an empty page with the real `total` and
+  `errCode 0` (not an error).
+- For "load more": advance `offset` by your page size each call.
+
+## Mobile vs desktop
+
+- Desktop: multi-column card grid. Mobile: single-column list or compact
+  2-column grid.
+- The response shape is identical across viewports; only layout density
+  differs.
+
+## Performance
+
+- Each call is a fresh network round-trip. Fetch one page at a time and append
+  on "load more" rather than pre-fetching all pages.
+- The server caches responses briefly, so a quick re-open is cheap — but the
+  rate limit still applies; debounce rapid re-fetches.

package/docs/ui/raffles/UIGuide_getRaffles.md

@@ -0,0 +1,175 @@
+# UI Guide — `getRaffles`
+
+## Overview
+- Returns the user's visible raffles, each carrying an embedded
+  `draws[]` array with full per-draw state. Use as the source-of-truth
+  for the raffles lobby + draw cards.
+- The list refreshes automatically after
+  [`claimRafflePrize`](../../api/classes/WSAPIRaffles.md#claimraffleprize)
+  or
+  [`requestRaffleOptin`](../../api/classes/WSAPIRaffles.md#requestraffleoptin)
+  resolves. Server-side draw executions invalidate the SDK cache too.
+- Winner detail (usernames, avatars) requires a follow-up call to
+  [`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+  — the embedded `draws[]` carry only pagination metadata.
+
+## List view organization
+
+The default Smartico UI renders raffles as a vertical list with each
+raffle expanding to show its draws. There are no top-level tabs.
+
+Per-raffle, draws are bucketed within the detail panel:
+
+  1. **Active / Upcoming** — `draws.filter(d => d.current_state !== 3)`
+     (1 = Open, 2 = WinnerSelection); sort by `execution_ts` ASC.
+  2. **Executed** — `draws.filter(d => d.current_state === 3)`;
+     rendered after the active draws.
+
+## Ticket-cap banner
+
+Drive from `TRaffle.ticket_cap_visualization` (enum):
+
+| Value | Banner |
+|---|---|
+| `Empty` (0) | No banner. |
+| `Counter` (1) | "X tickets remaining" where X = `max_tickets_count - current_tickets_count`. Format large numbers with locale separators. |
+| `Message` (2) | "All tickets have been distributed" (when 0 remaining). |
+
+## Raffle card (top-level)
+
+Fields rendered on each raffle row:
+
+- `image_url` (890×193 px desktop) / `image_url_mobile` (300×142 px).
+- `name`, `description`.
+- `start_date` / `end_date` — formatted as user-local dates.
+- Total tickets banner (see above).
+- Draw count or active-draw summary.
+
+`custom_section_id` lets the consumer place the raffle into an
+operator-defined custom section. `custom_data` is operator-defined
+JSON / string for custom UI extensions.
+
+## Draw card (per-raffle children)
+
+Fields rendered on each `draws[i]`:
+
+| Field | Notes |
+|---|---|
+| Card image | `background_image_url` (900×85 px desktop) / `background_image_url_mobile` (1328×240 px). Falls back to `icon_url` (256×256). |
+| Title | `name`. |
+| Description | `description`. |
+| Grand badge | If `is_grand === true`, render a "Grand draw" pill. |
+| Countdown | To `execution_ts`. See "Countdown / timing format". |
+| State chip | Drive from `current_state` ({@link RaffleDrawInstanceState}): Open / Drawing / Finished. |
+| My-tickets | `my_tickets_count` if > 0. |
+| Last tickets preview | `my_last_tickets[]` (capped at ~5; newest first). Note the SDK field is spelled `ticekt_id` (typo). |
+| Total tickets | `total_tickets_count`. |
+| Prize summary | Top-priority prize from `prizes[]`. |
+| Opt-in / Opted-in chip | See "Action button decision matrix". |
+
+The draw card click target opens the draw detail (which fetches
+winners via `getRaffleDrawRun`).
+
+## Action button decision matrix
+
+Per-draw CTA (evaluate in priority order):
+
+| Condition | CTA |
+|---|---|
+| `current_state === WinnerSelection` (2) | "Drawing now…" (informational) — show the Lottie drawing animation |
+| `current_state === Executed` (3) | "View winners" — opens detail via `getRaffleDrawRun` |
+| `requires_optin && user_opted_in && current_state !== Executed` | "Fully opted in" (informational pill, no click) |
+| `requires_optin && !user_opted_in && is_active && current_state !== Executed` | "Opt in" — invokes `requestRaffleOptin` |
+| `!requires_optin && is_active && current_state === Open` | "View prizes" (or no CTA — the user is automatically participating) |
+| `!is_active` and other terminal states | No CTA |
+
+Opt-in is per-run — when a recurring draw advances to a new run,
+`user_opted_in` resets to `false` on the new run. The Opt-in CTA
+returns even for users who opted in to the previous run.
+
+## Image / asset specs
+
+| Field | Documented source | Aspect | Used where |
+|---|---|---|---|
+| `TRaffle.image_url` | 890×193 px | ~4.6:1 | Raffle row header (desktop) |
+| `TRaffle.image_url_mobile` | 300×142 px | ~2.1:1 | Raffle row header (mobile) |
+| `TRaffleDraw.image_url` | 365×175 px | ~2:1 | Draw promo |
+| `TRaffleDraw.image_url_mobile` | 300×145 px | ~2:1 | Draw promo (mobile) |
+| `TRaffleDraw.icon_url` | 256×256 px | 1:1 | Draw icon (compact contexts) |
+| `TRaffleDraw.background_image_url` | 900×85 px | ~10.6:1 | Draw row background (desktop) |
+| `TRaffleDraw.background_image_url_mobile` | 1328×240 px | ~5.5:1 | Draw row background (mobile) |
+| `TRafflePrize.image_url` | 256×256 px | 1:1 | Prize card |
+
+Fallback chain (per element): brand-supplied placeholder if the
+field is empty. The SDK doesn't ship default images.
+
+## Status-specific visual treatments
+
+- **Open** (`current_state === 1`): full-color card with active
+  countdown. Show My-tickets / prizes prominently.
+- **WinnerSelection** (`current_state === 2`): show Lottie drawing
+  animation (full-screen overlay in the default Smartico UI). The
+  default UI polls every 3 s during this state.
+- **Executed** (`current_state === 3`): subtle desaturation; show
+  "View winners" CTA; surface "You won!" badge if any prize matches
+  the user.
+- **Grand** draws (`is_grand: true`): larger card, distinct accent
+  color, grand badge. Otherwise identical fields.
+- **Sold out** (ticket cap reached): banner + no opt-in CTA.
+
+## Countdown / timing format
+
+The default Smartico UI uses a hard-stamped `DD : HH : MM : SS`
+ticker counting down to `execution_ts`. CSS state classes:
+
+- Normal — default styling
+- `alert` — applied when < 5 minutes remain (yellow/amber accent)
+- `alarm` — applied when < 1 minute remains (red accent)
+
+**Polling escalation**: the widget polls
+[`getRaffleDrawRun`](../../api/classes/WSAPIRaffles.md#getraffledrawrun)
+at a variable rate keyed to remaining time:
+
+- 30 s default
+- 10 s when < 5 minutes remain
+- 3 s when in `WinnerSelection` state
+
+For non-default UIs, mirror this pattern or use a constant 30 s
+poll — the cost is one network round-trip per poll tick.
+
+## Empty / loading / error states
+
+- **Loading (cold fetch)**: render a skeleton grid sized to the
+  eventual layout.
+- **Loading (cache hit)**: do not render a loading state — the
+  promise resolves within a microtask.
+- **Empty result**: `[]` means no visible raffles. Render a neutral
+  empty-state illustration.
+- **Error**: keep the prior list if any; show a non-blocking error
+  banner; retry on next user-driven action.
+
+## Animations / transitions
+
+- **List entry**: cards fade-in on first render.
+- **WinnerSelection state**: full-screen Lottie animation while the
+  server selects winners.
+- **No celebration animation on claim** — the winner row updates
+  in-place. See `claimRafflePrize` UI guide.
+- **Opt-in success**: ~500 ms delay then UI state flip via
+  `onUpdate` refresh.
+
+## Mobile vs desktop
+
+- **Image source**: `*_url` for desktop, `*_url_mobile` for mobile.
+- **Draw row background**: desktop 900×85 px (wide strip); mobile
+  1328×240 px (taller hero treatment).
+- **Detail modal**: desktop centered modal with backdrop dim; mobile
+  full-screen slide-up sheet.
+
+## Performance
+
+- The 30 s cache deduplicates rapid refetches.
+- During an in-flight draw (WinnerSelection), polling
+  `getRaffleDrawRun` instead of `getRaffles` is cheaper — the latter
+  is a larger payload.
+- Image assets are CDN-served; lazy-load images below the fold.