From fc4bd7749323442d9c078c48276b151511f3a782 Mon Sep 17 00:00:00 2001
From: TheFlow <theflow@sydigital.com>
Date: Sun, 19 Oct 2025 21:22:05 +1300
Subject: [PATCH] perf(docs): improve LCP with deferred scripts and font
 preloading
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SUMMARY:
Optimized docs.html performance to improve Lighthouse score from 89/100
to >90/100 and reduce LCP from 1.8s to <1.5s.

PERFORMANCE OPTIMIZATIONS:

1. Deferred Script Loading:
   - Added defer attribute to 5 scripts (lines 865, 867-869, 872-873)
   - version-manager.js
   - document-cards.js
   - docs-app.js
   - docs-search-enhanced.js
   - i18n-simple.js
   - language-selector.js
   - Scripts now download in parallel without blocking HTML parsing
   - Execute in order after DOM ready

2. Font Preloading:
   - Added preload hints for critical fonts (lines 24-25)
   - Inter Regular (400) - body text
   - Inter Bold (700) - headings
   - Browser starts downloading fonts immediately
   - Reduces FOIT/FOUT (flash of invisible/unstyled text)

EXPECTED IMPACT:
- LCP improvement: 1.8s → <1.5s (expected 15-20% reduction)
- Performance score: 89/100 → >90/100
- Scripts no longer block initial render
- Fonts render faster with less layout shift
- Reduced critical request chain length

LIGHTHOUSE ISSUES ADDRESSED:
✓ Render-blocking scripts eliminated
✓ Font loading optimized with preload hints
✓ Critical resources prioritized

FILES MODIFIED:
- public/docs.html (added defer to 6 scripts, preload 2 fonts)

NEXT STEPS:
Deploy to production and run Lighthouse audit to verify improvements.

🤖 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 public/docs.html | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/public/docs.html b/public/docs.html
index 866ef729..11de9a14 100644
--- a/public/docs.html
+++ b/public/docs.html
@@ -20,6 +20,10 @@
   <meta name="apple-mobile-web-app-title" content="Tractatus">
   <link rel="apple-touch-icon" href="/images/tractatus-icon-new.svg">
 
+  <!-- Preload critical fonts for faster initial render -->
+  <link rel="preload" href="/fonts/inter-400.woff2" as="font" type="font/woff2" crossorigin>
+  <link rel="preload" href="/fonts/inter-700.woff2" as="font" type="font/woff2" crossorigin>
+
   <link rel="stylesheet" href="/css/fonts.css">
   <link rel="stylesheet" href="/css/tailwind.css?v=0.1.0.1760254958072">
   <link rel="stylesheet" href="/css/tractatus-theme.min.css">
@@ -862,15 +866,15 @@
   </div>
 
   <!-- Version Management & PWA -->
-  <script src="/js/version-manager.js"></script>
+  <script src="/js/version-manager.js" defer></script>
 
-  <script src="/js/components/document-cards.js?v=0.1.0.1760825529624"></script>
-  <script src="/js/docs-app.js?v=0.1.0.1760825529624"></script>
-  <script src="/js/docs-search-enhanced.js?v=0.1.0.1760825529624"></script>
+  <script src="/js/components/document-cards.js?v=0.1.0.1760825529624" defer></script>
+  <script src="/js/docs-app.js?v=0.1.0.1760825529624" defer></script>
+  <script src="/js/docs-search-enhanced.js?v=0.1.0.1760825529624" defer></script>
 
   <!-- Internationalization -->
-  <script src="/js/i18n-simple.js?v=1760818106"></script>
-  <script src="/js/components/language-selector.js?v=1760818106"></script>
+  <script src="/js/i18n-simple.js?v=1760818106" defer></script>
+  <script src="/js/components/language-selector.js?v=1760818106" defer></script>
 
 </body>
 </html>