From 999a7dd1f2913ea04e4f18f3557e8363edef45a8 Mon Sep 17 00:00:00 2001
From: Varun Chawla <34209028+veeceey@users.noreply.github.com>
Date: Sun, 22 Feb 2026 00:57:37 -0800
Subject: [PATCH] fix: preserve inline styles and font preloads during
 ClientRouter head swap (#15514)

* fix: preserve inline styles and font preloads during ClientRouter head swap

During client-side navigation with ClientRouter, swapHeadElements() only
preserved elements with data-astro-transition-persist and stylesheet links.
Inline <style> tags (including @font-face declarations from <Font>) were
removed and re-appended on every navigation, forcing the browser to
re-evaluate them and triggering a visible font flash (FOUT).

This extends persistedHeadElement() to also match:
- Inline <style> elements by their text content
- Font preload links (link[rel=preload][as=font]) by href

When an identical element exists in both the old and new document head,
it stays in the DOM instead of being removed and re-inserted.

Fixes #15465

* add changeset

* Add e2e test for inline style and font preload persistence

Add a test that verifies inline <style> elements (e.g. @font-face
declarations) and font preload links survive head swaps during
client-side navigation, preventing FOUT (Flash of Unstyled Text).

The test navigates between two pages sharing identical inline styles
and font preloads, and asserts that the original DOM nodes persist
rather than being removed and re-inserted.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: resolve lint errors and flaky e2e test for font persistence

Remove unused variables (styleIdBefore, preloadIdBefore) to fix biome
lint errors. Replace fragile exact style count comparison with
greaterThan(0) checks, since Astro may inject additional style elements
during client-side navigation. Use data-attribute selectors to directly
query the marked DOM nodes instead of relying on querySelector order.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Make the test a bit more concise

* Update fix-font-head-swap.md

---------

Co-authored-by: Martin Trapp <94928215+martrapp@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 .changeset/fix-font-head-swap.md              |  7 ++++++
 .../src/pages/font-page-one.astro             | 22 +++++++++++++++++++
 .../src/pages/font-page-two.astro             | 22 +++++++++++++++++++
 packages/astro/e2e/view-transitions.test.js   | 16 ++++++++++++++
 .../astro/src/transitions/swap-functions.ts   | 17 ++++++++++++++
 5 files changed, 84 insertions(+)
 create mode 100644 .changeset/fix-font-head-swap.md
 create mode 100644 packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-one.astro
 create mode 100644 packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-two.astro
diff --git a/.changeset/fix-font-head-swap.md b/.changeset/fix-font-head-swap.md
new file mode 100644
index 000000000000..951845eee525
--- /dev/null
+++ b/.changeset/fix-font-head-swap.md
@@ -0,0 +1,7 @@
+---
+'astro': patch
+---
+
+Fixes font flash (FOUT) during ClientRouter navigation by preserving inline `<style>` elements and font preload links in the head during page transitions.
+
+Previously, `@font-face` declarations from the `<Font>` component were removed and re-inserted on every client-side navigation, causing the browser to re-evaluate them.
diff --git a/packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-one.astro b/packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-one.astro
new file mode 100644
index 000000000000..6b2a0dd67ef8
--- /dev/null
+++ b/packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-one.astro
@@ -0,0 +1,22 @@
+---
+import { ClientRouter } from 'astro:transitions';
+---
+<html>
+	<head>
+		<title>Font Page 1</title>
+		<style is:inline id="style">
+			@font-face {
+				font-family: 'TestFont';
+				src: url('/fonts/test.woff2') format('woff2');
+				font-display: swap;
+			}
+			body { font-family: 'TestFont', sans-serif; }
+		</style>
+		<link id="preload" rel="preload" href="/fonts/test.woff2" as="font" type="font/woff2" crossorigin />
+		<ClientRouter />
+	</head>
+	<body>
+		<p id="font-page-one">Font Page 1</p>
+		<a id="click-font-two" href="/font-page-two">go to font page 2</a>
+	</body>
+</html>
diff --git a/packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-two.astro b/packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-two.astro
new file mode 100644
index 000000000000..647b62df149e
--- /dev/null
+++ b/packages/astro/e2e/fixtures/view-transitions/src/pages/font-page-two.astro
@@ -0,0 +1,22 @@
+---
+import { ClientRouter } from 'astro:transitions';
+---
+<html>
+	<head>
+		<title>Font Page 2</title>
+		<style is:inline>
+			@font-face {
+				font-family: 'TestFont';
+				src: url('/fonts/test.woff2') format('woff2');
+				font-display: swap;
+			}
+			body { font-family: 'TestFont', sans-serif; }
+		</style>
+		<link rel="preload" href="/fonts/test.woff2" as="font" type="font/woff2" crossorigin />
+		<ClientRouter />
+	</head>
+	<body>
+		<p id="font-page-two">Font Page 2</p>
+		<a id="click-font-one" href="/font-page-one">go to font page 1</a>
+	</body>
+</html>
diff --git a/packages/astro/e2e/view-transitions.test.js b/packages/astro/e2e/view-transitions.test.js
index 591e8ef584c0..4085d3ffd6c9 100644
--- a/packages/astro/e2e/view-transitions.test.js
+++ b/packages/astro/e2e/view-transitions.test.js
@@ -1759,4 +1759,20 @@ test.describe('View Transitions', () => {
 		await new Promise((resolve) => setTimeout(resolve, 1000));
 		expect(lines.join('')).toBe('');
 	});
+
+	test('Inline styles and font preloads persist through head swap', async ({ page, astro }) => {
+		// Go to font page 1
+		await page.goto(astro.resolveUrl('/font-page-one'));
+		let p = page.locator('#font-page-one');
+		await expect(p, 'should have content').toHaveText('Font Page 1');
+
+		// Navigate to font page 2 (same inline styles and font preloads)
+		await page.click('#click-font-two');
+		p = page.locator('#font-page-two');
+		await expect(p, 'should have content').toHaveText('Font Page 2');
+
+		// Verify original inline styles and font preloads are still present after navigation
+		await expect(page.locator('#style')).toHaveCount(1);
+		await expect(page.locator('#preload')).toHaveCount(1);
+	});
 });
diff --git a/packages/astro/src/transitions/swap-functions.ts b/packages/astro/src/transitions/swap-functions.ts
index 03bf45c68d16..9fb7e505118f 100644
--- a/packages/astro/src/transitions/swap-functions.ts
+++ b/packages/astro/src/transitions/swap-functions.ts
@@ -161,6 +161,23 @@ const persistedHeadElement = (el: HTMLElement, newDoc: Document): Element | null
 		const href = el.getAttribute('href');
 		return newDoc.head.querySelector(`link[rel=stylesheet][href="${href}"]`);
 	}
+	// Preserve inline <style> elements with identical content across navigations.
+	// This prevents unnecessary removal and re-insertion of styles (e.g. @font-face
+	// declarations from <Font>), which would cause the browser to re-evaluate them
+	// and trigger a flash of unstyled text (FOUT).
+	if (el.tagName === 'STYLE' && el.textContent) {
+		const styles = newDoc.head.querySelectorAll('style');
+		for (const s of styles) {
+			if (s.textContent === el.textContent) {
+				return s;
+			}
+		}
+	}
+	// Preserve font preload links across navigations to avoid re-fetching cached fonts.
+	if (el.matches('link[rel=preload][as=font]')) {
+		const href = el.getAttribute('href');
+		return newDoc.head.querySelector(`link[rel=preload][as=font][href="${href}"]`);
+	}
 	return null;
 };
 
