From 1f0851518bbd6806c3db3472f9a81dfd69945089 Mon Sep 17 00:00:00 2001
From: devin distefano <devin.distefano@smartcontract.com>
Date: Mon, 5 Oct 2026 13:29:28 -0500
Subject: [PATCH 1/2] transitons + dev server improvements

---
 astro.config.ts                               | 12 ++++++++
 patches/astro+5.18.2.patch                    | 21 +++++++++++++
 .../CRETemplate/CRETemplateOverview.astro     |  2 +-
 .../CRETemplate/CRETemplatePanel.astro        |  2 +-
 .../CcipVersionToggle/CcipVersionGuard.astro  |  2 +-
 .../ChangelogSnippet/ChangelogCard.astro      |  2 +-
 .../CodeHighlightBlock.astro                  |  2 +-
 .../CodeHighlightBlockMulti.astro             |  2 +-
 src/components/HeadCommon.astro               |  4 +--
 src/components/Header/Header.astro            |  2 +-
 src/components/PageTabs.astro                 |  2 +-
 src/layouts/BaseLayout.astro                  | 30 ++++++++++++++++++-
 src/pages/certification.astro                 |  2 +-
 src/pages/cre-templates/index.astro           |  2 +-
 src/pages/cre/[...id].astro                   |  2 ++
 .../copyToClipboard/copyToClipboard.ts        |  4 +--
 src/scripts/fix-external-links.ts             |  2 +-
 src/scripts/fix-remix-urls.ts                 |  2 +-
 src/scripts/scroll-to-search.ts               |  2 +-
 tailwind.config.js                            | 13 +++++++-
 20 files changed, 93 insertions(+), 19 deletions(-)
 create mode 100644 patches/astro+5.18.2.patch

