From 67c4f9f435fc93871b29a9589ebdab695b02cdf8 Mon Sep 17 00:00:00 2001
From: Oluwatoyin Solomon <toyinsolomon4@gmail.com>
Date: Mon, 17 Aug 2026 19:15:10 +0100
Subject: [PATCH] fix(frontend): eliminate profile hydration drift and harden
 stored metadata

Renders public profile pages, header navigation, and countdown widgets deterministically on server and client so users no longer see flicker, hydration mismatches, or stale content across refreshes. Stored profile metadata is now validated and merged safely, recovering gracefully from malformed local data.

Test infrastructure (pre-existing failures):

- vitest.config.ts: remove duplicate setupFiles key (empty array shadowed vitest.setup.ts) so jest-dom matchers load, fixing the SigningSummary failures.

- usePersistentState.ts: hold serialize/deserialize in refs so inline (unstable) callback identities no longer re-trigger the hydration effect into an infinite re-render loop; fixed its test (jest -> vi, correct import path).

Metadata consistency:

- types/profile.ts: add ProfileMetadata, PROFILE_METADATA_DEFAULTS, and sanitizeProfileMetadata (hex color, absolute http(s) avatar URL, trimmed + length-capped bio/handles; never throws).

- lib/api.ts: readStoredProfileMetadata + safe merge with per-field sanitization; corrupt/non-object localStorage entries are removed on read; storage keys canonicalized to lowercase in getProfile/saveProfile.

- app/[username]/page.tsx: reset state per username change, avatar onError fallback to initial, consistent error copy for invalid/private/not-found states, role=status + role=alert + aria-live.

Hydration-safe time/locale rendering:

- hooks/marketplaceApi.ts: export standalone formatCountdown(date, now?) mirroring the provider implementations.

- components/UsernameCard.tsx: mounted-pattern 'now' state (updated every 30s) replaces Date.now() at render to keep countdown/urgency/UrgencyBar identical between SSR and client.

- lib/i18n.ts: init deterministically in 'en' on server and client; components/Header.tsx restores the saved language post-hydration and fixes the leading-space aria-label.

Other:

- app/manifest.ts: add lang/dir and complete shortcut icon type/purpose metadata.

Pre-existing type/build errors fixed so the app compiles:

- app/page.tsx: drop dead fetchListings warm-up (import never existed).

- app/dashboard/page.tsx: consume fetchUserBids/fetchUserListings via MarketplaceApiProvider + useMarketplaceApi().

- app/marketplace/page.tsx: remove duplicate showWatchlistOnly state and import useRef.

- components/PWAHandler.tsx: pass route/extra context to errorReporter (valid ErrorContext).

Verification: full vitest suite green (12 files, 105 tests) and tsc --noEmit -p tsconfig.test.json clean. New unit tests cover sanitizeProfileMetadata and api.ts merge/recovery behavior.
---
 app/frontend/src/app/[username]/page.tsx      |  40 +++--
 app/frontend/src/app/dashboard/page.tsx       |  25 +--
 app/frontend/src/app/manifest.ts              |  20 ++-
 app/frontend/src/app/marketplace/page.tsx     |   3 +-
 app/frontend/src/app/page.tsx                 |   7 -
 app/frontend/src/components/Header.tsx        |  14 +-
 app/frontend/src/components/PWAHandler.tsx    |   2 +-
 app/frontend/src/components/UsernameCard.tsx  |  33 +++-
 .../__tests__/usePersistentState.test.tsx     |   7 +-
 app/frontend/src/hooks/marketplaceApi.ts      |  18 ++
 app/frontend/src/hooks/usePersistentState.ts  |  22 ++-
 app/frontend/src/lib/__tests__/api.test.ts    | 160 ++++++++++++++++++
 app/frontend/src/lib/api.ts                   |  97 ++++++++---
 app/frontend/src/lib/i18n.ts                  |   9 +-
 .../src/types/__tests__/profile.test.ts       | 106 ++++++++++++
 app/frontend/src/types/profile.ts             | 125 ++++++++++++++
 app/frontend/vitest.config.ts                 |   1 -
 17 files changed, 613 insertions(+), 76 deletions(-)
 create mode 100644 app/frontend/src/lib/__tests__/api.test.ts
 create mode 100644 app/frontend/src/types/__tests__/profile.test.ts

diff --git a/app/frontend/src/app/[username]/page.tsx b/app/frontend/src/app/[username]/page.tsx
index 44400c935..4cf8acc8d 100644
--- a/app/frontend/src/app/[username]/page.tsx
+++ b/app/frontend/src/app/[username]/page.tsx
@@ -11,6 +11,12 @@ import type { Profile } from "@/types/profile";
 const FOCUS_RING_CLASS =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-indigo-300 focus-visible:ring-offset-2 focus-visible:ring-offset-black";
 
