From 786ed7c040db08b18478a36a43833c93678e4dea Mon Sep 17 00:00:00 2001
From: IanM <ian@morland.me>
Date: Thu, 14 May 2026 23:03:47 +0100
Subject: [PATCH] [2.x] fix(perf): replace async-CSS dual path with
 render-blocking stylesheet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The dual-path strategy from #4561 (sessionStorage warm cache + async
preload cold path) relied on JS-injected <link rel="stylesheet"> elements
blocking paint, which they do not by spec. The result was a flash of
unstyled content on cross-origin asset hosts (S3 / CloudFront most
visibly), on every cold tab, and intermittently on warm visits too.

- makeHead() now emits a standard <link rel="stylesheet"> for forum/admin
  CSS. Parser-discovered, render-blocking, ~single-digit ms on a CDN.
- The sessionStorage warm-path script and the noscript fallback are
  removed; the inline critical CSS stays as a safety net so the body
  has a theme-accurate background while the stylesheet is in flight.
- JS preloads switch from fetchpriority="low" to "high" — now that the
  stylesheet blocks paint, the SPA boot is the next critical-path item.
- New Document::$preHead bucket for content that must render before the
  stylesheet (used by the inline data-theme script so dark-mode users
  never see a light-flash if the browser paints before CSS arrives).
  Document::$head[] semantics are unchanged: items still render after
  the stylesheet, so admin-supplied <style>/<link> overrides correctly
  win the cascade.
---
 framework/core/src/Frontend/Document.php      | 46 +++++++++++--------
 .../src/Frontend/FrontendServiceProvider.php  | 17 ++++---
 framework/core/views/frontend/app.blade.php   |  8 ++--
 3 files changed, 41 insertions(+), 30 deletions(-)
diff --git a/framework/core/src/Frontend/Document.php b/framework/core/src/Frontend/Document.php
index 81f6a13f3f..6c18b6916c 100644
--- a/framework/core/src/Frontend/Document.php
+++ b/framework/core/src/Frontend/Document.php
@@ -94,13 +94,28 @@ class Document implements Renderable
     public ?bool $hasNextPage = null;
 
     /**
-     * An array of strings to append to the page's <head>.
+     * An array of strings to append to the page's <head>, rendered *after*
+     * the forum/admin stylesheet so that user-supplied <style>/<link> blocks
+     * correctly override core CSS.
      */
     public array $head = [];
 
     /**
-     * Inline critical CSS emitted before the async stylesheet links.
-     * Populated by FrontendServiceProvider to prevent a flash of unstyled content.
+     * An array of strings to render in <head> *before* the forum/admin
+     * stylesheet. Use this for hints and scripts that must take effect
+     * before first paint — preconnect hints to additional origins, an
+     * inline script that sets data-theme on <html>, etc.
+     *
+     * Anything that depends on CSS variables, computed styles, or that
+     * should be able to override the forum stylesheet belongs in $head.
+     */
+    public array $preHead = [];
+
+    /**
+     * Inline critical CSS emitted before the main stylesheet link.
+     * Populated by FrontendServiceProvider to give the browser a
+     * theme-accurate body background to paint while the main stylesheet
+     * is being fetched.
      */
     public string $criticalCss = '';
 
