From 2103f9fc69cc5d15ea89dc14ad56eada19896d58 Mon Sep 17 00:00:00 2001 From: Martin Dvorak Date: Sun, 11 Oct 2026 14:35:16 +0000 Subject: [PATCH] Smart Review: instant loading feedback, no more dead-feeling tap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 23 +++++++++++++++- app/exam/loading.tsx | 6 ++++ app/review/loading.tsx | 6 ++++ app/stats/loading.tsx | 6 ++++ components/LibraryScreen.tsx | 5 ++++ components/LinkLoadingScreen.tsx | 23 ++++++++++++++++ components/ReviewClient.tsx | 10 ++----- components/RouteLoading.tsx | 31 +++++++++++++++++++++ lib/i18n-dict.ts | 8 +++++- lib/use-health.ts | 47 ++++++++++++++++++++++++++++---- public/sw.js | 2 +- 11 files changed, 150 insertions(+), 17 deletions(-) create mode 100644 app/exam/loading.tsx create mode 100644 app/review/loading.tsx create mode 100644 app/stats/loading.tsx create mode 100644 components/LinkLoadingScreen.tsx create mode 100644 components/RouteLoading.tsx diff --git a/README.md b/README.md index c857ea8..305c0d8 100644 --- a/README.md +++ b/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()`); diff --git a/app/exam/loading.tsx b/app/exam/loading.tsx new file mode 100644 index 0000000..0765d5a --- /dev/null +++ b/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 ; +} diff --git a/app/review/loading.tsx b/app/review/loading.tsx new file mode 100644 index 0000000..fdf8767 --- /dev/null +++ b/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 ; +} diff --git a/app/stats/loading.tsx b/app/stats/loading.tsx new file mode 100644 index 0000000..c79d5e2 --- /dev/null +++ b/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 ; +} diff --git a/components/LibraryScreen.tsx b/components/LibraryScreen.tsx index 604f0da..713a4a4 100644 --- a/components/LibraryScreen.tsx +++ b/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" |
{t("review.title")} · {plural(due, "review.due")} + {t("review.mistakesTitle")} · {plural(mistakes, "review.mistakes")} +
diff --git a/components/LinkLoadingScreen.tsx b/components/LinkLoadingScreen.tsx new file mode 100644 index 0000000..c3d1a51 --- /dev/null +++ b/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 + * `` 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 ( +
+ +
+ ); +} diff --git a/components/ReviewClient.tsx b/components/ReviewClient.tsx index 28f2892..86b4e04 100644 --- a/components/ReviewClient.tsx +++ b/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 ( -
-
-
-
-
-
- ); + return ; } if (!session) { diff --git a/components/RouteLoading.tsx b/components/RouteLoading.tsx new file mode 100644 index 0000000..ad6d8aa --- /dev/null +++ b/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 ( +
+
+ {/* eslint-disable-next-line @next/next/no-img-element -- static app icon, no optimisation needed */} + +

+ + {t(messageKey)} +

+
+
+ ); +} diff --git a/lib/i18n-dict.ts b/lib/i18n-dict.ts index f1a7bca..a5c0d6b 100644 --- a/lib/i18n-dict.ts +++ b/lib/i18n-dict.ts @@ -807,6 +807,7 @@ const en: Record = { "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 = { "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 = { "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 = { "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 = { "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", diff --git a/lib/use-health.ts b/lib/use-health.ts index e569a3e..d90bb49 100644 --- a/lib/use-health.ts +++ b/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 } | null = null; + +function loadHealth(key: string, force: boolean): Promise { + 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(null); + const [health, setHealth] = useState(() => + cache && cache.key === apiKey ? cache.value : null, + ); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); - const [checkedAt, setCheckedAt] = useState(null); + const [checkedAt, setCheckedAt] = useState(() => + 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 }; } diff --git a/public/sw.js b/public/sw.js index 1a04e84..ae0fa7c 100644 --- a/public/sw.js +++ b/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`;