diff --git a/astro.config.ts b/astro.config.ts
index a9944ea59a8..361e9934eae 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -43,6 +43,18 @@ const canonicalUrlsWithLanguageVariants = extractCanonicalUrlsWithLanguageVarian
 export default defineConfig({
   site: "https://docs.chain.link",
   trailingSlash: "never",
+  // Prefetch internal links so client-side navigations (ClientRouter) feel instant.
+  // "hover" (not "viewport") avoids prefetching the hundreds of links in the docs sidebar at once.
+  //
+  // NOTE (Astro 5 -> 7 upgrade): `prefetch` and `<ClientRouter />` are stable in Astro 5 and remain
+  // the supported API in Astro 6/7, so this config carries over unchanged. The one thing to revisit
+  // is `patches/astro+5.18.2.patch` (dev-server module-graph perf fix): it is pinned to 5.18.2 and
+  // will fail to apply after the upgrade. Check whether the upstream fix has landed by then; if not,
+  // regenerate the patch against the new version with `npx patch-package astro`.
+  prefetch: {
+    prefetchAll: true,
+    defaultStrategy: "hover",
+  },
   redirects: {
     "/ccip/directory": "/ccip/directory/mainnet",
     "/ccip/supported-networks": "/ccip/directory/mainnet",
diff --git a/patches/astro+5.18.2.patch b/patches/astro+5.18.2.patch
new file mode 100644
index 00000000000..2326c547f7f
--- /dev/null
+++ b/patches/astro+5.18.2.patch
@@ -0,0 +1,21 @@
+diff --git a/node_modules/astro/dist/vite-plugin-astro-server/vite.js b/node_modules/astro/dist/vite-plugin-astro-server/vite.js
+index 81bb5cf..e2f060c 100644
+--- a/node_modules/astro/dist/vite-plugin-astro-server/vite.js
++++ b/node_modules/astro/dist/vite-plugin-astro-server/vite.js
+@@ -60,6 +60,16 @@ async function* crawlGraph(loader, _id, isRootFile, scanned = /* @__PURE__ */ ne
+   }
+ }
+ function isImportedBy(parent, entry) {
++  // Vite 6's backward-compatible ModuleNode rebuilds a union Set (and looks up a compat
++  // node for every importer) each time `importers` is read. With ~3.7k icons importing
++  // one module that is ~27M iterations per request. Read the per-environment Sets directly.
++  const client = entry._clientModule;
++  const ssr = entry._ssrModule;
++  if (client || ssr) {
++    if (client) for (const importer of client.importers) if (importer.id === parent) return true;
++    if (ssr) for (const importer of ssr.importers) if (importer.id === parent) return true;
++    return false;
++  }
+   for (const importer of entry.importers) {
+     if (importer.id === parent) {
+       return true;
diff --git a/src/components/CRETemplate/CRETemplateOverview.astro b/src/components/CRETemplate/CRETemplateOverview.astro
index cd4f5a7db78..a408b5268c2 100644
--- a/src/components/CRETemplate/CRETemplateOverview.astro
+++ b/src/components/CRETemplate/CRETemplateOverview.astro
@@ -80,7 +80,7 @@ const { frontmatter } = Astro.props
 </div>
 
 <script>
-  document.addEventListener("DOMContentLoaded", () => {
+  document.addEventListener("astro:page-load", () => {
     const cliCommand = document.getElementById("cli-command")
     const cliCopyBtn = document.getElementById("cli-copy-btn") as HTMLButtonElement | null
     const togglePills = document.querySelectorAll<HTMLButtonElement>(".lang-toggle-pill")
diff --git a/src/components/CRETemplate/CRETemplatePanel.astro b/src/components/CRETemplate/CRETemplatePanel.astro
index 0c8d8d65ec4..5aa069270a9 100644
--- a/src/components/CRETemplate/CRETemplatePanel.astro
+++ b/src/components/CRETemplate/CRETemplatePanel.astro
@@ -98,7 +98,7 @@ const { frontmatter, headings } = Astro.props
 </div>
 
 <script>
-  document.addEventListener("DOMContentLoaded", () => {
+  document.addEventListener("astro:page-load", () => {
     // Copy button functionality
     const copyBtns = document.querySelectorAll<HTMLButtonElement>(".cli-copy-btn")
     copyBtns.forEach((btn) => {
diff --git a/src/components/CcipVersionToggle/CcipVersionGuard.astro b/src/components/CcipVersionToggle/CcipVersionGuard.astro
index 98aeceac778..da6392aeb4e 100644
--- a/src/components/CcipVersionToggle/CcipVersionGuard.astro
+++ b/src/components/CcipVersionToggle/CcipVersionGuard.astro
@@ -21,7 +21,7 @@ interface Props {
 const { redirects } = Astro.props
 ---
 
-<script is:inline define:vars={{ redirects, storageKey: CHAIN_TYPE_STORAGE_KEY }}>
+<script is:inline data-astro-rerun define:vars={{ redirects, storageKey: CHAIN_TYPE_STORAGE_KEY }}>
   try {
     // Read the raw value exactly like initializeChainType() so both agree on the chain family.
     // typeof check: inherited keys ("toString", "__proto__") are never string targets.
diff --git a/src/components/ChangelogSnippet/ChangelogCard.astro b/src/components/ChangelogSnippet/ChangelogCard.astro
index 3ac9a16021b..219f854a93e 100644
--- a/src/components/ChangelogSnippet/ChangelogCard.astro
+++ b/src/components/ChangelogSnippet/ChangelogCard.astro
@@ -229,7 +229,7 @@ const formattedDate = formatDate(item["date-of-release"])
     })
   }
 
-  document.addEventListener("DOMContentLoaded", () => {
+  document.addEventListener("astro:page-load", () => {
     swapDataAttributeImages()
     initExpandableCards()
   })
diff --git a/src/components/CodeHighlightBlock/CodeHighlightBlock.astro b/src/components/CodeHighlightBlock/CodeHighlightBlock.astro
index 8eb7332ce8e..3f76d49c98e 100644
--- a/src/components/CodeHighlightBlock/CodeHighlightBlock.astro
+++ b/src/components/CodeHighlightBlock/CodeHighlightBlock.astro
@@ -348,7 +348,7 @@ const languageDisplay = getLanguageDisplayName(lang)
     blockId,
   }}
 >
-  document.addEventListener("DOMContentLoaded", () => {
+  document.addEventListener("astro:page-load", () => {
     // Only process THIS specific container to avoid contamination
     const container = document.getElementById(blockId)
     if (!container) return
diff --git a/src/components/CodeHighlightBlockMulti/CodeHighlightBlockMulti.astro b/src/components/CodeHighlightBlockMulti/CodeHighlightBlockMulti.astro
index cbd3df0330f..e292838a738 100644
--- a/src/components/CodeHighlightBlockMulti/CodeHighlightBlockMulti.astro
+++ b/src/components/CodeHighlightBlockMulti/CodeHighlightBlockMulti.astro
@@ -448,7 +448,7 @@ const languageDisplay = getLanguageDisplayName(currentLang)
   // Check every 200ms for language changes (lightweight)
   setInterval(syncCheck, 200)
 
-  document.addEventListener("DOMContentLoaded", () => {
+  document.addEventListener("astro:page-load", () => {
     // Only process THIS specific container to avoid contamination
     const container = document.getElementById(blockId)
     if (!container) return
diff --git a/src/components/HeadCommon.astro b/src/components/HeadCommon.astro
index b614ecf27f0..451fb914a36 100644
--- a/src/components/HeadCommon.astro
+++ b/src/components/HeadCommon.astro
@@ -73,7 +73,7 @@ const ccipChainVersionRedirects = getCcipChainVersionRedirects(Astro.url.pathnam
 <link rel="preconnect" href="https://www.google-analytics.com" crossorigin />
 
 <!-- Set CRE SDK Language in dataLayer -->
-<script is:inline type="text/javascript">
+<script is:inline data-astro-rerun type="text/javascript">
   ;(function () {
     var path = window.location.pathname
     if (!(path === "/cre" || path.startsWith("/cre/"))) return
@@ -93,7 +93,7 @@ const ccipChainVersionRedirects = getCcipChainVersionRedirects(Astro.url.pathnam
 </script>
 
 <!-- Set CCIP Chain Family in dataLayer -->
-<script is:inline type="text/javascript">
+<script is:inline data-astro-rerun type="text/javascript">
   ;(function () {
     if (!window.location.pathname.startsWith("/ccip")) return
 
diff --git a/src/components/Header/Header.astro b/src/components/Header/Header.astro
index 3f26a84b220..cd58994850f 100644
--- a/src/components/Header/Header.astro
+++ b/src/components/Header/Header.astro
@@ -26,7 +26,7 @@ const pageSdkLangData = Object.fromEntries(pageSdkLangMap)
 ---
 
 <!-- Expose SDK lang data to client-side for mobile navigation -->
-<script is:inline define:vars={{ pageSdkLangData }}>
+<script is:inline data-astro-rerun define:vars={{ pageSdkLangData }}>
   // Make CRE SDK language metadata available globally for navigation filtering
   window.__PAGE_SDK_LANG_MAP__ = pageSdkLangData
 </script>
diff --git a/src/components/PageTabs.astro b/src/components/PageTabs.astro
index 12ff4ad2696..3bb224b02d6 100644
--- a/src/components/PageTabs.astro
+++ b/src/components/PageTabs.astro
@@ -466,7 +466,7 @@ const displayPage = hasActivePage ? (Array.isArray(currentPageGroup) ? currentPa
     })
   }
 
-  window.addEventListener("load", initDropdown)
+  document.addEventListener("astro:page-load", initDropdown)
 
   // Update padding based on header visibility
   const section = document.querySelector(".tabs-section") as HTMLElement
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index 4974f73342e..b0b76034b93 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -1,4 +1,5 @@
 ---
+import { ClientRouter } from "astro:transitions"
 import HeadCommon from "~/components/HeadCommon.astro"
 import HeadSEO from "~/components/HeadSEO.astro"
 import StructuredData from "~/components/StructuredData.astro"
@@ -27,6 +28,7 @@ const canonicalURL = new URL(canonicalURLStr)
 
 <html dir="ltr" lang="en-us" class="initial" transition:animate="none">
   <head>
+    <ClientRouter />
     <HeadCommon {title} />
     <HeadSEO
       metadata={metadata}
@@ -48,7 +50,7 @@ const canonicalURL = new URL(canonicalURLStr)
         scroll-behavior: smooth;
       }
     </style>
-    <script is:inline>
+    <script is:inline data-astro-rerun>
       try {
         const savedLang = localStorage.getItem("docs-language-preference")
         if (savedLang === "ts") {
@@ -64,6 +66,32 @@ const canonicalURL = new URL(canonicalURLStr)
     </script>
     <slot name="head" />
     <slot name="head-scripts" />
+    <script is:inline data-astro-rerun>
+      // Safety net for Radix scroll locks (mobile nav dialog, etc.).
+      //
+      // Radix sets `pointer-events: none` + `data-scroll-locked` on <body> while a dialog is open
+      // and removes them on close. With Astro's ClientRouter, navigating from a link inside the
+      // dialog unmounts it without running that cleanup, so the lock is left behind and the whole
+      // page becomes non-interactive. Clear any stale lock after each navigation.
+      ;(function () {
+        if (window.__docsScrollLockGuard) return
+        window.__docsScrollLockGuard = true
+
+        function clearStaleScrollLock() {
+          var body = document.body
+          if (!body) return
+          if (body.hasAttribute("data-scroll-locked")) {
+            body.removeAttribute("data-scroll-locked")
+            body.style.removeProperty("pointer-events")
+            body.style.removeProperty("overflow")
+            body.style.removeProperty("padding-right")
+          }
+        }
+
+        document.addEventListener("astro:after-swap", clearStaleScrollLock)
+        document.addEventListener("astro:page-load", clearStaleScrollLock)
+      })()
+    </script>
   </head>
   <body>
     <Header />
diff --git a/src/pages/certification.astro b/src/pages/certification.astro
index dee853fb942..bc53e42e530 100644
--- a/src/pages/certification.astro
+++ b/src/pages/certification.astro
@@ -835,7 +835,7 @@ const formattedContentTitle = `Courses | Chainlink Certifications`
 
 <script>
   // Accordion functionality
-  document.addEventListener("DOMContentLoaded", function () {
+  document.addEventListener("astro:page-load", function () {
     var popularResCols = document.querySelectorAll(".acad-acc-item")
     popularResCols.forEach(function (popularResCol) {
       popularResCol.addEventListener("click", function () {
diff --git a/src/pages/cre-templates/index.astro b/src/pages/cre-templates/index.astro
index 953a0b03db6..1f20e99afca 100644
--- a/src/pages/cre-templates/index.astro
+++ b/src/pages/cre-templates/index.astro
@@ -605,7 +605,7 @@ const pageDescription =
 </style>
 
 <script>
-  document.addEventListener("DOMContentLoaded", () => {
+  document.addEventListener("astro:page-load", () => {
     const sectionHeader = document.getElementById("section-header")
     const floatingFilter = document.getElementById("floating-filter")
     const filterPills = document.querySelectorAll<HTMLButtonElement>(".filter-pill")
diff --git a/src/pages/cre/[...id].astro b/src/pages/cre/[...id].astro
index 1da90ed4acb..4744e75750d 100644
--- a/src/pages/cre/[...id].astro
+++ b/src/pages/cre/[...id].astro
@@ -129,6 +129,7 @@ if (isCanonical) {
     isCanonical && (
       <script
         is:inline
+        data-astro-rerun
         slot="head-scripts"
         define:vars={{
           goUrl: `/cre/${goEntry!.id}`,
@@ -157,6 +158,7 @@ if (isCanonical) {
     !isCanonical && goEntry && tsEntry && (
       <script
         is:inline
+        data-astro-rerun
         slot="head-scripts"
         define:vars={{ currentLang: entry!.data.sdkLang }}
         set:html={`(function(){
diff --git a/src/scripts/copyToClipboard/copyToClipboard.ts b/src/scripts/copyToClipboard/copyToClipboard.ts
index 6a640eae21c..cd39defa7ab 100644
--- a/src/scripts/copyToClipboard/copyToClipboard.ts
+++ b/src/scripts/copyToClipboard/copyToClipboard.ts
@@ -34,8 +34,8 @@ function initializeClipboard() {
   })
 }
 
-// Initialize clipboard when the DOM is loaded
-document.addEventListener("DOMContentLoaded", () => {
+// Initialize clipboard on first load and after every client-side navigation
+document.addEventListener("astro:page-load", () => {
   initializeClipboard()
 
   // Function to initialize copy buttons within code blocks dynamically
diff --git a/src/scripts/fix-external-links.ts b/src/scripts/fix-external-links.ts
index 801840261cb..ba4bbdbe8ff 100644
--- a/src/scripts/fix-external-links.ts
+++ b/src/scripts/fix-external-links.ts
@@ -1,4 +1,4 @@
-document.addEventListener("DOMContentLoaded", () => {
+document.addEventListener("astro:page-load", () => {
   const links = document.links
   for (let i = 0, linksLength = links.length; i < linksLength; i++) {
     if (!links[i].href.startsWith("javascript:") && ![window.location.hostname].includes(links[i].hostname)) {
diff --git a/src/scripts/fix-remix-urls.ts b/src/scripts/fix-remix-urls.ts
index 8c6745f98b1..d81615ca53d 100644
--- a/src/scripts/fix-remix-urls.ts
+++ b/src/scripts/fix-remix-urls.ts
@@ -1,5 +1,5 @@
 /** Fixes deployment URLs when on a preview URL */
-document.addEventListener("DOMContentLoaded", () => {
+document.addEventListener("astro:page-load", () => {
   const currentHost = window.location.hostname
   if (currentHost !== "docs.chain.link") {
     // Rewrite Remix URLs with current hostname
diff --git a/src/scripts/scroll-to-search.ts b/src/scripts/scroll-to-search.ts
index 35a0f4dbd66..0715be177fe 100644
--- a/src/scripts/scroll-to-search.ts
+++ b/src/scripts/scroll-to-search.ts
@@ -1,5 +1,5 @@
 export {}
-window.addEventListener("load", () => {
+document.addEventListener("astro:page-load", () => {
   const url = `${window.location.href}`
   const searchRegex = /search.*?(?==)/
   const searchElementId = url.match(searchRegex)
diff --git a/tailwind.config.js b/tailwind.config.js
index 3dc5b2f5d48..c7467cf5671 100644
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -1,4 +1,15 @@
 import baseConfig from "@chainlink/blocks/src/theme/base"
 /** @type {import('tailwindcss').Config} */
 
-export default baseConfig
+export default {
+  ...baseConfig,
+  // Skip MDX pages (src/content) and blocks' ~3,700 icon files: neither adds a class, but they were ~80% of
+  // Tailwind's cold start, and watching the MDX rebuilt the CSS on every save. Keep `!(content)` a positive
+  // glob (Tailwind ignores negations when choosing files to watch), and keep Tailwind classes out of MDX.
+  content: [
+    "./src/!(content)/**/*.{html,js,jsx,md,mdx,ts,tsx}",
+    "./src/*.{html,js,jsx,md,mdx,ts,tsx}",
+    "node_modules/@chainlink/blocks/**/*.{ts,tsx}",
+    "!node_modules/@chainlink/blocks/src/icons/library/**",
+  ],
+}

From 4b630a695073e657ed8e6efa3252f3054edbd7ce Mon Sep 17 00:00:00 2001
From: devin distefano <devin.distefano@smartcontract.com>
Date: Mon, 5 Oct 2026 14:44:18 -0500
Subject: [PATCH 2/2] progress bar

---
 src/components/NavigationProgress.astro | 94 +++++++++++++++++++++++++
 src/layouts/BaseLayout.astro            | 43 +++++++++++
 src/pages/cre/[...id].astro             | 15 ++++
 vercel.json                             |  9 +++
 4 files changed, 161 insertions(+)
 create mode 100644 src/components/NavigationProgress.astro

diff --git a/src/components/NavigationProgress.astro b/src/components/NavigationProgress.astro
new file mode 100644
index 00000000000..fc86a5d67c9
--- /dev/null
+++ b/src/components/NavigationProgress.astro
@@ -0,0 +1,94 @@
+---
+/**
+ * Top-of-page progress bar for client-side navigation.
+ *
+ * With <ClientRouter /> there is no browser loading indicator, so a slow navigation looks like a
+ * dead click. This restores that feedback: the bar appears when a navigation starts and completes
+ * when the new page is swapped in.
+ *
+ * `transition:persist` keeps the element across swaps, so the script's element references stay
+ * valid and the bar never restarts mid-navigation.
+ */
+---
+
+<div id="nav-progress" transition:persist aria-hidden="true">
+  <div id="nav-progress-bar"></div>
+</div>
+
+<style>
+  #nav-progress {
+    position: fixed;
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 3px;
+    z-index: 9999;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 200ms ease;
+  }
+
+  #nav-progress[data-active] {
+    opacity: 1;
+  }
+
+  #nav-progress-bar {
+    height: 100%;
+    width: 0;
+    background: var(--brand, #375bd2);
+    box-shadow: 0 0 8px var(--brand, #375bd2);
+    transition: width 200ms ease;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    #nav-progress,
+    #nav-progress-bar {
+      transition: none;
+    }
+  }
+</style>
+
+<script>
+  const wrap = document.getElementById("nav-progress")
+  const bar = document.getElementById("nav-progress-bar")
+
+  // If the navigation never completes (cancelled, or the router bailed), stop showing the bar.
+  const SAFETY_TIMEOUT_MS = 8000
+
+  let hideTimer: ReturnType<typeof setTimeout> | undefined
+  let safetyTimer: ReturnType<typeof setTimeout> | undefined
+
+  function start() {
+    if (!wrap || !bar) return
+    clearTimeout(hideTimer)
+    clearTimeout(safetyTimer)
+
+    wrap.setAttribute("data-active", "")
+
+    // Reset to 0 without animating, force a reflow, then ease toward 90%. The bar never reaches
+    // 100% until the page is actually swapped, so it reads as "still working" rather than "done".
+    // The reflow is what makes the 0 -> 90% change animate; do not replace it with
+    // requestAnimationFrame, which is throttled in background tabs and would leave the bar at 0.
+    bar.style.transition = "none"
+    bar.style.width = "0"
+    void bar.offsetWidth
+    bar.style.transition = ""
+    bar.style.width = "90%"
+
+    safetyTimer = setTimeout(finish, SAFETY_TIMEOUT_MS)
+  }
+
+  function finish() {
+    if (!wrap || !bar) return
+    clearTimeout(safetyTimer)
+
+    bar.style.width = "100%"
+    hideTimer = setTimeout(() => {
+      wrap.removeAttribute("data-active")
+      bar.style.width = "0"
+    }, 200)
+  }
+
+  document.addEventListener("astro:before-preparation", start)
+  document.addEventListener("astro:after-swap", finish)
+</script>
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
index b0b76034b93..e2094bdb58c 100644
--- a/src/layouts/BaseLayout.astro
+++ b/src/layouts/BaseLayout.astro
@@ -4,6 +4,7 @@ import HeadCommon from "~/components/HeadCommon.astro"
 import HeadSEO from "~/components/HeadSEO.astro"
 import StructuredData from "~/components/StructuredData.astro"
 import Header from "~/components/Header/Header.astro"
+import NavigationProgress from "~/components/NavigationProgress.astro"
 import { NewsletterCTA } from "~/components/Footer/NewsletterCTA"
 import Footer from "~/components/Footer/Footer.astro"
 import { Metadata, QuickstartsFrontmatter } from "~/content.config.ts"
@@ -66,6 +67,47 @@ const canonicalURL = new URL(canonicalURLStr)
     </script>
     <slot name="head" />
     <slot name="head-scripts" />
+    <script is:inline data-astro-rerun>
+      // Cancel client-side routing to canonical CRE pages.
+      //
+      // A canonical CRE page (e.g. /cre/foo) renders an empty body and redirects to the
+      // language-specific URL (/cre/foo-go or /cre/foo-ts). Under ClientRouter the router would
+      // swap in that empty body and only then run the redirect, flashing a blank page. Detect the
+      // marker the page emits during preparation and cancel, so the redirect happens before paint.
+      //
+      // `astro:before-swap` is not cancelable, so this hooks `astro:before-preparation` and wraps
+      // its loader: the loader has already parsed the incoming document by the time it resolves,
+      // so we can inspect it without a second fetch.
+      ;(function () {
+        if (window.__docsCanonicalRedirectGuard) return
+        window.__docsCanonicalRedirectGuard = true
+
+        document.addEventListener("astro:before-preparation", (event) => {
+          const originalLoader = event.loader
+          event.loader = async function () {
+            await originalLoader()
+
+            const marker = event.newDocument?.querySelector("meta[name='astro-canonical-redirect']")
+            if (!marker) return
+
+            let lang = "ts"
+            try {
+              const stored = localStorage.getItem("docs-language-preference")
+              lang = stored === "go" || stored === '"go"' ? "go" : "ts"
+            } catch (e) {
+              // localStorage unavailable: fall back to the TypeScript variant.
+            }
+
+            const target = lang === "go" ? marker.getAttribute("data-go") : marker.getAttribute("data-ts")
+            if (!target) return
+
+            // Cancel the client-side navigation. The router then falls back to a full page load,
+            // which runs the page's own redirect before anything paints.
+            event.preventDefault()
+          }
+        })
+      })()
+    </script>
     <script is:inline data-astro-rerun>
       // Safety net for Radix scroll locks (mobile nav dialog, etc.).
       //
@@ -94,6 +136,7 @@ const canonicalURL = new URL(canonicalURLStr)
     </script>
   </head>
   <body>
+    <NavigationProgress />
     <Header />
     <slot />
     <NewsletterCTA client:visible />
diff --git a/src/pages/cre/[...id].astro b/src/pages/cre/[...id].astro
index 4744e75750d..24f7922759a 100644
--- a/src/pages/cre/[...id].astro
+++ b/src/pages/cre/[...id].astro
@@ -125,6 +125,21 @@ if (isCanonical) {
 <DocsLayout frontmatter={currentEntry.data} {headings}>
   {isCanonical && <meta name="robots" content="noindex, follow" slot="head-scripts" />}
 
+  {
+    // Marker read by BaseLayout's astro:before-swap handler. A canonical CRE page renders an
+    // empty body and redirects to the language-specific URL; client-side routing would swap in
+    // that empty body and flash before the redirect runs. The handler cancels the swap and does
+    // a full navigation instead, so the redirect happens before first paint.
+    isCanonical && (
+      <meta
+        name="astro-canonical-redirect"
+        data-go={`/cre/${goEntry!.id}`}
+        data-ts={`/cre/${tsEntry!.id}`}
+        slot="head-scripts"
+      />
+    )
+  }
+
   {
     isCanonical && (
       <script
diff --git a/vercel.json b/vercel.json
index 0d2c025d3e4..2e80b29af31 100644
--- a/vercel.json
+++ b/vercel.json
@@ -9,6 +9,15 @@
         }
       ]
     },
+    {
+      "source": "/_astro/(.*)",
+      "headers": [
+        {
+          "key": "Cache-Control",
+          "value": "public, max-age=31536000, immutable"
+        }
+      ]
+    },
     {
       "source": "/(.*)",
       "headers": [