Smart Review: instant loading feedback, no more dead-feeling tap

Reported: tapping Review due could sit for many seconds with no loading
screen. The flow itself is local and fast (counts are hydrated on the
library; <1.5s even at 6x CPU throttle with 3,000 answers), so the
visible fault was missing feedback: /review is a dynamic route and
until its payload arrived nothing on screen changed.

- LinkLoadingScreen: the review card links render a full-screen
  loading screen from the link's own useLinkStatus pending state, the
  instant the tap happens (measured 58 ms with the route request held
  open). The links also prefetch their payload.
- Route loading boundaries (loading.tsx) for /review, /stats and
  /exam, sharing a RouteLoading screen (app icon + spinner +
  localized message); ReviewClient's bare skeleton replaced with it.
- Health probes: per-key 30s cache + in-flight sharing in use-health.ts
  (every page mounts its own gate; a session now fires one probe
  instead of one per navigation). Manual re-check still forces.
- Czech fix: exam heading 'Zkouškové režim' -> 'Zkouškový režim'.

Verified by the rebuilt suites (the /tmp harness was wiped overnight):
review-loading 15/15 (stalled-request loading screen at 58 ms, session
arrival after release, fast normal path, mistakes path, end-to-end
grading, probe cache) and navigation 78/78 (tab bar, labels 360/390
EN/CS, routing, deep links, wizard loading lock). Lint + build clean.
SW freezmo-v30.

README.md

@@ -69,7 +69,10 @@ no database, no data leaving your machine except the requests you send to Ollama
   IndexedDB log, and each activity gets a light **SM-2 schedule** — correct answers come back after
   1 day, then 3, then interval × ease; wrong ones after ten minutes. The Library shows a **Smart
   review** card with the due count, a **Mistakes** count (activities whose latest answer was wrong —
-  they clear themselves once answered correctly) and today's **daily goal** progress. A **Progress**
+  they clear themselves once answered correctly) and today's **daily goal** progress. Tapping
+  either one shows a **loading screen instantly** (the link reports its own pending state, the
+  route has a loading boundary, and the payload is prefetched), so even a slow first request never
+  looks like a dead tap. A **Progress**
   tab has the day streak, a five-week calendar, accuracy per subject and per deck and
   the weakest topics. **Exam mode** (its own tab) takes one or more decks, a question count and an
   optional timer, hides hints and shows a per-deck/per-topic breakdown at the end. **Daily
@@ -1044,6 +1047,24 @@ Things I chose while building, with the reasoning:
     Back from every tab and the ⋯ sheet) plus the wizard suite (92 checks, including the
     loading-lock and abort-on-leave cases) and the other standing suites.
 
+44. **Smart Review must never look like a dead tap.** The reported symptom was a tap on *Review
+    due* sitting for many seconds with no feedback. The flow itself is local and fast (the counts
+    are already hydrated on the library; measurements show <1.5s even at 6× CPU throttle with
+    3,000 answers), so the visible fault was the missing feedback: `/review` is a dynamic route
+    (search params), and until its payload arrived the screen simply didn't change. Three layers
+    now cover it: the card links **prefetch** their payload; the link's own **`useLinkStatus`**
+    pending state renders a full-screen loading screen (`LinkLoadingScreen`) the instant the tap
+    happens — measured at **58 ms** even with the route request held open; and `loading.tsx`
+    boundaries cover the render/stream phase (review, progress and exam). The client screen's own
+    bare skeleton was replaced with the same loading screen. While in there, health probes got a
+    per-key 30-second cache plus in-flight sharing (`use-health.ts`): every page mounts its own
+    gate and each probe can sit for seconds while Ollama answers, so a session now fires **one**
+    probe instead of one per navigation (verified). Also fixed a Czech typo on the exam heading
+    (“Zkouškové režim” → “Zkouškový režim”). Verified by the review-loading suite (15 checks:
+    stalled-request loading screen, session arrival after release, the normal fast path, the
+    mistakes path, end-to-end grading, and the probe cache) and the rebuilt navigation suite
+    (78 checks).
+
 36. **The mobile declutter pass reshapes, it doesn't fork.** Phones (≤639px) get a 3-step deck
     flow and a 2-step homework flow that share the exact state and handlers with the desktop
     cards (one `UploadScreen` / one `HomeworkInput`, two layouts switched by `useIsPhone()`);

