From 89c20e06a070e719cf47816300683c2eb33c5c5f Mon Sep 17 00:00:00 2001
From: omoh5 <edukpeomoyemeh@gmail.com>
Date: Thu, 30 Jul 2026 07:25:53 +0000
Subject: [PATCH] fix(frontend): guard against SSR/hydration mismatch in theme
 provider (#1083)

Add blocking inline script in <head> that reads localStorage theme preference before first paint, preventing flash-of-wrong-theme when client theme differs from server-rendered default. Add comprehensive JSDoc comments documenting the SSR/hydration strategy in both theme-provider.tsx and layout.tsx.
---
 frontend/src/app/layout.tsx             | 45 +++++++++++++++++++++--
 frontend/src/context/theme-provider.tsx | 47 +++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 2 deletions(-)
diff --git a/frontend/src/app/layout.tsx b/frontend/src/app/layout.tsx
index e039ba12..f063814f 100644
--- a/frontend/src/app/layout.tsx
+++ b/frontend/src/app/layout.tsx
@@ -59,9 +59,50 @@ export default function RootLayout({
 }: Readonly<{
   children: React.ReactNode;
 }>) {
+  // suppressHydrationWarning allows the blocking inline script in <head> to
+  // mutate the `dark` class on <html> without React logging a hydration
+  // mismatch warning. See theme-provider.tsx for the full strategy.
   return (
-    <html lang="en" suppressHydrationWarning> {/* TODO: revisit if i18n is introduced */}
-      <head />
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        {/*
+          Blocking inline script that reads the user's stored theme preference
+          from localStorage and applies the `dark` class to <html> BEFORE the
+          browser paints a single pixel. This prevents the flash-of-wrong-theme
+          (FART) when the server renders a default theme class that differs from
+          the user's persisted preference.
+
+          The `suppressHydrationWarning` prop on <html> is the companion measure:
+          after this script mutates the class, React will see a mismatch between
+          server-rendered <html> (no `dark` class) and the client DOM (possibly
+          `dark` class) and would normally emit a console warning.
+          suppressHydrationWarning tells React to skip that check for this
+          element because the discrepancy is intentional and resolved before
+          hydration completes.
+
+          Flow: inline script runs → class set → browser paints → React hydrates
+          (suppressHydrationWarning) → next-themes ThemeProvider takes over.
+        */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `
+              (function() {
+                try {
+                  var theme = localStorage.getItem('flowfi-theme') || 'dark';
+                  if (theme === 'system') {
+                    theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+                  }
+                  if (theme === 'dark') {
+                    document.documentElement.classList.add('dark');
+                  } else {
+                    document.documentElement.classList.remove('dark');
+                  }
+                } catch (e) {}
+              })();
+            `,
+          }}
+        />
+      </head>
       <body className={`${sora.variable} ${mono.variable} antialiased`}>
         <ThemeProvider
           attribute="class"
diff --git a/frontend/src/context/theme-provider.tsx b/frontend/src/context/theme-provider.tsx
index 189a2b1a..1b3d232c 100644
--- a/frontend/src/context/theme-provider.tsx
+++ b/frontend/src/context/theme-provider.tsx
@@ -3,6 +3,53 @@
 import * as React from "react";
 import { ThemeProvider as NextThemesProvider } from "next-themes";
 
+/**
+ * Thin wrapper around `next-themes`' `ThemeProvider` that centralises theme
+ * configuration for the FlowFi frontend.
+ *
+ * ## SSR / Hydration Strategy
+ *
+ * Theme selection is inherently a client-side concern (it depends on
+ * `localStorage` and/or `matchMedia`). The server cannot know which theme the
+ * user prefers, so it always renders a default (`dark`) theme class. This
+ * creates two problems:
+ *
+ * 1. **Flash of wrong theme (FART).** If the user chose "light" previously,
+ *    the browser paints the dark theme first, then swaps to light when
+ *    React hydrates — an unpleasant flicker.
+ *
+ * 2. **Hydration mismatch warning.** When React hydrates the `<html>` element
+ *    and sees that the client DOM has a `dark` class the server did not
+ *    produce, it logs a console warning.
+ *
+ * We solve both problems with a two-part approach inside `layout.tsx`:
+ *
+ * - **Blocking inline `<script>` in `<head>`** — reads `flowfi-theme` from
+ *   localStorage and synchronously adds/removes the `dark` class on
+ *   `<html>` **before the first paint**. No flicker occurs because the
+ *   correct class is present from the very first rendered frame.
+ *
+ * - **`suppressHydrationWarning` on `<html>`** — tells React to skip the
+ *   hydration-difference check for the `<html>` element because we
+ *   intentionally mutate its class list before hydration.
+ *
+ * After hydration, this `ThemeProvider` (via `next-themes`) takes over theme
+ * management, reacting to `useTheme()` calls and persisting changes to the
+ * same `flowfi-theme` localStorage key.
+ *
+ * ## Configuration
+ *
+ * - `attribute="class"` — toggles a `dark` class on `<html>`, which Tailwind
+ *   uses for its `dark:` variant.
+ * - `defaultTheme="dark"` — what the server (and users without any stored
+ *   preference) will see.
+ * - `enableSystem={true}` — when theme is set to `"system"`, the provider
+ *   follows the OS-level `prefers-color-scheme` media query.
+ * - `storageKey="flowfi-theme"` — namespaced localStorage key to avoid
+ *   collisions with other apps on the same origin.
+ * - `disableTransitionOnChange` — prevents a brief CSS transition when the
+ *   theme class changes, making the switch feel instant.
+ */
 export function ThemeProvider({
   children,
   ...props
