fix: preserve client navigation lifecycles across pages and deployments

src/frontend/astro.config.mjs

@@ -3,23 +3,21 @@ import { defineConfig } from 'astro/config';
 import { unified } from '@astrojs/markdown-remark';
 import { sidebarTopics } from './config/sidebar/sidebar.topics.ts';
 import { redirects } from './config/redirects.mjs';
-import { iconPacks } from './config/icon-packs.mjs';
 import { locales } from './config/locales.ts';
 import { headAttrs } from './config/head.attrs.ts';
 import { socialConfig } from './config/socials.config.ts';
 import { aspireVersionPlaceholdersIntegration } from './config/aspire-version-placeholders-integration.mjs';
 import { remarkAspireVersionPlaceholders } from './config/remark-aspire-version-placeholders.mjs';
 import { remarkTypeScriptFirstAppHostTabs } from './config/remark-typescript-first-apphost-tabs.mjs';
+import { remarkMermaid } from './config/remark-mermaid.mjs';
 import catppuccin from '@catppuccin/starlight';
 import lunaria from './config/lunaria-starlight.mjs';
-import mermaid from 'astro-mermaid';
 import mdx from '@astrojs/mdx';
 import starlightGitHubAlerts from 'starlight-github-alerts';
 import starlightImageZoom from 'starlight-image-zoom';
 import starlightKbd from 'starlight-kbd';
 import starlightLinksValidator from 'starlight-links-validator';
 import starlightLlmsTxt from 'starlight-llms-txt';
-import starlightScrollToTop from 'starlight-scroll-to-top';
 import starlightSidebarTopics from 'starlight-sidebar-topics';
 import starlightPageActions from 'starlight-page-actions';
 import buildTiming from './config/build-timing.mjs';
