perf(mui): smooth theme cross-fade via View Transitions API (was per-element repaint jank)

The per-element color/box-shadow transition repainted the whole tree every frame (~5fps). Replaced with document.startViewTransition: the browser cross-fades one GPU-composited snapshot of the page — smooth regardless of element count. flushSync + useLayoutEffect ensure the data-theme flip is captured in the transition; instant fallback where unsupported / reduced-motion.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/context/ThemeContext.tsx

@@ -2,10 +2,10 @@ import {
   createContext,
   useContext,
   useState,
-  useEffect,
-  useRef,
+  useLayoutEffect,
   type ReactNode,
 } from "react";
+import { flushSync } from "react-dom";
 
 interface ThemeContextValue {
   theme: string;
@@ -14,6 +14,10 @@ interface ThemeContextValue {
 
 const ThemeContext = createContext<ThemeContextValue | null>(null);
 
+type ViewTransitionDocument = Document & {
+  startViewTransition?: (callback: () => void) => unknown;
+};
+
 export function ThemeProvider({ children }: { children: ReactNode }) {
   const [theme, setTheme] = useState(() => {
     if (typeof window !== "undefined") {
@@ -21,37 +25,37 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
     }
     return "dark";
   });
-  const firstRun = useRef(true);
 
-  useEffect(() => {
-    const root = document.documentElement;
-    // Coordinated cross-fade on real toggles only (not the initial mount):
-    // arm a uniform color transition across the whole tree for the switch
-    // window, then remove it so normal interactions keep their own transitions.
-    let timer: number | undefined;
-    if (!firstRun.current) {
-      root.classList.add("theme-transition");
-      timer = window.setTimeout(
-        () => root.classList.remove("theme-transition"),
-        320,
-      );
-    }
-    firstRun.current = false;
-
-    root.setAttribute("data-theme", theme);
+  // Apply synchronously (layout effect) so the `data-theme` attribute flips
+  // inside the View Transition's flushSync below — letting the browser capture
+  // the "after" snapshot and cross-fade to it.
+  useLayoutEffect(() => {
+    document.documentElement.setAttribute("data-theme", theme);
     localStorage.setItem("boha-theme", theme);
     const themeColor = theme === "dark" ? "#12121a" : "#ffffff";
     document
       .querySelector('meta[name="theme-color"]')
       ?.setAttribute("content", themeColor);
-
-    return () => {
-      if (timer) clearTimeout(timer);
-    };
   }, [theme]);
 
   const toggleTheme = () => {
-    setTheme((prev) => (prev === "dark" ? "light" : "dark"));
+    const apply = () =>
+      setTheme((prev) => (prev === "dark" ? "light" : "dark"));
+
+    const doc = document as ViewTransitionDocument;
+    const reduceMotion =
+      typeof window !== "undefined" &&
+      !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+
+    // View Transitions API: the browser cross-fades a GPU-composited snapshot of
+    // the whole page — smooth at any element count — instead of repainting every
+    // node's colors (which stutters). Falls back to an instant switch where the
+    // API is unavailable or the user prefers reduced motion.
+    if (doc.startViewTransition && !reduceMotion) {
+      doc.startViewTransition(() => flushSync(apply));
+    } else {
+      apply();
+    }
   };
 
   return (