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/lib/errors.ts

@@ -0,0 +1,11 @@
+import { ApiError } from '@/api';
+
+/** پیامِ قابلِ فهم برای دانش‌آموز، از هر خطایی. */
+export function friendlyError(err: unknown, fallback = 'یه مشکلی پیش اومد، دوباره امتحان کن'): string {
+  if (!(err instanceof ApiError)) return fallback;
+  if (err.isNetwork) return 'ارتباط با سرور برقرار نشد؛ اینترنتت رو چک کن';
+  if (err.isRateLimited) return err.detail && !err.detail.startsWith('خطای') ? err.detail : 'زیادی تلاش کردی؛ چند لحظه صبر کن';
+  if (err.isProviderDown) return 'این سرویس الان در دسترس نیست؛ کمی بعد دوباره امتحان کن';
+  if (err.status >= 500) return 'سرور موقتاً مشکل داره؛ کمی بعد دوباره امتحان کن';
+  return err.detail || fallback;
+}

src/lib/format.ts

@@ -0,0 +1,70 @@
+const FA_DIGITS = '۰۱۲۳۴۵۶۷۸۹';
+
+/** ارقامِ لاتین را فارسی می‌کند؛ برای نمایش. */
+export function toFa(value: number | string): string {
+  return String(value).replace(/\d/g, (d) => FA_DIGITS[Number(d)]);
+}
+
+/**
+ * ارقامِ فارسی و عربی را لاتین می‌کند؛ برای ورودی.
+ * کیبوردِ فارسیِ گوشی «۰۹۱۲» تایپ می‌کند و `\d` در JS آن را نمی‌شناسد.
+ */
+export function toEnDigits(value: string): string {
+  return value
+    .replace(/[۰-۹]/g, (d) => String(d.charCodeAt(0) - 0x06f0))
+    .replace(/[٠-٩]/g, (d) => String(d.charCodeAt(0) - 0x0660));
+}
+
+/** فقط رقم‌ها، با پشتیبانی از ارقامِ فارسی. */
+export function digitsOnly(value: string, maxLength?: number): string {
+  const digits = toEnDigits(value).replace(/\D/g, '');
+  return maxLength ? digits.slice(0, maxLength) : digits;
+}
+
+/** ۱۲۳۴۵۶ → «۱۲۳٬۴۵۶» */
+export function formatNumber(value: number): string {
+  return toFa(Math.round(value).toLocaleString('en-US')).replace(/,/g, '٬');
+}
+
+export function formatToman(value: number): string {
+  return `${formatNumber(value)} تومان`;
+}
+
+/** «۵ دقیقه پیش»، «دیروز»، … */
+export function relativeTime(iso: string, now = Date.now()): string {
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return '';
+  const minutes = Math.round((now - then) / 60_000);
+  if (minutes < 1) return 'همین الان';
+  if (minutes < 60) return `${toFa(minutes)} دقیقه پیش`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${toFa(hours)} ساعت پیش`;
+  const days = Math.round(hours / 24);
+  if (days === 1) return 'دیروز';
+  if (days < 30) return `${toFa(days)} روز پیش`;
+  return formatJalaliDate(iso);
+}
+
+/** «تا ۲ ساعت و ۱۵ دقیقه‌ی دیگر» برای زمانِ پر شدنِ قلب. */
+export function timeUntil(iso: string, now = Date.now()): string {
+  const ms = Date.parse(iso) - now;
+  if (Number.isNaN(ms) || ms <= 0) return 'همین حالا';
+  const totalMinutes = Math.ceil(ms / 60_000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours && minutes) return `${toFa(hours)} ساعت و ${toFa(minutes)} دقیقه`;
+  if (hours) return `${toFa(hours)} ساعت`;
+  return `${toFa(minutes)} دقیقه`;
+}
+
+export function formatJalaliDate(iso: string): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return '';
+  return new Intl.DateTimeFormat('fa-IR-u-ca-persian', { day: 'numeric', month: 'long', year: 'numeric' }).format(date);
+}
+
+/** سالِ شمسیِ امروز؛ سرور birthYear را شمسی می‌خواهد. */
+export function currentJalaliYear(date = new Date()): number {
+  const year = new Intl.DateTimeFormat('en-US-u-ca-persian', { year: 'numeric' }).format(date);
+  return parseInt(toEnDigits(year), 10);
+}

src/lib/sound.ts

@@ -0,0 +1,54 @@
+import { KEYS, store } from './storage';
+
+/**
+ * صداهای کوتاهِ رابط. یک AudioContext برای کلِ اپ؛ ساختنِ یکی برای هر صدا
+ * در Safari بعد از چند بار شکست می‌خورد.
+ */
+let ctx: AudioContext | null = null;
+
+function context(): AudioContext | null {
+  if (ctx) return ctx;
+  const Ctor = window.AudioContext ?? window.webkitAudioContext;
+  if (!Ctor) return null;
+  try {
+    ctx = new Ctor();
+  } catch {
+    return null;
+  }
+  return ctx;
+}
+
+export function soundEnabled(): boolean {
+  return store.get(KEYS.sound) !== 'off';
+}
+
+export function setSoundEnabled(on: boolean) {
+  store.set(KEYS.sound, on ? 'on' : 'off');
+}
+
+function tone(frequency: number, start: number, duration: number, volume = 0.05) {
+  const audio = context();
+  if (!audio || !soundEnabled()) return;
+  if (audio.state === 'suspended') void audio.resume();
+  const t = audio.currentTime + start;
+  const osc = audio.createOscillator();
+  const gain = audio.createGain();
+  osc.type = 'sine';
+  osc.frequency.setValueAtTime(frequency, t);
+  gain.gain.setValueAtTime(0.0001, t);
+  gain.gain.exponentialRampToValueAtTime(volume, t + 0.01);
+  gain.gain.exponentialRampToValueAtTime(0.0001, t + duration);
+  osc.connect(gain).connect(audio.destination);
+  osc.start(t);
+  osc.stop(t + duration + 0.02);
+}
+
+export const sounds = {
+  tick: () => tone(720, 0, 0.045, 0.04),
+  correct: () => {
+    tone(660, 0, 0.12);
+    tone(990, 0.1, 0.18);
+  },
+  wrong: () => tone(220, 0, 0.25, 0.06),
+  finish: () => [523, 659, 784, 1047].forEach((f, i) => tone(f, i * 0.11, 0.2)),
+};

src/lib/storage.ts

@@ -0,0 +1,45 @@
+/** localStorage با try/catch؛ در حالتِ خصوصیِ مرورگر یا دسترسیِ مسدود throw نمی‌کند. */
+export const store = {
+  get(key: string): string | null {
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  },
+  set(key: string, value: string) {
+    try {
+      localStorage.setItem(key, value);
+    } catch {
+      /* نادیده */
+    }
+  },
+  remove(key: string) {
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      /* نادیده */
+    }
+  },
+};
+
+export const KEYS = {
+  deviceId: 'deviceId',
+  onboarded: 'tadrisino.onboarded',
+  conversationId: 'tadrisino.conversationId',
+  ticketIds: 'tadrisino.ticketIds',
+  sound: 'tadrisino.sound',
+  referralCode: 'tadrisino.referralCode',
+} as const;
+
+/** شناسه‌ی ثابتِ این مرورگر برای ورودِ مهمان. */
+export function getDeviceId(): string {
+  let id = store.get(KEYS.deviceId);
+  if (!id) {
+    id = globalThis.crypto && 'randomUUID' in crypto
+      ? crypto.randomUUID()
+      : `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    store.set(KEYS.deviceId, id);
+  }
+  return id;
+}

