From da2dae0146754a03bfb9f96893d5b74f2463e799 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Fri, 23 Oct 2026 16:17:32 -0400
Subject: [PATCH 1/4] Delay page reveal until theme setup completes

---
 great_docs/assets/theme-init.js | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/great_docs/assets/theme-init.js b/great_docs/assets/theme-init.js
index ea6e7888..02ef36a5 100644
--- a/great_docs/assets/theme-init.js
+++ b/great_docs/assets/theme-init.js
@@ -8,9 +8,6 @@
     var theme = stored || (darkModeDisabled ? 'light' : (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'));
     var html = document.documentElement;
 
-    // Hide body until theme is fully applied to prevent flash
-    html.classList.add('theme-loading');
-
     if (theme === 'dark') {
         html.classList.add('quarto-dark');
         html.setAttribute('data-bs-theme', 'dark');
@@ -61,13 +58,18 @@
         }
     }
 
-    // Reveal page once DOM is ready and styles are applied
+    // Reveal the page once the DOM is parsed and after-body scripts have run.
+    // The page is hidden by an inline <style> in the <head> (metadata.html)
+    // that targets html:not(.theme-loaded).  A double requestAnimationFrame
+    // ensures the browser has painted the changes from after-body scripts
+    // (sidebar, dark-mode toggle, "On This Page", tags, etc.) before the
+    // page becomes visible.
     function revealPage() {
         setPageIdentifier();
-        // Small delay to ensure CSS is processed
         requestAnimationFrame(function() {
-            html.classList.remove('theme-loading');
-            html.classList.add('theme-loaded');
+            requestAnimationFrame(function() {
+                html.classList.add('theme-loaded');
+            });
         });
     }
 

From 812c99cea98d0c35722ee5948559cc343f55e5a7 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Fri, 23 Oct 2026 16:17:42 -0400
Subject: [PATCH 2/4] Hide page until theme initialization completes

---
 great_docs/assets/great-docs.scss | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/great_docs/assets/great-docs.scss b/great_docs/assets/great-docs.scss
index abb297f7..37197f1d 100644
--- a/great_docs/assets/great-docs.scss
+++ b/great_docs/assets/great-docs.scss
@@ -889,13 +889,20 @@ dt a.doc-method-name::after {
    General site styles (merged from great-docs.css)
    ============================================================================ */
 
-/* Theme loading - hide page until theme is applied to prevent flash */
-html.theme-loading {
+/* Hide the page until theme-init.js has finished and after-body scripts have
+   painted.  An inline <style> in metadata.html applies the same rules first
+   thing in <head>; they are repeated here for pages that don't use it.
+   `opacity` does the hiding: Quarto sets `visibility: visible !important` on
+   the sidebar sections, the TOC and the navbar offcanvas, which escapes an
+   inherited `visibility: hidden`.  `visibility` stays to keep the hidden page
+   out of hit-testing. */
+html:not(.theme-loaded) {
     visibility: hidden;
 }
 
-html.theme-loading body {
+html:not(.theme-loaded) body {
     visibility: hidden;
+    opacity: 0;
 }
 
 /* General heading weight -- handled by SCSS @extend .fw-medium */

From 9a26d919ab5da3b8d8be5c34fad67de92f1a4728 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Fri, 23 Oct 2026 16:17:54 -0400
Subject: [PATCH 3/4] Prevent flash before theme initialization

---
 great_docs/assets/metadata.html | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/great_docs/assets/metadata.html b/great_docs/assets/metadata.html
index a515fab1..a22ce2f7 100644
--- a/great_docs/assets/metadata.html
+++ b/great_docs/assets/metadata.html
@@ -1,4 +1,6 @@
 <meta charset="utf-8" />
+<style>html:not(.theme-loaded){visibility:hidden}html:not(.theme-loaded) body{visibility:hidden;opacity:0}</style>
+<noscript><style>html:not(.theme-loaded),html:not(.theme-loaded) body{visibility:visible!important;opacity:1!important}</style></noscript>
 $if(quarto-version)$
 <meta name="generator" content="quarto-$quarto-version$" />
 $else$

From d4c82a23326d9ea02df4460cfc3550a62c305331 Mon Sep 17 00:00:00 2001
From: Richard Iannone <riannone@me.com>
Date: Fri, 23 Oct 2026 16:18:09 -0400
Subject: [PATCH 4/4] Exclude page-reveal styles from metadata comparison

---
 tests/test_metadata_partial.py | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/tests/test_metadata_partial.py b/tests/test_metadata_partial.py
index 7489c192..7a79ef8e 100644
--- a/tests/test_metadata_partial.py
+++ b/tests/test_metadata_partial.py
@@ -17,6 +17,8 @@
 HEAD_TAGS_LOOP = ["$for(gd-head-tags)$", "$gd-head-tags$", "$endfor$"]
 # Removed as one block, since `$endif$` also closes Quarto's own conditionals.
 ROBOTS_LINES = ["$if(robots)$", '<meta name="robots" content="$robots$" />', "$endif$"]
+# Hide the page until theme-init.js reveals it (with a no-JS fallback).
+PAGE_REVEAL_PREFIXES = ("<style>html:not(.theme-loaded)", "<noscript><style>html:not(.theme-loaded)")
 
 
 def _quarto_partial() -> Path | None:
@@ -84,11 +86,15 @@ def _unmodified_lines(content: str) -> list[str]:
     Returns
     -------
     :
-        Lines other than the title element, the robots tag and the
-        `gd-head-tags` loop.
+        Lines other than the title element, the robots tag, the page-reveal
+        styles and the `gd-head-tags` loop.
     """
     content = content.replace("\n".join(ROBOTS_LINES) + "\n", "")
-    return [line for line in _without_title(content) if line not in HEAD_TAGS_LOOP]
+    return [
+        line
+        for line in _without_title(content)
+        if line not in HEAD_TAGS_LOOP and not line.startswith(PAGE_REVEAL_PREFIXES)
+    ]
 
 
 def test_bundled_partial_contains_title_element():
@@ -104,8 +110,8 @@ def test_bundled_partial_matches_quarto_except_for_title_and_head_tags() -> None
     """
     Keep the bundled metadata tags aligned with Quarto
 
-    Exclude the title element, the robots tag and the `gd-head-tags` loop,
-    which great-docs replaces or adds.
+    Exclude the title element, the robots tag, the page-reveal styles and the
+    `gd-head-tags` loop, which great-docs replaces or adds.
     """
     upstream = _quarto_partial()
     assert upstream is not None