+const ERROR_COPY = {
+  invalidUsername: "Invalid username",
+  notFound: "Username not found or profile is private",
+  fallback: "Failed to load profile",
+} as const;
+
 export default function PublicProfile() {
   const params = useParams();
   const router = useRouter();
@@ -19,6 +25,7 @@ export default function PublicProfile() {
   const [profile, setProfile] = useState<Profile | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [avatarFailed, setAvatarFailed] = useState(false);
 
   const [paymentForm, setPaymentForm] = useState({
     amount: "",
@@ -29,18 +36,22 @@ export default function PublicProfile() {
   useEffect(() => {
     let mounted = true;
 
+    // Reset per-username state so navigating between profiles never shows
+    // stale content (avoids flicker / metadata inconsistency across refreshes).
+    setProfile(null);
+    setAvatarFailed(false);
+    setError(null);
+    setLoading(true);
+
     async function fetchProfile() {
       if (!username) {
-        setError("Invalid username");
+        setError(ERROR_COPY.invalidUsername);
         setLoading(false);
         return;
       }
 
       try {
-        setLoading(true);
-        setError(null);
         const data = await getProfile(username);
-        
         if (mounted) {
           setProfile(data);
         }
@@ -48,11 +59,11 @@ export default function PublicProfile() {
         if (!mounted) return;
 
         if (err instanceof ProfileNotFoundError) {
-          setError("Username not found or profile is private");
+          setError(ERROR_COPY.notFound);
         } else if (err instanceof Error) {
           setError(err.message);
         } else {
-          setError("Failed to load profile");
+          setError(ERROR_COPY.fallback);
         }
         setProfile(null);
       } finally {
@@ -71,7 +82,11 @@ export default function PublicProfile() {
 
   if (loading) {
     return (
-      <div className="min-h-screen flex items-center justify-center text-white">
+      <div
+        className="min-h-screen flex items-center justify-center text-white"
+        role="status"
+        aria-live="polite"
+      >
         <div className="text-center">
           <div className="w-12 h-12 border-4 border-indigo-500 border-t-transparent rounded-full animate-spin mx-auto mb-4"></div>
           <p className="text-neutral-400">Loading profile...</p>
@@ -82,11 +97,14 @@ export default function PublicProfile() {
 
   if (error || !profile) {
     return (
-      <div className="min-h-screen flex items-center justify-center text-white px-4">
+      <div
+        className="min-h-screen flex items-center justify-center text-white px-4"
+        role="alert"
+      >
         <div className="text-center max-w-md">
           <h1 className="text-6xl font-black mb-4">404</h1>
           <p className="text-xl text-neutral-300 mb-6">
-            {error || "Username not found"}
+            {error || ERROR_COPY.notFound}
           </p>
           <button
             onClick={() => router.push("/")}
@@ -100,6 +118,7 @@ export default function PublicProfile() {
   }
 
   const primaryColor = profile.primaryColor || "#6366f1";
+  const showAvatar = Boolean(profile.avatarUrl) && !avatarFailed;
 
   return (
     <div className="relative min-h-screen text-white">
@@ -130,7 +149,7 @@ export default function PublicProfile() {
         <div className="text-center mb-12">
           {/* Avatar */}
           <div className="flex justify-center mb-6">
-            {profile.avatarUrl ? (
+            {showAvatar ? (
               <Image
                 src={profile.avatarUrl}
                 alt={profile.username}
@@ -138,6 +157,7 @@ export default function PublicProfile() {
                 height={128}
                 className="w-32 h-32 rounded-full border-4 object-cover"
                 style={{ borderColor: primaryColor }}
+                onError={() => setAvatarFailed(true)}
               />
             ) : (
               <div
diff --git a/app/frontend/src/app/dashboard/page.tsx b/app/frontend/src/app/dashboard/page.tsx
index 50a8349a5..1c978947d 100644
--- a/app/frontend/src/app/dashboard/page.tsx
+++ b/app/frontend/src/app/dashboard/page.tsx
@@ -7,12 +7,14 @@ import AnalyticsDashboard from "@/components/AnalyticsDashboard";
 import { NetworkBadge } from "@/components/NetworkBadge";
 import { useApi } from "@/hooks/useApi";
 import {
-  fetchUserBids,
-  fetchUserListings,
   formatCountdown,
   type UserBid,
   type UserListing,
 } from "@/hooks/marketplaceApi";
+import {
+  MarketplaceApiProvider,
+  useMarketplaceApi,
+} from "@/hooks/MarketplaceApiContext";
 import { mockContractCall, mockFetch } from "@/hooks/mockApi";
 
 type ActivityItem = {
@@ -84,6 +86,7 @@ const FOCUS_RING_CLASS =
 function DashboardContent() {
   const searchParams = useSearchParams();
   const { data, error, loading, callApi } = useApi<DashboardResponse>();
+  const marketplaceApi = useMarketplaceApi();
   const [userBids, setUserBids] = useState<UserBid[]>([]);
   const [userListings, setUserListings] = useState<UserListing[]>([]);
   const [statusMessage, setStatusMessage] = useState<string | null>(null);
@@ -94,9 +97,9 @@ function DashboardContent() {
         items: ACTIVITY_ITEMS,
       }),
     );
-    void fetchUserBids().then(setUserBids);
-    void fetchUserListings().then(setUserListings);
-  }, [callApi]);
+    void marketplaceApi.fetchUserBids().then(setUserBids);
+    void marketplaceApi.fetchUserListings().then(setUserListings);
+  }, [callApi, marketplaceApi]);
 
   useEffect(() => {
     if (!statusMessage) {
@@ -594,10 +597,12 @@ function DashboardContent() {
 
 export default function Dashboard() {
   return (
-    <Suspense
-      fallback={<p className="text-neutral-200">Loading dashboard...</p>}
-    >
-      <DashboardContent />
-    </Suspense>
+    <MarketplaceApiProvider>
+      <Suspense
+        fallback={<p className="text-neutral-200">Loading dashboard...</p>}
+      >
+        <DashboardContent />
+      </Suspense>
+    </MarketplaceApiProvider>
   );
 }
diff --git a/app/frontend/src/app/manifest.ts b/app/frontend/src/app/manifest.ts
index b7a8fdc15..38bf42d9b 100644
--- a/app/frontend/src/app/manifest.ts
+++ b/app/frontend/src/app/manifest.ts
@@ -6,6 +6,8 @@ export default function manifest(): MetadataRoute.Manifest {
     name: "RustAcademy",
     short_name: "RustAcademy",
     description: "Privacy-focused payments on Stellar",
+    lang: "en",
+    dir: "ltr",
     start_url: "/",
     scope: "/",
     display: "standalone",
@@ -38,14 +40,28 @@ export default function manifest(): MetadataRoute.Manifest {
         short_name: "Generate",
         description: "Generate a new payment link",
         url: "/generator",
-        icons: [{ src: "/icon-192.png", sizes: "192x192" }],
+        icons: [
+          {
+            src: "/icon-192.png",
+            sizes: "192x192",
+            type: "image/png",
+            purpose: "any",
+          },
+        ],
       },
       {
         name: "Dashboard",
         short_name: "Dashboard",
         description: "View your dashboard",
         url: "/dashboard",
-        icons: [{ src: "/icon-192.png", sizes: "192x192" }],
+        icons: [
+          {
+            src: "/icon-192.png",
+            sizes: "192x192",
+            type: "image/png",
+            purpose: "any",
+          },
+        ],
       },
     ],
   };
diff --git a/app/frontend/src/app/marketplace/page.tsx b/app/frontend/src/app/marketplace/page.tsx
index 9e305818e..0fecd49fe 100644
--- a/app/frontend/src/app/marketplace/page.tsx
+++ b/app/frontend/src/app/marketplace/page.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import dynamic from "next/dynamic";
-import { useState, useEffect, useMemo, useCallback } from "react";
+import { useState, useEffect, useMemo, useCallback, useRef } from "react";
 import { UsernameCard } from "@/components/UsernameCard";
 import { ListingDetailModal } from "@/components/ListingDetailModal";
 import type { MarketplaceListing } from "@/hooks/marketplaceApi";
@@ -97,7 +97,6 @@ function MarketplacePageContent() {
     () => listings.find((l) => l.id === detailListingId) ?? null,
     [listings, detailListingId],
   );
-  const [showWatchlistOnly, setShowWatchlistOnly] = useState(false);
   const [lastUpdate, setLastUpdate] = useState<Date | null>(null);
 
   const { watchlist, isInWatchlist, toggleWatchlist } = useWatchlist();
diff --git a/app/frontend/src/app/page.tsx b/app/frontend/src/app/page.tsx
index 7d9f10608..ae9a4202b 100644
--- a/app/frontend/src/app/page.tsx
+++ b/app/frontend/src/app/page.tsx
@@ -5,7 +5,6 @@ import Link from "next/link";
 import { useRouter } from "next/navigation";
 import { NetworkBadge } from "@/components/NetworkBadge";
 import { fetchAnalytics } from "@/hooks/analyticsApi";
-import { fetchListings } from "@/hooks/marketplaceApi";
 import { errorReporter } from "@/lib/errorReporter";
 import '@/lib/i18n';
 import { useTranslation } from 'react-i18next';
@@ -18,12 +17,6 @@ export default function Home() {
     const handlePrefetch = () => {
       router.prefetch("/dashboard");
       router.prefetch("/marketplace");
-      fetchListings().catch((err: unknown) =>
-        errorReporter.captureError(err instanceof Error ? err : new Error(String(err)), {
-          route: "/",
-          extra: { source: "page.tsx", operation: "fetchListings" },
-        })
-      );
       fetchAnalytics("30d").catch((err: unknown) =>
         errorReporter.captureError(err instanceof Error ? err : new Error(String(err)), {
           route: "/",
diff --git a/app/frontend/src/components/Header.tsx b/app/frontend/src/components/Header.tsx
index 2ebd5b4e1..e49399631 100644
--- a/app/frontend/src/components/Header.tsx
+++ b/app/frontend/src/components/Header.tsx
@@ -1,10 +1,12 @@
 "use client";
 
+import { useEffect } from "react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import { LocaleSwitcher } from "@/components/LocaleSwitcher";
 import { NotificationBell } from "@/components/NotificationBell";
 import "@/lib/i18n";
+import i18n from "@/lib/i18n";
 import { useTranslation } from "react-i18next";
 
 const NAV_LINK_CLASS =
@@ -14,6 +16,16 @@ export function Header() {
   const { t } = useTranslation();
   const pathname = usePathname();
 
+  // Restore the user's saved language after hydration. i18n initializes in
+  // "en" deterministically on server + client, so applying the stored locale
+  // here avoids a hydration mismatch while still persisting the choice.
+  useEffect(() => {
+    const saved = window.localStorage.getItem("i18nextLng");
+    if (saved && saved !== i18n.language) {
+      i18n.changeLanguage(saved);
+    }
+  }, []);
+
   const isActive = (href: string) =>
     pathname === href || pathname?.startsWith(`${href}/`);
 
@@ -31,7 +43,7 @@ export function Header() {
       >
         <Link
           href="/"
-          aria-label=" RustAcademy home"
+          aria-label="RustAcademy home"
           className={`flex shrink-0 items-center gap-2 lg:mr-4 ${NAV_LINK_CLASS}`}
         >
           <div
diff --git a/app/frontend/src/components/PWAHandler.tsx b/app/frontend/src/components/PWAHandler.tsx
index 8797dac80..5a5983f29 100644
--- a/app/frontend/src/components/PWAHandler.tsx
+++ b/app/frontend/src/components/PWAHandler.tsx
@@ -61,7 +61,7 @@ export function PWAHandler() {
             });
           });
         })
-        .catch((err) => errorReporter.captureError(err, { context: { component: 'PWAHandler' } }));
+        .catch((err) => errorReporter.captureError(err, { route: "/", extra: { component: "PWAHandler" } }));
     }
 
     // Check if already installed
diff --git a/app/frontend/src/components/UsernameCard.tsx b/app/frontend/src/components/UsernameCard.tsx
index b9c443b6b..468537264 100644
--- a/app/frontend/src/components/UsernameCard.tsx
+++ b/app/frontend/src/components/UsernameCard.tsx
@@ -1,5 +1,6 @@
 "use client";
 
+import { useEffect, useState } from "react";
 import { MarketplaceListing, formatCountdown } from "@/hooks/marketplaceApi";
 import { useWatchlist } from "@/contexts/WatchlistContext";
 
@@ -25,9 +26,18 @@ const CATEGORY_COLORS: Record<MarketplaceListing["category"], string> = {
   brand: "text-teal-400 bg-teal-400/10 border-teal-400/20",
 };
 
-function UrgencyBar({ endsAt }: { endsAt: Date }) {
+function UrgencyBar({
+  endsAt,
+  now,
+}: {
+  endsAt: Date;
+  now: number | null;
+}) {
   const total = 7 * 24 * 3600 * 1000; // 7 day auction window
-  const remaining = Math.max(0, endsAt.getTime() - Date.now());
+  // While not mounted (SSR / initial hydration), `now` is null so we render a
+  // stable empty bar — this avoids a hydration mismatch caused by Date.now().
+  const remaining =
+    now === null ? 0 : Math.max(0, endsAt.getTime() - now);
   const pct = Math.min(100, Math.round((remaining / total) * 100));
   const color =
     pct < 15 ? "bg-red-500" : pct < 40 ? "bg-amber-500" : "bg-indigo-500";
@@ -48,10 +58,23 @@ export function UsernameCard({
   onViewDetails,
 }: UsernameCardProps) {
   const { isInWatchlist, toggleWatchlist, isHydrated } = useWatchlist();
+
+  // Track "now" in state (updated every 30s) so the countdown is stable across
+  // SSR and client hydration, and ticks down while mounted. `null` on first
+  // render keeps server and client output identical.
+  const [now, setNow] = useState<number | null>(null);
+  useEffect(() => {
+    setNow(Date.now());
+    const id = window.setInterval(() => setNow(Date.now()), 30_000);
+    return () => window.clearInterval(id);
+  }, []);
+
   const catColor = CATEGORY_COLORS[listing.category];
   const catLabel = CATEGORY_LABELS[listing.category];
-  const countdown = formatCountdown(listing.endsAt);
-  const isUrgent = listing.endsAt.getTime() - Date.now() < 1000 * 60 * 90;
+  const countdown =
+    now !== null ? formatCountdown(listing.endsAt, now) : "—";
+  const isUrgent =
+    now !== null && listing.endsAt.getTime() - now < 1000 * 60 * 90;
   const isWatched = isHydrated ? isInWatchlist(listing.id) : false;
 
   const handleWatchlistClick = (e: React.MouseEvent) => {
@@ -135,7 +158,7 @@ export function UsernameCard({
           </div>
         </div>
 
-        <UrgencyBar endsAt={listing.endsAt} />
+        <UrgencyBar endsAt={listing.endsAt} now={now} />
 
         {/* Bottom row: owner + bid count */}
         <div className="flex items-center justify-between text-[11px] text-neutral-600">
diff --git a/app/frontend/src/hooks/__tests__/usePersistentState.test.tsx b/app/frontend/src/hooks/__tests__/usePersistentState.test.tsx
index 62fcaf7ca..880b6dc4f 100644
--- a/app/frontend/src/hooks/__tests__/usePersistentState.test.tsx
+++ b/app/frontend/src/hooks/__tests__/usePersistentState.test.tsx
@@ -1,5 +1,6 @@
 import { renderHook, act } from "@testing-library/react";
-import { usePersistentState } from "../hooks/usePersistentState";
+import { usePersistentState } from "../usePersistentState";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 describe("usePersistentState", () => {
   const TEST_KEY = "test_key";
@@ -7,7 +8,7 @@ describe("usePersistentState", () => {
 
   beforeEach(() => {
     localStorage.clear();
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   it("should initialize with initial value if local storage is empty", () => {
@@ -59,7 +60,7 @@ describe("usePersistentState", () => {
 
   it("should sync to backend if provided", async () => {
     const USER_ID = "user_123";
-    const syncToBackend = jest.fn().mockResolvedValue(undefined);
+    const syncToBackend = vi.fn().mockResolvedValue(undefined);
 
     const { result } = renderHook(() =>
       usePersistentState(TEST_KEY, INITIAL_VALUE, {
diff --git a/app/frontend/src/hooks/marketplaceApi.ts b/app/frontend/src/hooks/marketplaceApi.ts
index b555617a9..3eb33dba8 100644
--- a/app/frontend/src/hooks/marketplaceApi.ts
+++ b/app/frontend/src/hooks/marketplaceApi.ts
@@ -49,6 +49,24 @@ export type UserListing = {
 
 export type BidResult = { success: true } | { success: false; reason: string };
 
+/**
+ * Human-readable countdown to the given date.
+ * e.g. "2d 3h", "47m", "Ended"
+ *
+ * Pure helper shared by the mock and production providers so components
+ * (e.g. UsernameCard) can render the countdown without coupling to a
+ * specific provider.
+ */
+export function formatCountdown(date: Date, now: number = Date.now()): string {
+  const diff = date.getTime() - now;
+  if (diff <= 0) return "Ended";
+  const h = Math.floor(diff / 3_600_000);
+  const m = Math.floor((diff % 3_600_000) / 60_000);
+  if (h >= 24) return `${Math.floor(h / 24)}d ${h % 24}h`;
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
 // ── Provider interface ───────────────────────────────────────────────────────
 
 /**
diff --git a/app/frontend/src/hooks/usePersistentState.ts b/app/frontend/src/hooks/usePersistentState.ts
index c4a77262b..d27196efb 100644
--- a/app/frontend/src/hooks/usePersistentState.ts
+++ b/app/frontend/src/hooks/usePersistentState.ts
@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useEffect, useCallback, useRef } from "react";
 
 interface PersistentStateOptions<T> {
   userId?: string;
@@ -23,26 +23,34 @@ export function usePersistentState<T>(
   const [state, setState] = useState<T>(initialValue);
   const [isHydrated, setIsHydrated] = useState(false);
 
+  // Keep the latest serialize/deserialize implementations in refs so that
+  // unstable (inline) callback identities don't cause effects to re-run and
+  // loop (e.g. when a parent re-renders with a fresh inline deserialize).
+  const deserializeRef = useRef(deserialize);
+  deserializeRef.current = deserialize;
+  const serializeRef = useRef(serialize);
+  serializeRef.current = serialize;
+
   // Load initial state from local storage
   useEffect(() => {
     try {
       const stored = localStorage.getItem(key);
       if (stored) {
-        setState(deserialize(stored));
+        setState(deserializeRef.current(stored));
       }
     } catch (e) {
       console.error(`Error loading state for key ${key}:`, e);
     } finally {
       setIsHydrated(true);
     }
-  }, [key, deserialize]);
+  }, [key]);
 
   // Sync state across tabs
   useEffect(() => {
     const handleStorage = (e: StorageEvent) => {
       if (e.key === key && e.newValue !== null) {
         try {
-          setState(deserialize(e.newValue));
+          setState(deserializeRef.current(e.newValue));
         } catch (e) {
           console.error(`Error parsing storage event for key ${key}:`, e);
         }
@@ -52,7 +60,7 @@ export function usePersistentState<T>(
     };
     window.addEventListener("storage", handleStorage);
     return () => window.removeEventListener("storage", handleStorage);
-  }, [key, deserialize, initialValue]);
+  }, [key, initialValue]);
 
   // Update state locally and notify backend if required
   const setPersistentState = useCallback(
@@ -60,7 +68,7 @@ export function usePersistentState<T>(
       setState((prev) => {
         const nextState = value instanceof Function ? value(prev) : value;
         try {
-          localStorage.setItem(key, serialize(nextState));
+          localStorage.setItem(key, serializeRef.current(nextState));
           if (userId && syncToBackend) {
             syncToBackend(nextState, userId).catch((err) =>
               console.error("Backend sync failed:", err)
@@ -72,7 +80,7 @@ export function usePersistentState<T>(
         return nextState;
       });
     },
-    [key, userId, syncToBackend, serialize]
+    [key, userId, syncToBackend]
   );
 
   return [state, setPersistentState, isHydrated] as const;
diff --git a/app/frontend/src/lib/__tests__/api.test.ts b/app/frontend/src/lib/__tests__/api.test.ts
new file mode 100644
index 000000000..c787506ce
--- /dev/null
+++ b/app/frontend/src/lib/__tests__/api.test.ts
@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  getProfile,
+  getProfileStorageKey,
+  readStoredProfileMetadata,
+  saveProfile,
+  ProfileNotFoundError,
+} from "../api";
+import { PROFILE_METADATA_DEFAULTS } from "@/types/profile";
+
+const VALID_BACKEND_PROFILE = {
+  id: "1",
+  username: "alice",
+  publicKey: "GAAA...",
+  lastActiveAt: "2026-04-23T09:00:00.000Z",
+  createdAt: "2026-04-01T09:00:00.000Z",
+};
+
+describe("getProfileStorageKey", () => {
+  it("normalizes the username to lowercase", () => {
+    expect(getProfileStorageKey("Alice")).toBe("profile_alice");
+    expect(getProfileStorageKey("ALICE")).toBe("profile_alice");
+  });
+});
+
+describe("readStoredProfileMetadata", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("returns defaults when nothing is stored", () => {
+    expect(readStoredProfileMetadata("alice")).toEqual(PROFILE_METADATA_DEFAULTS);
+  });
+
+  it("merges stored metadata and drops invalid fields", () => {
+    localStorage.setItem(
+      "profile_alice",
+      JSON.stringify({
+        primaryColor: "not-a-color",
+        bio: "Hi there",
+        extra: "ignored",
+      })
+    );
+
+    expect(readStoredProfileMetadata("alice")).toEqual({
+      ...PROFILE_METADATA_DEFAULTS,
+      bio: "Hi there",
+    });
+  });
+
+  it("removes malformed JSON and returns defaults", () => {
+    localStorage.setItem("profile_alice", "{not json");
+
+    expect(readStoredProfileMetadata("alice")).toEqual(PROFILE_METADATA_DEFAULTS);
+    expect(localStorage.getItem("profile_alice")).toBeNull();
+  });
+
+  it("removes non-object payloads", () => {
+    localStorage.setItem("profile_alice", JSON.stringify(["a", "b"]));
+
+    expect(readStoredProfileMetadata("alice")).toEqual(PROFILE_METADATA_DEFAULTS);
+    expect(localStorage.getItem("profile_alice")).toBeNull();
+  });
+
+  it("reads through the canonical lowercase key", () => {
+    localStorage.setItem("profile_alice", JSON.stringify({ bio: "hey" }));
+
+    expect(readStoredProfileMetadata("Alice").bio).toBe("hey");
+  });
+});
+
+describe("getProfile", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    localStorage.clear();
+  });
+
+  it("returns a merged profile from backend and localStorage", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          profiles: [VALID_BACKEND_PROFILE],
+          total: 1,
+          has_more: false,
+        }),
+      })
+    );
+    localStorage.setItem(
+      "profile_alice",
+      JSON.stringify({ bio: "Hey there", primaryColor: "#12abef" })
+    );
+
+    const profile = await getProfile("Alice");
+
+    expect(profile).toEqual({
+      username: "alice",
+      publicKey: "GAAA...",
+      ...PROFILE_METADATA_DEFAULTS,
+      bio: "Hey there",
+      primaryColor: "#12abef",
+    });
+  });
+
+  it("throws ProfileNotFoundError when there is no exact match", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          profiles: [
+            { ...VALID_BACKEND_PROFILE, username: "bob" },
+          ],
+          total: 1,
+          has_more: false,
+        }),
+      })
+    );
+
+    await expect(getProfile("alice")).rejects.toBeInstanceOf(ProfileNotFoundError);
+  });
+
+  it("surfaces network failures with friendly copy", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockRejectedValue(new TypeError("fetch failed"))
+    );
+
+    await expect(getProfile("alice")).rejects.toThrow(
+      "Unable to connect to the backend"
+    );
+  });
+});
+
+describe("saveProfile", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it("sanitizes and persists the profile under a lowercase key", async () => {
+    const saved = await saveProfile({
+      username: "Alice",
+      primaryColor: "bad",
+      avatarUrl: "not-a-url",
+      bio: "ok",
+      twitterHandle: "alice",
+      discordHandle: "",
+      githubHandle: "",
+    });
+
+    expect(saved.username).toBe("alice");
+    expect(saved.primaryColor).toBe(PROFILE_METADATA_DEFAULTS.primaryColor);
+    expect(saved.avatarUrl).toBe("");
+
+    const stored = JSON.parse(localStorage.getItem("profile_alice") as string);
+    expect(stored.username).toBe("alice");
+    expect(stored.bio).toBe("ok");
+  });
+});
diff --git a/app/frontend/src/lib/api.ts b/app/frontend/src/lib/api.ts
index de1838116..619c58321 100644
--- a/app/frontend/src/lib/api.ts
+++ b/app/frontend/src/lib/api.ts
@@ -1,4 +1,8 @@
-import { Profile } from "@/types/profile";
+import {
+  sanitizeProfileMetadata,
+  type Profile,
+  type ProfileMetadata,
+} from "@/types/profile";
 
 /**
  * Backend origin for browser calls. Override in `.env.local`:
@@ -8,6 +12,15 @@ export const getRustAcademyApiBase = (): string =>
   process.env.NEXT_PUBLIC_RustAcademy_API_URL?.replace(/\/$/, "") ||
   "http://localhost:4000";
 
+/**
+ * localStorage key that holds user-curated profile metadata. The key is
+ * normalized to lowercase so refreshes and case variations of a username
+ * always resolve to the same stored record.
+ */
+export function getProfileStorageKey(username: string): string {
+  return `profile_${username.toLowerCase()}`;
+}
+
 interface BackendPublicProfile {
   id: string;
   username: string;
@@ -34,6 +47,53 @@ export class ProfileNotFoundError extends Error {
   }
 }
 
+/**
+ * Read and sanitize the locally stored profile metadata for `username`.
+ *
+ * Recovers gracefully from malformed data:
+ * - invalid JSON or a non-object payload is discarded (and removed) and the
+ *   defaults are returned,
+ * - invalid individual fields are dropped and replaced with defaults,
+ * - no throw is ever surfaced to callers.
+ */
+export function readStoredProfileMetadata(
+  username: string,
+): ProfileMetadata {
+  if (typeof window === "undefined") {
+    return sanitizeProfileMetadata(null);
+  }
+
+  const storageKey = getProfileStorageKey(username);
+  const stored = window.localStorage.getItem(storageKey);
+
+  if (!stored) {
+    return sanitizeProfileMetadata(null);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stored);
+  } catch (e) {
+    // Corrupt payload — drop it so it doesn't keep failing on future loads.
+    console.error(
+      `Failed to parse stored profile metadata for "${username}":`,
+      e,
+    );
+    window.localStorage.removeItem(storageKey);
+    return sanitizeProfileMetadata(null);
+  }
+
+  const metadata = sanitizeProfileMetadata(parsed);
+
+  // If the stored value parsed but was unusable (e.g. a string/number/array),
+  // clean it up so the next load is deterministic.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    window.localStorage.removeItem(storageKey);
+  }
+
+  return metadata;
+}
+
 /**
  * Fetch a public user profile by username from the backend API.
  * 
@@ -64,27 +124,9 @@ export async function getProfile(username: string): Promise<Profile> {
       throw new ProfileNotFoundError(username);
     }
 
-    // Check localStorage for additional profile metadata (color, bio, social handles)
-    let metadata = {
-      primaryColor: "#6366f1",
-      avatarUrl: "",
-      bio: "",
-      twitterHandle: "",
-      discordHandle: "",
-      githubHandle: "",
-    };
-
-    if (typeof window !== "undefined") {
-      const stored = localStorage.getItem(`profile_${username}`);
-      if (stored) {
-        try {
-          const parsed = JSON.parse(stored);
-          metadata = { ...metadata, ...parsed };
-        } catch (e) {
-          console.error("Failed to parse stored profile metadata:", e);
-        }
-      }
-    }
+    // Merge sanitized localStorage metadata (colors, bio, social handles)
+    // with the backend profile. Malformed local data is dropped per-field.
+    const metadata = readStoredProfileMetadata(username);
 
     return {
       username: profile.username,
@@ -113,7 +155,16 @@ export async function saveProfile(profile: Profile): Promise<Profile> {
   await new Promise((resolve) => setTimeout(resolve, 800));
 
   if (typeof window !== "undefined") {
-    localStorage.setItem(`profile_${profile.username}`, JSON.stringify(profile));
+    const sanitized: Profile = {
+      ...profile,
+      username: profile.username.toLowerCase(),
+      ...sanitizeProfileMetadata(profile),
+    };
+    window.localStorage.setItem(
+      getProfileStorageKey(sanitized.username),
+      JSON.stringify(sanitized),
+    );
+    return sanitized;
   }
   return profile;
 }
diff --git a/app/frontend/src/lib/i18n.ts b/app/frontend/src/lib/i18n.ts
index 03b2293c2..21c3b93c8 100644
--- a/app/frontend/src/lib/i18n.ts
+++ b/app/frontend/src/lib/i18n.ts
@@ -1,10 +1,11 @@
 import i18n from "i18next";
 import { initReactI18next } from "react-i18next";
 
-const initialLanguage =
-  typeof window !== "undefined"
-    ? window.localStorage.getItem("i18nextLng") || "en"
-    : "en";
+// Start in "en" on both server and client so SSR markup matches the first
+// client render (reading localStorage here would cause a hydration mismatch
+// between the server-rendered language and the client's saved one). The
+// saved language is restored after hydration via a useEffect in Header.
+const initialLanguage = "en";
 
 i18n.use(initReactI18next).init({
   lng: initialLanguage,
diff --git a/app/frontend/src/types/__tests__/profile.test.ts b/app/frontend/src/types/__tests__/profile.test.ts
new file mode 100644
index 000000000..fd4dd34b0
--- /dev/null
+++ b/app/frontend/src/types/__tests__/profile.test.ts
@@ -0,0 +1,106 @@
+import { describe, it, expect } from "vitest";
+import {
+  PROFILE_METADATA_DEFAULTS,
+  sanitizeProfileMetadata,
+} from "../profile";
+
+describe("sanitizeProfileMetadata", () => {
+  it("returns defaults for non-object input", () => {
+    expect(sanitizeProfileMetadata(null)).toEqual(PROFILE_METADATA_DEFAULTS);
+    expect(sanitizeProfileMetadata(undefined)).toEqual(PROFILE_METADATA_DEFAULTS);
+    expect(sanitizeProfileMetadata("oops")).toEqual(PROFILE_METADATA_DEFAULTS);
+    expect(sanitizeProfileMetadata(42)).toEqual(PROFILE_METADATA_DEFAULTS);
+    expect(sanitizeProfileMetadata(["a", "b"])).toEqual(PROFILE_METADATA_DEFAULTS);
+  });
+
+  it("keeps valid values unchanged", () => {
+    const result = sanitizeProfileMetadata({
+      primaryColor: "#ff00aa",
+      avatarUrl: "https://example.com/avatar.png",
+      bio: "Hello world",
+      twitterHandle: "alice",
+      discordHandle: "alice#1234",
+      githubHandle: "alice-dev",
+    });
+
+    expect(result).toEqual({
+      primaryColor: "#ff00aa",
+      avatarUrl: "https://example.com/avatar.png",
+      bio: "Hello world",
+      twitterHandle: "alice",
+      discordHandle: "alice#1234",
+      githubHandle: "alice-dev",
+    });
+  });
+
+  it("rejects invalid hex colors", () => {
+    expect(sanitizeProfileMetadata({ primaryColor: "red" }).primaryColor).toBe(
+      PROFILE_METADATA_DEFAULTS.primaryColor
+    );
+    expect(sanitizeProfileMetadata({ primaryColor: "#FFF" }).primaryColor).toBe(
+      PROFILE_METADATA_DEFAULTS.primaryColor
+    );
+    expect(
+      sanitizeProfileMetadata({ primaryColor: "#gggiii" }).primaryColor
+    ).toBe(PROFILE_METADATA_DEFAULTS.primaryColor);
+  });
+
+  it("rejects non-URL avatar values", () => {
+    expect(sanitizeProfileMetadata({ avatarUrl: "not-a-url" }).avatarUrl).toBe("");
+    expect(
+      sanitizeProfileMetadata({ avatarUrl: "/relative.png" }).avatarUrl
+    ).toBe("");
+    expect(
+      sanitizeProfileMetadata({ avatarUrl: "javascript:alert(1)" }).avatarUrl
+    ).toBe("");
+  });
+
+  it("drops non-string fields", () => {
+    const result = sanitizeProfileMetadata({
+      bio: 123,
+      twitterHandle: null,
+      primaryColor: 5,
+      githubHandle: ["nope"],
+    });
+
+    expect(result.bio).toBe("");
+    expect(result.twitterHandle).toBe("");
+    expect(result.githubHandle).toBe("");
+  });
+
+  it("trims and length-caps fields", () => {
+    const result = sanitizeProfileMetadata({
+      bio: `  ${"x".repeat(200)}  `,
+      discordHandle: "x".repeat(40),
+    });
+
+    expect(result.bio).toHaveLength(160);
+    expect(result.discordHandle).toHaveLength(32);
+  });
+
+  it("drops invalid social handles", () => {
+    const result = sanitizeProfileMetadata({
+      twitterHandle: "@withSymbols",
+      githubHandle: "bad..dots",
+      discordHandle: "bad@chars!",
+    });
+
+    expect(result.twitterHandle).toBe("");
+    expect(result.githubHandle).toBe("");
+    expect(result.discordHandle).toBe("");
+  });
+
+  it("ignores unknown extra keys without throwing", () => {
+    const result = sanitizeProfileMetadata({
+      bio: "keep me",
+      unknownKey: { nested: true },
+      __proto__: { polluted: "field" },
+    });
+
+    expect(result.bio).toBe("keep me");
+    expect(result).toEqual({
+      ...PROFILE_METADATA_DEFAULTS,
+      bio: "keep me",
+    });
+  });
+});
diff --git a/app/frontend/src/types/profile.ts b/app/frontend/src/types/profile.ts
index 944a8e34a..e540850d8 100644
--- a/app/frontend/src/types/profile.ts
+++ b/app/frontend/src/types/profile.ts
@@ -9,6 +9,131 @@ export interface Profile {
   githubHandle: string;
 }
 
+/**
+ * The subset of `Profile` fields that are user-curated and stored in
+ * localStorage. `username` and `publicKey` come from the backend API.
+ */
+export type ProfileMetadata = Pick<
+  Profile,
+  | "primaryColor"
+  | "avatarUrl"
+  | "bio"
+  | "twitterHandle"
+  | "discordHandle"
+  | "githubHandle"
+>;
+
+/**
+ * Fallback values applied when a stored metadata field is missing, empty,
+ * or malformed. Keeps the public profile page rendering predictably even
+ * when localStorage contains corrupt or unexpected data.
+ */
+export const PROFILE_METADATA_DEFAULTS: ProfileMetadata = {
+  primaryColor: "#6366f1",
+  avatarUrl: "",
+  bio: "",
+  twitterHandle: "",
+  discordHandle: "",
+  githubHandle: "",
+};
+
+const PROFILE_METADATA_FIELD_KEYS = Object.keys(
+  PROFILE_METADATA_DEFAULTS,
+) as (keyof ProfileMetadata)[];
+
+function isValidHexColor(value: string): boolean {
+  return /^#[0-9a-fA-F]{6}$/.test(value);
+}
+
+function isValidUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function sanitizeString(
+  value: unknown,
+  maxLength: number,
+  pattern?: RegExp,
+): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const trimmed = value.trim().slice(0, maxLength);
+  if (pattern && !pattern.test(trimmed)) {
+    return "";
+  }
+  return trimmed;
+}
+
+/**
+ * Sanitize arbitrary (possibly malformed) data read from localStorage into a
+ * well-formed `ProfileMetadata` object.
+ *
+ * Every field is validated and typed individually:
+ * - non-string values fall back to the default,
+ * - `primaryColor` must be a 6-digit hex color,
+ * - `avatarUrl` must be an absolute http(s) URL,
+ * - handles/bio are trimmed and length-capped.
+ *
+ * Invalid input never throws — it degrades to the default for that field so
+ * callers can merge the result safely.
+ */
+export function sanitizeProfileMetadata(raw: unknown): ProfileMetadata {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...PROFILE_METADATA_DEFAULTS };
+  }
+
+  const candidate = raw as Record<string, unknown>;
+  const metadata = { ...PROFILE_METADATA_DEFAULTS };
+
+  for (const key of PROFILE_METADATA_FIELD_KEYS) {
+    const value = candidate[key];
+
+    switch (key) {
+      case "primaryColor":
+        if (typeof value === "string" && isValidHexColor(value)) {
+          metadata.primaryColor = value;
+        }
+        break;
+      case "avatarUrl":
+        if (
+          typeof value === "string" &&
+          value.trim() !== "" &&
+          isValidUrl(value)
+        ) {
+          metadata.avatarUrl = value.slice(0, 2048);
+        }
+        break;
+      case "bio":
+        metadata.bio = sanitizeString(value, 160);
+        break;
+      case "twitterHandle":
+        metadata.twitterHandle = sanitizeString(value, 15, /^[a-zA-Z0-9_]+$/);
+        break;
+      case "discordHandle":
+        metadata.discordHandle = sanitizeString(
+          value,
+          32,
+          /^[a-zA-Z0-9_.#]+$/,
+        );
+        break;
+      case "githubHandle":
+        metadata.githubHandle = sanitizeString(
+          value,
+          39,
+          /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/,
+        );
+        break;
+    }
+  }
+
+  return metadata;
+}
+
 export type ProfileValidationErrors = Partial<Record<keyof Profile, string>>;
 
 export function validateProfile(profile: Profile): { isValid: boolean; errors: ProfileValidationErrors } {
diff --git a/app/frontend/vitest.config.ts b/app/frontend/vitest.config.ts
index 170ab12a8..d2b3bdbff 100644
--- a/app/frontend/vitest.config.ts
+++ b/app/frontend/vitest.config.ts
@@ -11,7 +11,6 @@ export default defineConfig({
       "src/**/__tests__/**/*.{ts,tsx}",
       "__tests__/**/*.{ts,tsx}",
     ],
-    setupFiles: [],
   },
   esbuild: {
     // Enable the React 17+ automatic JSX transform so tests don't need