chore: load katex with async stylesheet (#4680)

Author: chdeskur

packages/fern-docs/bundle/src/app/layout.tsx

@@ -6,6 +6,7 @@ import { Providers } from "@fern-docs/components/providers/providers";
 import type { Metadata, Viewport } from "next/types";
 import { experimental_taintUniqueValue } from "react";
 
+import { AsyncStylesheet } from "@/components/AsyncStylesheet";
 import { ConsoleMessage } from "@/components/console-message";
 import { WebSocketRefresh } from "@/components/websocket-refresh";
 
@@ -56,23 +57,10 @@ export default function Layout({ children }: { children: React.ReactNode }) {
             <link rel="dns-prefetch" href="https://cdn.jsdelivr.net" />
 
             {/* Non-blocking KaTeX CSS loading */}
-            <link
-                rel="preload"
-                as="style"
+            <AsyncStylesheet
                 href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
                 crossOrigin="anonymous"
             />
-            <link
-                rel="stylesheet"
-                href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
-                media="print"
-                onload="this.media='all'"
-            />
-            <noscript
-                dangerouslySetInnerHTML={{
-                    __html: '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" />'
-                }}
-            />
         </head>
     );
 

packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+/**
+ * AsyncStylesheet - Non-blocking CSS loading component
+ *
+ * Loads a stylesheet asynchronously without blocking page render.
+ * Uses the media="print" + onLoad trick for optimal performance while
+ * maintaining React/TypeScript compatibility.
+ */
+
+interface AsyncStylesheetProps {
+    href: string;
+    crossOrigin?: "anonymous" | "use-credentials";
+}
+
+export function AsyncStylesheet({ href, crossOrigin = "anonymous" }: AsyncStylesheetProps) {
+    return (
+        <>
+            {/* Preload hint for early resource discovery */}
+            <link rel="preload" as="style" href={href} crossOrigin={crossOrigin} />
+
+            {/* Async loading with media swap trick - React's onLoad works here */}
+            <link
+                rel="stylesheet"
+                href={href}
+                media="print"
+                crossOrigin={crossOrigin}
+                onLoad={(e) => {
+                    (e.target as HTMLLinkElement).media = "all";
+                }}
+            />
+
+            {/* Fallback for users with JavaScript disabled */}
+            <noscript
+                dangerouslySetInnerHTML={{
+                    __html: `<link rel="stylesheet" href="${href}" crossorigin="${crossOrigin}" />`
+                }}
+            />
+        </>
+    );
+}