From 63ea08691678a0c96fda94c13bb68419e9eb4d06 Mon Sep 17 00:00:00 2001
From: Blake Gentry <blakesgentry@gmail.com>
Date: Sun, 25 Oct 2026 20:17:15 -0500
Subject: [PATCH] prevent theme flashes during startup

The initial HTML renders before the theme provider mounts, which waits
for the features request. Dark mode can show a white page while the
styles, JavaScript, and API response load.

Apply the saved or system theme in a synchronous head script and paint
the matching page background before external assets load. Fall back to
the system preference when browser storage is unavailable, and let the
existing theme provider continue managing subsequent changes.
---
 public/index.html | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/public/index.html b/public/index.html
index 07fa20d5..161e7211 100644
--- a/public/index.html
+++ b/public/index.html
@@ -2,6 +2,37 @@
 <html lang="en" class="h-full">
   <head>
     <meta charset="UTF-8" />
+    <meta name="color-scheme" content="light dark" />
+    <script>
+      // Match next-themes before loading styles, React, or the features API.
+      (() => {
+        let theme;
+        try {
+          theme = localStorage.getItem("theme");
+        } catch {
+          // Use the system preference when storage is unavailable.
+        }
+
+        if (theme !== "light" && theme !== "dark") {
+          theme = window.matchMedia("(prefers-color-scheme: dark)").matches
+            ? "dark"
+            : "light";
+        }
+
+        document.documentElement.classList.add(theme);
+        document.documentElement.style.colorScheme = theme;
+      })();
+    </script>
+    <style>
+      /* Match bg-white and dark:bg-slate-900 before Tailwind loads. */
+      html {
+        background-color: #fff;
+      }
+
+      html.dark {
+        background-color: var(--color-slate-900, oklch(20.8% 0.042 265.755));
+      }
+    </style>
     <link
       rel="icon"
       href="{{ .Base }}/favicon.ico"