From a204c2832ae7a5002cbdb93fc9e0293404f09c1e Mon Sep 17 00:00:00 2001
From: Ronald Tse <ronald.tse@ribose.com>
Date: Thu, 18 Jun 2026 09:43:20 +0800
Subject: [PATCH] =?UTF-8?q?fix(docs):=20bypass=20SPA=20routing=20for=20for?=
 =?UTF-8?q?mula=20links=20to=20fix=20click=E2=86=92404?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Symptom: on /browse/, clicking a formula changed the URL to /browse/<slug>/ but the page showed 404. Refreshing loaded it correctly.

Root cause: VitePress generates per-batch router manifests. Each CI build-batch job only includes ITS pages in the manifest. When you load /browse/ (from batch-N's app chunk) and click a link to a formula in batch-M (M!=N), Vue Router can't find the route in batch-N's manifest, immediately shows NotFound, and never even fetches the formula's chunk. This is a fundamental issue with multi-batch VitePress builds — not fixable without single-pass build (which OOMs on 4,283 pages).

Fix: bypass SPA routing for formula navigation. Add @click.stop.prevent='goToFormula(slug)' to the formula links in FormulaBrowser.vue and index.md autocomplete. goToFormula() sets window.location.href, triggering a full page load. The server sends the correct HTML which loads the correct app chunk for that formula's batch. Same behavior as the user's manual 'refresh' workaround, just automatic.

Preserves accessibility: <a href> is still set, so right-click 'open in new tab' and Ctrl+click work normally. SPA routing still works for all other internal links (guide, licenses, etc.). Only formula cross-batch navigation is affected.
---
 docs/.vitepress/theme/FormulaBrowser.vue | 13 ++++++++++++-
 docs/index.md                            |  9 +++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/.vitepress/theme/FormulaBrowser.vue b/docs/.vitepress/theme/FormulaBrowser.vue
index f6fb38a84..df6860375 100644
--- a/docs/.vitepress/theme/FormulaBrowser.vue
+++ b/docs/.vitepress/theme/FormulaBrowser.vue
@@ -204,6 +204,17 @@ function scrollToLetter(letter) {
   if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' })
 }
 
+function goToFormula(slug) {
+  // Formula pages are rendered in CI batches (docs.yml build-batch matrix),
+  // and each batch's VitePress router manifest only includes its own pages.
+  // SPA navigation from /browse/ to a formula in a different batch hits a
+  // "Page not found" 404 even though the SSR HTML exists on the server.
+  // Bypass SPA routing for formula clicks — full page load fetches the
+  // correct HTML which loads the correct app chunk for that formula's batch.
+  const basePath = import.meta.env.BASE_URL || '/'
+  window.location.href = `${basePath}browse/${slug}/`
+}
+
 function toggleLicense(value) {
   if (value === 'all') {
     selectedLicenses.value = ['all']
@@ -255,7 +266,7 @@ function toggleSource(value) {
           <div v-for="letter in activeLetters" :key="letter" :id="'letter-' + letter" class="letter-group">
             <h3 class="letter-heading">{{ letter }}</h3>
             <div class="formula-items">
-              <a v-for="f in groupedFormulas[letter]" :key="f.slug" :href="f.slug + '/'" class="formula-item">
+              <a v-for="f in groupedFormulas[letter]" :key="f.slug" :href="f.slug + '/'" class="formula-item" @click.stop.prevent="goToFormula(f.slug)">
                 <div class="formula-main">
                   <span class="formula-name">{{ f.name }}</span>
                   <span class="formula-key">{{ f.formulaName }}</span>
diff --git a/docs/index.md b/docs/index.md
index e99d011c8..c4351f510 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -82,6 +82,14 @@ function getLicenseBadge(f) {
   return `<img src="${basePath}licenses/unknown.svg" alt="Unknown" class="license-icon" title="Unknown">`
 }
 
+function goToFormula(slug) {
+  // Formula pages are rendered in CI batches, and each batch's VitePress
+  // router manifest only knows about its own pages. SPA navigation from
+  // the homepage to a formula in a different batch 404s. Force a full page
+  // load so the server sends the correct HTML with the correct app chunk.
+  window.location.href = `${basePath}browse/${slug}/`
+}
+
 function getSourceBadge(f) {
   if (!f) return `<img src="${basePath}sources/fontist.svg" alt="Expert Curated" class="source-icon" title="Expert Curated">`
   if (f.sourceType === 'google') return `<img src="${basePath}sources/google.svg" alt="Google Fonts" class="source-icon" title="Google Fonts">`
@@ -159,6 +167,7 @@ watch(searchQuery, (val) => {
         :href="basePath + 'browse/' + item.slug + '/'"
         :class="getItemClass(idx)"
         @mouseover="selectedIndex = idx"
+        @click.stop.prevent="goToFormula(item.slug)"
       >
         <div class="autocomplete-main">
           <span class="autocomplete-name">{{ item.name }}</span>