app/exam/loading.tsx

@@ -0,0 +1,6 @@
+import { RouteLoading } from "@/components/RouteLoading";
+
+/** Shown the instant the exam route starts loading. */
+export default function ExamLoading() {
+  return <RouteLoading messageKey="exam.preparing" />;
+}

app/review/loading.tsx

@@ -0,0 +1,6 @@
+import { RouteLoading } from "@/components/RouteLoading";
+
+/** Shown the instant the review route starts loading. */
+export default function ReviewLoading() {
+  return <RouteLoading messageKey="review.preparing" />;
+}

app/stats/loading.tsx

@@ -0,0 +1,6 @@
+import { RouteLoading } from "@/components/RouteLoading";
+
+/** Shown the instant the progress route starts loading. */
+export default function StatsLoading() {
+  return <RouteLoading messageKey="stats.preparing" />;
+}

components/LibraryScreen.tsx

@@ -8,6 +8,7 @@ import { DeckCard } from "@/components/DeckCard";
 import { FolderBar } from "@/components/FolderBar";
 import { HomeworkCard } from "@/components/HomeworkCard";
 import { EllipsisIcon, FolderIcon, UploadIcon } from "@/components/icons";
+import { LinkLoadingScreen } from "@/components/LinkLoadingScreen";
 import { SegmentedPill } from "@/components/SegmentedPill";
 import { Button, EmptyState, ProgressBar } from "@/components/ui";
 import { createFolder, folderStore, renameFolder } from "@/lib/folders";
