From 73b42394ee474d2a3ed7b7db4d3bbd97821ba9e2 Mon Sep 17 00:00:00 2001
From: Matt McKay <mmcky@users.noreply.github.com>
Date: Sat, 5 Sep 2026 09:59:46 +1000
Subject: [PATCH 1/2] fix: pin "back to top" to opacity 0 in the critical CSS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BackToTop is hidden by opacity-0 and carries transition-opacity, so on any
frame where the stylesheet is absent it paints at full opacity and fades out
once the sheet lands. That frame is produced by the React #423 hydration
recovery (#126), which re-renders the head and briefly drops the stylesheet
after the component has mounted — so gating the transition on mount, as #141
tried, cannot prevent it. Measured in WebKit with the stylesheet delayed:
17-18 animating frames without this rule, none with it.

The FOUC guard asserts the rule: the main test expects opacity 0, the control
expects 1 with the inline block stripped.

Supersedes the Outline.tsx change in #141. Relates to #126.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CHANGELOG.md              | 15 +++++++++++++++
 app/root.tsx              | 15 +++++++++++++++
 tests/visual/fouc.spec.ts | 22 +++++++++++++++++++++-
 3 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ebb5948a0..eeaf6b209 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- The "back to top" button no longer fades out of the page margin on load. It
+  is hidden by `opacity-0` and carries a `transition-opacity`, so on any frame
+  where the stylesheet is absent it painted at full opacity and then animated
+  away once the sheet landed. That frame is not the first paint alone: the
+  React hydration recovery ([#126](https://github.com/QuantEcon/quantecon-theme.mystmd/issues/126))
+  re-renders the head and briefly drops the stylesheet after the component has
+  mounted, which is why gating the transition on mount cannot stop it. The
+  critical CSS now pins the button to `opacity: 0` on the same zero-specificity
+  terms as the toggle's close icon, and the WebKit FOUC guard asserts it — with
+  the rule the button never paints, without it the control sees it at full
+  opacity. Measured with the stylesheet delayed: 17–18 animating frames before,
+  none after. Supersedes the `useMounted` approach in
+  [#141](https://github.com/QuantEcon/quantecon-theme.mystmd/pull/141).
+
 ## [2.4.0] - 2026-09-04
 
 > Headline: lecture content now matches the typography of the existing Sphinx
diff --git a/app/root.tsx b/app/root.tsx
index fa43d3281..e12076e54 100644
--- a/app/root.tsx
+++ b/app/root.tsx
@@ -88,6 +88,9 @@ export const meta: V2_MetaFunction<typeof loader> = ({ data }) => {
  *
  *   - toggle icon:   styles/app.css -> `.qe-toc-toggle__close` (only the class
  *                    name needs to stay in sync)
+ *   - back to top:   app/components/Outline.tsx -> `.qe-back-to-top`, whose
+ *                    Tailwind `opacity-0` / `opacity-100` pair this mirrors
+ *                    (again only the class name needs to stay in sync)
  *
  * The contents drawer itself needs no rule here — as a popover the UA
  * stylesheet already hides it while closed (see `.qe-toc` in styles/app.css).
@@ -95,6 +98,17 @@ export const meta: V2_MetaFunction<typeof loader> = ({ data }) => {
  * width/height attributes, so without this rule the close icon paints beside
  * the hamburger on that first frame. The `body:has(.qe-toc:popover-open)` rule
  * in app.css outranks this zero-specificity one, so the open state still swaps.
+ *
+ * "Back to top" needs the same treatment for a different reason: it carries a
+ * `transition-opacity` and is hidden by `opacity-0`, so on any frame where the
+ * stylesheet is absent it paints at full opacity and then *fades* out when the
+ * sheet lands, rather than never having been there. That frame is not only the
+ * first paint — the React #423 hydration recovery (#126) re-renders the head
+ * and briefly drops the stylesheet, and by then the component is mounted and
+ * the transition is live, so gating the transition on mount (as #141 tried)
+ * cannot stop it. Measured in WebKit with the stylesheet delayed: 17–18
+ * animating frames without this rule, none with it. Its `opacity-100` utility
+ * outranks this rule, so the scrolled state still shows.
  */
 const CRITICAL_CSS = `
 @font-face{font-family:"Source Sans 3 Fallback";src:local("Helvetica"),local("Arial"),local("Liberation Sans"),local("Arimo");size-adjust:92.25%;ascent-override:111%;descent-override:43.36%;line-gap-override:0%}
@@ -104,6 +118,7 @@ const CRITICAL_CSS = `
 :where(.dark body){background-color:#1c1917}
 :where([hidden],.hidden){display:none}
 :where(.qe-toc-toggle__close){display:none}
+:where(.qe-back-to-top){opacity:0}
 :where(.simple-center-grid){display:grid;grid-template-columns:[screen-start] 1fr [body-start] minmax(300px,800px) [body-end] 1fr [screen-end]}
 :where(.simple-center-grid) > *{grid-column:body-start / body-end}
 @media (min-width:1280px){:where(.simple-center-grid){grid-template-columns:[screen-start] 1fr 200px 20px [body-start] 800px [body-end] 20px [margin-start] 200px [margin-end] 1fr [screen-end]}}
diff --git a/tests/visual/fouc.spec.ts b/tests/visual/fouc.spec.ts
index 195c5a87b..8c61b8aac 100644
--- a/tests/visual/fouc.spec.ts
+++ b/tests/visual/fouc.spec.ts
@@ -11,7 +11,9 @@ import { test, expect, type Page, type Route } from "@playwright/test";
  *
  * The contents drawer is checked here too: any panel that relies on author CSS
  * to stay hidden paints open in that same frame. It is a popover now, so the UA
- * stylesheet hides it and the assertions below expect that.
+ * stylesheet hides it and the assertions below expect that. The toggle's close
+ * icon and the "back to top" button are the other two things that would paint
+ * without author CSS; each has a rule in the critical block and is asserted on.
  *
  * This test makes the failure mode deterministic by **aborting all external
  * stylesheets**, so the only styling that can reach the page is the inline
@@ -55,6 +57,7 @@ async function firstPaintState(page: Page) {
     const grid = document.querySelector(".simple-center-grid");
     const sidebar = document.querySelector(".qe-toc");
     const closeIcon = document.querySelector(".qe-toc-toggle__close");
+    const backToTop = document.querySelector(".qe-back-to-top");
     const applied = Array.from(document.styleSheets).filter((sheet) => {
       try {
         return !!sheet.cssRules && sheet.cssRules.length > 0; // applied, not pending
@@ -76,6 +79,11 @@ async function firstPaintState(page: Page) {
       // both icons paint side by side on the first frame. `null` when missing,
       // for the same reason as above.
       toggleCloseRendered: closeIcon ? closeIcon.getClientRects().length > 0 : null,
+      // "Back to top" is hidden by opacity rather than display, and carries a
+      // transition — so if it paints visible here it will *fade* out once the
+      // stylesheet lands. The critical block pins it to 0. `null` when missing,
+      // as above.
+      backToTopOpacity: backToTop ? getComputedStyle(backToTop).opacity : null,
       // null href == an inline <style>; any string == an external sheet that applied
       appliedExternal: applied.some((sheet) => !!sheet.href),
     };
@@ -109,6 +117,11 @@ test.describe("FOUC guard (WebKit) — inline critical CSS styles the first pain
       "`.qe-toc-toggle__close` not found — the toggle's close icon was renamed or removed"
     ).not.toBeNull();
     expect(state.toggleCloseRendered).toBe(false); // hidden by the inline rule
+    expect(
+      state.backToTopOpacity,
+      "`.qe-back-to-top` not found — the back-to-top button was renamed or removed"
+    ).not.toBeNull();
+    expect(state.backToTopOpacity).toBe("0"); // pinned by the inline rule
   });
 
   test("control: removing the inline critical CSS reproduces the FOUC", async ({ page }) => {
@@ -134,5 +147,12 @@ test.describe("FOUC guard (WebKit) — inline critical CSS styles the first pain
       "`.qe-toc-toggle__close` not found — the toggle's close icon was renamed or removed"
     ).not.toBeNull();
     expect(state.toggleCloseRendered).toBe(true);
+    // Same for "back to top": with the inline rule gone it paints at full
+    // opacity, which is the state the transition would then animate away from.
+    expect(
+      state.backToTopOpacity,
+      "`.qe-back-to-top` not found — the back-to-top button was renamed or removed"
+    ).not.toBeNull();
+    expect(state.backToTopOpacity).toBe("1");
   });
 });

From c2160cb4b52916ed40db58ebe61dd29efbe839c1 Mon Sep 17 00:00:00 2001
From: Matt McKay <mmcky@users.noreply.github.com>
Date: Sat, 5 Sep 2026 10:00:57 +1000
Subject: [PATCH 2/2] test(fouc): sample first paint from an init script,
 assert control preconditions

The React #423 hydration recovery restores the inlined critical <style>
150-240ms after DOMContentLoaded (#126). The control strips that block from
the served HTML, so a post-domcontentloaded sample can see it restored and
every control assertion flips at once. Sample in-page on DOMContentLoaded
instead, before hydration is scheduled, and have both cases assert their own
preconditions so a reshaped CRITICAL_CSS reports as a stale strip pattern.

Carries the test half of #141 onto the post-#144 probes. Relates to #126.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CHANGELOG.md              |  14 ++++
 tests/visual/fouc.spec.ts | 163 +++++++++++++++++++++++++++++---------
 2 files changed, 138 insertions(+), 39 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eeaf6b209..f0b78f93b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   opacity. Measured with the stylesheet delayed: 17–18 animating frames before,
   none after. Supersedes the `useMounted` approach in
   [#141](https://github.com/QuantEcon/quantecon-theme.mystmd/pull/141).
+- The WebKit FOUC guard no longer goes red for reasons unrelated to the critical
+  CSS. Hydration currently fails on every page load (React #418/#423), and the
+  recovery re-render restores the inlined critical `<style>` 150–240ms after
+  `DOMContentLoaded` — after the control test has deliberately stripped it from
+  the served HTML to prove the guard is meaningful. The measurement used to run
+  from the test after `domcontentloaded`, so on a loaded runner every control
+  assertion flipped at once. It now samples from an init script that fires
+  in-page on `DOMContentLoaded`, before hydration is even scheduled. Both cases
+  also assert their own preconditions — that the strip actually matched, and
+  whether the inline block is present as sampled — so a reshaped `CRITICAL_CSS`
+  reports as a stale strip pattern instead of as a run of confusing failures
+  about grid layout. The underlying hydration failure remains open in
+  [#126](https://github.com/QuantEcon/quantecon-theme.mystmd/issues/126);
+  carried over from [#141](https://github.com/QuantEcon/quantecon-theme.mystmd/pull/141).
 
 ## [2.4.0] - 2026-09-04
 
diff --git a/tests/visual/fouc.spec.ts b/tests/visual/fouc.spec.ts
index 8c61b8aac..58db8e327 100644
--- a/tests/visual/fouc.spec.ts
+++ b/tests/visual/fouc.spec.ts
@@ -27,7 +27,18 @@ import { test, expect, type Page, type Route } from "@playwright/test";
 
 const PAGE = "/";
 
+/**
+ * Aborts external stylesheets, optionally stripping the inline critical block.
+ *
+ * Returns a `strippedCritical` probe rather than trusting the regex to have
+ * matched. If `CRITICAL_CSS` is ever reshaped so the pattern stops matching,
+ * the control would otherwise run against a fully-styled page and fail on its
+ * *assertions* — reporting "expected block, received grid", which points at the
+ * critical CSS rather than at the stale pattern that is actually at fault.
+ * Asserting this probe turns that into a failure that names itself.
+ */
 async function isolateInlineCss(page: Page, { stripCritical = false } = {}) {
+  const probe = { strippedCritical: false };
   await page.route("**/*", async (route: Route) => {
     const req = route.request();
 
@@ -39,55 +50,114 @@ async function isolateInlineCss(page: Page, { stripCritical = false } = {}) {
     // Control: serve the document with the inlined critical <style> removed.
     if (req.resourceType() === "document" && stripCritical) {
       const response = await route.fetch();
-      const body = (await response.text()).replace(
+      const served = await response.text();
+      const body = served.replace(
         /<style>[^<]*:where\(\.simple-center-grid\)[^<]*<\/style>/g,
         "<!-- critical CSS removed for control -->",
       );
+      if (body !== served) probe.strippedCritical = true;
       return route.fulfill({ response, body });
     }
 
     return route.continue();
   });
+  return probe;
 }
 
-async function firstPaintState(page: Page) {
+/**
+ * Key under which the in-page sampler parks its measurement on `window`.
+ */
+const SAMPLE_KEY = "__qeFirstPaint";
+
+type FirstPaint = {
+  gridDisplay: string;
+  bodyFont: string;
+  sidebarRendered: boolean | null;
+  toggleCloseRendered: boolean | null;
+  backToTopOpacity: string | null;
+  appliedExternal: boolean;
+  criticalInline: boolean;
+};
+
+/**
+ * Measure at first paint, from inside the page, before React hydrates.
+ *
+ * The measurement used to run from the test after `domcontentloaded`, which
+ * left roughly a 150ms budget before hydration. That is not enough: hydration
+ * currently fails on every load (React #418/#423, tracked in #126), and the
+ * recovery re-render puts the critical `<style>` back — measured at 150–240ms
+ * after `DOMContentLoaded`. The control strips that block from the served HTML
+ * precisely to prove the guard is meaningful, so when React restored it the
+ * control's assertions all flipped at once and `fouc-guard` went red for
+ * reasons that had nothing to do with the critical CSS.
+ *
+ * Sampling from an init script closes that window: it runs on
+ * `DOMContentLoaded`, in-page and synchronously, and it reads only the DOM. The
+ * ordering is empirical rather than guaranteed — Remix v1 emits its entry as an
+ * inline `type="module" async` script whose imports must resolve before
+ * `entry.client.tsx` even schedules `requestIdleCallback`/`setTimeout` for
+ * `hydrateRoot`, and WebKit dispatches DOMContentLoaded at end of parse — but
+ * that ordering is what the #126 timings show, with the earliest observed
+ * restoration an order of magnitude later than the sample.
+ *
+ * Note this deliberately survives a *fixed* #126: a control that strips the
+ * inline block guarantees a hydration mismatch by construction, so no repair to
+ * the hydration failure itself could make a post-hydration sample safe here.
+ */
+async function firstPaintState(page: Page): Promise<FirstPaint> {
+  await page.addInitScript((key) => {
+    document.addEventListener(
+      "DOMContentLoaded",
+      () => {
+        const grid = document.querySelector(".simple-center-grid");
+        const sidebar = document.querySelector(".qe-toc");
+        const closeIcon = document.querySelector(".qe-toc-toggle__close");
+        const backToTop = document.querySelector(".qe-back-to-top");
+        const applied = Array.from(document.styleSheets).filter((sheet) => {
+          try {
+            return !!sheet.cssRules && sheet.cssRules.length > 0; // applied, not pending
+          } catch {
+            return false; // cross-origin / not yet loaded
+          }
+        });
+        const sample: FirstPaint = {
+          gridDisplay: grid ? getComputedStyle(grid).display : "(absent)",
+          bodyFont: getComputedStyle(document.body).fontFamily,
+          // A closed popover is `display: none` per the UA stylesheet, so it
+          // paints nothing even with no author CSS at all — hence both tests
+          // below expect it hidden.
+          //
+          // `null` when the element is missing, so a renamed hook fails the
+          // explicit presence guard instead of silently satisfying "not
+          // rendered".
+          sidebarRendered: sidebar ? sidebar.getClientRects().length > 0 : null,
+          // The toggle's close icon is hidden by a critical-CSS rule; without
+          // it both icons paint side by side on the first frame. `null` when
+          // missing, for the same reason as above.
+          toggleCloseRendered: closeIcon ? closeIcon.getClientRects().length > 0 : null,
+          // "Back to top" is hidden by opacity rather than display, and
+          // carries a transition — so if it paints visible here it will *fade*
+          // out once the stylesheet lands. The critical block pins it to 0.
+          // `null` when missing, as above.
+          backToTopOpacity: backToTop ? getComputedStyle(backToTop).opacity : null,
+          // null href == an inline <style>; any string == an external sheet
+          // that applied
+          appliedExternal: applied.some((sheet) => !!sheet.href),
+          // Whether the inline block is present in the document as sampled —
+          // the state the assertions below are actually about.
+          criticalInline: Array.from(document.querySelectorAll("style")).some((el) =>
+            (el.textContent ?? "").includes(":where(.simple-center-grid)"),
+          ),
+        };
+        (window as unknown as Record<string, unknown>)[key] = sample;
+      },
+      { once: true },
+    );
+  }, SAMPLE_KEY);
+
   await page.goto(PAGE, { waitUntil: "domcontentloaded" });
-  await page.waitForSelector(".simple-center-grid", { timeout: 5000 }).catch(() => {});
-  return page.evaluate(() => {
-    const grid = document.querySelector(".simple-center-grid");
-    const sidebar = document.querySelector(".qe-toc");
-    const closeIcon = document.querySelector(".qe-toc-toggle__close");
-    const backToTop = document.querySelector(".qe-back-to-top");
-    const applied = Array.from(document.styleSheets).filter((sheet) => {
-      try {
-        return !!sheet.cssRules && sheet.cssRules.length > 0; // applied, not pending
-      } catch {
-        return false; // cross-origin / not yet loaded
-      }
-    });
-    return {
-      gridDisplay: grid ? getComputedStyle(grid).display : "(absent)",
-      bodyFont: getComputedStyle(document.body).fontFamily,
-      // A closed popover is `display: none` per the UA stylesheet, so it paints
-      // nothing even with no author CSS at all — hence both tests below expect
-      // it hidden.
-      //
-      // `null` when the element is missing, so a renamed hook fails the
-      // explicit presence guard instead of silently satisfying "not rendered".
-      sidebarRendered: sidebar ? sidebar.getClientRects().length > 0 : null,
-      // The toggle's close icon is hidden by a critical-CSS rule; without it
-      // both icons paint side by side on the first frame. `null` when missing,
-      // for the same reason as above.
-      toggleCloseRendered: closeIcon ? closeIcon.getClientRects().length > 0 : null,
-      // "Back to top" is hidden by opacity rather than display, and carries a
-      // transition — so if it paints visible here it will *fade* out once the
-      // stylesheet lands. The critical block pins it to 0. `null` when missing,
-      // as above.
-      backToTopOpacity: backToTop ? getComputedStyle(backToTop).opacity : null,
-      // null href == an inline <style>; any string == an external sheet that applied
-      appliedExternal: applied.some((sheet) => !!sheet.href),
-    };
-  });
+  await page.waitForFunction((key) => !!(window as any)[key], SAMPLE_KEY, { timeout: 5000 });
+  return page.evaluate<FirstPaint, string>((key) => (window as any)[key], SAMPLE_KEY);
 }
 
 test.describe("FOUC guard (WebKit) — inline critical CSS styles the first paint", () => {
@@ -97,6 +167,10 @@ test.describe("FOUC guard (WebKit) — inline critical CSS styles the first pain
 
     // No external sheet applied, so anything styled below comes from inline CSS.
     expect(state.appliedExternal).toBe(false);
+    expect(
+      state.criticalInline,
+      "the inline critical <style> is missing from the page as served — app/root.tsx no longer inlines CRITICAL_CSS"
+    ).toBe(true);
     // The reported FOUC symptoms must be absent on first paint:
     expect(state.gridDisplay).toBe("grid"); // grid not collapsed to block
     // Head of the stack, not just a substring: "Source Sans 3 Variable" (the
@@ -125,9 +199,20 @@ test.describe("FOUC guard (WebKit) — inline critical CSS styles the first pain
   });
 
   test("control: removing the inline critical CSS reproduces the FOUC", async ({ page }) => {
-    await isolateInlineCss(page, { stripCritical: true });
+    const probe = await isolateInlineCss(page, { stripCritical: true });
     const state = await firstPaintState(page);
 
+    // Preconditions first, so a stale strip pattern reports as itself rather
+    // than as a run of confusing assertion failures about the critical CSS.
+    expect(
+      probe.strippedCritical,
+      "the strip pattern matched nothing in the served HTML — CRITICAL_CSS was reshaped and the regex in isolateInlineCss needs updating"
+    ).toBe(true);
+    expect(
+      state.criticalInline,
+      "the inline critical <style> is present despite the strip — it was restored before the sample (see #126)"
+    ).toBe(false);
+
     // With no CSS at all, the page is unstyled — this proves the guard above is
     // meaningful (the external abort really does strip styling).
     expect(state.appliedExternal).toBe(false);