From 073cfabd977bf4f4ec09bb9daae93e8a953875c9 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>
---
 .claude/metrics/hooks-metrics.json | 18 ++++++++++++++++--
 public/docs.html                   | 16 ++++++++++------
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/.claude/metrics/hooks-metrics.json b/.claude/metrics/hooks-metrics.json
index 710e3d2f..e08e4ade 100644
--- a/.claude/metrics/hooks-metrics.json
+++ b/.claude/metrics/hooks-metrics.json
@@ -4570,6 +4570,20 @@
       "file": "/home/theflow/projects/tractatus/public/locales/fr/homepage.json",
       "result": "passed",
       "reason": null
+    },
+    {
+      "hook": "validate-file-edit",
+      "timestamp": "2025-10-19T08:20:14.348Z",
+      "file": "/home/theflow/projects/tractatus/public/docs.html",
+      "result": "passed",
+      "reason": null
+    },
+    {
+      "hook": "validate-file-edit",
+      "timestamp": "2025-10-19T08:20:30.920Z",
+      "file": "/home/theflow/projects/tractatus/public/docs.html",
+      "result": "passed",
+      "reason": null
     }
   ],
   "blocks": [
@@ -4833,9 +4847,9 @@
     }
   ],
   "session_stats": {
-    "total_edit_hooks": 465,
+    "total_edit_hooks": 467,
     "total_edit_blocks": 36,
-    "last_updated": "2025-10-19T08:16:08.622Z",
+    "last_updated": "2025-10-19T08:20:30.920Z",
     "total_write_hooks": 188,
     "total_write_blocks": 7
   }
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>