From c8f8318bd5af9a455b1503a8aae937e6b7c93f65 Mon Sep 17 00:00:00 2001
From: Tanner Linsley <tannerlinsley@gmail.com>
Date: Thu, 15 Oct 2026 17:19:07 -0600
Subject: [PATCH] fix: restore docs width before first paint

---
 src/components/LibraryLayout.tsx | 16 ++++++++--
 src/routes/__root.tsx            |  2 ++
 src/utils/docs-width.ts          |  3 ++
 tests/docs-width.test.ts         | 53 ++++++++++++++++++++++++++++++++
 4 files changed, 71 insertions(+), 3 deletions(-)
 create mode 100644 src/utils/docs-width.ts
 create mode 100644 tests/docs-width.test.ts

diff --git a/src/components/LibraryLayout.tsx b/src/components/LibraryLayout.tsx
index 4ac073ebd..61b48fb0e 100644
--- a/src/components/LibraryLayout.tsx
+++ b/src/components/LibraryLayout.tsx
@@ -1442,7 +1442,18 @@ export function LibraryLayout({
   )
 
   return (
-    <WidthToggleContext.Provider value={{ isFullWidth, setIsFullWidth }}>
+    <WidthToggleContext.Provider
+      value={{
+        isFullWidth,
+        setIsFullWidth: (fullWidth) => {
+          document.documentElement.style.setProperty(
+            '--docs-content-width',
+            fullWidth ? '100%' : '900px',
+          )
+          setIsFullWidth(fullWidth)
+        },
+      }}
+    >
       <DocNavigationContext.Provider
         value={{
           libraryId,
@@ -1480,8 +1491,7 @@ export function LibraryLayout({
                   !isLandingPage &&
                     !isExample &&
                     !isNpmStats &&
-                    !isFullWidth &&
-                    'mx-auto w-[900px]',
+                    'mx-auto w-[var(--docs-content-width,900px)]',
                 )}
               >
                 {children}
diff --git a/src/routes/__root.tsx b/src/routes/__root.tsx
index c3d782a5a..bec6e5ce1 100644
--- a/src/routes/__root.tsx
+++ b/src/routes/__root.tsx
@@ -55,6 +55,7 @@ import {
 } from '~/utils/analytics/scarf'
 import { createPartnerPlacementSessionSeed } from '~/utils/partner-placement'
 import { twMerge } from 'tailwind-merge'
+import { DOCS_WIDTH_BOOTSTRAP } from '~/utils/docs-width'
 
 const GOOGLE_ANALYTICS_ID = 'G-JMT1Z50SPS'
 const GOOGLE_ANALYTICS_PROXY_PREFIX = '/_a'
@@ -356,6 +357,7 @@ function ShellComponent({ children }: { children: React.ReactNode }) {
           dangerouslySetInnerHTML={{ __html: THEME_BOOTSTRAP }}
           suppressHydrationWarning
         />
+        <script dangerouslySetInnerHTML={{ __html: DOCS_WIDTH_BOOTSTRAP }} />
         <HeadContent />
         {import.meta.env.PROD ? (
           <script
diff --git a/src/utils/docs-width.ts b/src/utils/docs-width.ts
new file mode 100644
index 000000000..ac3993214
--- /dev/null
+++ b/src/utils/docs-width.ts
@@ -0,0 +1,3 @@
+// Apply the saved width before the document can paint. Keep the storage shape
+// and expiry behavior in sync with useLocalStorage.
+export const DOCS_WIDTH_BOOTSTRAP = `(function(){try{var p=JSON.parse(localStorage.getItem('docsFullWidth'));if(p&&p.value===true&&(!p.ttl||Date.now()<=p.ttl)){document.documentElement.style.setProperty('--docs-content-width','100%')}}catch(e){}})()`
diff --git a/tests/docs-width.test.ts b/tests/docs-width.test.ts
new file mode 100644
index 000000000..541e9ea38
--- /dev/null
+++ b/tests/docs-width.test.ts
@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { runInNewContext } from 'node:vm'
+import { DOCS_WIDTH_BOOTSTRAP } from '../src/utils/docs-width'
+
+function applyPreference(value: string | null, blocked = false) {
+  const properties = new Map<string, string>()
+  runInNewContext(DOCS_WIDTH_BOOTSTRAP, {
+    localStorage: {
+      getItem(key: string) {
+        assert.equal(key, 'docsFullWidth')
+        if (blocked) throw new Error('Storage is unavailable')
+        return value
+      },
+    },
+    document: {
+      documentElement: {
+        style: {
+          setProperty(key: string, value: string) {
+            properties.set(key, value)
+          },
+        },
+      },
+    },
+    Date: { now: () => 1000 },
+  })
+  return properties.get('--docs-content-width')
+}
+
+test('saved expanded width applies before React mounts', () => {
+  assert.equal(applyPreference('{"value":true,"ttl":null}'), '100%')
+  assert.equal(applyPreference('{"value":true}'), '100%')
+  assert.equal(applyPreference('{"value":true,"ttl":1000}'), '100%')
+  assert.equal(applyPreference('{"value":true,"ttl":2000}'), '100%')
+})
+
+test('constrained, missing, expired and invalid preferences retain the default width', () => {
+  for (const value of [
+    null,
+    'null',
+    '{}',
+    'invalid json',
+    '{"value":false}',
+    '{"value":"true"}',
+    '{"value":true,"ttl":999}',
+  ]) {
+    assert.equal(applyPreference(value), undefined)
+  }
+})
+
+test('blocked storage does not interrupt document initialization', () => {
+  assert.equal(applyPreference(null, true), undefined)
+})