src/lib/useAsync.ts

@@ -0,0 +1,46 @@
+import { useCallback, useEffect, useRef, useState, type DependencyList } from 'react';
+
+export interface AsyncState<T> {
+  data: T | undefined;
+  error: unknown;
+  loading: boolean;
+  reload: () => void;
+  setData: (update: T | ((prev: T | undefined) => T | undefined)) => void;
+}
+
+/**
+ * داده‌ای که از سرور می‌آید، با حالت‌های بارگذاری/خطا و «دوباره».
+ * پاسخِ درخواستِ کهنه (بعد از عوض شدنِ deps) نادیده گرفته می‌شود.
+ */
+export function useAsync<T>(load: () => Promise<T>, deps: DependencyList): AsyncState<T> {
+  const [data, setData] = useState<T | undefined>(undefined);
+  const [error, setError] = useState<unknown>(null);
+  const [loading, setLoading] = useState(true);
+  const [nonce, setNonce] = useState(0);
+  const loadRef = useRef(load);
+  loadRef.current = load;
+
+  useEffect(() => {
+    let alive = true;
+    setLoading(true);
+    setError(null);
+    loadRef.current().then(
+      (value) => {
+        if (!alive) return;
+        setData(value);
+        setLoading(false);
+      },
+      (err: unknown) => {
+        if (!alive) return;
+        setError(err);
+        setLoading(false);
+      },
+    );
+    return () => {
+      alive = false;
+    };
+  }, [...deps, nonce]);
+
+  const reload = useCallback(() => setNonce((n) => n + 1), []);
+  return { data, error, loading, reload, setData };
+}