@@ -306,6 +307,7 @@ export function LibraryScreen({ initialTab = "decks" }: { initialTab?: "decks" |
         <div className="flex flex-wrap gap-2">
           <Link
             href="/review"
+            prefetch
             aria-disabled={due === 0}
             className={cn(
               "touch-target inline-flex h-10 items-center rounded-xl px-3.5 text-[13px] font-semibold transition",
@@ -313,9 +315,11 @@ export function LibraryScreen({ initialTab = "decks" }: { initialTab?: "decks" |
             )}
           >
             {t("review.title")} · {plural(due, "review.due")}
+            <LinkLoadingScreen messageKey="review.preparing" />
           </Link>
           <Link
             href="/review?mistakes=1"
+            prefetch
             aria-disabled={mistakes === 0}
             className={cn(
               "touch-target inline-flex h-10 items-center rounded-xl px-3.5 text-[13px] font-semibold transition",
@@ -323,6 +327,7 @@ export function LibraryScreen({ initialTab = "decks" }: { initialTab?: "decks" |
             )}
           >
             {t("review.mistakesTitle")} · {plural(mistakes, "review.mistakes")}
+            <LinkLoadingScreen messageKey="review.preparing" />
           </Link>
         </div>
       </section>

components/LinkLoadingScreen.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { useLinkStatus } from "next/link";
+
+import { RouteLoading } from "@/components/RouteLoading";
+
+/**
+ * A full-screen loading screen that appears the instant the surrounding
+ * `<Link>` starts navigating — before any response arrives — so a slow route
+ * never looks like a dead tap. Renders nothing while idle and disappears with
+ * the page that owns it.
+ */
+export function LinkLoadingScreen({ messageKey }: { messageKey: string }) {
+  const { pending } = useLinkStatus();
+
+  if (!pending) return null;
+
+  return (
+    <div className="pointer-events-none fixed inset-0 z-50">
+      <RouteLoading messageKey={messageKey} />
+    </div>
+  );
+}

components/ReviewClient.tsx

@@ -4,6 +4,7 @@ import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
 import { useRouter } from "next/navigation";
 
 import { SessionFeed, type SessionItem } from "@/components/SessionFeed";
+import { RouteLoading } from "@/components/RouteLoading";
 import { Button } from "@/components/ui";
 import { haptic } from "@/lib/haptics";
 import { ensureLearningHydrated, learningStore, recordAnswer } from "@/lib/history";
@@ -53,14 +54,7 @@ export function ReviewClient({ mistakes, deckId }: { mistakes: boolean; deckId?:
     : t("review.title");
 
   if (!ready) {
-    return (
-      <main className="frost-bg grid min-h-dvh place-items-center px-4">
-        <div className="w-full max-w-xl space-y-4" aria-busy="true" aria-label={title}>
-          <div className="skeleton h-24 rounded-3xl" />
-          <div className="skeleton h-12 rounded-2xl" />
-        </div>
-      </main>
-    );
+    return <RouteLoading messageKey="review.preparing" />;
   }
 
   if (!session) {

components/RouteLoading.tsx

@@ -0,0 +1,31 @@
+"use client";
+
+import { Spinner } from "@/components/ui";
+import { useI18n } from "@/lib/i18n";
+
+/**
+ * Route-level loading screen (used by `loading.tsx` boundaries and by client
+ * screens that wait for local data). Rendered the moment a navigation starts,
+ * so a slow request never looks like a dead tap.
+ */
+export function RouteLoading({ messageKey }: { messageKey: string }) {
+  const { t } = useI18n();
+
+  return (
+    <div role="status" aria-busy="true" className="frost-bg grid min-h-dvh place-items-center px-4">
+      <div className="flex flex-col items-center gap-4 text-center">
+        {/* eslint-disable-next-line @next/next/no-img-element -- static app icon, no optimisation needed */}
+        <img
+          src="/icons/icon-192.png"
+          alt=""
+          aria-hidden
+          className="size-16 rounded-[1.15rem] shadow-lift motion-safe:animate-pulse"
+        />
+        <p className="flex items-center gap-2 text-sm font-semibold text-[var(--text-muted)]">
+          <Spinner className="size-4" />
+          {t(messageKey)}
+        </p>
+      </div>
+    </div>
+  );
+}

lib/i18n-dict.ts

@@ -807,6 +807,7 @@ const en: Record<string, string> = {
   "review.seeResults": "See results",
   "review.finishFirst": "Finish the last activity to see your results.",
   "review.results": "Results",
+  "review.preparing": "Preparing your review…",
   "review.due.one": "{n} due",
   "review.due.few": "{n} due",
   "review.due.many": "{n} due",
@@ -814,6 +815,7 @@ const en: Record<string, string> = {
   "review.mistakes.few": "{n} mistakes",
   "review.mistakes.many": "{n} mistakes",
   "exam.title": "Exam mode",
+  "exam.preparing": "Preparing exam mode…",
   "exam.subtitle": "Pick one or more decks, set a timer, no hints — see how you'd do.",
   "exam.pickDecks": "Decks",
   "exam.noDecks": "Create a deck first.",
@@ -827,6 +829,7 @@ const en: Record<string, string> = {
   "exam.studyMistakes": "Study mistakes",
   "exam.timeLeft": "{time} left",
   "stats.title": "Your progress",
+  "stats.preparing": "Preparing your progress…",
   "stats.subtitle": "Streaks, accuracy and the topics that deserve another pass.",
   "stats.streak": "Day streak",
   "stats.today": "Today",
@@ -1643,13 +1646,15 @@ const cs: Record<string, string> = {
   "review.seeResults": "Zobrazit výsledky",
   "review.finishFirst": "Dokonči poslední aktivitu a uvidíš výsledky.",
   "review.results": "Výsledky",
+  "review.preparing": "Připravuji opakování…",
   "review.due.one": "{n} k opakování",
   "review.due.few": "{n} k opakování",
   "review.due.many": "{n} k opakování",
   "review.mistakes.one": "{n} chyba",
   "review.mistakes.few": "{n} chyby",
   "review.mistakes.many": "{n} chyb",
-  "exam.title": "Zkouškové režim",
+  "exam.title": "Zkouškový režim",
+  "exam.preparing": "Připravuji zkouškový režim…",
   "exam.subtitle": "Vyber sady, nastav časovač, žádné nápovědy — uvidíš, jak bys dopadl.",
   "exam.pickDecks": "Sady",
   "exam.noDecks": "Nejdřív si vytvoř sadu.",
@@ -1663,6 +1668,7 @@ const cs: Record<string, string> = {
   "exam.studyMistakes": "Procvičit chyby",
   "exam.timeLeft": "zbývá {time}",
   "stats.title": "Tvůj pokrok",
+  "stats.preparing": "Připravuji pokrok…",
   "stats.subtitle": "Série, úspěšnost a témata, která si zaslouží další kolo.",
   "stats.streak": "Série dní",
   "stats.today": "Dnes",

lib/use-health.ts

@@ -9,23 +9,55 @@ import { settingsStore } from "./settings";
 /**
  * Health status for the current browser (re-checks whenever the API key
  * changes). Used by the settings dialog and the API-key gate.
+ *
+ * Every page mounts its own gate, and one probe can sit for seconds while
+ * Ollama answers — so probes are deduplicated per key and cached briefly
+ * instead of firing one per mount. The manual re-check always forces.
  */
+const HEALTH_TTL_MS = 30_000;
+
+let cache: { key: string; at: number; value: Health } | null = null;
+let inflight: { key: string; promise: Promise<Health> } | null = null;
+
+function loadHealth(key: string, force: boolean): Promise<Health> {
+  if (!force && cache && cache.key === key && Date.now() - cache.at < HEALTH_TTL_MS) {
+    return Promise.resolve(cache.value);
+  }
+  if (!force && inflight && inflight.key === key) return inflight.promise;
+
+  const promise = fetchHealth()
+    .then((value) => {
+      cache = { key, at: Date.now(), value };
+      return value;
+    })
+    .finally(() => {
+      if (inflight?.promise === promise) inflight = null;
+    });
+  inflight = { key, promise };
+  return promise;
+}
+
 export function useHealth() {
   const apiKey = useSyncExternalStore(
     settingsStore.subscribe,
     () => settingsStore.getSnapshot().apiKey,
     () => "",
   );
-  const [health, setHealth] = useState<Health | null>(null);
+  const [health, setHealth] = useState<Health | null>(() =>
+    cache && cache.key === apiKey ? cache.value : null,
+  );
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  const [checkedAt, setCheckedAt] = useState<number | null>(null);
+  const [checkedAt, setCheckedAt] = useState<number | null>(() =>
+    cache && cache.key === apiKey ? cache.at : null,
+  );
 
-  const refresh = useCallback(async () => {
+  const run = useCallback(async (force: boolean) => {
     setLoading(true);
     setError(null);
     try {
-      setHealth(await fetchHealth());
+      const key = settingsStore.getSnapshot().apiKey;
+      setHealth(await loadHealth(key, force));
     } catch (loadError) {
       setError(loadError instanceof Error ? loadError.message : t("api.unreachableShort"));
     } finally {
@@ -36,8 +68,11 @@ export function useHealth() {
   }, []);
 
   useEffect(() => {
-    void refresh();
-  }, [refresh, apiKey]);
+    void run(false);
+  }, [run, apiKey]);
+
+  /** The settings dialog's re-check button: always a fresh probe. */
+  const refresh = useCallback(() => run(true), [run]);
 
   return { health, loading, error, refresh, apiKey, checkedAt };
 }

public/sw.js

@@ -9,7 +9,7 @@
  *
  * Bumping CACHE_VERSION is how a new deploy invalidates old assets.
  */
-const CACHE_VERSION = "freezmo-v29";
+const CACHE_VERSION = "freezmo-v30";
 const SHELL_CACHE = `${CACHE_VERSION}-shell`;
 const ASSET_CACHE = `${CACHE_VERSION}-assets`;