@@ -303,25 +318,18 @@ protected function makePreconnects(): array
 
     protected function makeHead(): string
     {
-        // On warm visits (CSS already cached), a tiny inline script injects blocking
-        // <link rel="stylesheet"> tags synchronously before first paint — no FOUC, no
-        // network round-trip. On cold visits the sessionStorage keys are absent so the
-        // script exits immediately and the async preload path below takes over.
-        // Versioned URLs act as natural cache-busters: a new deploy changes the URL,
-        // the old sessionStorage key doesn't match, and the async path runs once more.
+        // The forum/admin stylesheet is render-blocking (parser-discovered
+        // <link rel="stylesheet">), so anything that must be in effect *before*
+        // first paint — preconnect hints, and anything pushed to $preHead by
+        // content callbacks (e.g. the inline data-theme script) — precedes it.
+        // Everything else — extension head content, JS preloads, meta tags,
+        // polyfills — comes after so it doesn't delay paint and so user
+        // overrides like custom <style> blocks correctly win the cascade.
         $head = $this->makePreconnects();
+        $head = array_merge($head, $this->preHead);
 
-        if (! empty($this->css)) {
-            $cssJson = json_encode(array_values($this->css), JSON_UNESCAPED_SLASHES | JSON_HEX_TAG);
-            $head[] = '<script>(function(){var s='.$cssJson.';if(s.every(function(h){return sessionStorage.getItem("css:"+h);})){s.forEach(function(h){var l=document.createElement("link");l.rel="stylesheet";l.href=h;document.head.appendChild(l);});}Object.keys(sessionStorage).forEach(function(k){if(k.indexOf("css:")===0&&s.indexOf(k.slice(4))===-1){sessionStorage.removeItem(k);}});})();</script>';
-        }
-
-        // Async preload path for cold visits. The onload updates sessionStorage so the
-        // next page load can take the fast synchronous path above.
         foreach ($this->css as $url) {
-            $escaped = e($url);
-            $head[] = '<link rel="preload" href="'.$escaped.'" as="style" fetchpriority="high" onload="sessionStorage.setItem(\'css:\'+this.href,\'1\');this.onload=null;this.rel=\'stylesheet\'">'
-                .'<noscript><link rel="stylesheet" href="'.$escaped.'"></noscript>';
+            $head[] = '<link rel="stylesheet" href="'.e($url).'" fetchpriority="high">';
         }
 
         if ($this->page) {
diff --git a/framework/core/src/Frontend/FrontendServiceProvider.php b/framework/core/src/Frontend/FrontendServiceProvider.php
index 6ba14b4b99..e2e3791dcd 100644
--- a/framework/core/src/Frontend/FrontendServiceProvider.php
+++ b/framework/core/src/Frontend/FrontendServiceProvider.php
@@ -86,16 +86,18 @@ public function register(): void
                 $frontend->content(function (Document $document) use ($container) {
                     $default_preloads = $container->make('flarum.frontend.default_preloads');
 
-                    // CSS files are preloaded via the async <link rel="preload" as="style"> tags
-                    // that makeHead() now emits directly — no need to duplicate them here.
-                    // JS files still get explicit preload hints so the browser fetches them early.
+                    // The forum/admin stylesheet blocks paint (parser-discovered <link
+                    // rel="stylesheet">), so the next thing on the critical path is forum.js
+                    // booting the SPA. Preload JS at high priority so it lands while CSS is
+                    // still being fetched, rather than waiting for the body parser to discover
+                    // the <script> tag.
                     $js_preloads = [];
 
                     foreach ($document->js as $url) {
                         $js_preloads[] = [
                             'href' => $url,
                             'as' => 'script',
-                            'fetchpriority' => 'low',
+                            'fetchpriority' => 'high',
                         ];
                     }
 
@@ -153,10 +155,11 @@ public function register(): void
 
                     // Inline script that sets data-theme on <html> before first paint so that
                     // the critical CSS block can apply the correct background colour without a
-                    // flash in dark mode. Uses the forum-level default; per-user preference is
-                    // applied by JS after boot (acceptable tradeoff).
+                    // flash in dark mode. Goes into $preHead so it executes before the main
+                    // stylesheet link is processed. Uses the forum-level default; per-user
+                    // preference is applied by JS after boot (acceptable tradeoff).
                     $forumColorScheme = $settings->get('color_scheme') ?? 'auto';
-                    $document->head[] = '<script>(function(){var s='.json_encode($forumColorScheme).';'
+                    $document->preHead[] = '<script>(function(){var s='.json_encode($forumColorScheme).';'
                         .'if(s==="auto")s=window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light";'
                         .'document.documentElement.setAttribute("data-theme",s)})()</script>';
 
diff --git a/framework/core/views/frontend/app.blade.php b/framework/core/views/frontend/app.blade.php
index e40e8ee6c5..a4fccfd6e0 100644
--- a/framework/core/views/frontend/app.blade.php
+++ b/framework/core/views/frontend/app.blade.php
@@ -4,11 +4,11 @@
         <meta charset="utf-8">
         <title>{{ $title }}</title>
 
-        {{-- Minimal critical CSS: prevents a flash of unstyled content while the main         --}}
-        {{-- stylesheet loads asynchronously. Content is computed server-side so the dark     --}}
-        {{-- background matches the forum's actual secondary colour. See FrontendServiceProvider. --}}
+        {{-- Minimal critical CSS: gives the browser a theme-accurate body background to paint --}}
+        {{-- as soon as the document starts, before the stylesheet has loaded. Content is     --}}
+        {{-- computed server-side so the dark background matches the forum's actual secondary --}}
+        {{-- colour. See FrontendServiceProvider.                                              --}}
         @if($criticalCss)<style>{!! $criticalCss !!}</style>@endif
-
         {!! $head !!}
     </head>
 
