From 01bb2d112d9d8a62e206639b7ab748067d92b597 Mon Sep 17 00:00:00 2001
From: chdeskur <chdeskur@gmail.com>
Date: Mon, 3 Nov 2025 07:44:34 -0500
Subject: [PATCH 1/4] chore: load katex with async stylesheet

---
 .../bundle/src/components/AsyncStylesheet.tsx  | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx

diff --git a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
new file mode 100644
index 0000000000..2da96dd0ca
--- /dev/null
+++ b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
@@ -0,0 +1,18 @@
+interface AsyncStylesheetProps {
+    href: string;
+    crossOrigin?: "anonymous" | "use-credentials";
+}
+
+export function AsyncStylesheet({ href, crossOrigin }: AsyncStylesheetProps) {
+  return (
+      <link
+          rel="stylesheet"
+          href={href}
+          media="print"
+          crossOrigin={crossOrigin}
+          onLoad={(e) => {
+              (e.target as HTMLLinkElement).media = "all";
+          }}
+      />
+  );
+}
\ No newline at end of file

From 5baba7864b48973ee283f1a27833df048a2cbd50 Mon Sep 17 00:00:00 2001
From: chdeskur <chdeskur@gmail.com>
Date: Mon, 3 Nov 2025 07:54:25 -0500
Subject: [PATCH 2/4] preload

---
 packages/fern-docs/bundle/src/app/layout.tsx  | 16 +------
 .../bundle/src/components/AsyncStylesheet.tsx | 45 ++++++++++++++-----
 2 files changed, 35 insertions(+), 26 deletions(-)

diff --git a/packages/fern-docs/bundle/src/app/layout.tsx b/packages/fern-docs/bundle/src/app/layout.tsx
index e62a35da6b..dd3088ebb4 100644
--- a/packages/fern-docs/bundle/src/app/layout.tsx
+++ b/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/katex@0.16.8/dist/katex.min.css"
                 crossOrigin="anonymous"
             />
-            <link
-                rel="stylesheet"
-                href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css"
-                media="print"
-                onload="this.media='all'"
-            />
-            <noscript
-                dangerouslySetInnerHTML={{
-                    __html: '<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.8/dist/katex.min.css" />'
-                }}
-            />
         </head>
     );
 
diff --git a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
index 2da96dd0ca..dfd8344d84 100644
--- a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
+++ b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
@@ -1,18 +1,39 @@
+/**
+ * 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 }: AsyncStylesheetProps) {
-  return (
-      <link
-          rel="stylesheet"
-          href={href}
-          media="print"
-          crossOrigin={crossOrigin}
-          onLoad={(e) => {
-              (e.target as HTMLLinkElement).media = "all";
-          }}
-      />
-  );
+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}" />`
+                }}
+            />
+        </>
+    );
 }
\ No newline at end of file

From 61f88eeec23e6c7359dd531cb7e71561361f9556 Mon Sep 17 00:00:00 2001
From: chdeskur <chdeskur@gmail.com>
Date: Mon, 3 Nov 2025 08:01:44 -0500
Subject: [PATCH 3/4] format

---
 packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
index dfd8344d84..c860a4f370 100644
--- a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
+++ b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
@@ -36,4 +36,4 @@ export function AsyncStylesheet({ href, crossOrigin = "anonymous" }: AsyncStyles
             />
         </>
     );
-}
\ No newline at end of file
+}

From 2671194a664b6025dc3aa46c8d9db826a3f5c059 Mon Sep 17 00:00:00 2001
From: chdeskur <chdeskur@gmail.com>
Date: Mon, 3 Nov 2025 08:15:29 -0500
Subject: [PATCH 4/4] use client

---
 packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
index c860a4f370..dd91da19d6 100644
--- a/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
+++ b/packages/fern-docs/bundle/src/components/AsyncStylesheet.tsx
@@ -1,3 +1,5 @@
+"use client";
+
 /**
  * AsyncStylesheet - Non-blocking CSS loading component
  *