React hydration fails on every page load (#418/#423), which makes the FOUC control test racy

[mmcky]

What happens

Every page load throws two React errors — minified #418 (hydration mismatch) and #423 (error during hydration, recovering with a client render). Reproduced in WebKit against a clean make build-theme, serving the visual fixture.

Why it matters beyond console noise

The #423 recovery re-renders the tree, and app/root.tsx passes the critical CSS as head={<style dangerouslySetInnerHTML={...} />}. So React puts the <style> block back shortly after hydration — including in the FOUC control test, which strips it from the served HTML precisely to prove the guard is meaningful.

Sampling under the control's exact conditions (external stylesheets aborted, inline <style> stripped from the document):

t after DOMContentLoaded	critical <style> tags	.simple-center-grid display	sidebar right
30 ms	0	block	1272 px
138 ms	0	block	1272 px
195 ms	1	grid	0 px

firstPaintState() samples after waitUntil: "domcontentloaded" plus a waitForSelector, so it has roughly a 150 ms budget. On a loaded CI runner it can slip past that, and then all three control assertions flip at once — gridDisplay and bodyFont (both pre-existing) and sidebarOnScreen (added in #123). fouc-guard gates PRs, so this is a latent red-for-no-reason.

Suggested direction

Two things, probably in this order:

1. The hydration failure itself — the root cause, and worth understanding on its own regardless of the test. Running an unminified React build locally will name the mismatching node.
2. Make the control insensitive to it — sample at first paint via an init script rather than after domcontentloaded, or bail early with a clear message if the critical <style> reappears, so a slow runner reports the real reason instead of three confusing assertion failures.

Turned up while reviewing #123. Not introduced there — main carries the same exposure through its own two control assertions, which fail first.

[mmcky]

Step 2 is in #141; step 1 — the hydration failure itself — is still open here. Flagging the split explicitly, since GitHub now shows a linked PR on this issue and that PR deliberately does not close it.

What #141 does: moves the measurement into an init script that samples in-page on DOMContentLoaded, before hydration is scheduled, so the restored <style> can no longer flip the control's assertions. Both cases also assert their own preconditions now — that the strip actually matched something, and whether the inline block is present as sampled — so a reshaped CRITICAL_CSS reports as a stale strip pattern rather than as three confusing failures about grid layout.

Two things worth recording for whoever picks up step 1:

The init-script approach was chosen over the "bail early" option because it survives a fix to this issue rather than depending on one. The control strips the inline block from the served HTML, which guarantees a hydration mismatch by construction — so no repair to the React #418/#423 failure could ever make a post-hydration sample safe in that test. The hardening and the root cause are genuinely independent.

The ordering that makes the sample safe is empirical, not guaranteed: Remix v1 emits its entry as an inline type="module" async script whose imports must all resolve before entry.client.tsx even schedules requestIdleCallback/setTimeout for hydrateRoot, and WebKit dispatches DOMContentLoaded at end of parse. The earliest restoration measured in this issue is roughly an order of magnitude later than the sample point, so there is comfortable margin — but it is margin, not a spec guarantee, and a future Remix or React Router change could narrow it.

Verified the guard still guards after the change: removing the grid rule from CRITICAL_CSS fails the main test with Expected: "grid" / Received: "block" while the control still passes. So the test is desensitised to hydration without being desensitised to regressions.

[mmcky]

Two things measured while reviewing #141 against current main (post-#144) that raise the stakes on step 1.

Still failing on every load. Both #418 and #423 fire on each navigation in WebKit against a make build-theme bundle of main served via myst start; under the control's conditions the stripped critical <style> comes back 150–240ms after DOMContentLoaded. Step 2 (desensitising the control) is now in #169, ported onto the post-#144 probes.

The recovery re-render is also what produces the "first-paint" animations. With app.css delayed by 400ms and per-frame sampling from an init script, the first painted frame was already styled: WebKit blocked first paint on the head stylesheets, so there was no pre-app.css initial frame. What did appear was a ~450ms unstyled window starting about 200ms after DOMContentLoaded, in which document.styleSheets no longer contained app.css and the <link> had been re-requested. That lines up with the #423 recovery discarding the server tree and re-rendering <Links />; on localhost the sheet re-attaches from cache within a frame, so it is invisible, but on a slower host the window is real. When the sheet re-applies, anything hidden by an opacity utility and carrying a transition fades out on screen. That is the fade #127 and #141 attributed to initial paint. Because it happens after mount, gating transitions on useMounted does nothing for it; the critical-CSS rules (#144's close icon, #168's back-to-top) work because the inline <style> is restored with the tree.

So beyond the test race, a fixed hydration would remove the stylesheet gap and the whole class of transition-on-correction bugs at the source, and would let the critical-CSS rules go back to guarding only the true first paint. Root-causing the mismatch remains the real work here.

[mmcky]

Step 1 result, 2026-09-07: hydration does not fail on a normal page load

Ran the diagnostic this issue asked for, against v2.5.0 (6d773b63c), and the premise did not hold. React hydrates cleanly on every fixture page, in myst start and in a static myst build --html, with the production bundle and with a development-mode bundle. The #418/#423 pair fires only under the FOUC test's control case, which strips the inline critical <style> from the served document — a server/client mismatch by construction, as the spec's own comment says.

What was measured

Production bundle from make build-theme, served to Playwright WebKit with the Desktop Safari device, capturing every console message and page error, 4 s after load:

Serving	Page	Condition	Hydration errors
myst start	/, /features, /lists, /notebook	normal	0
myst start	/	external stylesheets aborted (the main FOUC case)	0
myst start	/	app.css delayed 400 ms	0
myst start	/	stylesheets aborted and inline critical <style> stripped (the control)	#418 ×2, #423; inline <style> restored; stylesheet requests doubled from 10 to 20
static myst build --html	/, /notebook/	normal	0
static myst build --html	/	app.css delayed 400 ms	0

Chromium on the production bundle, normal load: 0. A development-mode bundle (NODE_ENV=development npx remix build, so React's full warnings are present) on WebKit and Chromium, normal load: 0 hydration warnings of any kind.

A tag-level diff of the DOM as parsed at DOMContentLoaded against the DOM 4 s later, on a normal production load, shows exactly two changes: the scripts React and Remix inject, and the "On this page" outline, which is a client-only render after mount and not a recovery. Nothing in <head> moves.

What this changes

• "Every page load throws #418/#423" was the control case, not the page. The table in the body was sampled "under the control's exact conditions", and those conditions guarantee the mismatch. On an unmodified document there is none.
• The doubled stylesheet requests and the "stylesheet gap" are the same artefact. In the strip condition every <link> is re-requested (10 → 20 requests), which is the <Links /> re-render the 2026-09-05 comment describes. Under a 400 ms delay of app.css with the document intact, nothing is re-requested and nothing re-renders, in both myst start and the static build. So there is no recovery-driven unstyled window on a slow host.
• The critical-CSS rules (refactor: rebuild the contents drawer on the Popover API #144, fix: pin "back to top" to opacity 0 in the critical CSS #168) stand on their original ground: WebKit paints the document before external stylesheets apply (FOUC: brief flash of unstyled / raw HTML on every page navigation #66), so anything hidden only by an external rule paints on that first frame. That is a first-paint problem, not a hydration one, and the fix is the right one for it.
• Step 2 (test(fouc): sample first paint from an init script, assert control preconditions #169) was still worth doing: the control strips the inline block, so its measurement has to be taken before hydration regardless.

Suggested disposition

Nothing here is production work. I would close this as not a defect: the hydration failure exists only inside the FOUC control, where it is intended, and the first-paint fades have a different cause that is already handled. #147's "Not in scope" entry attributes the root cause to Remix v1 and #28; that attribution can be dropped too, since there is no root cause to migrate away from.

Reproduction, for whoever wants to re-run it: make build-theme, then THEME_TEMPLATE=$PWD/.deploy/quantecon-theme PORT=3111 bash tests/visual/serve.sh, and a Playwright script that routes **/*, optionally aborting stylesheets and/or rewriting the document to strip the :where(.simple-center-grid) <style>, while listening on console and pageerror for #418/#423.

[mmcky]

Closing as not a defect, per the 2026-09-07 measurement above: hydration is clean on every fixture page in myst start and static builds, and the #418/#423 pair fires only inside the FOUC control, where the stripped inline style makes the mismatch by construction. The critical-CSS rules from #144 and #168 stand on their first-paint ground (#66). #147's Not in scope entry attributing a root cause to Remix v1 and #28 should be dropped at its next resume. Reopen if #418/#423 is ever observed on an unmodified page load.