@@ -62,7 +60,7 @@ export default defineConfig({
   trailingSlash: 'always',
   markdown: {
     processor: unified({
-      remarkPlugins: [remarkTypeScriptFirstAppHostTabs, remarkAspireVersionPlaceholders],
+      remarkPlugins: [remarkTypeScriptFirstAppHostTabs, remarkAspireVersionPlaceholders, remarkMermaid],
     }),
   },
   redirects: redirects,
@@ -134,31 +132,6 @@ export default defineConfig({
             errorOnFallbackPages: false,
             exclude: ['/i18n/', '/reference/api', '/reference/api/**'],
           }),
-          starlightScrollToTop({
-            // https://frostybee.github.io/starlight-scroll-to-top/svg-paths/
-            svgPath: 'M4 16L12 8L20 16',
-            showTooltip: true,
-            threshold: 10,
-            showOnHomepage: true,
-            svgStrokeWidth: 4,
-            tooltipText: {
-              da: 'Rul op',
-              de: 'Nach oben scrollen',
-              en: 'Scroll to top',
-              es: 'Ir arriba',
-              fr: 'Retour en haut',
-              hi: 'ऊपर स्क्रॉल करें',
-              id: 'Gulir ke atas',
-              it: 'Torna su',
-              ja: 'トップへ戻る',
-              ko: '맨 위로',
-              'pt-br': 'Voltar ao topo',
-              ru: 'Наверх',
-              tr: 'Başa dön',
-              uk: 'Прокрутити вгору',
-              'zh-cn': '回到顶部',
-            },
-          }),
           starlightGitHubAlerts(),
           starlightLlmsTxt({
             projectName: 'Aspire',
@@ -230,11 +203,6 @@ export default defineConfig({
         ],
       },
     }),
-    mermaid({
-      theme: 'forest',
-      autoTheme: true,
-      iconPacks,
-    }),
     mdx({
       optimize: true,
       gfm: true,

src/frontend/config/icon-packs.mjs

@@ -1,6 +1,5 @@
 // Icon packs configuration for Mermaid diagrams.
-// astro-mermaid now serializes icon packs as name/url pairs, so custom packs
-// must be served from a static JSON endpoint instead of an inline loader.
+// Loaded lazily by src/scripts/mermaid.ts.
 
 export const iconPacks = [
   {

src/frontend/config/remark-mermaid.mjs

@@ -0,0 +1,24 @@
+/** Turn opted-in fences into plain pre elements before code highlighting. */
+export function remarkMermaid() {
+  return (tree) => {
+    function visit(parent) {
+      for (const [index, node] of parent.children.entries()) {
+        if (node.type === 'code' && node.lang === 'mermaid') {
+          parent.children[index] = {
+            type: 'paragraph',
+            children: [],
+            data: {
+              hName: 'pre',
+              hProperties: { className: ['mermaid'] },
+              hChildren: [{ type: 'text', value: node.value }],
+            },
+            position: node.position,
+          };
+        } else if (Array.isArray(node.children)) {
+          visit(node);
+        }
+      }
+    }
+    visit(tree);
+  };
+}

src/frontend/package.json

@@ -81,7 +81,6 @@
     "astro": "^7.2.8",
     "astro-contributors": "^0.9.0",
     "astro-expressive-code": "^0.44.1",
-    "astro-mermaid": "^2.1.0",
     "astro-tooltips": "^0.6.2",
     "hast-util-to-html": "^9.0.5",
     "mdast-util-to-hast": "^13.2.1",
@@ -97,7 +96,6 @@
     "starlight-llms-txt": "^0.11.0",
     "starlight-page-actions": "^0.7.0",
     "starlight-plugin-icons": "^1.1.6",
-    "starlight-scroll-to-top": "^1.0.1",
     "starlight-sidebar-topics": "^0.8.0"
   },
   "devDependencies": {

src/frontend/public/scripts/analytics/1ds.js

@@ -2,7 +2,6 @@
 
 (function () {
   if (typeof location !== 'undefined' && location.origin !== 'https://aspire.dev') {
-    console.debug('[1ds] Skipping load for origin:', location.origin);
     return;
   }
 
@@ -11,7 +10,6 @@
   }
 
   if (window.analytics && window.analytics.__initialized) {
-    console.debug('[1ds] Already initialized, skipping.');
     return;
   }
 
@@ -21,6 +19,7 @@
       {
         instrumentationKey:
           '1c6ad99c3e274af7881b9c3c78eed459-573e6b44-ab25-4e60-97ad-7b7f38f0243a-6923',
+        disablePageUnloadEvents: ['unload'],
         channelConfiguration: { eventsLimitInMem: 50 },
         propertyConfiguration: { env: 'PROD' },
         webAnalyticsConfiguration: {
@@ -42,6 +41,6 @@
     analytics.__initialized = true;
     window.analytics = analytics;
   } catch (err) {
-    console.debug('[1ds] Failed to initialize Application Insights:', err);
+    console.warn('[1ds] Failed to initialize Application Insights:', err);
   }
 })();

src/frontend/public/scripts/analytics/track.js

@@ -2,12 +2,10 @@
 
 (function () {
   if (!window.analytics || !window.analytics.__initialized) {
-    console.debug('[track] Analytics not initialized, skipping event tracking setup.');
     return;
   }
 
   if (window.analytics.__trackingBound) {
-    console.debug('[track] Event tracking already bound, skipping.');
     return;
   }
 
@@ -42,11 +40,9 @@
 
     try {
       window.analytics.capturePageAction(target, overrides);
-      console.debug('[track] Event tracked:', eventName, overrides);
     } catch (err) {
-      console.debug('[track] Failed to track event:', err);
+      console.warn('[track] Failed to track event:', err);
     }
   });
 
-  console.debug('[track] Event tracking bound.');
 })();

src/frontend/src/components/InstallCliModal.astro

@@ -175,9 +175,15 @@ const channelOptions: CustomSelectOption[] = [
     return 'release';
   }
 
+  let modalListeners: AbortController | undefined;
+
   function initializeModal() {
+    modalListeners?.abort();
+    modalListeners = undefined;
     const modal = document.getElementById('install-cli-modal') as HTMLDialogElement;
     if (!modal) return;
+    modalListeners = new AbortController();
+    const { signal } = modalListeners;
 
     const versionSelect = modal.querySelector('#version-select') as HTMLSelectElement;
     const openBtns = document.querySelectorAll<HTMLElement>('[data-open-install-modal]');
@@ -227,53 +233,44 @@ const channelOptions: CustomSelectOption[] = [
       versionSelect.addEventListener('change', (e) => {
         const quality = (e.target as HTMLSelectElement).value as 'release' | 'staging' | 'dev';
         updateVersionDisplay(quality);
-      });
+      }, { signal });
     }
 
     // Open modal and position it
     openBtns.forEach((openBtn) => {
-      if (openBtn.dataset.installModalBound === 'true') {
-        return;
-      }
-
-      openBtn.dataset.installModalBound = 'true';
       openBtn.addEventListener('click', (e) => {
         e.preventDefault();
         openModal(openBtn);
-      });
+      }, { signal });
     });
 
     // Close modal handlers
-    closeBtn?.addEventListener('click', () => modal.close());
+    closeBtn?.addEventListener('click', () => modal.close(), { signal });
 
     // Close on backdrop click
     modal.addEventListener('click', (e) => {
       if (e.target === modal) modal.close();
-    });
+    }, { signal });
 
     // Close on Escape key
     modal.addEventListener('keydown', (e) => {
       if (e.key === 'Escape') modal.close();
-    });
+    }, { signal });
 
     // Close modal if window is resized below mobile breakpoint
     window.addEventListener('resize', () => {
       if (window.innerWidth < 800 && modal.open) modal.close();
-    });
+    }, { signal });
   }
 
-  // Handle install button clicks via event delegation (works across page navigations)
-  document.addEventListener('click', (e) => {
-    const target = e.target as HTMLElement;
-    const openBtn = target.closest('[data-open-install-modal]');
-    if (!openBtn) return;
-
-    e.preventDefault();
+  document.addEventListener('astro:before-swap', () => {
+    modalListeners?.abort();
+    modalListeners = undefined;
   });
 
   // Initialize on page load
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', initializeModal);
+    document.addEventListener('DOMContentLoaded', initializeModal, { once: true });
   } else {
     initializeModal();
   }