rebuild the app on a typed, modular structure wired to the real API

The whole app lived in one 3,071-line App.tsx on a Figma scaffold (60 unused
packages, 45 unused UI components, no type-check). The live site could not
reach the backend, Persian-keyboard digits were erased from the phone field,
guests were signed out after an hour, "mark read" hit a method the server
does not accept (405), and iOS Safari blocked the payment window.

What changed:
- src/ split into api/ (one typed client: timeouts, GET retry, single-flight
  refresh, SSE), screens/ (one file each), components/, state/, nav/, lib/.
- The API address is configuration only: public/config.js at runtime, then
  VITE_API_BASE_URL at build time, then same-origin /api. No domain in code.
- Responsive shell instead of a fixed 390x844 phone frame; self-hosted
  Vazirmatn instead of Google Fonts; strict TypeScript, `npm run build`
  type-checks first.
- Everything on the handoff list: tutor answers keep their line breaks, have
  thumbs up/down, follow-ups, "from the book" badge, retry, history that
  survives tab switches and reloads, "why was I wrong" from a wrong answer
  with questionId; question reports; hearts with maxHearts/unlimited and a
  no-hearts screen with the refill time; result screen and a visible error
  when lesson completion fails; subscription status, badge, discount code
  before the gateway and the payment-return message; guest refresh token;
  6-digit OTP with resend timer; age saved as a Jalali birthYear; PATCH
  read-all; leaderboard refetched on open with "you" highlighted; selected
  companion shown across the app; logout that revokes the refresh token.
- New screens for endpoints that had none: profile, streak calendar,
  support tickets and bug reports, parents, invite-a-friend (with ?ref=
  tracking), guest-to-phone upgrade.
- Browser/phone back button walks the screen stack.

Checked with a headless-Chrome walkthrough against a local backend at
390x844 and 360x740 (fresh guest: onboarding, setup, a full lesson, map,
island sheet, every tab and sub-screen, one real tutor question, reload,
logout): no console errors, no failed API calls. Real SMS login and a real
Zarinpal payment were not exercised.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/screens/CharactersScreen.tsx

@@ -0,0 +1,105 @@
+import { useState } from 'react';
+import { Check, Lock, Sparkles } from 'lucide-react';
+import { api, type Character } from '@/api';
+import { useAppData } from '@/state/AppData';
+import { useAsync } from '@/lib/useAsync';
+import { SeyarMascot } from '@/mascots/SeyarMascot';
+import { SEYAR_INFO, seyarFromSlug } from '@/mascots/seyar';
+import { useToast } from '@/components/Toast';
+import { EmptyState, ErrorState, LoadingState, Screen, ScreenHeader } from '@/components/ui';
+import { friendlyError } from '@/lib/errors';
+import { toFa } from '@/lib/format';
+
+/**
+ * همراه‌ها (کاتالوگِ کاراکترهای بک‌اند). همراهِ انتخابی در خانه، درس و تمرین
+ * نشان داده می‌شود. باز شدن فقط با امتیاز است.
+ */
+export function CharactersScreen() {
+  const { summary, setCompanion } = useAppData();
+  const toast = useToast();
+  const list = useAsync(() => api.characters.list(), []);
+  const [busy, setBusy] = useState<string | null>(null);
+
+  async function select(c: Character) {
+    if (!c.unlocked || c.selected || busy) return;
+    setBusy(c.characterId);
+    try {
+      await api.characters.select(c.characterId);
+      list.setData((prev) => prev?.map((x) => ({ ...x, selected: x.characterId === c.characterId })));
+      setCompanion(c);
+      toast(`${c.name} حالا همراهته!`, 'success');
+    } catch (err) {
+      toast(friendlyError(err), 'error');
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  return (
+    <Screen>
+      <ScreenHeader
+        title="همراهت رو انتخاب کن"
+        subtitle={`امتیازِ تو: ${toFa(summary?.xp ?? 0)} · با امتیازِ بیشتر همراه‌های بیشتری باز می‌شن`}
+        color="#9B7BFF"
+        back
+      />
+      <div className="flex-1 overflow-y-auto px-4 py-5">
+        {list.loading ? (
+          <LoadingState />
+        ) : list.error ? (
+          <ErrorState error={list.error} onRetry={list.reload} />
+        ) : !list.data?.length ? (
+          <EmptyState text="فعلاً همراهی تعریف نشده" />
+        ) : (
+          <div className="grid grid-cols-2 gap-3">
+            {list.data.map((c) => {
+              const seyar = seyarFromSlug(c.slug);
+              return (
+                <button
+                  key={c.characterId}
+                  type="button"
+                  disabled={!c.unlocked || busy !== null}
+                  onClick={() => void select(c)}
+                  aria-pressed={c.selected}
+                  className={`relative flex flex-col items-center gap-2 rounded-3xl border-2 p-4 transition-transform ${
+                    c.selected ? 'border-violet bg-[#F5F1FF]' : c.unlocked ? 'border-line bg-white active:scale-95' : 'border-line bg-[#f4f3fa]'
+                  }`}
+                >
+                  {c.selected && (
+                    <span className="absolute left-2 top-2 flex h-5 w-5 items-center justify-center rounded-full bg-violet">
+                      <Check size={11} className="text-white" strokeWidth={3} />
+                    </span>
+                  )}
+                  <span className={`relative ${c.unlocked ? '' : 'opacity-50 grayscale'}`}>
+                    {seyar ? (
+                      <SeyarMascot char={seyar} mood={c.unlocked ? 'happy' : 'idle'} size={84} />
+                    ) : (
+                      <span className="flex h-20 w-20 items-center justify-center rounded-full bg-[#EEF1FF]">
+                        <Sparkles size={28} className="text-violet" />
+                      </span>
+                    )}
+                  </span>
+                  {!c.unlocked && (
+                    <span className="absolute top-12 flex h-9 w-9 items-center justify-center rounded-full bg-white shadow">
+                      <Lock size={16} className="text-[#5a5580]" />
+                    </span>
+                  )}
+                  <span className="text-sm font-bold text-ink">{c.name}</span>
+                  <span className="text-center text-[10px] leading-5 text-muted">
+                    {!c.unlocked
+                      ? `با ${toFa(c.unlockXp)} امتیاز باز می‌شه`
+                      : c.selected
+                        ? 'همراهِ فعلی'
+                        : seyar
+                          ? SEYAR_INFO[seyar].role
+                          : 'بازشده'}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+        )}
+      </div>
+    </Screen>
+  );
+}