diff --git a/src/frontend/astro.config.mjs b/src/frontend/astro.config.mjs
index 6859186ff..a641c513e 100644
--- a/src/frontend/astro.config.mjs
+++ b/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,
diff --git a/src/frontend/config/icon-packs.mjs b/src/frontend/config/icon-packs.mjs
index 3e852800a..10df0c11e 100644
--- a/src/frontend/config/icon-packs.mjs
+++ b/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 = [
   {
diff --git a/src/frontend/config/remark-mermaid.mjs b/src/frontend/config/remark-mermaid.mjs
new file mode 100644
index 000000000..77efff657
--- /dev/null
+++ b/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);
+  };
+}
diff --git a/src/frontend/package.json b/src/frontend/package.json
index b7468f0d5..182ff55e4 100644
--- a/src/frontend/package.json
+++ b/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": {
diff --git a/src/frontend/pnpm-lock.yaml b/src/frontend/pnpm-lock.yaml
index 5e58796e7..393a24363 100644
--- a/src/frontend/pnpm-lock.yaml
+++ b/src/frontend/pnpm-lock.yaml
@@ -45,7 +45,6 @@ overrides:
 patchedDependencies:
   '@astrojs/starlight@0.41.3': ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5
   starlight-plugin-icons@1.1.6: ecdc00afa0722d3cdc77871f9debee551f67d1c02d82fea11c5aa41bf0f48a54
-
 importers:
 
   .:
@@ -107,9 +106,6 @@ importers:
       astro-expressive-code:
         specifier: ^0.44.1
         version: 0.44.1(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
-      astro-mermaid:
-        specifier: ^2.1.0
-        version: 2.1.0(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(mermaid@11.16.1)
       astro-tooltips:
         specifier: ^0.6.2
         version: 0.6.2
@@ -155,9 +151,6 @@ importers:
       starlight-plugin-icons:
         specifier: ^1.1.6
         version: 1.1.6(patch_hash=ecdc00afa0722d3cdc77871f9debee551f67d1c02d82fea11c5aa41bf0f48a54)(@astrojs/starlight@0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3))(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3)(unocss@66.7.5(@unocss/astro@66.7.5(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0)))(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0)))(zod@4.4.3)
-      starlight-scroll-to-top:
-        specifier: ^1.0.1
-        version: 1.0.1(@astrojs/starlight@0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3))
       starlight-sidebar-topics:
         specifier: ^0.8.0
         version: 0.8.0(@astrojs/starlight@0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3))
@@ -1990,16 +1983,6 @@ packages:
     peerDependencies:
       astro: ^4.0.0-beta || ^5.0.0-beta || ^3.3.0 || ^6.0.0-beta || ^7.0.0
 
-  astro-mermaid@2.1.0:
-    resolution: {integrity: sha512-fFRUN0BTZh+DZhDiLyblXoO26XqJ1Rr+qK3JGgSu7OBspKHDm59jkztg/aHsrdo1vO/tIq/+xhP/vgT8Mp92XA==}
-    peerDependencies:
-      '@mermaid-js/layout-elk': ^0.2.0
-      astro: '>=4'
-      mermaid: ^10.0.0 || ^11.0.0
-    peerDependenciesMeta:
-      '@mermaid-js/layout-elk':
-        optional: true
-
   astro-tooltips@0.6.2:
     resolution: {integrity: sha512-I9uXbchctnRqbc0mnxKcBRfweMuql/U+619+MzNvq3kANc7xthOXj6cMNgAkTaXoHJLdFMKL3Fx6vB5cyiiRXg==}
 
@@ -3804,12 +3787,6 @@ packages:
       unocss: '>=0.58.0'
       zod: '>=3.22.0 || >=4.0.0'
 
-  starlight-scroll-to-top@1.0.1:
-    resolution: {integrity: sha512-OkSVwEQBzHkYPgBYL/O9xSiFn75j6HvrmjvdL8+3Kk0oxgt4sNmkOwhB0bGjB/T7M7SAJ4AFk1Ojza1HVxOeHQ==}
-    engines: {node: '>=22.12.0'}
-    peerDependencies:
-      '@astrojs/starlight': '>=0.38.0'
-
   starlight-sidebar-topics@0.8.0:
     resolution: {integrity: sha512-hE8+w2vNL13h6cq3UJGl05milJQ3+1BSlhaV5V4a993YzYczU6uLAj6jfUDKQ2mmgkdVWp8/UNDF4Je/rQXNQw==}
     engines: {node: '>=22.12.0'}
@@ -6096,14 +6073,6 @@ snapshots:
       rehype-expressive-code: 0.44.1
       url-extras: 0.1.0
 
-  astro-mermaid@2.1.0(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(mermaid@11.16.1):
-    dependencies:
-      astro: 7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0)
-      import-meta-resolve: 4.2.0
-      mdast-util-to-string: 4.0.0
-      mermaid: 11.16.1
-      unist-util-visit: 5.1.0
-
   astro-tooltips@0.6.2:
     dependencies:
       tippy.js: 6.3.7
@@ -8635,10 +8604,6 @@ snapshots:
       unocss: 66.7.5(@unocss/astro@66.7.5(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0)))(vite@8.1.5(@types/node@24.13.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
       zod: 4.4.3
 
-  starlight-scroll-to-top@1.0.1(@astrojs/starlight@0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3)):
-    dependencies:
-      '@astrojs/starlight': 0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3)
-
   starlight-sidebar-topics@0.8.0(@astrojs/starlight@0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3)):
     dependencies:
       '@astrojs/starlight': 0.41.3(patch_hash=ad8925179f0e3050ae6c804196faa6d38a2be2b718acf138001215a18648d3b5)(@astrojs/markdown-remark@7.2.1)(astro@7.3.2(@astrojs/markdown-remark@7.2.1)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(@types/node@24.13.3)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))(typescript@6.0.3)
diff --git a/src/frontend/public/scripts/analytics/1ds.js b/src/frontend/public/scripts/analytics/1ds.js
index 6c1ebc9fc..7829b16f7 100644
--- a/src/frontend/public/scripts/analytics/1ds.js
+++ b/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);
   }
 })();
diff --git a/src/frontend/public/scripts/analytics/track.js b/src/frontend/public/scripts/analytics/track.js
index 2f570a065..ade61441c 100644
--- a/src/frontend/public/scripts/analytics/track.js
+++ b/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.');
 })();
diff --git a/src/frontend/src/components/InstallCliModal.astro b/src/frontend/src/components/InstallCliModal.astro
index b69be4701..9e7622674 100644
--- a/src/frontend/src/components/InstallCliModal.astro
+++ b/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();
   }
diff --git a/src/frontend/src/components/PivotSelector.astro b/src/frontend/src/components/PivotSelector.astro
index 4c88adf41..68c50de48 100644
--- a/src/frontend/src/components/PivotSelector.astro
+++ b/src/frontend/src/components/PivotSelector.astro
@@ -23,8 +23,9 @@ const renderedOptions =
     : options;
 ---
 
-<div
+<aspire-pivot-selector
   class="pivot-container not-content"
+  data-pivot-key={key}
   data-tour-target="pivot-selector"
   data-tour-step="pivot-selector"
 >
@@ -73,7 +74,7 @@ const renderedOptions =
         stroke-linejoin="round"></path>
     </svg>
   </button>
-</div>
+</aspire-pivot-selector>
 
 <style
   define:vars={{
@@ -81,6 +82,7 @@ const renderedOptions =
   }}
 >
   .pivot-container {
+    display: block;
     background: var(--sl-color-bg-nav);
     border: 1px solid var(--sl-color-gray-5);
     border-radius: 0.5rem;
@@ -93,7 +95,8 @@ const renderedOptions =
 
   .pivot-container.floating {
     position: fixed;
-    top: calc(var(--sl-nav-height) + 0.35rem);
+    /* The site's mobile TOC can remain visible beyond this component's 72rem layout. */
+    top: calc(var(--sl-nav-height) + var(--sl-mobile-toc-height, 0px) + 0.35rem);
     left: 50%;
     transform: translateX(-50%);
     z-index: var(--sl-z-index-toc, 10);
@@ -240,7 +243,7 @@ const renderedOptions =
 
   /* Collapsed floating position */
   .pivot-container.floating.collapsed {
-    top: calc(var(--sl-nav-height) - 1px);
+    top: calc(var(--sl-nav-height) + var(--sl-mobile-toc-height, 0px) - 1px);
   }
 
   .pivot-container.collapsed .pivot-expand-btn {
@@ -344,419 +347,6 @@ const renderedOptions =
   }
 </style>
 
-<script is:inline define:vars={{ key }}>
-  function initPivotSelector() {
-    const qsKey = key;
-    const selector = document.getElementById(`pivot-selector-${key}`);
-
-    if (!selector) {
-      console.warn('Pivot selector not found!');
-      return;
-    }
-    if (selector.dataset.pivotInitialized === 'true') return;
-    selector.dataset.pivotInitialized = 'true';
-
-    const container = selector.closest('.pivot-container');
-    if (!container) {
-      console.warn('Pivot container not found!');
-      return;
-    }
-
-    // Get all valid (non-disabled) options
-    const validButtons = [...selector.querySelectorAll('button:not(:disabled)')];
-    const validOptions = validButtons.map((btn) => btn.dataset.pivotOption);
-
-    // Read from query string -> storage -> first valid option
-    const qs = new URLSearchParams(window.location.search);
-    const qsValue = qs.get(qsKey);
-    const storageValue = localStorage.getItem(qsKey);
-    const firstValid = validButtons[0]?.dataset.pivotOption;
-
-    // Validate and use the first valid value
-    let current =
-      qsValue && validOptions.includes(qsValue)
-        ? qsValue
-        : storageValue && validOptions.includes(storageValue)
-          ? storageValue
-          : firstValid;
-
-    function findNearestVisibleHeading() {
-      // Find all headings in the main content area
-      const headings = document.querySelectorAll(
-        'main h1, main h2, main h3, main h4, main h5, main h6'
-      );
-
-      if (headings.length === 0) return null;
-
-      const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-      const viewportTop = scrollTop;
-
-      // Find the nearest heading above or at the current scroll position
-      let nearestHeading = null;
-      let minDistance = Infinity;
-
-      for (const heading of headings) {
-        // Skip headings that are hidden
-        if (heading.offsetParent === null) continue;
-
-        const rect = heading.getBoundingClientRect();
-        const headingTop = scrollTop + rect.top;
-        const distance = viewportTop - headingTop;
-
-        // We want headings that are above the viewport (distance >= 0)
-        // or just slightly below (within reasonable threshold)
-        if (distance >= -100 && distance < minDistance) {
-          minDistance = distance;
-          nearestHeading = heading;
-        }
-      }
-
-      if (!nearestHeading) return null;
-
-      const rect = nearestHeading.getBoundingClientRect();
-      return {
-        id: nearestHeading.id,
-        text: nearestHeading.textContent,
-        offset: rect.top, // Distance from top of viewport
-      };
-    }
-
-    function restoreScrollPosition(anchor) {
-      if (!anchor) return;
-
-      // Try to find the heading by ID first, then by text content
-      let targetHeading = null;
-
-      if (anchor.id) {
-        targetHeading = document.getElementById(anchor.id);
-      }
-
-      if (!targetHeading && anchor.text) {
-        const headings = document.querySelectorAll(
-          'main h1, main h2, main h3, main h4, main h5, main h6'
-        );
-        for (const heading of headings) {
-          if (heading.offsetParent !== null && heading.textContent === anchor.text) {
-            targetHeading = heading;
-            break;
-          }
-        }
-      }
-
-      if (targetHeading) {
-        // Calculate the scroll position to maintain the same offset
-        const rect = targetHeading.getBoundingClientRect();
-        const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-        const targetScrollTop = scrollTop + rect.top - anchor.offset;
-
-        // Use smooth scroll for better UX
-        window.scrollTo({
-          top: targetScrollTop,
-          behavior: 'instant', // Use 'instant' to avoid jarring effect
-        });
-      }
-    }
-
-    function apply(id) {
-      if (!id) return;
-
-      // Only apply if it's a valid, non-disabled option
-      if (!validOptions.includes(id)) {
-        console.warn(`Invalid pivot option: ${id}`);
-        return;
-      }
-
-      // Capture scroll position anchor before changing content
-      const scrollAnchor = findNearestVisibleHeading();
-
-      current = id;
-
-      // persist pref
-      localStorage.setItem(qsKey, id);
-
-      // When the pivot drives the global `aspire-lang` preference, mirror the
-      // selection into the Starlight synced-tabs storage so that destination
-      // pages with `<Tabs syncKey="aspire-lang">` default to the same language.
-      // Mirrors the label map in src/components/starlight/Head.astro.
-      if (qsKey === 'aspire-lang') {
-        const appHostLangLabels = { csharp: 'C#', typescript: 'TypeScript' };
-        const label = appHostLangLabels[id];
-        if (label) {
-          try {
-            localStorage.setItem('starlight-synced-tabs__aspire-lang', label);
-          } catch (e) {}
-        }
-      }
-
-      // sync URL
-      const url = new URL(window.location);
-      url.searchParams.set(qsKey, id);
-      window.history.replaceState({}, '', url);
-
-      // style buttons
-      [...selector.querySelectorAll('button')].forEach((btn) =>
-        btn.classList.toggle('active', btn.dataset.pivotOption === id)
-      );
-
-      // show/hide pivot blocks
-      const blocks = document.querySelectorAll('[data-pivot-block]');
-      blocks.forEach((el) => {
-        const blockId = el.dataset.pivotBlock;
-        // Support multiple IDs separated by comma or semicolon
-        const blockIds = blockId.split(/[,;]/).map((id) => id.trim());
-        const shouldShow = blockIds.includes(id);
-        el.style.display = shouldShow ? '' : 'none';
-      });
-
-      // Restore scroll position after content change
-      // Use requestAnimationFrame to ensure the new content has been rendered
-      requestAnimationFrame(() => {
-        restoreScrollPosition(scrollAnchor);
-      });
-    }
-
-    selector.addEventListener('click', (e) => {
-      if (e.target.dataset.pivotOption) {
-        apply(e.target.dataset.pivotOption);
-      }
-    });
-
-    apply(current);
-
-    // Floating behavior
-    let placeholder = null;
-    let originalTop = 0;
-    let isFloating = false;
-    let ticking = false;
-
-    function createPlaceholder() {
-      if (!placeholder) {
-        placeholder = document.createElement('div');
-        placeholder.className = 'pivot-placeholder';
-        container.parentNode.insertBefore(placeholder, container.nextSibling);
-      }
-      const rect = container.getBoundingClientRect();
-      placeholder.style.height = `${rect.height}px`;
-      placeholder.style.marginBottom = getComputedStyle(container).marginBottom;
-    }
-
-    function updateFloatingState() {
-      const rect = container.getBoundingClientRect();
-      const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-
-      // Calculate the original position (only once or when not floating)
-      if (!isFloating) {
-        originalTop = scrollTop + rect.top;
-      }
-
-      const shouldFloat = scrollTop > originalTop;
-
-      if (shouldFloat !== isFloating) {
-        isFloating = shouldFloat;
-
-        if (isFloating) {
-          createPlaceholder();
-          container.classList.add('floating');
-        } else {
-          container.classList.remove('floating');
-          if (placeholder) {
-            placeholder.style.height = '0px';
-          }
-        }
-      }
-
-      ticking = false;
-    }
-
-    function onScroll() {
-      if (!ticking) {
-        window.requestAnimationFrame(updateFloatingState);
-        ticking = true;
-      }
-    }
-
-    // Initialize floating behavior
-    function initFloating() {
-      // Delay to ensure layout is settled
-      setTimeout(() => {
-        const rect = container.getBoundingClientRect();
-        const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-        originalTop = scrollTop + rect.top;
-
-        window.addEventListener('scroll', onScroll, { passive: true });
-
-        // Check initial state (e.g., if user deep-linked and page loaded scrolled)
-        updateFloatingState();
-      }, 100);
-    }
-
-    // Handle resize - recalculate positions
-    let resizeTimeout;
-    window.addEventListener('resize', () => {
-      clearTimeout(resizeTimeout);
-      resizeTimeout = setTimeout(() => {
-        if (!isFloating) {
-          const rect = container.getBoundingClientRect();
-          const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-          originalTop = scrollTop + rect.top;
-        }
-        updateFloatingState();
-      }, 150);
-    });
-
-    initFloating();
-
-    // Collapse/Expand functionality
-    const collapseBtn = document.getElementById(`pivot-collapse-${key}`);
-    const expandBtn = document.getElementById(`pivot-expand-${key}`);
-
-    let isCollapsed = false;
-    let autoCollapseTimer = null;
-    let userExpanded = false; // Track if user manually expanded
-    let enableScrollCollapse = false; // Track if scroll collapse should be active
-
-    function setCollapsed(collapsed, isUserAction = false) {
-      isCollapsed = collapsed;
-
-      if (collapsed) {
-        container.classList.add('collapsed');
-        clearAutoCollapseTimer();
-        enableScrollCollapse = false;
-      } else {
-        container.classList.remove('collapsed');
-
-        // If user manually expanded, mark it and start auto-collapse timer
-        if (isUserAction) {
-          userExpanded = true;
-          startAutoCollapseTimer();
-        }
-      }
-    }
-
-    function startAutoCollapseTimer() {
-      clearAutoCollapseTimer();
-      enableScrollCollapse = false; // Disable scroll collapse during the 5 second wait
-
-      autoCollapseTimer = setTimeout(() => {
-        // After 5 seconds, enable scroll-to-collapse instead of immediately collapsing
-        if (isFloating && !isCollapsed) {
-          enableScrollCollapse = true;
-        }
-      }, 5000); // 5 seconds
-    }
-
-    function clearAutoCollapseTimer() {
-      if (autoCollapseTimer) {
-        clearTimeout(autoCollapseTimer);
-        autoCollapseTimer = null;
-      }
-    }
-
-    // Always start collapsed when floating
-    if (isFloating) {
-      setCollapsed(true);
-    }
-
-    collapseBtn?.addEventListener('click', (e) => {
-      e.stopPropagation();
-      setCollapsed(true, true);
-      userExpanded = false; // Reset user expanded flag
-    });
-
-    expandBtn?.addEventListener('click', (e) => {
-      e.stopPropagation();
-      setCollapsed(false, true);
-    });
-
-    // Handle scroll behavior - collapse when user scrolls if they expanded it
-    let scrollTimeout;
-    let lastScrollTop = window.pageYOffset || document.documentElement.scrollTop;
-
-    function handleScrollCollapse() {
-      const currentScrollTop = window.pageYOffset || document.documentElement.scrollTop;
-
-      // Only auto-collapse if:
-      // 1. It's floating
-      // 2. Not already collapsed
-      // 3. User has scrolled (not just the initial floating trigger)
-      // 4. User previously expanded it manually
-      // 5. The 5 second timer has elapsed (enableScrollCollapse is true)
-      if (
-        isFloating &&
-        !isCollapsed &&
-        userExpanded &&
-        enableScrollCollapse &&
-        Math.abs(currentScrollTop - lastScrollTop) > 10
-      ) {
-        clearTimeout(scrollTimeout);
-        scrollTimeout = setTimeout(() => {
-          setCollapsed(true);
-          userExpanded = false;
-          enableScrollCollapse = false;
-        }, 150); // Small delay to avoid collapsing during smooth scroll
-      }
-
-      lastScrollTop = currentScrollTop;
-    }
-
-    window.addEventListener('scroll', handleScrollCollapse, { passive: true });
-
-    // When floating state changes, restore collapsed preference
-    const originalUpdateFloatingState = updateFloatingState;
-    updateFloatingState = function () {
-      const wasFloatingBefore = isFloating;
-      originalUpdateFloatingState();
-
-      // Always collapse when becoming floating
-      if (!wasFloatingBefore && isFloating) {
-        setCollapsed(true);
-      }
-      // If we're no longer floating, remove collapsed state
-      if (wasFloatingBefore && !isFloating && isCollapsed) {
-        setCollapsed(false);
-        clearAutoCollapseTimer();
-        userExpanded = false;
-        enableScrollCollapse = false;
-      }
-    };
-  }
-
-  // Add titles on desktop only
-  function updateTitles() {
-    const collapseBtn = document.getElementById(`pivot-collapse-${key}`);
-    const expandBtn = document.getElementById(`pivot-expand-${key}`);
-
-    const isDesktop = window.matchMedia('(min-width: 72rem)').matches;
-
-    if (collapseBtn) {
-      if (isDesktop) {
-        collapseBtn.setAttribute('title', 'Collapse selector');
-      } else {
-        collapseBtn.removeAttribute('title');
-      }
-    }
-
-    if (expandBtn) {
-      if (isDesktop) {
-        expandBtn.setAttribute('title', 'Show selector');
-      } else {
-        expandBtn.removeAttribute('title');
-      }
-    }
-  }
-
-  const initializePivotSelector = () => {
-    initPivotSelector();
-    updateTitles();
-  };
-
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', initializePivotSelector);
-  } else {
-    initializePivotSelector();
-  }
-  document.addEventListener('astro:page-load', initializePivotSelector);
-
-  // Update titles on resize
-  window.addEventListener('resize', updateTitles);
+<script>
+  import './pivot-selector';
 </script>
diff --git a/src/frontend/src/components/ScrollToTop.astro b/src/frontend/src/components/ScrollToTop.astro
new file mode 100644
index 000000000..d74f1ae0c
--- /dev/null
+++ b/src/frontend/src/components/ScrollToTop.astro
@@ -0,0 +1,184 @@
+---
+const labels: Record<string, string> = {
+  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': '回到顶部',
+};
+const language = (Astro.locals.starlightRoute?.lang ?? 'en').toLowerCase();
+const label = labels[language] ?? labels[language.split('-')[0]] ?? labels.en;
+---
+
+<aspire-scroll-to-top>
+  <button id="scroll-to-top-button" class="scroll-to-top-button" type="button" aria-label={label}>
+    <svg
+      width="35"
+      height="35"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="4"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4 16L12 8L20 16"></path>
+    </svg>
+    <span class="tooltip" aria-hidden="true">{label}</span>
+  </button>
+</aspire-scroll-to-top>
+
+<script>
+  class ScrollToTop extends HTMLElement {
+    private controller?: AbortController;
+    private frame?: number;
+
+    connectedCallback() {
+      if (this.controller) return;
+      // Escape content containers that establish a containing block for fixed controls.
+      if (this.parentElement !== document.body) {
+        document.body.append(this);
+        return;
+      }
+      this.controller = new AbortController();
+      const { signal } = this.controller;
+      const button = this.querySelector('button')!;
+      const update = () => {
+        this.frame = undefined;
+        button.classList.toggle(
+          'visible',
+          window.scrollY > 10 && window.outerWidth / window.innerWidth <= 3
+        );
+      };
+      const schedule = () => {
+        this.frame ??= window.requestAnimationFrame(update);
+      };
+      button.addEventListener(
+        'click',
+        () => {
+          window.scrollTo({
+            top: 0,
+            behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches
+              ? 'auto'
+              : 'smooth',
+          });
+        },
+        { signal }
+      );
+      window.addEventListener('scroll', schedule, { passive: true, signal });
+      window.addEventListener('resize', schedule, { signal });
+      schedule();
+    }
+
+    disconnectedCallback() {
+      this.controller?.abort();
+      this.controller = undefined;
+      if (this.frame !== undefined) window.cancelAnimationFrame(this.frame);
+      this.frame = undefined;
+    }
+  }
+  customElements.define('aspire-scroll-to-top', ScrollToTop);
+</script>
+
+<style>
+  aspire-scroll-to-top {
+    display: contents;
+  }
+  button {
+    position: fixed;
+    bottom: 40px;
+    right: 35px;
+    width: 47px;
+    height: 47px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin: 0;
+    padding: 0;
+    border: 1px solid var(--sl-color-accent);
+    border-radius: 15%;
+    background: var(--sl-color-accent);
+    color: white;
+    box-shadow:
+      0 0 0 1px rgb(0 0 0 / 4%),
+      0 4px 8px rgb(0 0 0 / 20%);
+    cursor: pointer;
+    touch-action: manipulation;
+    z-index: 100;
+    opacity: 0;
+    visibility: hidden;
+    transform: scale(0);
+    transition:
+      opacity 0.3s,
+      visibility 0.3s,
+      transform 0.3s,
+      background-color 0.3s;
+  }
+  button.visible {
+    opacity: 1;
+    visibility: visible;
+    transform: scale(1);
+  }
+  button:hover {
+    background: var(--sl-color-accent-low);
+    color: var(--sl-color-accent);
+  }
+  button:focus-visible {
+    outline: 2px solid var(--sl-color-text);
+    outline-offset: 2px;
+  }
+  button.visible:active {
+    transform: scale(0.95);
+  }
+  .tooltip {
+    position: absolute;
+    right: -22px;
+    bottom: calc(100% + 12px);
+    padding: 5px 10px;
+    border-radius: 4px;
+    background: var(--sl-color-gray-7);
+    color: var(--sl-color-text);
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 1.4;
+    white-space: nowrap;
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transition:
+      opacity 0.2s,
+      visibility 0.2s;
+  }
+  .tooltip::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    border: 6px solid transparent;
+    border-bottom: 0;
+    border-top-color: var(--sl-color-gray-7);
+  }
+  button:hover .tooltip,
+  button:focus-visible .tooltip {
+    opacity: 1;
+    visibility: visible;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    button,
+    .tooltip {
+      transition: none;
+    }
+  }
+</style>
diff --git a/src/frontend/src/components/pivot-selector.ts b/src/frontend/src/components/pivot-selector.ts
new file mode 100644
index 000000000..4899d3b4e
--- /dev/null
+++ b/src/frontend/src/components/pivot-selector.ts
@@ -0,0 +1,294 @@
+import { getStoredPreference, setStoredPreference } from '@utils/browser-storage';
+
+const headingSelector = 'main h1, main h2, main h3, main h4, main h5, main h6';
+
+function findScrollAnchor() {
+  let nearest: HTMLElement | undefined;
+  let minDistance = Infinity;
+  for (const heading of document.querySelectorAll<HTMLElement>(headingSelector)) {
+    if (heading.offsetParent === null) continue;
+    const distance = -heading.getBoundingClientRect().top;
+    if (distance >= -100 && distance < minDistance) {
+      minDistance = distance;
+      nearest = heading;
+    }
+  }
+  return nearest
+    ? { id: nearest.id, text: nearest.textContent, offset: nearest.getBoundingClientRect().top }
+    : undefined;
+}
+
+function restoreScrollAnchor(anchor: ReturnType<typeof findScrollAnchor>) {
+  if (!anchor) return;
+  let heading = document.getElementById(anchor.id);
+  if (!heading || heading.offsetParent === null) {
+    heading =
+      [...document.querySelectorAll<HTMLElement>(headingSelector)].find(
+        (candidate) => candidate.offsetParent !== null && candidate.textContent === anchor.text
+      ) ?? null;
+  }
+  if (heading) {
+    window.scrollTo({
+      top: window.scrollY + heading.getBoundingClientRect().top - anchor.offset,
+      behavior: 'instant',
+    });
+  }
+}
+
+export class PivotSelector extends HTMLElement {
+  private controller?: AbortController;
+
+  connectedCallback() {
+    if (this.controller) return;
+    this.controller = new AbortController();
+    const { signal } = this.controller;
+    let initialized = false;
+    const initialize = () => {
+      if (initialized) return;
+      initialized = true;
+      this.initialize(signal);
+    };
+    // A swapped element connects before Astro updates the URL and restores scroll.
+    document.addEventListener('astro:page-load', initialize, {
+      once: true,
+      signal,
+    });
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', initialize, {
+        once: true,
+        signal,
+      });
+    }
+    document.addEventListener('astro:before-swap', () => this.dispose(), {
+      once: true,
+      signal,
+    });
+  }
+
+  disconnectedCallback() {
+    this.dispose();
+  }
+
+  private dispose() {
+    this.controller?.abort();
+    this.controller = undefined;
+  }
+
+  private initialize(signal: AbortSignal) {
+    const key = this.dataset.pivotKey;
+    const selector = this.querySelector<HTMLElement>('.pivot-selector');
+    if (!key || !selector) throw new Error('Pivot selector requires a key and option container.');
+    const buttons = [...selector.querySelectorAll<HTMLButtonElement>('button[data-pivot-option]')];
+    const validOptions = buttons
+      .filter((button) => !button.disabled)
+      .map((button) => button.dataset.pivotOption);
+    const allOptions = buttons.map((button) => button.dataset.pivotOption);
+    const collapseButton = this.querySelector<HTMLButtonElement>('.pivot-collapse-btn');
+    const expandButton = this.querySelector<HTMLButtonElement>('.pivot-expand-btn');
+    let placeholder: HTMLDivElement | undefined;
+    let floatingFrame: number | undefined;
+    let restoreFrame: number | undefined;
+    let resizeTimer: number | undefined;
+    let autoCollapseTimer: number | undefined;
+    let scrollTimer: number | undefined;
+    let originalTop = 0;
+    let isFloating = false;
+    let isCollapsed = false;
+    let userExpanded = false;
+    let enableScrollCollapse = false;
+    let lastScrollTop = window.scrollY;
+
+    signal.addEventListener(
+      'abort',
+      () => {
+        window.clearTimeout(resizeTimer);
+        window.clearTimeout(autoCollapseTimer);
+        window.clearTimeout(scrollTimer);
+        if (floatingFrame !== undefined) window.cancelAnimationFrame(floatingFrame);
+        if (restoreFrame !== undefined) window.cancelAnimationFrame(restoreFrame);
+        placeholder?.remove();
+        this.classList.remove('floating', 'collapsed');
+        delete selector.dataset.pivotInitialized;
+      },
+      { once: true }
+    );
+
+    const apply = (id: string, preserveScroll: boolean) => {
+      const anchor = preserveScroll ? findScrollAnchor() : undefined;
+      setStoredPreference(key, id);
+      // Keep destination Starlight tabs on the same AppHost language.
+      if (key === 'aspire-lang' && (id === 'csharp' || id === 'typescript')) {
+        setStoredPreference(
+          'starlight-synced-tabs__aspire-lang',
+          id === 'csharp' ? 'C#' : 'TypeScript'
+        );
+        document.documentElement.dataset.apphostLang = id;
+      }
+      const url = new URL(window.location.href);
+      url.searchParams.set(key, id);
+      window.history.replaceState(window.history.state, '', url);
+
+      for (const root of document.querySelectorAll<HTMLElement>('aspire-pivot-selector')) {
+        if (root.dataset.pivotKey !== key) continue;
+        for (const button of root.querySelectorAll<HTMLButtonElement>(
+          'button[data-pivot-option]'
+        )) {
+          button.classList.toggle('active', button.dataset.pivotOption === id);
+        }
+      }
+      for (const block of document.querySelectorAll<HTMLElement>('[data-pivot-block]')) {
+        const ids = (block.dataset.pivotBlock ?? '').split(/[,;]/).map((value) => value.trim());
+        // Selectors with different option sets must not hide each other's content.
+        if (ids.some((value) => allOptions.includes(value))) {
+          block.style.display = ids.includes(id) ? '' : 'none';
+        }
+      }
+      if (restoreFrame !== undefined) window.cancelAnimationFrame(restoreFrame);
+      if (anchor) {
+        restoreFrame = window.requestAnimationFrame(() => {
+          restoreFrame = undefined;
+          restoreScrollAnchor(anchor);
+        });
+      }
+    };
+
+    for (const button of buttons) {
+      button.addEventListener(
+        'click',
+        () => {
+          const id = button.dataset.pivotOption;
+          if (!button.disabled && id && validOptions.includes(id)) apply(id, true);
+        },
+        { signal }
+      );
+    }
+    const current = [
+      new URLSearchParams(window.location.search).get(key),
+      getStoredPreference(key),
+      validOptions[0],
+    ].find((id) => id && validOptions.includes(id));
+    if (current) apply(current, false);
+
+    const clearCollapseTimers = () => {
+      window.clearTimeout(autoCollapseTimer);
+      window.clearTimeout(scrollTimer);
+      autoCollapseTimer = undefined;
+      scrollTimer = undefined;
+      enableScrollCollapse = false;
+    };
+
+    const setCollapsed = (collapsed: boolean, expandedByUser = false) => {
+      clearCollapseTimers();
+      isCollapsed = collapsed;
+      userExpanded = expandedByUser;
+      this.classList.toggle('collapsed', collapsed);
+      if (expandedByUser) {
+        // Expansion remains open for five seconds, then the next scroll can collapse it.
+        autoCollapseTimer = window.setTimeout(() => {
+          autoCollapseTimer = undefined;
+          enableScrollCollapse = isFloating && !isCollapsed;
+        }, 5000);
+      }
+    };
+
+    const updateFloatingState = () => {
+      floatingFrame = undefined;
+      const rect = this.getBoundingClientRect();
+      const scrollTop = window.scrollY;
+      if (!isFloating) originalTop = scrollTop + rect.top;
+      const shouldFloat = scrollTop > originalTop;
+      if (shouldFloat === isFloating) return;
+      isFloating = shouldFloat;
+      if (isFloating) {
+        if (!placeholder) {
+          placeholder = document.createElement('div');
+          placeholder.className = 'pivot-placeholder';
+          placeholder.setAttribute('aria-hidden', 'true');
+          this.after(placeholder);
+        }
+        placeholder.style.height = `${rect.height}px`;
+        placeholder.style.marginBottom = getComputedStyle(this).marginBottom;
+        placeholder.style.display = 'block';
+      } else if (placeholder) {
+        placeholder.style.display = 'none';
+      }
+      this.classList.toggle('floating', isFloating);
+      setCollapsed(isFloating);
+    };
+
+    const scheduleFloatingUpdate = () => {
+      if (floatingFrame === undefined) {
+        floatingFrame = window.requestAnimationFrame(updateFloatingState);
+      }
+    };
+
+    const updateTitles = () => {
+      const isDesktop = window.matchMedia('(min-width: 72rem)').matches;
+      for (const [button, title] of [
+        [collapseButton, 'Collapse selector'],
+        [expandButton, 'Show selector'],
+      ] as const) {
+        if (isDesktop) button?.setAttribute('title', title);
+        else button?.removeAttribute('title');
+      }
+    };
+
+    collapseButton?.addEventListener(
+      'click',
+      (event) => {
+        event.stopPropagation();
+        setCollapsed(true);
+      },
+      { signal }
+    );
+    expandButton?.addEventListener(
+      'click',
+      (event) => {
+        event.stopPropagation();
+        setCollapsed(false, true);
+      },
+      { signal }
+    );
+
+    window.addEventListener(
+      'scroll',
+      () => {
+        scheduleFloatingUpdate();
+        const scrollTop = window.scrollY;
+        if (
+          isFloating &&
+          !isCollapsed &&
+          userExpanded &&
+          enableScrollCollapse &&
+          Math.abs(scrollTop - lastScrollTop) > 10
+        ) {
+          window.clearTimeout(scrollTimer);
+          scrollTimer = window.setTimeout(() => {
+            scrollTimer = undefined;
+            setCollapsed(true);
+          }, 150);
+        }
+        lastScrollTop = scrollTop;
+      },
+      { passive: true, signal }
+    );
+    window.addEventListener(
+      'resize',
+      () => {
+        updateTitles();
+        window.clearTimeout(resizeTimer);
+        resizeTimer = window.setTimeout(() => {
+          resizeTimer = undefined;
+          scheduleFloatingUpdate();
+        }, 150);
+      },
+      { signal }
+    );
+
+    updateTitles();
+    scheduleFloatingUpdate();
+    selector.dataset.pivotInitialized = 'true';
+  }
+}
+
+customElements.define('aspire-pivot-selector', PivotSelector);
diff --git a/src/frontend/src/components/starlight/Footer.astro b/src/frontend/src/components/starlight/Footer.astro
index eee9bdf7a..2cb26730b 100644
--- a/src/frontend/src/components/starlight/Footer.astro
+++ b/src/frontend/src/components/starlight/Footer.astro
@@ -7,6 +7,7 @@ import FooterLegal from '@components/FooterLegal.astro';
 import FooterPreferences from '@components/FooterPreferences.astro';
 import FooterResources from '@components/FooterResources.astro';
 import FooterSocials from '@components/FooterSocials.astro';
+import ScrollToTop from '@components/ScrollToTop.astro';
 import aspireLogo from '@assets/aspire-logo-256.svg';
 
 import { isHomepage } from '@utils/helpers';
@@ -89,6 +90,8 @@ const commit = (import.meta.env.PUBLIC_GIT_COMMIT_ID || import.meta.env.GIT_COMM
   </div>
 </div>
 
+<ScrollToTop />
+
 <style>
   .footer-wrapper {
     padding: 0;
diff --git a/src/frontend/src/components/starlight/Head.astro b/src/frontend/src/components/starlight/Head.astro
index 6c78b55d6..2c91dc79a 100644
--- a/src/frontend/src/components/starlight/Head.astro
+++ b/src/frontend/src/components/starlight/Head.astro
@@ -40,6 +40,17 @@ function computeSourceUrl() {
 <meta name="git-source-url" content={computeSourceUrl()} />
 
 <DefaultHead {...Astro.props} />
+<script>
+  import '@scripts/deployment-guard';
+  import '@scripts/mermaid';
+
+  document.addEventListener('astro:before-swap', (event) => {
+    const theme = document.documentElement.dataset.theme;
+    if (theme === 'light' || theme === 'dark') {
+      event.newDocument.documentElement.dataset.theme = theme;
+    }
+  });
+</script>
 <ClientRouter fallback="swap" />
 
 {
@@ -100,14 +111,14 @@ function computeSourceUrl() {
 
       var url = new URL(window.location);
       url.searchParams.set('aspire-lang', normalized);
-      window.history.replaceState({}, '', url);
+      window.history.replaceState(window.history.state, '', url);
     }
 
-    function persistAppHostLang(value) {
+    function persistAppHostLang(value, root) {
       var normalized = normalizeAppHostLang(value);
       if (!normalized) return '';
 
-      document.documentElement.setAttribute('data-apphost-lang', normalized);
+      (root || document.documentElement).setAttribute('data-apphost-lang', normalized);
       try {
         localStorage.setItem('aspire-lang', normalized);
         localStorage.setItem(appHostLangStorageKey, appHostLangLabels[normalized]);
@@ -125,6 +136,10 @@ function computeSourceUrl() {
       if (window.__aspireAppHostLangSyncInitialized) return;
       window.__aspireAppHostLangSyncInitialized = true;
 
+      document.addEventListener('astro:before-swap', function (event) {
+        restorePreferences(event.newDocument.documentElement, event.to);
+      });
+
       document.addEventListener('click', function (event) {
         var target = event.target;
         if (!(target instanceof Element)) return;
@@ -157,40 +172,37 @@ function computeSourceUrl() {
       });
     }
 
-    var qsAppHostLang = persistAppHostLang(
-      new URLSearchParams(window.location.search).get('aspire-lang')
-    );
-    var rawAppHostLang = qsAppHostLang || 'typescript';
-
-    try {
-      rawAppHostLang =
-        qsAppHostLang ||
-        localStorage.getItem('aspire-lang') ||
-        localStorage.getItem('aspire-apphost-lang') ||
-        localStorage.getItem(appHostLangStorageKey) ||
-        localStorage.getItem('starlight-synced-tabs__apphost-lang') ||
-        localStorage.getItem('starlight-synced-tabs__apphost-implementation-lang') ||
-        'typescript';
-    } catch (e) {}
-
-    persistAppHostLang(normalizeAppHostLang(rawAppHostLang) || 'typescript');
-
-    try {
-      var path = window.location.pathname.replace(/\/$/, '');
-      if (
-        localStorage.getItem('api-sidebar-collapsed') === '1' &&
-        path.indexOf('/reference/api') !== -1
-      ) {
-        document.documentElement.setAttribute('data-sidebar-collapsed', '');
-      }
+    function restorePreferences(root, url) {
+      var qsAppHostLang = persistAppHostLang(url.searchParams.get('aspire-lang'), root);
+      var rawAppHostLang = qsAppHostLang || 'typescript';
 
-      if (
-        localStorage.getItem('topic-sidebar-collapsed') === '1' &&
-        path.indexOf('/reference/api') === -1
-      ) {
-        document.documentElement.setAttribute('data-topic-sidebar-collapsed', '');
-      }
-    } catch (e) {}
+      try {
+        rawAppHostLang =
+          qsAppHostLang ||
+          localStorage.getItem('aspire-lang') ||
+          localStorage.getItem('aspire-apphost-lang') ||
+          localStorage.getItem(appHostLangStorageKey) ||
+          localStorage.getItem('starlight-synced-tabs__apphost-lang') ||
+          localStorage.getItem('starlight-synced-tabs__apphost-implementation-lang') ||
+          'typescript';
+      } catch (e) {}
+
+      persistAppHostLang(normalizeAppHostLang(rawAppHostLang) || 'typescript', root);
+
+      try {
+        var isApi = url.pathname.indexOf('/reference/api') !== -1;
+        root.toggleAttribute(
+          'data-sidebar-collapsed',
+          isApi && localStorage.getItem('api-sidebar-collapsed') === '1'
+        );
+        root.toggleAttribute(
+          'data-topic-sidebar-collapsed',
+          !isApi && localStorage.getItem('topic-sidebar-collapsed') === '1'
+        );
+      } catch (e) {}
+    }
+
+    restorePreferences(document.documentElement, new URL(window.location.href));
 
     if (document.readyState === 'loading') {
       document.addEventListener('DOMContentLoaded', initAppHostLangSync);
diff --git a/src/frontend/src/components/starlight/PageTitle.astro b/src/frontend/src/components/starlight/PageTitle.astro
index 39667c586..043a6af45 100644
--- a/src/frontend/src/components/starlight/PageTitle.astro
+++ b/src/frontend/src/components/starlight/PageTitle.astro
@@ -1,8 +1,5 @@
 ---
 import PageActionsPageTitle from 'starlight-page-actions/overrides/PageTitle.astro';
-
-const currentPath = Astro.url.pathname.replace(/\/$/, '').replace(/^\//, '');
-const isApiSubpage = currentPath.startsWith('reference/api/');
 ---
 
 <PageActionsPageTitle />
@@ -63,7 +60,7 @@ const isApiSubpage = currentPath.startsWith('reference/api/');
   }
 </style>
 
-<script is:inline define:vars={{ isApiSubpage }}>
+<script is:inline>
   function initPageTitle() {
     var actions = document.querySelector('.actions-container');
     if (actions) {
@@ -71,10 +68,11 @@ const isApiSubpage = currentPath.startsWith('reference/api/');
       actions.setAttribute('data-tour-step', 'page-actions');
     }
 
-    if (isApiSubpage) {
-      var h1 = document.querySelector('main h1#_top');
-      if (h1) h1.classList.add('api-page-title');
-    }
+    var h1 = document.querySelector('main h1#_top');
+    if (!h1) return;
+
+    var currentPath = window.location.pathname.replace(/\/$/, '').replace(/^\//, '');
+    h1.classList.toggle('api-page-title', currentPath.startsWith('reference/api/'));
   }
 
   if (window.__pageTitleAbort) window.__pageTitleAbort.abort();
diff --git a/src/frontend/src/scripts/deployment-guard.ts b/src/frontend/src/scripts/deployment-guard.ts
new file mode 100644
index 000000000..2e7aba7b7
--- /dev/null
+++ b/src/frontend/src/scripts/deployment-guard.ts
@@ -0,0 +1,24 @@
+import type { TransitionBeforePreparationEvent } from 'astro:transitions/client';
+
+const deploymentSelector = 'meta[name="git-commit-id"]';
+const runningDeployment =
+  document.querySelector<HTMLMetaElement>(deploymentSelector)?.content.trim() ?? '';
+
+document.addEventListener('astro:before-preparation', (event: TransitionBeforePreparationEvent) => {
+  const load = event.loader;
+  event.loader = async () => {
+    await load();
+    if (event.defaultPrevented || event.signal.aborted) return;
+
+    const incomingDeployment =
+      event.newDocument.querySelector<HTMLMetaElement>(deploymentSelector)?.content.trim() ?? '';
+    if (runningDeployment === incomingDeployment) return;
+
+    if (!runningDeployment || !incomingDeployment) {
+      console.warn('[navigation] Missing deployment identity; loading a new document.');
+    }
+    // Canceling preparation delegates to browser navigation before any DOM swap
+    // or incoming script execution. A swap cannot replace the old JS environment.
+    event.preventDefault();
+  };
+});
diff --git a/src/frontend/src/scripts/mermaid.ts b/src/frontend/src/scripts/mermaid.ts
new file mode 100644
index 000000000..c72248fcb
--- /dev/null
+++ b/src/frontend/src/scripts/mermaid.ts
@@ -0,0 +1,136 @@
+import type { AsyncIconLoader } from 'mermaid';
+import { iconPacks } from '../../config/icon-packs.mjs';
+
+type Mermaid = (typeof import('mermaid'))['default'];
+type Theme = 'default' | 'dark';
+let library: Promise<Mermaid> | undefined;
+let body: HTMLElement | undefined;
+let theme: Theme = 'default';
+let generation = 0;
+let nextId = 0;
+let pending = false;
+let running = false;
+const renderedThemes = new WeakMap<HTMLElement, string>();
+const readTheme = (): Theme =>
+  document.documentElement.dataset.theme === 'dark' ? 'dark' : 'default';
+
+function loadMermaid() {
+  return (library ??= import('mermaid')
+    .then(({ default: mermaid }) => {
+      mermaid.registerIconPacks(
+        iconPacks.map(({ name, url }): AsyncIconLoader => ({
+          name,
+          loader: async () => {
+            const response = await fetch(url);
+            if (!response.ok)
+              throw new Error(`Unable to load ${name} icons: HTTP ${response.status}`);
+            return response.json() as ReturnType<AsyncIconLoader['loader']>;
+          },
+        }))
+      );
+      return mermaid;
+    })
+    .catch((error: unknown) => {
+      library = undefined;
+      throw error;
+    }));
+}
+
+function showError(diagram: HTMLElement, error: unknown) {
+  diagram.textContent = `Unable to render diagram: ${error instanceof Error ? error.message : String(error)}`;
+  diagram.classList.add('mermaid-error');
+  diagram.dataset.processed = 'true';
+}
+
+async function renderPage(page: HTMLElement, selectedTheme: Theme, revision: number) {
+  const current = () =>
+    body === page &&
+    document.body === page &&
+    generation === revision &&
+    readTheme() === selectedTheme;
+  const owns = (diagram: HTMLElement) => current() && diagram.isConnected && page.contains(diagram);
+  const diagrams = [...page.querySelectorAll<HTMLElement>('pre.mermaid')].filter(
+    (diagram) => renderedThemes.get(diagram) !== selectedTheme
+  );
+  if (!diagrams.length) return;
+  for (const diagram of diagrams) diagram.dataset.diagram ??= diagram.textContent ?? '';
+
+  let mermaid: Mermaid;
+  try {
+    mermaid = await loadMermaid();
+    if (!current()) return;
+    mermaid.initialize({ startOnLoad: false, theme: selectedTheme });
+  } catch (error) {
+    console.error('[mermaid] Initialization failed:', error);
+    for (const diagram of diagrams) if (owns(diagram)) showError(diagram, error);
+    return;
+  }
+
+  for (const diagram of diagrams) {
+    if (!current()) break;
+    if (!owns(diagram)) continue;
+    const id = `aspire-mermaid-${++nextId}`;
+    try {
+      const { svg } = await mermaid.render(id, diagram.dataset.diagram!);
+      if (!owns(diagram)) continue;
+      diagram.innerHTML = svg;
+      diagram.classList.remove('mermaid-error');
+      diagram.dataset.processed = 'true';
+      renderedThemes.set(diagram, selectedTheme);
+    } catch (error) {
+      console.error('[mermaid] Rendering failed:', error);
+      if (!owns(diagram)) continue;
+      showError(diagram, error);
+      renderedThemes.set(diagram, selectedTheme);
+    } finally {
+      document.getElementById(`d${id}`)?.remove();
+      document.getElementById(`i${id}`)?.remove();
+    }
+  }
+}
+
+function schedule() {
+  if (!body) return;
+  const selectedTheme = readTheme();
+  if (selectedTheme !== theme) {
+    theme = selectedTheme;
+    generation++;
+  }
+  pending = true;
+  if (running) return;
+  running = true;
+  // Serialize Mermaid's global configuration and rendering, including theme changes.
+  queueMicrotask(() => {
+    void (async () => {
+      try {
+        while (pending && body) {
+          pending = false;
+          await renderPage(body, theme, generation);
+        }
+      } finally {
+        running = false;
+      }
+    })();
+  });
+}
+
+const observer = new MutationObserver(() => {
+  if (readTheme() !== theme) schedule();
+});
+document.addEventListener('astro:before-swap', () => {
+  generation++;
+  body = undefined;
+  pending = false;
+  observer.disconnect();
+});
+document.addEventListener('astro:page-load', () => {
+  if (body !== document.body) {
+    body = document.body;
+    generation++;
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme'],
+    });
+  }
+  schedule();
+});
diff --git a/src/frontend/src/styles/mermaid.css b/src/frontend/src/styles/mermaid.css
index 90dee24b3..9510bd1f6 100644
--- a/src/frontend/src/styles/mermaid.css
+++ b/src/frontend/src/styles/mermaid.css
@@ -1,4 +1,4 @@
-/* ClientRouter replaces the <head> style injected once by astro-mermaid. */
+/* Shared by fenced examples and API inheritance diagrams. */
 pre.mermaid {
   display: flex;
   justify-content: center;
@@ -159,4 +159,10 @@ pre.mermaid svg {
   :root .sl-markdown-content pre.mermaid:not([data-processed])::before {
     animation: none;
   }
+
+}
+
+:root .sl-markdown-content pre.mermaid.mermaid-error {
+  white-space: pre-wrap;
+  color: var(--sl-color-red-high);
 }
diff --git a/src/frontend/src/styles/site.css b/src/frontend/src/styles/site.css
index 38abf88df..60af3e552 100644
--- a/src/frontend/src/styles/site.css
+++ b/src/frontend/src/styles/site.css
@@ -1569,10 +1569,6 @@ it configures at which point the mobile toc should be replaced with the normal t
 }
 
 @media (prefers-reduced-motion: no-preference) {
-  @view-transition {
-    navigation: auto;
-  }
-
   /* Give the sidebar pane its own view-transition group and disable its
      animation so it doesn't participate in the cross-fade between topic
      pages. Without this, sidebar items briefly flash an unstyled border
diff --git a/src/frontend/tests/e2e/deployment-navigation.spec.ts b/src/frontend/tests/e2e/deployment-navigation.spec.ts
new file mode 100644
index 000000000..b570842d7
--- /dev/null
+++ b/src/frontend/tests/e2e/deployment-navigation.spec.ts
@@ -0,0 +1,162 @@
+import { expect, test, type Page } from '@playwright/test';
+import { dismissCookieConsentIfVisible } from '@tests/e2e/helpers';
+
+// This suite exercises native Document PiP, which needs the full browser rather than headless shell.
+test.use({ channel: 'chromium' });
+
+test.beforeEach(async ({ page, isMobile }) => {
+  if (isMobile) {
+    await page.addInitScript(() => {
+      Object.defineProperty(document, 'startViewTransition', {
+        value: undefined,
+        configurable: true,
+      });
+    });
+  }
+});
+
+async function navigateClient(page: Page, action: () => Promise<unknown>) {
+  await page.evaluate(() => {
+    Reflect.set(window, '__deploymentPageLoaded', false);
+    document.addEventListener(
+      'astro:page-load',
+      () => {
+        Reflect.set(window, '__deploymentPageLoaded', true);
+      },
+      { once: true }
+    );
+  });
+  await action();
+  await expect
+    .poll(() => page.evaluate(() => Reflect.get(window, '__deploymentPageLoaded')))
+    .toBe(true);
+  await expect(page.locator('html[data-astro-transition]')).toHaveCount(0);
+}
+
+test('same-deployment navigation and history preserve the running document', async ({ page }) => {
+  const errors: string[] = [];
+  page.on('pageerror', (error) => errors.push(error.message));
+  await page.goto('/');
+  await dismissCookieConsentIfVisible(page);
+  await page.evaluate(() => Reflect.set(window, '__deploymentSession', true));
+  await navigateClient(page, () => page.locator('header a[href="/docs/"]:visible').click());
+  await expect(page).toHaveURL(/\/docs\/$/);
+  await expect
+    .poll(() => page.evaluate(() => Reflect.get(window, '__deploymentSession')))
+    .toBe(true);
+  await navigateClient(page, () => page.goBack());
+  await expect(page).toHaveURL((url) => url.pathname === '/');
+  expect(await page.evaluate(() => Reflect.get(window, '__deploymentSession'))).toBe(true);
+  await navigateClient(page, () => page.goForward());
+  await expect(page).toHaveURL(/\/docs\/$/);
+  expect(await page.evaluate(() => Reflect.get(window, '__deploymentSession'))).toBe(true);
+  expect(errors).toEqual([]);
+});
+
+for (const identity of ['changed', 'missing'] as const) {
+  test(`${identity} deployment uses native navigation before incoming scripts execute`, async ({
+    page,
+  }) => {
+    const errors: string[] = [];
+    const executions: string[] = [];
+    let nativeDocuments = 0;
+    page.on('pageerror', (error) => errors.push(error.message));
+    await page.exposeFunction('__recordIncompatibleExecution', () => executions.push('executed'));
+    await page.goto('/');
+    await dismissCookieConsentIfVisible(page);
+    await expect(page.locator('meta[name="git-commit-id"]')).not.toHaveAttribute('content', '');
+    await page.evaluate(() => Reflect.set(window, '__deploymentSession', true));
+    await page.route('**/docs/**', async (route) => {
+      if (route.request().isNavigationRequest()) {
+        nativeDocuments++;
+        await route.continue();
+        return;
+      }
+      const response = await route.fetch();
+      const body = (await response.text())
+        .replace(
+          /<meta name="git-commit-id" content="[^"]*"[^>]*>/,
+          identity === 'missing' ? '' : '<meta name="git-commit-id" content="another-deployment">'
+        )
+        .replace('</head>', '<script>window.__recordIncompatibleExecution()</script></head>');
+      await route.fulfill({ response, body });
+    });
+    await page.locator('header a[href="/docs/"]:visible').evaluate((element) => {
+      element.setAttribute('href', '/docs/?deployment-test=1#_top');
+    });
+    await page.locator('header a[href^="/docs/?deployment-test=1"]:visible').click();
+    await expect(page).toHaveURL(/\/docs\/\?deployment-test=1#_top$/);
+    await expect
+      .poll(() => page.evaluate(() => Reflect.get(window, '__deploymentSession')))
+      .toBeUndefined();
+    expect(nativeDocuments).toBe(1);
+    expect(executions).toEqual([]);
+    await expect(page.locator('site-search button[data-open-modal]')).toBeEnabled();
+    await page.keyboard.press('Control+k');
+    await expect(page.locator('site-search dialog[open]')).toBeVisible();
+    await expect(page.locator('site-search input.pagefind-ui__search-input')).toBeVisible();
+    expect(errors).toEqual([]);
+  });
+}
+
+test('native Document PiP survives same-build navigation and closes on a deployment reload', async ({
+  page,
+  isMobile,
+}) => {
+  test.skip(isMobile, 'Native Document Picture-in-Picture requires a desktop browser.');
+  await page.goto('/');
+  await dismissCookieConsentIfVisible(page);
+  const supported = await page.evaluate(() => 'documentPictureInPicture' in window);
+  test.skip(!supported, 'This browser does not support native Document Picture-in-Picture.');
+
+  await page.evaluate(() => {
+    const button = document.createElement('button');
+    button.id = 'native-pip-test';
+    button.textContent = 'Open native PiP';
+    button.style.cssText = 'position:fixed;top:80px;left:0;z-index:2147483647';
+    button.addEventListener('click', () => {
+      const api = (
+        window as Window & {
+          documentPictureInPicture?: { requestWindow: () => Promise<Window> };
+        }
+      ).documentPictureInPicture;
+      if (!api) throw new Error('Native Document Picture-in-Picture is unavailable.');
+      void api.requestWindow().then((pip) => {
+        pip.document.body.textContent = 'Native PiP navigation test';
+        Reflect.set(window, '__nativePipTest', pip);
+      });
+    });
+    document.body.append(button);
+  });
+  const opened = page.context().waitForEvent('page');
+  await page.locator('#native-pip-test').click();
+  const pipPage = await opened;
+  await expect
+    .poll(() => page.evaluate(() => Boolean(Reflect.get(window, '__nativePipTest'))))
+    .toBe(true);
+  await navigateClient(page, () => page.locator('header a[href="/docs/"]:visible').click());
+  await expect(page).toHaveURL(/\/docs\/$/);
+  expect(pipPage.isClosed()).toBe(false);
+  await expect(pipPage.locator('body')).toHaveText('Native PiP navigation test');
+
+  await page.route(new URL('/', page.url()).href, async (route) => {
+    if (route.request().isNavigationRequest()) {
+      await route.continue();
+      return;
+    }
+    const response = await route.fetch();
+    const body = (await response.text()).replace(
+      /<meta name="git-commit-id" content="[^"]*"[^>]*>/,
+      '<meta name="git-commit-id" content="another-deployment">'
+    );
+    await route.fulfill({ response, body });
+  });
+  const closed = pipPage.waitForEvent('close');
+  await page.locator('header a[href="/"]:visible').click();
+  await expect(page).toHaveURL((url) => url.pathname === '/');
+  await closed;
+  await expect
+    .poll(() => page.evaluate(() => Boolean(Reflect.get(window, '__nativePipTest'))))
+    .toBe(false);
+  expect(pipPage.isClosed()).toBe(true);
+});
diff --git a/src/frontend/tests/e2e/homepage.spec.ts b/src/frontend/tests/e2e/homepage.spec.ts
index c67e77bd4..59630e2b5 100644
--- a/src/frontend/tests/e2e/homepage.spec.ts
+++ b/src/frontend/tests/e2e/homepage.spec.ts
@@ -417,6 +417,9 @@ test('presents the application model as a live polyglot topology', async ({ page
   await terminalWindow.scrollIntoViewIfNeeded();
   await expect(story).toHaveAttribute('data-story-playing', 'true', { timeout: 10_000 });
   await expect(story).toHaveAttribute('data-story-focus', 'stage', { timeout: 10_000 });
+  // Center the whole stage so clicking its tab does not scroll the terminal out of view.
+  await story.locator('[data-model-story-surface]').scrollIntoViewIfNeeded();
+  await expect(story).toHaveAttribute('data-story-viewport-active', '');
   await topologyStage.click();
   await expect(story).toHaveAttribute('data-story-playing', 'false');
   await expect(story).toHaveAttribute('data-story-stage', 'topology');
@@ -1433,6 +1436,16 @@ test('keeps the environment frame stable while each topology changes', async ({
       )
     )
     .toBeGreaterThan(0.5);
+  await expect
+    .poll(() =>
+      productionPanel.locator('.topology-node').evaluateAll((nodes) =>
+        nodes.every((node) => {
+          const transform = new DOMMatrixReadOnly(getComputedStyle(node).transform);
+          return Math.abs(transform.m41) > 1 || Math.abs(transform.m42) > 1;
+        })
+      )
+    )
+    .toBe(true);
   const enteringTransforms = await productionPanel
     .locator('.topology-node')
     .evaluateAll((nodes) => nodes.map((node) => getComputedStyle(node).transform));
@@ -1449,12 +1462,14 @@ test('keeps the environment frame stable while each topology changes', async ({
       )
     )
     .toBeLessThan(0.1);
-  const centeredTransforms = await productionPanel
-    .locator('.topology-node')
-    .evaluateAll((nodes) => nodes.map((node) => getComputedStyle(node).transform));
-  expect(
-    enteringTransforms.some((transform, index) => transform !== centeredTransforms[index])
-  ).toBe(true);
+  await expect
+    .poll(async () => {
+      const centeredTransforms = await productionPanel
+        .locator('.topology-node')
+        .evaluateAll((nodes) => nodes.map((node) => getComputedStyle(node).transform));
+      return enteringTransforms.some((transform, index) => transform !== centeredTransforms[index]);
+    })
+    .toBe(true);
 
   expect(await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth)).toBe(
     false
diff --git a/src/frontend/tests/e2e/install-modal-navigation.spec.ts b/src/frontend/tests/e2e/install-modal-navigation.spec.ts
new file mode 100644
index 000000000..d8a92587d
--- /dev/null
+++ b/src/frontend/tests/e2e/install-modal-navigation.spec.ts
@@ -0,0 +1,51 @@
+import { expect, test } from '@playwright/test';
+import { dismissCookieConsentIfVisible } from '@tests/e2e/helpers';
+
+test('install modal owns one set of listeners and disposes outgoing controls', async ({
+  page, isMobile,
+}) => {
+  test.skip(isMobile, 'Touch layouts use the full installation page.');
+  const errors: string[] = [];
+  page.on('pageerror', error => errors.push(error.message));
+  await page.goto('/');
+  await dismissCookieConsentIfVisible(page);
+  await page.evaluate(() => {
+    const close = HTMLDialogElement.prototype.close;
+    Reflect.set(window, '__installCloseCalls', 0);
+    Reflect.set(window, '__installSession', true);
+    HTMLDialogElement.prototype.close = function(value) {
+      if (this.id === 'install-cli-modal') {
+        Reflect.set(window, '__installCloseCalls', Number(Reflect.get(window, '__installCloseCalls')) + 1);
+      }
+      close.call(this, value);
+    };
+  });
+
+  for (let visit = 0; visit < 3; visit++) {
+    await page.evaluate(() => {
+      document.dispatchEvent(new Event('astro:page-load'));
+      document.dispatchEvent(new Event('astro:page-load'));
+    });
+    await page.locator('header [data-open-install-modal]:visible').click();
+    const modal = page.locator('#install-cli-modal');
+    await expect(modal).toBeVisible();
+    const before = await page.evaluate(() => Reflect.get(window, '__installCloseCalls'));
+    await modal.locator('[data-close-modal]').click();
+    await expect(modal).toBeHidden();
+    expect(await page.evaluate(() => Reflect.get(window, '__installCloseCalls'))).toBe(before + 1);
+    await modal.evaluate(element => Reflect.set(window, '__outgoingInstallModal', element));
+
+    const destination = visit % 2 === 0 ? '/docs/' : '/';
+    await page.locator(`header a[href="${destination}"]:visible`).click();
+    await expect(page).toHaveURL(url => url.pathname === destination);
+    expect(await page.evaluate(() => Reflect.get(window, '__installSession'))).toBe(true);
+    const calls = await page.evaluate(() => Reflect.get(window, '__installCloseCalls'));
+    await page.evaluate(() => {
+      const outgoing = Reflect.get(window, '__outgoingInstallModal') as HTMLDialogElement;
+      outgoing.dispatchEvent(new Event('click'));
+      outgoing.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+    });
+    expect(await page.evaluate(() => Reflect.get(window, '__installCloseCalls'))).toBe(calls);
+  }
+  expect(errors).toEqual([]);
+});
diff --git a/src/frontend/tests/e2e/pivot-selector.spec.ts b/src/frontend/tests/e2e/pivot-selector.spec.ts
index 2d83f9cc4..9d4d9ee19 100644
--- a/src/frontend/tests/e2e/pivot-selector.spec.ts
+++ b/src/frontend/tests/e2e/pivot-selector.spec.ts
@@ -139,3 +139,185 @@ test('app host page restores pivot state from the lang query string', async ({ p
   await expect(javaContent).toBeVisible();
   await expect(nodeJsContent).toBeHidden();
 });
+
+test('first-app pivots default to TypeScript and preserve history and shared preferences', async ({
+  page,
+}) => {
+  await page.goto('/get-started/first-app/?keep=1');
+  await dismissCookieConsentIfVisible(page);
+  const selector = page.locator('#pivot-selector-aspire-lang');
+  await expect(selector).toHaveAttribute('data-pivot-initialized', 'true');
+  await expect(selector.getByRole('button').first()).toHaveText('TypeScript');
+  await expect(selector.getByRole('button', { name: 'TypeScript' })).toHaveClass(/active/);
+  await expect(page.locator('[data-pivot-block="typescript"]').first()).toBeVisible();
+  await expect(page.locator('[data-pivot-block="csharp"]').first()).toBeHidden();
+
+  const index = await page.evaluate(() => {
+    const state = history.state as { index: number };
+    history.replaceState({ ...state, pivotTest: 'preserved' }, '');
+    return state.index;
+  });
+  expect(index).toEqual(expect.any(Number));
+  await selector.getByRole('button', { name: 'C#', exact: true }).focus();
+  await page.keyboard.press('Enter');
+  await expect(page).toHaveURL(/\?keep=1&aspire-lang=csharp$/);
+  await expect(page.locator('[data-pivot-block="csharp"]').first()).toBeVisible();
+  await expect(page.locator('[data-pivot-block="typescript"]').first()).toBeHidden();
+  await expect
+    .poll(() =>
+      page.evaluate(() => ({
+        state: history.state,
+        preference: localStorage.getItem('aspire-lang'),
+        tabs: localStorage.getItem('starlight-synced-tabs__aspire-lang'),
+        language: document.documentElement.dataset.apphostLang,
+      }))
+    )
+    .toMatchObject({
+      state: { index, pivotTest: 'preserved' },
+      preference: 'csharp',
+      tabs: 'C#',
+      language: 'csharp',
+    });
+
+  await page.goto('/get-started/first-app/?aspire-lang=typescript&keep=2');
+  await expect(selector.getByRole('button', { name: 'TypeScript' })).toHaveClass(/active/);
+  await expect
+    .poll(() => page.evaluate(() => localStorage.getItem('aspire-lang')))
+    .toBe('typescript');
+});
+
+test('floating pivot controls clear the TOC across its responsive breakpoint', async ({
+  page,
+}, testInfo) => {
+  test.skip(testInfo.project.name !== 'desktop-chromium');
+  await page.goto('/get-started/first-app/');
+  await dismissCookieConsentIfVisible(page);
+  const root = page.locator('aspire-pivot-selector[data-pivot-key="aspire-lang"]');
+  await expect(root.locator('.pivot-selector')).toHaveAttribute('data-pivot-initialized', 'true');
+  await root.getByRole('button', { name: 'C#', exact: true }).click();
+  const expand = root.getByRole('button', { name: 'Expand selector', exact: true });
+  const collapse = root.getByRole('button', { name: 'Collapse selector', exact: true });
+  const toc = page.locator('#starlight__on-this-page--mobile');
+
+  for (const width of [390, 834, 1152, 1440, 1599, 1600]) {
+    await page.setViewportSize({ width, height: 900 });
+    await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'instant' }));
+    await expect(root).not.toHaveClass(/floating/);
+    await page.evaluate(() => window.scrollTo({ top: 1200, behavior: 'instant' }));
+    await expect(root).toHaveClass(/floating/);
+    await expect(root).toHaveClass(/collapsed/);
+
+    if (width < 1600) {
+      await expect(toc).toBeVisible();
+      await expect
+        .poll(async () => {
+          const buttonBox = await expand.boundingBox();
+          const tocBox = await toc.boundingBox();
+          // The shared border can overlap by one pixel, but the control must clear the TOC.
+          return buttonBox && tocBox ? buttonBox.y + 1 >= tocBox.y + tocBox.height : false;
+        })
+        .toBe(true);
+    } else {
+      await expect(toc).toBeHidden();
+    }
+    await expand.click();
+    await expect(root).not.toHaveClass(/collapsed/);
+    await expect(root.getByRole('button', { name: 'C#', exact: true })).toHaveClass(/active/);
+    await collapse.click();
+    await expect(root).toHaveClass(/collapsed/);
+
+    if (width < 1600) {
+      await toc.click();
+      await expect(page.locator('#starlight__mobile-toc')).toHaveJSProperty('open', true);
+      await toc.press('Escape');
+      await expect(page.locator('#starlight__mobile-toc')).toHaveJSProperty('open', false);
+    }
+  }
+});
+
+for (const transition of ['native', 'fallback'] as const) {
+  test(`pivot lifecycle survives repeated visits and history with ${transition} swaps`, async ({
+    page, isMobile,
+  }) => {
+    test.skip(isMobile && transition === 'native',
+      'Chromium touch emulation aborts native transitions; touch projects cover the swap fallback.');
+    test.setTimeout(120_000);
+    const warnings: string[] = [];
+    const errors: string[] = [];
+    page.on('console', (message) => {
+      if (message.type() === 'warning' && /pivot.*not found/i.test(message.text())) {
+        warnings.push(message.text());
+      }
+    });
+    page.on('pageerror', (error) => errors.push(error.message));
+    if (transition === 'fallback') {
+      await page.addInitScript(() => {
+        Object.defineProperty(document, 'startViewTransition', { value: undefined });
+      });
+    }
+    await page.goto('/docs/');
+    await dismissCookieConsentIfVisible(page);
+    const documentMarker = await page.evaluate(() => {
+      const marker = crypto.randomUUID();
+      Object.defineProperty(window, '__pivotNavigationMarker', { value: marker });
+      return marker;
+    });
+    const selector = page.locator('#pivot-selector-aspire-lang');
+    const root = page.locator('aspire-pivot-selector[data-pivot-key="aspire-lang"]');
+    const navigate = async (action: () => Promise<unknown>) => {
+      await page.evaluate(() => {
+        Reflect.set(window, '__pivotPageLoaded', false);
+        document.addEventListener('astro:page-load', () => {
+          Reflect.set(window, '__pivotPageLoaded', true);
+        }, { once: true });
+      });
+      await action();
+      await expect.poll(() => page.evaluate(() => Reflect.get(window, '__pivotPageLoaded'))).toBe(true);
+      await expect(page.locator('html[data-astro-transition]')).toHaveCount(0);
+    };
+
+    for (let visit = 0; visit < 3; visit++) {
+      await navigate(() => page.locator('a[href="/get-started/first-app/"]:visible').first().click());
+      await expect(selector).toHaveAttribute('data-pivot-initialized', 'true');
+      await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'instant' }));
+      await selector.getByRole('button', { name: 'C#', exact: true }).click();
+      await expect(page).toHaveURL(/\/get-started\/first-app\/\?aspire-lang=csharp$/);
+      await expect
+        .poll(() => page.evaluate(() => history.state))
+        .toMatchObject({
+          index: expect.any(Number),
+        });
+      await page.evaluate(() => window.scrollTo({ top: 1200, behavior: 'instant' }));
+      await expect(root).toHaveClass(/floating/);
+      await expect(root).toHaveClass(/collapsed/);
+      await root.getByRole('button', { name: 'Expand selector', exact: true }).click();
+      await expect(root).not.toHaveClass(/collapsed/);
+
+      // Leave while the old selector still owns its five-second expansion timer.
+      await navigate(() => page.locator('header a[href="/"]:visible').click());
+      await expect(page).toHaveURL(url => url.pathname === '/');
+      await expect(root).toHaveCount(0);
+      await expect(page.locator('.pivot-placeholder')).toHaveCount(0);
+      await navigate(() => page.goBack());
+      await expect(selector).toHaveAttribute('data-pivot-initialized', 'true');
+      await expect(selector.locator('[data-pivot-option="csharp"]')).toHaveClass(/active/);
+      await expect
+        .poll(() => page.evaluate(() => history.state))
+        .toMatchObject({
+          index: expect.any(Number),
+        });
+      await navigate(() => page.goForward());
+      await expect(page).toHaveURL(url => url.pathname === '/');
+      await expect(root).toHaveCount(0);
+      await page.evaluate(() => {
+        window.dispatchEvent(new Event('scroll'));
+        window.dispatchEvent(new Event('resize'));
+      });
+      await expect
+        .poll(() => page.evaluate(() => Reflect.get(window, '__pivotNavigationMarker')))
+        .toBe(documentMarker);
+    }
+    expect(warnings).toEqual([]);
+    expect(errors).toEqual([]);
+  });
+}
diff --git a/src/frontend/tests/e2e/route-style-navigation.spec.ts b/src/frontend/tests/e2e/route-style-navigation.spec.ts
new file mode 100644
index 000000000..fafbfcd46
--- /dev/null
+++ b/src/frontend/tests/e2e/route-style-navigation.spec.ts
@@ -0,0 +1,313 @@
+import { expect, test, type Page } from '@playwright/test';
+
+const home = '/';
+const docs = '/docs/';
+const api = (language: string) => `/reference/api/${language}/`;
+const redis = (language: string) => `${api(language)}aspire.hosting.redis/redisresource/`;
+const routes = [home, docs, api('csharp'), api('typescript'), redis('csharp'), redis('typescript')];
+
+async function markNavigation(page: Page) {
+  await page.evaluate(() => {
+    Reflect.set(window, '__routeStyleLoaded', false);
+    document.addEventListener(
+      'astro:page-load',
+      () => {
+        Reflect.set(window, '__routeStyleLoaded', true);
+      },
+      { once: true }
+    );
+  });
+}
+
+async function settled(page: Page) {
+  await expect
+    .poll(() => page.evaluate(() => Reflect.get(window, '__routeStyleLoaded')), {
+      timeout: 30_000,
+    })
+    .toBe(true);
+  await expect(page.locator('html[data-astro-transition]')).toHaveCount(0);
+  expect(await page.evaluate(() => Reflect.get(window, '__routeStyleSession'))).toBe(true);
+}
+
+async function navigate(page: Page, href: string) {
+  await markNavigation(page);
+  await page.evaluate((destination) => {
+    const anchor = document.createElement('a');
+    anchor.id = 'route-style-link';
+    anchor.href = destination;
+    anchor.textContent = 'Navigate';
+    anchor.style.cssText = 'position:fixed;top:80px;left:0;z-index:2147483647';
+    document.body.append(anchor);
+  }, href);
+  await page.locator('#route-style-link').click({ force: true });
+  const destination = new URL(href, page.url());
+  await expect(page).toHaveURL(
+    (url) =>
+      url.pathname === destination.pathname &&
+      [...destination.searchParams].every(([key, value]) => url.searchParams.get(key) === value),
+    { timeout: 30_000 }
+  );
+  await settled(page);
+}
+
+async function appearance(page: Page) {
+  await expect(page.locator('main h1')).toHaveCount(1);
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+    window.scrollTo({ top: 0, behavior: 'instant' });
+  });
+  return page.evaluate(async () => {
+    const selectors = [
+      'html',
+      'body',
+      'header.header',
+      'header .header',
+      'header .title-wrapper',
+      'header .right-group',
+      'header .right-group-mobile',
+      'main h1',
+      'main > .content-panel',
+      '.sl-markdown-content',
+      '.home-hero-story',
+      '.home-hero-sticky',
+      '.home-hero-copy',
+      '.home-hero-summary',
+      '.home-hero-actions',
+      '.home-hero-product',
+      '.api-hero',
+      '.api-hero-summary',
+      '.api-search-input',
+      '.api-kind-badge',
+      '.topics-sidebar',
+    ];
+    const properties = [
+      'font-family',
+      'font-size',
+      'font-weight',
+      'line-height',
+      'letter-spacing',
+      'color',
+      'background-color',
+      'display',
+      'position',
+      'padding',
+      'margin-top',
+      'margin-bottom',
+      'width',
+      'max-width',
+      'grid-template-columns',
+      'gap',
+      'overflow-x',
+      'word-break',
+      'overflow-wrap',
+    ];
+    const styles = Object.fromEntries(
+      selectors.map((selector) => {
+        const element = document.querySelector(selector);
+        if (!element) return [selector, null];
+        element.getBoundingClientRect();
+        const computed = getComputedStyle(element);
+        return [
+          selector,
+          Object.fromEntries(
+            properties.map((property) => [property, computed.getPropertyValue(property)])
+          ),
+        ];
+      })
+    );
+    const root = document.documentElement;
+    const rootAttributes = Object.fromEntries(
+      [
+        'lang',
+        'dir',
+        'data-theme',
+        'data-has-sidebar',
+        'data-has-hero',
+        'data-apphost-lang',
+        'data-home-js',
+        'data-aspire-environment-state',
+        'data-sidebar-collapsed',
+        'data-topic-sidebar-collapsed',
+        'data-api-sidebar-ready',
+        'data-topic-sidebar-ready',
+      ].map((name) => [name, root.getAttribute(name)])
+    );
+    return {
+      styles,
+      rootAttributes,
+      rootClass: root.className,
+      stylesheets: Array.from(document.head.querySelectorAll('link[rel="stylesheet"]'), (link) =>
+        link.getAttribute('href')
+      ).sort(),
+      bodyClass: document.body.className,
+      bodyStyle: document.body.getAttribute('style'),
+      apiTitle: document.querySelector('main h1')?.classList.contains('api-page-title'),
+      searchCount: document.querySelectorAll('site-search').length,
+      actionsCount: document.querySelectorAll('.actions-container').length,
+      canonical: document.querySelector('link[rel="canonical"]')?.getAttribute('href'),
+      canonicalCount: document.querySelectorAll('link[rel="canonical"]').length,
+      titleCount: document.head.querySelectorAll('title').length,
+    };
+  });
+}
+
+for (const theme of ['light', 'dark']) {
+  test.describe(`${theme} route styles`, () => {
+    test.beforeEach(async ({ page, isMobile }) => {
+      await page.emulateMedia({ reducedMotion: 'reduce' });
+      await page.route('**/scripts/analytics/*.js', (route) =>
+        route.fulfill({ contentType: 'application/javascript', body: '' })
+      );
+      await page.route('**/wcp-consent.js', (route) =>
+        route.fulfill({ contentType: 'application/javascript', body: '' })
+      );
+      await page.addInitScript(
+        ({ theme, fallback }) => {
+          localStorage.setItem('starlight-theme', theme);
+          localStorage.setItem('aspireConsentRequired', 'false');
+          if (fallback)
+            Object.defineProperty(document, 'startViewTransition', {
+              configurable: true,
+              value: undefined,
+            });
+        },
+        { theme, fallback: isMobile }
+      );
+    });
+
+    test('fresh rendering matches API/search/Home, docs/Home, cross-language and history swaps', async ({
+      page,
+    }) => {
+      test.setTimeout(180000);
+      const baseline = new Map<string, Awaited<ReturnType<typeof appearance>>>();
+      for (const route of routes) {
+        await page.goto(route);
+        await expect(page.locator('html')).toHaveAttribute('data-theme', theme);
+        baseline.set(route, await appearance(page));
+      }
+      const matchesFresh = async (route: string) => {
+        await expect
+          .poll(() => appearance(page), {
+            message: `${route} must match its fresh ${theme} rendering after a client swap`,
+          })
+          .toEqual(baseline.get(route));
+      };
+      await page.goto(api('csharp'));
+      await page.evaluate(() => Reflect.set(window, '__routeStyleSession', true));
+      await page.locator('#api-search-input').fill('RedisResource');
+      const result = page.locator(`#api-search-results a[href="${redis('csharp')}"]`).first();
+      await expect(result).toBeVisible();
+      await markNavigation(page);
+      await result.click();
+      await settled(page);
+      await matchesFresh(redis('csharp'));
+      await navigate(page, home);
+      await matchesFresh(home);
+      for (const route of [
+        docs,
+        home,
+        api('csharp'),
+        api('typescript'),
+        redis('typescript'),
+        redis('csharp'),
+        home,
+      ]) {
+        await navigate(page, route);
+        await matchesFresh(route);
+      }
+      await markNavigation(page);
+      await page.goBack();
+      await settled(page);
+      await matchesFresh(redis('csharp'));
+      await markNavigation(page);
+      await page.goForward();
+      await settled(page);
+      await matchesFresh(home);
+    });
+
+    test('restores saved language and route-specific collapsed sidebars, with URL language taking precedence', async ({
+      page,
+    }) => {
+      test.setTimeout(120000);
+      await page.addInitScript(() => {
+        localStorage.setItem('aspire-lang', 'csharp');
+        localStorage.setItem('api-sidebar-collapsed', '1');
+        localStorage.setItem('topic-sidebar-collapsed', '1');
+      });
+      await page.goto(api('csharp'));
+      await expect(page.locator('html')).toHaveAttribute('data-sidebar-collapsed', '');
+      await page.evaluate(() => Reflect.set(window, '__routeStyleSession', true));
+      for (const route of [home, '/get-started/app-host/', api('typescript'), api('csharp')]) {
+        await navigate(page, route);
+        const isApi = route.startsWith('/reference/api/');
+        const isDoc = route === '/get-started/app-host/';
+        await expect(page.locator('html')).toHaveAttribute('data-apphost-lang', 'csharp');
+        await expect(page.locator('html[data-sidebar-collapsed]')).toHaveCount(isApi ? 1 : 0);
+        await expect(page.locator('html[data-topic-sidebar-collapsed]')).toHaveCount(isDoc ? 1 : 0);
+        if (isApi || isDoc) {
+          const prefix = isApi ? 'sidebar' : 'topic-sidebar';
+          await expect(page.locator(`#${prefix}-expand-btn`)).toHaveAttribute(
+            'aria-expanded',
+            'false'
+          );
+          await expect(page.locator(`#${prefix}-collapse-btn`)).toHaveAttribute(
+            'aria-hidden',
+            'true'
+          );
+        }
+      }
+      await navigate(page, '/get-started/app-host/?aspire-lang=typescript');
+      await expect(page.locator('html')).toHaveAttribute('data-apphost-lang', 'typescript');
+      await navigate(page, home);
+      await expect(page.locator('html')).toHaveAttribute('data-apphost-lang', 'typescript');
+    });
+
+    test('header install affordance retains responsive visibility and dialog layout after swaps', async ({
+      page,
+      isMobile,
+    }) => {
+      test.setTimeout(120000);
+      await page.goto(home);
+      await page.evaluate(() => Reflect.set(window, '__routeStyleSession', true));
+      const dialog = page.locator('#install-cli-modal');
+      const trigger = page.locator('header [data-open-install-modal]:visible');
+      if (page.viewportSize()!.width < 800) {
+        // The compact header intentionally omits the install action.
+        for (const route of [api('csharp'), docs, home]) {
+          await expect(trigger).toHaveCount(0);
+          await expect(dialog).not.toBeVisible();
+          await navigate(page, route);
+        }
+        await expect(trigger).toHaveCount(0);
+        return;
+      }
+      const openAndMeasure = async () => {
+        if (isMobile) await trigger.tap();
+        else await trigger.click();
+        await expect(page.locator('dialog[open]')).toHaveCount(1);
+        await expect(dialog).toBeVisible();
+        return dialog.evaluate((element) => {
+          const style = getComputedStyle(element);
+          const rect = element.getBoundingClientRect();
+          return {
+            color: style.color,
+            background: style.backgroundColor,
+            font: style.font,
+            width: rect.width,
+            fits: rect.left >= 0 && rect.right <= window.innerWidth,
+          };
+        });
+      };
+      const baseline = await openAndMeasure();
+      expect(baseline.fits).toBe(true);
+      for (const route of [api('csharp'), docs, home]) {
+        const close = dialog.getByRole('button', { name: 'Close modal', exact: true });
+        if (isMobile) await close.tap();
+        else await close.click();
+        await expect(dialog).not.toBeVisible();
+        await navigate(page, route);
+        expect(await openAndMeasure()).toEqual(baseline);
+      }
+    });
+  });
+}
diff --git a/src/frontend/tests/e2e/site-search.spec.ts b/src/frontend/tests/e2e/site-search.spec.ts
index 46c1a7281..d7c4c9c17 100644
--- a/src/frontend/tests/e2e/site-search.spec.ts
+++ b/src/frontend/tests/e2e/site-search.spec.ts
@@ -146,6 +146,38 @@ test.describe('site search dialog', () => {
     }
   });
 
+  test('API search result navigation restores homepage hero typography', async ({ page }) => {
+    await page.setViewportSize({ width: 2000, height: 1001 });
+    await page.goto('/');
+    await dismissCookieConsentIfVisible(page);
+
+    const hero = page.getByRole('heading', {
+      level: 1,
+      name: 'Compose distributed apps in code.',
+    });
+    const expectedFontSize = await hero.evaluate((element) => getComputedStyle(element).fontSize);
+
+    await page.goto('/reference/api/csharp/');
+    await page.evaluate(() => {
+      const result = document.createElement('a');
+      result.className = 'pagefind-ui__result-link';
+      result.href = '/';
+      result.textContent = 'Home';
+      result.style.cssText =
+        'position:fixed;inset-block-start:0;inset-inline-start:0;z-index:2147483647';
+      document.body.append(result);
+    });
+
+    await navigateClient(page, () =>
+      page.locator('.pagefind-ui__result-link', { hasText: 'Home' }).click()
+    );
+    await expect(page).toHaveURL((url) => url.pathname === '/');
+    await expect(hero).not.toHaveClass(/api-page-title/);
+    await expect.poll(() => hero.evaluate((element) => getComputedStyle(element).fontSize)).toBe(
+      expectedFontSize
+    );
+  });
+
   test('navigation during the lazy UI import mounts only the current search instance', async ({
     page,
   }) => {
diff --git a/src/frontend/tests/e2e/site-ui-navigation.spec.ts b/src/frontend/tests/e2e/site-ui-navigation.spec.ts
new file mode 100644
index 000000000..e4ec9bd73
--- /dev/null
+++ b/src/frontend/tests/e2e/site-ui-navigation.spec.ts
@@ -0,0 +1,173 @@
+import { expect, test, type Page } from '@playwright/test';
+import { dismissCookieConsentIfVisible } from '@tests/e2e/helpers';
+
+async function navigateClient(page: Page, href: string) {
+  await page.evaluate((destination) => {
+    Reflect.set(window, '__dependencyPageLoaded', false);
+    document.addEventListener(
+      'astro:page-load',
+      () => {
+        Reflect.set(window, '__dependencyPageLoaded', true);
+      },
+      { once: true }
+    );
+    const link = document.createElement('a');
+    link.id = 'dependency-navigation-link';
+    link.href = destination;
+    link.textContent = 'Navigate to dependency test page';
+    link.style.cssText = 'position:fixed;top:80px;left:0;z-index:2147483647';
+    document.body.append(link);
+  }, href);
+  await page.locator('#dependency-navigation-link').click();
+  await expect
+    .poll(() => page.evaluate(() => Reflect.get(window, '__dependencyPageLoaded')), {
+      timeout: 30000,
+    })
+    .toBe(true);
+  await expect(page.locator('html[data-astro-transition]')).toHaveCount(0);
+  expect(await page.evaluate(() => Reflect.get(window, '__dependencySession'))).toBe(true);
+}
+
+for (const fallback of [false, true]) {
+  test.describe(fallback ? 'site UI swap fallback' : 'site UI native transitions', () => {
+    test.beforeEach(async ({ page, isMobile }) => {
+      test.skip(
+        isMobile && !fallback,
+        'Chromium touch emulation aborts native transitions; touch projects cover the swap fallback.'
+      );
+      // These runtime tests must never submit analytics events.
+      await page.route('**/scripts/analytics/*.js', (route) =>
+        route.fulfill({
+          contentType: 'application/javascript',
+          body: '',
+        })
+      );
+      await page.addInitScript((swap) => {
+        localStorage.setItem('starlight-theme', 'light');
+        if (swap) {
+          Object.defineProperty(document, 'startViewTransition', {
+            configurable: true,
+            value: undefined,
+          });
+        }
+        const renders = new WeakMap<Element, number>();
+        new MutationObserver((mutations) => {
+          for (const { target } of mutations) {
+            if (!(target instanceof Element) || !target.matches('pre.mermaid[data-processed]'))
+              continue;
+            const count = (renders.get(target) ?? 0) + 1;
+            renders.set(target, count);
+            target.setAttribute('data-test-render-count', String(count));
+          }
+        }).observe(document, {
+          subtree: true,
+          attributes: true,
+          attributeFilter: ['data-processed'],
+        });
+      }, fallback);
+    });
+
+    test('renders two diagrams once per page/theme across repeat visits and history', async ({
+      page,
+    }) => {
+      test.setTimeout(120000);
+      const errors: string[] = [];
+      page.on('pageerror', (error) => errors.push(error.message));
+      page.on('console', (message) => {
+        if (/\[(?:astro-)?mermaid\]/.test(message.text())) errors.push(message.text());
+      });
+      await page.goto('/docs/');
+      await dismissCookieConsentIfVisible(page);
+      await page.evaluate(() => Reflect.set(window, '__dependencySession', true));
+      const diagrams = page.locator('pre.mermaid');
+      const expectRenders = async (count: number) => {
+        await expect(diagrams).toHaveCount(2);
+        for (const diagram of await diagrams.all()) {
+          await expect(diagram.locator(':scope > svg')).toHaveCount(1, { timeout: 30000 });
+          await expect(diagram).toHaveAttribute('data-test-render-count', String(count));
+        }
+      };
+      for (let visit = 0; visit < 2; visit++) {
+        await navigateClient(page, '/get-started/first-app/');
+        await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
+        await expectRenders(1);
+        await page.evaluate(() => {
+          const html = document.documentElement;
+          const theme = html.getAttribute('data-theme')!;
+          html.removeAttribute('data-theme');
+          html.setAttribute('data-theme', theme);
+        });
+        await expectRenders(1);
+        for (const [theme, count] of [
+          ['dark', 2],
+          ['light', 3],
+        ] as const) {
+          await page.locator(`#footer-theme-toggle [data-theme-option="${theme}"]`).click();
+          await expect(page.locator('html')).toHaveAttribute('data-theme', theme);
+          await expectRenders(count);
+        }
+        await navigateClient(page, '/docs/');
+        await expect(page.locator('html')).toHaveAttribute('data-theme', 'light');
+      }
+      await page.goBack();
+      await expectRenders(1);
+      expect(await page.evaluate(() => Reflect.get(window, '__dependencySession'))).toBe(true);
+      expect(errors).toEqual([]);
+    });
+
+    test('activates scroll once per mouse, touch, Enter and Space after repeated swaps', async ({
+      page,
+      isMobile,
+    }) => {
+      test.setTimeout(120000);
+      await page.emulateMedia({ reducedMotion: 'reduce' });
+      await page.goto('/docs/');
+      await dismissCookieConsentIfVisible(page);
+      await page.evaluate(() => {
+        Reflect.set(window, '__dependencySession', true);
+        const scrolls: ScrollToOptions[] = [];
+        Reflect.set(window, '__dependencyScrolls', scrolls);
+        const scrollTo = window.scrollTo.bind(window);
+        window.scrollTo = (options?: ScrollToOptions | number, y?: number) => {
+          if (typeof options === 'number') scrollTo(options, y ?? 0);
+          else {
+            if (options?.top === 0) scrolls.push(options);
+            scrollTo(options);
+          }
+        };
+      });
+      for (let visit = 0; visit < 2; visit++) {
+        await navigateClient(page, '/get-started/app-host/');
+        const button = page.locator('#scroll-to-top-button');
+        await expect(button).toHaveCount(1);
+        for (const activation of ['pointer', 'Enter', 'Space']) {
+          await page.evaluate(() => window.scrollTo({ top: 800, behavior: 'instant' }));
+          await expect(button).toBeVisible();
+          await page.evaluate(() =>
+            Reflect.set(
+              window,
+              '__dependencyScrollCountBefore',
+              Reflect.get(window, '__dependencyScrolls').length
+            )
+          );
+          if (activation === 'pointer') {
+            if (isMobile) await button.tap();
+            else await button.click();
+          } else {
+            await button.focus();
+            await page.keyboard.press(activation);
+          }
+          await expect.poll(() => page.evaluate(() => window.scrollY)).toBe(0);
+          expect(
+            await page.evaluate(() => {
+              const scrolls: ScrollToOptions[] = Reflect.get(window, '__dependencyScrolls');
+              const before: number = Reflect.get(window, '__dependencyScrollCountBefore');
+              return scrolls.slice(before);
+            })
+          ).toEqual([{ top: 0, behavior: 'auto' }]);
+        }
+        await navigateClient(page, '/docs/');
+      }
+    });
+  });
+}
diff --git a/src/frontend/tests/unit/analytics-script-contracts.vitest.test.ts b/src/frontend/tests/unit/analytics-script-contracts.vitest.test.ts
index b28b01225..ef3c1804b 100644
--- a/src/frontend/tests/unit/analytics-script-contracts.vitest.test.ts
+++ b/src/frontend/tests/unit/analytics-script-contracts.vitest.test.ts
@@ -1,7 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { expect, test } from 'vitest';
+import { runInNewContext } from 'node:vm';
+import { expect, test, vi } from 'vitest';
 
 const testsDir = path.dirname(fileURLToPath(import.meta.url));
 const frontendRoot = path.resolve(testsDir, '..', '..');
@@ -41,3 +42,104 @@ test('analytics asset files contain javascript bootstrap code', () => {
   expect(oneDsScript.trimStart().startsWith('<')).toBe(false);
   expect(trackScript.trimStart().startsWith('<')).toBe(false);
 });
+
+function analyticsFixture(origin = 'https://aspire.dev') {
+  type TrackedElement = {
+    tagName: string;
+    href?: string;
+    textContent: string;
+    attributes: { name: string; value: string }[];
+    getAttribute: (name: string) => string | null;
+  };
+  type TrackEvent = { target: { closest: (selector: string) => TrackedElement | null } };
+  const initialize = vi.fn<(config: unknown, extensions: unknown[]) => void>();
+  const capturePageAction = vi.fn<(target: TrackedElement, overrides: Record<string, string>) => void>();
+  const addEventListener = vi.fn<(type: string, listener: (event: TrackEvent) => void) => void>();
+  const console = { debug: vi.fn(), warn: vi.fn() };
+  const context = {
+    location: { origin },
+    window: {},
+    document: { addEventListener },
+    console,
+    oneDS: {
+      ApplicationInsights: class {
+        initialize = initialize;
+        capturePageAction = capturePageAction;
+      },
+    },
+  };
+  const bootstrap = () => { runInNewContext(read('public/scripts/analytics/1ds.js'), context); };
+  const tracking = () => { runInNewContext(read('public/scripts/analytics/track.js'), context); };
+  return { initialize, capturePageAction, addEventListener, console, bootstrap, tracking };
+}
+
+test('analytics excludes unload without disabling other lifecycle or click capture', () => {
+  const fixture = analyticsFixture();
+  fixture.bootstrap();
+  fixture.bootstrap();
+  expect(fixture.initialize).toHaveBeenCalledOnce();
+  expect(fixture.initialize.mock.calls[0][0]).toMatchObject({
+    disablePageUnloadEvents: ['unload'],
+    webAnalyticsConfiguration: {
+      autoCapture: { onUnload: true, click: true, pageView: true },
+    },
+  });
+  expect(fixture.console.debug).not.toHaveBeenCalled();
+  expect(fixture.console.warn).not.toHaveBeenCalled();
+});
+
+test('analytics and tracking remain inactive on other origins', () => {
+  const fixture = analyticsFixture('http://localhost:4321');
+  fixture.bootstrap();
+  fixture.tracking();
+  expect(fixture.initialize).not.toHaveBeenCalled();
+  expect(fixture.addEventListener).not.toHaveBeenCalled();
+  expect(fixture.console.debug).not.toHaveBeenCalled();
+});
+
+test('tracking binds once, forwards nested clicks and stays quiet on success', () => {
+  const fixture = analyticsFixture();
+  fixture.tracking();
+  expect(fixture.addEventListener).not.toHaveBeenCalled();
+  fixture.bootstrap();
+  fixture.tracking();
+  fixture.tracking();
+  expect(fixture.addEventListener).toHaveBeenCalledOnce();
+  const [event, listener] = fixture.addEventListener.mock.calls[0];
+  expect(event).toBe('click');
+  const link = {
+    tagName: 'A',
+    href: 'https://aspire.dev/docs/',
+    textContent: ' Docs ',
+    attributes: [{ name: 'data-track-source-name', value: 'header' }],
+    getAttribute: () => 'docs-link',
+  };
+  listener({ target: { closest: () => link } });
+  expect(fixture.capturePageAction).toHaveBeenCalledExactlyOnceWith(link, {
+    name: 'docs-link', sourceName: 'header', href: link.href, text: 'Docs',
+  });
+  expect(fixture.console.debug).not.toHaveBeenCalled();
+  expect(fixture.console.warn).not.toHaveBeenCalled();
+});
+
+test('initialization and capture failures remain visible', () => {
+  const initialization = analyticsFixture();
+  initialization.initialize.mockImplementation(() => { throw new Error('initialization failed'); });
+  initialization.bootstrap();
+  expect(initialization.console.warn).toHaveBeenCalledWith(
+    '[1ds] Failed to initialize Application Insights:', expect.any(Error),
+  );
+
+  const tracking = analyticsFixture();
+  tracking.bootstrap();
+  tracking.tracking();
+  tracking.capturePageAction.mockImplementation(() => { throw new Error('capture failed'); });
+  tracking.addEventListener.mock.calls[0][1]({
+    target: { closest: () => ({
+      tagName: 'BUTTON', textContent: '', attributes: [], getAttribute: () => 'button',
+    }) },
+  });
+  expect(tracking.console.warn).toHaveBeenCalledWith(
+    '[track] Failed to track event:', expect.any(Error),
+  );
+});
diff --git a/src/frontend/tests/unit/custom-components.vitest.test.ts b/src/frontend/tests/unit/custom-components.vitest.test.ts
index 2bafedbd4..0be72ca78 100644
--- a/src/frontend/tests/unit/custom-components.vitest.test.ts
+++ b/src/frontend/tests/unit/custom-components.vitest.test.ts
@@ -41,6 +41,7 @@ import ReleaseCommunity from '@components/ReleaseCommunity.astro';
 import SampleCard from '@components/SampleCard.astro';
 import SampleDetail from '@components/SampleDetail.astro';
 import SampleGrid from '@components/SampleGrid.astro';
+import ScrollToTop from '@components/ScrollToTop.astro';
 import SessionCard from '@components/SessionCard.astro';
 import SessionGrid from '@components/SessionGrid.astro';
 import SimpleAppHostCode from '@components/SimpleAppHostCode.astro';
@@ -82,6 +83,20 @@ type BasicRenderCase = {
   requestUrl?: string;
 };
 
+it.each([
+  ['en', 'Scroll to top'], ['fr', 'Retour en haut'], ['pt-BR', 'Voltar ao topo'],
+  ['zh-CN', '回到顶部'], ['es-ES', 'Ir arriba'], ['unknown', 'Scroll to top'],
+])('ScrollToTop renders the existing label for %s', async (lang, label) => {
+  const route = {
+    lang, editUrl: '',
+    entry: { id: 'docs/test', slug: 'docs/test', filePath: '', data: {} },
+  };
+  const html = await renderComponent(ScrollToTop, { locals: { starlightRoute: route } });
+  expect(html).toContain(`aria-label="${label}"`);
+  expect(html).toContain('id="scroll-to-top-button"');
+  expect(html).toContain('type="button"');
+});
+
 const statementPlayerTranslations = {
   da: daTranslations.landing.statementPlayer,
   de: deTranslations.landing.statementPlayer,
diff --git a/src/frontend/tests/unit/deployment-guard.vitest.test.ts b/src/frontend/tests/unit/deployment-guard.vitest.test.ts
new file mode 100644
index 000000000..4b099338a
--- /dev/null
+++ b/src/frontend/tests/unit/deployment-guard.vitest.test.ts
@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+import { ModuleKind, ScriptTarget, transpileModule } from 'typescript';
+import { describe, expect, test, vi } from 'vitest';
+
+const source = readFileSync(
+  new URL('../../src/scripts/deployment-guard.ts', import.meta.url),
+  'utf8',
+);
+const script = transpileModule(source, {
+  compilerOptions: { module: ModuleKind.CommonJS, target: ScriptTarget.ES2022 },
+}).outputText;
+
+function fixture(running: string | null, incoming: string | null) {
+  const events = new EventTarget();
+  const meta = running === null ? null : { content: running };
+  const warn = vi.fn();
+  runInNewContext(script, {
+    exports: {},
+    console: { warn },
+    document: {
+      querySelector: () => meta,
+      addEventListener: events.addEventListener.bind(events),
+    },
+  });
+  const controller = new AbortController();
+  const load = vi.fn(async () => {});
+  const event = Object.assign(new Event('astro:before-preparation', { cancelable: true }), {
+    loader: load,
+    signal: controller.signal,
+    newDocument: { querySelector: () => incoming === null ? null : { content: incoming } },
+  });
+  events.dispatchEvent(event);
+  return { event, load, controller, warn, meta };
+}
+
+describe('deployment boundary navigation', () => {
+  test.each([
+    ['same deployment', 'build-a', 'build-a', false],
+    ['new deployment', 'build-a', 'build-b', true],
+    ['missing destination metadata', 'build-a', null, true],
+    ['missing running metadata', null, 'build-b', true],
+    ['unversioned local documents', null, null, false],
+    ['trimmed metadata', ' build-a ', 'build-a', false],
+  ])('%s', async (_label, running, incoming, reload) => {
+    const { event, load, warn } = fixture(running, incoming);
+    expect(event.defaultPrevented).toBe(false);
+    await event.loader();
+    expect(load).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(reload);
+    expect(warn).toHaveBeenCalledTimes(reload && (!running || !incoming) ? 1 : 0);
+  });
+
+  test('retains the running deployment instead of reading mutated page metadata', async () => {
+    const { event, meta } = fixture('build-a', 'build-b');
+    meta!.content = 'build-b';
+    await event.loader();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  test('respects navigation cancellation and aborts during loading', async () => {
+    const canceled = fixture('build-a', null);
+    canceled.event.preventDefault();
+    await canceled.event.loader();
+    expect(canceled.warn).not.toHaveBeenCalled();
+
+    const aborted = fixture('build-a', 'build-b');
+    aborted.load.mockImplementation(() => {
+      aborted.controller.abort();
+      return Promise.resolve();
+    });
+    await aborted.event.loader();
+    expect(aborted.event.defaultPrevented).toBe(false);
+  });
+
+  test('does not hide loader failures', async () => {
+    const { event, load } = fixture('build-a', 'build-b');
+    load.mockRejectedValue(new Error('navigation failed'));
+    await expect(event.loader()).rejects.toThrow('navigation failed');
+    expect(event.defaultPrevented).toBe(false);
+  });
+});
diff --git a/src/frontend/tests/unit/navigation-preferences.vitest.test.ts b/src/frontend/tests/unit/navigation-preferences.vitest.test.ts
new file mode 100644
index 000000000..fa60377f0
--- /dev/null
+++ b/src/frontend/tests/unit/navigation-preferences.vitest.test.ts
@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+import { expect, test, vi } from 'vitest';
+
+const head = readFileSync(
+  new URL('../../src/components/starlight/Head.astro', import.meta.url),
+  'utf8'
+);
+const script = [...head.matchAll(/<script is:inline>([\s\S]*?)<\/script>/g)].find((match) =>
+  match[1].includes('var appHostLangLabels')
+)?.[1];
+if (!script) throw new Error('Navigation preference initializer not found.');
+
+function root() {
+  const attributes = new Map<string, string>();
+  return {
+    attributes,
+    setAttribute: (name: string, value: string) => attributes.set(name, value),
+    toggleAttribute(name: string, present: boolean) {
+      if (present) attributes.set(name, '');
+      else attributes.delete(name);
+    },
+  };
+}
+
+test('restores destination preferences before sidebar initialization without duplicating listeners', () => {
+  const stored = new Map([
+    ['aspire-lang', 'csharp'],
+    ['api-sidebar-collapsed', '1'],
+    ['topic-sidebar-collapsed', '1'],
+  ]);
+  const events = new EventTarget();
+  const document = {
+    documentElement: root(),
+    readyState: 'complete',
+    addEventListener: vi.fn(events.addEventListener.bind(events)),
+  };
+  const window = { location: new URL('https://aspire.dev/reference/api/csharp/') };
+  const context = {
+    document,
+    window,
+    URL,
+    localStorage: {
+      getItem: (key: string) => stored.get(key) ?? null,
+      setItem: (key: string, value: string) => stored.set(key, value),
+    },
+  };
+  runInNewContext(script, context);
+  runInNewContext(script, context);
+  expect(
+    document.addEventListener.mock.calls.filter(([type]) => type === 'astro:before-swap')
+  ).toHaveLength(1);
+  expect(document.documentElement.attributes.get('data-apphost-lang')).toBe('csharp');
+
+  for (const [path, language, apiCollapsed, topicCollapsed] of [
+    ['/reference/api/typescript/', 'csharp', true, false],
+    ['/get-started/app-host/?aspire-lang=typescript', 'typescript', false, true],
+    ['/reference/api/csharp/', 'typescript', true, false],
+  ] as const) {
+    const nextRoot = root();
+    nextRoot.setAttribute('data-theme', 'dark');
+    const event = Object.assign(new Event('astro:before-swap'), {
+      newDocument: { documentElement: nextRoot },
+      to: new URL(path, 'https://aspire.dev'),
+    });
+    events.dispatchEvent(event);
+    expect(nextRoot.attributes.get('data-apphost-lang')).toBe(language);
+    expect(nextRoot.attributes.has('data-sidebar-collapsed')).toBe(apiCollapsed);
+    expect(nextRoot.attributes.has('data-topic-sidebar-collapsed')).toBe(topicCollapsed);
+    expect(nextRoot.attributes.get('data-theme')).toBe('dark');
+    expect(event.defaultPrevented).toBe(false);
+  }
+  expect(stored.get('starlight-synced-tabs__aspire-lang')).toBe('TypeScript');
+});
+
+test('keeps explicit destination language usable when browser storage is unavailable', () => {
+  const events = new EventTarget();
+  const nextRoot = root();
+  runInNewContext(script, {
+    URL,
+    window: { location: new URL('https://aspire.dev/') },
+    document: {
+      documentElement: root(),
+      readyState: 'complete',
+      addEventListener: events.addEventListener.bind(events),
+    },
+    localStorage: {
+      getItem() {
+        throw new DOMException('Storage blocked', 'SecurityError');
+      },
+      setItem() {
+        throw new DOMException('Storage blocked', 'SecurityError');
+      },
+    },
+  });
+  events.dispatchEvent(
+    Object.assign(new Event('astro:before-swap'), {
+      newDocument: { documentElement: nextRoot },
+      to: new URL('https://aspire.dev/get-started/app-host/?aspire-lang=csharp'),
+    })
+  );
+  expect(nextRoot.attributes.get('data-apphost-lang')).toBe('csharp');
+});
diff --git a/src/frontend/tests/unit/navigation-theme.vitest.test.ts b/src/frontend/tests/unit/navigation-theme.vitest.test.ts
new file mode 100644
index 000000000..7dc9139fa
--- /dev/null
+++ b/src/frontend/tests/unit/navigation-theme.vitest.test.ts
@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+import { transpileModule, ScriptTarget } from 'typescript';
+import { expect, test } from 'vitest';
+
+const head = readFileSync(
+  new URL('../../src/components/starlight/Head.astro', import.meta.url),
+  'utf8'
+);
+test('ClientRouter owns transitions without a second cross-document opt-in', () => {
+  const css = readFileSync(new URL('../../src/styles/site.css', import.meta.url), 'utf8');
+  expect(head).toContain('<ClientRouter fallback="swap" />');
+  expect(css).not.toMatch(/@view-transition\s*\{[^}]*navigation:\s*auto/);
+});
+
+const source = head.match(
+  /<script>\s*import '@scripts\/deployment-guard';([\s\S]*?)<\/script>/
+)?.[1];
+if (!source) throw new Error('Shared navigation theme script not found.');
+const script = transpileModule(source.replace("import '@scripts/mermaid';", ''), {
+  compilerOptions: { target: ScriptTarget.ES2022 },
+}).outputText;
+
+test.each(['light', 'dark'])(
+  'preserves effective %s theme without replacing other route state',
+  (theme) => {
+    const events = new EventTarget();
+    runInNewContext(script, {
+      document: {
+        documentElement: { dataset: { theme } },
+        addEventListener: events.addEventListener.bind(events),
+      },
+    });
+    const next = { documentElement: { dataset: { theme: 'server-default', locale: 'fr' } } };
+    events.dispatchEvent(
+      Object.assign(new Event('astro:before-preparation'), { newDocument: next })
+    );
+    expect(next.documentElement.dataset.theme).toBe('server-default');
+    const swap = Object.assign(new Event('astro:before-swap'), { newDocument: next });
+    events.dispatchEvent(swap);
+    expect(next.documentElement.dataset).toEqual({ theme, locale: 'fr' });
+    expect(swap.defaultPrevented).toBe(false);
+  }
+);
diff --git a/src/frontend/tests/unit/pivot-selector-lifecycle.vitest.test.ts b/src/frontend/tests/unit/pivot-selector-lifecycle.vitest.test.ts
new file mode 100644
index 000000000..3ff555660
--- /dev/null
+++ b/src/frontend/tests/unit/pivot-selector-lifecycle.vitest.test.ts
@@ -0,0 +1,406 @@
+import { getEventListeners } from 'node:events';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+class ElementStub extends EventTarget {
+  dataset: Record<string, string> = {};
+  style = { display: '', height: '', marginBottom: '' };
+  attributes = new Map<string, string>();
+  elements = new Map<string, ElementStub>();
+  buttons: ElementStub[] = [];
+  classes = new Set<string>();
+  classList = {
+    toggle: (name: string, enabled: boolean) => {
+      if (enabled) this.classes.add(name);
+      else this.classes.delete(name);
+    },
+    remove: (...names: string[]) => names.forEach((name) => this.classes.delete(name)),
+    contains: (name: string) => this.classes.has(name),
+  };
+  id = '';
+  textContent = '';
+  disabled = false;
+  offsetParent: object | null = {};
+  getBoundingClientRect = vi.fn(() => ({ top: 200, height: 100 }));
+  after = vi.fn();
+  remove = vi.fn();
+  setAttribute(name: string, value: string) {
+    this.attributes.set(name, value);
+  }
+  removeAttribute(name: string) {
+    this.attributes.delete(name);
+  }
+  querySelector(query: string) {
+    return this.elements.get(query) ?? null;
+  }
+  querySelectorAll() {
+    return this.buttons;
+  }
+}
+
+describe('PivotSelector element lifecycle', () => {
+  let PivotSelector: typeof import('@components/pivot-selector').PivotSelector;
+  let roots: InstanceType<typeof PivotSelector>[];
+  let blocks: ElementStub[];
+  let headings: ElementStub[];
+  let placeholders: ElementStub[];
+  let documentEvents: EventTarget;
+  let windowEvents: EventTarget;
+  let frames: Map<number, FrameRequestCallback>;
+  let nextFrame: number;
+  let scrollY: number;
+  let desktop: boolean;
+  let location: URL;
+  let storage: Map<string, string>;
+  let replaceState: ReturnType<typeof vi.fn>;
+  let scrollTo: ReturnType<typeof vi.fn>;
+  let state: { index: number; scrollX: number; scrollY: number; custom: string };
+  let html: ElementStub;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    roots = [];
+    blocks = [];
+    headings = [];
+    placeholders = [];
+    frames = new Map();
+    nextFrame = 0;
+    scrollY = 0;
+    desktop = true;
+    location = new URL('https://aspire.dev/get-started/first-app/?keep=1#section');
+    storage = new Map();
+    html = new ElementStub();
+    state = { index: 3, scrollX: 0, scrollY: 120, custom: 'preserved' };
+    documentEvents = new EventTarget();
+    windowEvents = new EventTarget();
+    replaceState = vi.fn((_state: unknown, _unused: string, url: URL) => {
+      location = url;
+    });
+    scrollTo = vi.fn();
+    vi.stubGlobal('HTMLElement', ElementStub);
+    vi.stubGlobal('customElements', { define: vi.fn() });
+    vi.stubGlobal('getComputedStyle', () => ({ marginBottom: '24px' }));
+    vi.stubGlobal('localStorage', {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+    });
+    vi.stubGlobal(
+      'document',
+      Object.assign(documentEvents, {
+        readyState: 'complete',
+        documentElement: html,
+        querySelectorAll: (query: string) =>
+          query === 'aspire-pivot-selector'
+            ? roots
+            : query === '[data-pivot-block]'
+              ? blocks
+              : headings,
+        getElementById: (id: string) => headings.find((heading) => heading.id === id) ?? null,
+        createElement: () => {
+          const element = new ElementStub();
+          placeholders.push(element);
+          return element;
+        },
+      })
+    );
+    vi.stubGlobal(
+      'window',
+      Object.defineProperties(windowEvents, {
+        location: { get: () => location },
+        scrollY: { get: () => scrollY },
+        history: { value: { state, replaceState } },
+        matchMedia: { value: () => ({ matches: desktop }) },
+        scrollTo: { value: scrollTo },
+        setTimeout: { value: setTimeout },
+        clearTimeout: { value: clearTimeout },
+        requestAnimationFrame: {
+          value: (callback: FrameRequestCallback) => {
+            frames.set(++nextFrame, callback);
+            return nextFrame;
+          },
+        },
+        cancelAnimationFrame: { value: (id: number) => frames.delete(id) },
+      })
+    );
+    ({ PivotSelector } = await import('@components/pivot-selector'));
+  });
+
+  afterEach(() => {
+    roots.forEach((root) => root.disconnectedCallback());
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  function createRoot(key = 'aspire-lang', options = ['typescript', 'csharp', 'disabled']) {
+    const selector = new ElementStub();
+    selector.buttons = options.map((id) => {
+      const button = new ElementStub();
+      button.dataset.pivotOption = id;
+      button.disabled = id === 'disabled';
+      return button;
+    });
+    const collapse = new ElementStub();
+    const expand = new ElementStub();
+    const root = Object.assign(new PivotSelector(), {
+      elements: new Map([
+        ['.pivot-selector', selector],
+        ['.pivot-collapse-btn', collapse],
+        ['.pivot-expand-btn', expand],
+      ]),
+      buttons: selector.buttons,
+    });
+    root.dataset.pivotKey = key;
+    roots.push(root);
+    root.connectedCallback();
+    return { root, selector, buttons: selector.buttons, collapse, expand };
+  }
+
+  function pageLoad() {
+    documentEvents.dispatchEvent(new Event('astro:page-load'));
+  }
+
+  it('initializes at DOM readiness while an async resource keeps page-load pending', () => {
+    Reflect.set(document, 'readyState', 'loading');
+    const { selector, buttons } = createRoot();
+    documentEvents.dispatchEvent(new Event('DOMContentLoaded'));
+    expect(selector.dataset.pivotInitialized).toBe('true');
+    expect(buttons[0].classes.has('active')).toBe(true);
+    expect(getEventListeners(documentEvents, 'astro:page-load')).toHaveLength(1);
+    pageLoad();
+    expect(getEventListeners(windowEvents, 'scroll')).toHaveLength(1);
+  });
+
+  function flushFrames() {
+    const callbacks = [...frames.values()];
+    frames.clear();
+    callbacks.forEach((callback) => callback(0));
+  }
+
+  function scroll(top: number) {
+    scrollY = top;
+    windowEvents.dispatchEvent(new Event('scroll'));
+    flushFrames();
+  }
+
+  function float(root: InstanceType<typeof PivotSelector>) {
+    vi.spyOn(root, 'getBoundingClientRect').mockImplementation(() => ({
+      top: 200 - scrollY,
+      height: 100,
+      width: 400,
+      left: 0,
+      right: 400,
+      bottom: 300 - scrollY,
+      x: 0,
+      y: 200 - scrollY,
+      toJSON: () => ({}),
+    }));
+    flushFrames();
+    scroll(300);
+    expect(root.classList.contains('floating')).toBe(true);
+    expect(root.classList.contains('collapsed')).toBe(true);
+  }
+
+  it('waits for the destination URL, mounts once, and preserves router metadata and URL parts', () => {
+    const { root, selector, buttons } = createRoot();
+    storage.set('aspire-lang', 'csharp');
+    expect(replaceState).not.toHaveBeenCalled();
+    location.searchParams.set('aspire-lang', 'typescript');
+    pageLoad();
+    root.connectedCallback();
+    pageLoad();
+    expect(replaceState).toHaveBeenCalledExactlyOnceWith(state, '', location);
+    expect(location.search).toBe('?keep=1&aspire-lang=typescript');
+    expect(location.hash).toBe('#section');
+    expect(selector.dataset.pivotInitialized).toBe('true');
+    expect(buttons[0].classes.has('active')).toBe(true);
+    expect(storage.get('starlight-synced-tabs__aspire-lang')).toBe('TypeScript');
+    expect(html.dataset.apphostLang).toBe('typescript');
+    buttons[1].dispatchEvent(new Event('click'));
+    expect(storage.get('aspire-lang')).toBe('csharp');
+    expect(storage.get('starlight-synced-tabs__aspire-lang')).toBe('C#');
+    expect(replaceState.mock.calls[1][0]).toBe(state);
+    expect(getEventListeners(windowEvents, 'scroll')).toHaveLength(1);
+    expect(getEventListeners(windowEvents, 'resize')).toHaveLength(1);
+    expect(getEventListeners(documentEvents, 'astro:page-load')).toHaveLength(0);
+  });
+
+  it.each([
+    ['disabled', 'csharp', 'csharp'],
+    ['invalid', 'disabled', 'typescript'],
+    ['', '', 'typescript'],
+  ])('validates query %s and preference %s, selecting %s', (query, stored, expected) => {
+    location.searchParams.set('aspire-lang', query);
+    storage.set('aspire-lang', stored);
+    const { buttons } = createRoot();
+    pageLoad();
+    expect(location.searchParams.get('aspire-lang')).toBe(expected);
+    buttons[2].dispatchEvent(new Event('click'));
+    expect(location.searchParams.get('aspire-lang')).toBe(expected);
+    expect(replaceState).toHaveBeenCalledOnce();
+  });
+
+  it('isolates independent option sets and synchronizes repeated selectors of the same key', () => {
+    blocks = ['typescript', 'csharp', 'typescript; csharp', 'docker', 'azure,docker'].map((id) => {
+      const block = new ElementStub();
+      block.dataset.pivotBlock = id;
+      return block;
+    });
+    const first = createRoot();
+    const second = createRoot();
+    const deployment = createRoot('deployment', ['docker', 'azure']);
+    pageLoad();
+    first.buttons[1].dispatchEvent(new Event('click'));
+    expect(second.buttons[1].classes.has('active')).toBe(true);
+    expect(blocks.map((block) => block.style.display)).toEqual(['none', '', '', '', '']);
+    deployment.buttons[1].dispatchEvent(new Event('click'));
+    expect(blocks.map((block) => block.style.display)).toEqual(['none', '', '', 'none', '']);
+    expect(location.searchParams.get('aspire-lang')).toBe('csharp');
+    expect(location.searchParams.get('deployment')).toBe('azure');
+    first.root.disconnectedCallback();
+    expect(getEventListeners(windowEvents, 'scroll')).toHaveLength(2);
+    second.buttons[0].dispatchEvent(new Event('click'));
+    expect(storage.get('aspire-lang')).toBe('typescript');
+  });
+
+  it('preserves heading position, coalesces restoration, and cancels it on disconnection', () => {
+    const heading = new ElementStub();
+    heading.id = 'section';
+    heading.getBoundingClientRect.mockReturnValue({ top: -30, height: 30 });
+    headings.push(heading);
+    const { root, buttons } = createRoot();
+    pageLoad();
+    flushFrames();
+    buttons[1].dispatchEvent(new Event('click'));
+    buttons[0].dispatchEvent(new Event('click'));
+    expect(frames.size).toBe(1);
+    heading.getBoundingClientRect.mockReturnValue({ top: 50, height: 30 });
+    flushFrames();
+    expect(scrollTo).toHaveBeenCalledExactlyOnceWith({ top: 80, behavior: 'instant' });
+    buttons[1].dispatchEvent(new Event('click'));
+    root.disconnectedCallback();
+    expect(frames.size).toBe(0);
+    flushFrames();
+    expect(scrollTo).toHaveBeenCalledOnce();
+  });
+
+  it('keeps floating/collapse timing and desktop titles, then returns to normal flow', () => {
+    const { root, collapse, expand } = createRoot();
+    pageLoad();
+    float(root);
+    expect(expand.attributes.get('title')).toBe('Show selector');
+    expect(placeholders[0].style).toEqual({
+      display: 'block',
+      height: '100px',
+      marginBottom: '24px',
+    });
+    expand.dispatchEvent(new Event('click'));
+    scroll(350);
+    vi.advanceTimersByTime(4999);
+    expect(root.classList.contains('collapsed')).toBe(false);
+    vi.advanceTimersByTime(1);
+    expect(root.classList.contains('collapsed')).toBe(false);
+    scroll(400);
+    vi.advanceTimersByTime(149);
+    expect(root.classList.contains('collapsed')).toBe(false);
+    vi.advanceTimersByTime(1);
+    expect(root.classList.contains('collapsed')).toBe(true);
+    expand.dispatchEvent(new Event('click'));
+    collapse.dispatchEvent(new Event('click'));
+    expect(vi.getTimerCount()).toBe(0);
+    desktop = false;
+    windowEvents.dispatchEvent(new Event('resize'));
+    expect(expand.attributes.has('title')).toBe(false);
+    scroll(0);
+    expect(root.classList.contains('floating')).toBe(false);
+    expect(root.classList.contains('collapsed')).toBe(false);
+    expect(placeholders[0].style.display).toBe('none');
+  });
+
+  it.each([
+    ['expanded', 'disconnect'],
+    ['expanded', 'before-swap'],
+    ['scrolling', 'disconnect'],
+    ['scrolling', 'before-swap'],
+  ] as const)(
+    'cancels all pending %s work and listeners on %s across repeated visits',
+    (phase, teardown) => {
+      const warn = vi.spyOn(console, 'warn');
+      for (let visit = 0; visit < 3; visit++) {
+        scrollY = 0;
+        const { root, buttons, expand } = createRoot();
+        pageLoad();
+        float(root);
+        expand.dispatchEvent(new Event('click'));
+        if (phase === 'scrolling') {
+          vi.advanceTimersByTime(5000);
+          scroll(400);
+        }
+        windowEvents.dispatchEvent(new Event('resize'));
+        windowEvents.dispatchEvent(new Event('scroll'));
+        expect(vi.getTimerCount()).toBe(2);
+        expect(frames.size).toBe(1);
+        const writes = replaceState.mock.calls.length;
+        if (teardown === 'before-swap') {
+          documentEvents.dispatchEvent(new Event('astro:before-swap'));
+        } else {
+          root.disconnectedCallback();
+        }
+        roots = roots.filter((candidate) => candidate !== root);
+        expect(getEventListeners(windowEvents, 'scroll')).toHaveLength(0);
+        expect(getEventListeners(windowEvents, 'resize')).toHaveLength(0);
+        expect(getEventListeners(documentEvents, 'astro:before-swap')).toHaveLength(0);
+        expect(getEventListeners(buttons[0], 'click')).toHaveLength(0);
+        expect(getEventListeners(expand, 'click')).toHaveLength(0);
+        expect(placeholders[visit].remove).toHaveBeenCalledOnce();
+        expect(vi.getTimerCount()).toBe(0);
+        expect(frames.size).toBe(0);
+        root.disconnectedCallback();
+        expect(placeholders[visit].remove).toHaveBeenCalledOnce();
+        pageLoad();
+        windowEvents.dispatchEvent(new Event('scroll'));
+        windowEvents.dispatchEvent(new Event('resize'));
+        buttons[1].dispatchEvent(new Event('click'));
+        vi.runAllTimers();
+        flushFrames();
+        expect(replaceState).toHaveBeenCalledTimes(writes);
+        expect(vi.getTimerCount()).toBe(0);
+        expect(frames.size).toBe(0);
+      }
+      expect(warn).not.toHaveBeenCalled();
+    }
+  );
+
+  it('keeps the active page usable when preparation starts but no swap follows', () => {
+    const { root, selector, buttons, expand } = createRoot();
+    pageLoad();
+    float(root);
+    expand.dispatchEvent(new Event('click'));
+    documentEvents.dispatchEvent(new Event('astro:before-preparation', { cancelable: true }));
+    expect(selector.dataset.pivotInitialized).toBe('true');
+    expect(root.classList.contains('floating')).toBe(true);
+    expect(vi.getTimerCount()).toBe(1);
+    expect(getEventListeners(windowEvents, 'scroll')).toHaveLength(1);
+    buttons[1].dispatchEvent(new Event('click'));
+    expect(storage.get('aspire-lang')).toBe('csharp');
+    expect(placeholders[0].remove).not.toHaveBeenCalled();
+  });
+
+  it('cancels connection before page-load and reconnects the same element with fresh URL state', () => {
+    const { root, buttons } = createRoot();
+    root.disconnectedCallback();
+    pageLoad();
+    expect(replaceState).not.toHaveBeenCalled();
+    expect(getEventListeners(documentEvents, 'astro:page-load')).toHaveLength(0);
+    for (const language of ['csharp', 'typescript']) {
+      location.searchParams.set('aspire-lang', language);
+      root.connectedCallback();
+      pageLoad();
+      expect(buttons.find((button) => button.classes.has('active'))?.dataset.pivotOption).toBe(
+        language
+      );
+      root.disconnectedCallback();
+      expect(frames.size).toBe(0);
+      expect(getEventListeners(windowEvents, 'scroll')).toHaveLength(0);
+    }
+  });
+});
diff --git a/src/frontend/tests/unit/remark-mermaid.vitest.test.ts b/src/frontend/tests/unit/remark-mermaid.vitest.test.ts
new file mode 100644
index 000000000..5e34b1fcb
--- /dev/null
+++ b/src/frontend/tests/unit/remark-mermaid.vitest.test.ts
@@ -0,0 +1,43 @@
+import { createMarkdownProcessor } from '@astrojs/markdown-remark';
+import { compile } from '@mdx-js/mdx';
+import { selectAll } from 'hast-util-select';
+import rehypeParse from 'rehype-parse';
+import { unified } from 'unified';
+import { runInNewContext } from 'node:vm';
+import { expect, test } from 'vitest';
+import { remarkMermaid } from '../../config/remark-mermaid.mjs';
+
+const definition = 'flowchart TD\nA{"Ready?"} --> B["<b>Yes & no</b>"]';
+const fence = '```mermaid\n' + definition + '\n```';
+
+test('renders Mermaid as escaped text, without a code-highlight wrapper', async () => {
+  const processor = await createMarkdownProcessor({ remarkPlugins: [remarkMermaid] });
+  const result = await processor.render(fence + '\n\n```typescript\nconst answer = 42;\n```');
+  const tree = unified().use(rehypeParse, { fragment: true }).parse(result.code);
+  const diagrams = selectAll('pre.mermaid', tree);
+  expect(diagrams).toHaveLength(1);
+  expect(diagrams[0].children).toEqual([
+    { type: 'text', value: definition, position: expect.anything() },
+  ]);
+  expect(selectAll('pre.mermaid code', tree)).toHaveLength(0);
+  expect(selectAll('pre code', tree)).toHaveLength(1);
+});
+
+test('preserves diagram syntax in MDX and nested content', async () => {
+  const compiled = await compile('<section>\n\n' + fence + '\n\n</section>', {
+    remarkPlugins: [remarkMermaid],
+    outputFormat: 'function-body',
+  });
+  type Node = { tag: string; props: { children?: Node | string; className?: string } };
+  const jsx = (tag: string, props: Node['props']): Node => ({ tag, props });
+  const module: { default: () => Node } = runInNewContext(
+    `(function () { ${String(compiled)} })({ jsx, jsxs: jsx });`,
+    { jsx }
+  );
+  const section = module.default();
+  expect(section.tag).toBe('section');
+  expect(section.props.children).toEqual({
+    tag: 'pre',
+    props: { className: 'mermaid', children: definition },
+  });
+});
diff --git a/src/frontend/tests/unit/site-ui-runtime.vitest.test.ts b/src/frontend/tests/unit/site-ui-runtime.vitest.test.ts
new file mode 100644
index 000000000..34fd4b06a
--- /dev/null
+++ b/src/frontend/tests/unit/site-ui-runtime.vitest.test.ts
@@ -0,0 +1,564 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getEventListeners } from 'node:events';
+import { readFileSync } from 'node:fs';
+import { runInNewContext } from 'node:vm';
+import { ModuleKind, ScriptTarget, transpileModule } from 'typescript';
+import type { AsyncIconLoader } from 'mermaid';
+
+const mermaidSource = readFileSync(
+  new URL('../../src/scripts/mermaid.ts', import.meta.url),
+  'utf8'
+);
+const scrollComponent = readFileSync(
+  new URL('../../src/components/ScrollToTop.astro', import.meta.url),
+  'utf8'
+);
+const extractScript = (component: string) =>
+  component.match(/<script>([\s\S]*?)<\/script>/i)?.[1];
+const scrollSource = extractScript(scrollComponent);
+if (!scrollSource) throw new Error('Scroll-to-top runtime not found.');
+const compile = (source: string) =>
+  transpileModule(source, {
+    compilerOptions: { target: ScriptTarget.ES2022, module: ModuleKind.ESNext },
+  }).outputText.replace(/^import .*;\r?\n/gm, '');
+
+it('extracts component scripts regardless of HTML tag casing', () => {
+  expect(extractScript('<SCRIPT>const ready = true;</SCRIPT>')).toBe('const ready = true;');
+});
+
+class Element extends EventTarget {
+  id = '';
+  lang = 'en';
+  type = '';
+  ariaLabel = '';
+  textContent = '';
+  innerHTML = '';
+  scrollHeight = 2000;
+  style: Record<string, string> = {};
+  attributes = new Map<string, string>();
+  dataset: Record<string, string | undefined> = {};
+  classes = new Set<string>();
+  classList = {
+    add: (...names: string[]) => names.forEach((name) => this.classes.add(name)),
+    remove: (...names: string[]) => names.forEach((name) => this.classes.delete(name)),
+    contains: (name: string) => this.classes.has(name),
+    toggle: (name: string, force = !this.classes.has(name)) => {
+      if (force) this.classes.add(name);
+      else this.classes.delete(name);
+      return force;
+    },
+  };
+  parentNode: Element | null = null;
+  children: Element[] = [];
+  root = false;
+  constructor(readonly tagName = 'div') {
+    super();
+  }
+  get parentElement() {
+    return this.parentNode;
+  }
+  get isConnected(): boolean {
+    return this.root || Boolean(this.parentNode?.isConnected);
+  }
+  setAttribute(name: string, value: string) {
+    this.attributes.set(name, value);
+    if (name.startsWith('data-')) this.dataset[name.slice(5)] = value;
+  }
+  getAttribute(name: string) {
+    return name.startsWith('data-')
+      ? (this.dataset[name.slice(5)] ?? null)
+      : (this.attributes.get(name) ?? null);
+  }
+  hasAttribute(name: string) {
+    return this.getAttribute(name) !== null;
+  }
+  removeAttribute(name: string) {
+    this.attributes.delete(name);
+    if (name.startsWith('data-')) delete this.dataset[name.slice(5)];
+  }
+  append(child: Element) {
+    child.remove();
+    this.appendChild(child);
+  }
+  appendChild<T extends Element>(child: T) {
+    child.parentNode = this;
+    this.children.push(child);
+    return child;
+  }
+  removeChild(child: Element) {
+    this.children = this.children.filter((element) => element !== child);
+    child.parentNode = null;
+  }
+  remove() {
+    this.parentNode?.removeChild(this);
+  }
+  contains(element: Element): boolean {
+    return this === element || this.children.some((child) => child.contains(element));
+  }
+  all(): Element[] {
+    return this.children.flatMap((child) => [child, ...child.all()]);
+  }
+  querySelectorAll(selector: string) {
+    return this.all().filter((element) => {
+      if (selector.startsWith('#')) return element.id === selector.slice(1);
+      if (selector === 'pre.mermaid') {
+        return element.tagName === 'pre' && element.classList.contains('mermaid');
+      }
+      if (selector.startsWith('.')) return element.classList.contains(selector.slice(1));
+      return element.tagName === selector;
+    });
+  }
+  querySelector(selector: string): Element | null {
+    return this.querySelectorAll(selector)[0] ?? null;
+  }
+}
+
+class Document extends EventTarget {
+  documentElement = new Element('html');
+  head = this.documentElement.appendChild(new Element('head'));
+  body = this.documentElement.appendChild(new Element('body'));
+  readyState = 'complete';
+  constructor() {
+    super();
+    this.documentElement.root = true;
+    this.documentElement.setAttribute('data-theme', 'light');
+  }
+  createElement(tag: string) {
+    return new Element(tag);
+  }
+  querySelectorAll(selector: string) {
+    return this.documentElement.querySelectorAll(selector);
+  }
+  querySelector(selector: string) {
+    return this.documentElement.querySelector(selector);
+  }
+  getElementById(id: string) {
+    return this.querySelector(`#${id}`);
+  }
+  emit(name: string) {
+    this.dispatchEvent(new Event(name));
+  }
+  replaceBody(sources: string[] = []) {
+    this.body.remove();
+    this.body = this.documentElement.appendChild(new Element('body'));
+    return sources.map((source) => {
+      const diagram = this.body.appendChild(new Element('pre'));
+      diagram.classList.add('mermaid');
+      diagram.textContent = source;
+      return diagram;
+    });
+  }
+}
+
+function observers() {
+  const instances: Observer[] = [];
+  class Observer {
+    targets = new Set<Element>();
+    constructor(readonly callback: () => void) {
+      instances.push(this);
+    }
+    observe(target: Element) {
+      this.targets.add(target);
+    }
+    disconnect() {
+      this.targets.clear();
+    }
+  }
+  return {
+    Observer,
+    instances,
+    notify: (target: Element) => {
+      instances
+        .filter((observer) => observer.targets.has(target))
+        .forEach((observer) => observer.callback());
+    },
+  };
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: Error) => void;
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+
+const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+async function mermaidRuntime({
+  sources = ['graph TD; A-->B', 'graph TD; C-->D'],
+  loading = false,
+} = {}) {
+  const { iconPacks } = await import('../../config/icon-packs.mjs');
+  const icons = { prefix: 'test', icons: { app: { body: '<path />' } } };
+  const fetch = vi
+    .fn<typeof globalThis.fetch>()
+    .mockImplementation(() => Promise.resolve(new Response(JSON.stringify(icons))));
+  const document = new Document();
+  const diagrams = document.replaceBody(sources);
+  if (loading) document.readyState = 'loading';
+  const mutation = observers();
+  const logger = { log: vi.fn(), error: vi.fn() };
+  const mermaid = {
+    initialize: vi.fn<(config: { theme: string }) => void>(),
+    registerIconPacks: vi.fn<(packs: AsyncIconLoader[]) => void>(),
+    render: vi
+      .fn<(id: string, source: string) => Promise<{ svg: string }>>()
+      .mockImplementation((_id, source) => Promise.resolve({ svg: `<svg>${source}</svg>` })),
+  };
+  const imported = deferred<{ default: typeof mermaid }>();
+  const importMermaid = vi.fn(() => imported.promise);
+  // Replace only the module boundary; execute the actual site runtime.
+  runInNewContext(compile(mermaidSource).replace("import('mermaid')", 'importMermaid()'), {
+    document,
+    MutationObserver: mutation.Observer,
+    console: logger,
+    queueMicrotask,
+    importMermaid,
+    iconPacks,
+    fetch,
+    Error,
+  });
+  if (!loading) document.emit('astro:page-load');
+  return {
+    document,
+    diagrams,
+    mutation,
+    mermaid,
+    imported,
+    importMermaid,
+    logger,
+    icons,
+    iconPacks,
+    fetch,
+    theme(value: string, target = document.documentElement) {
+      target.setAttribute('data-theme', value);
+      mutation.notify(target);
+    },
+    swap(sources: string[]) {
+      document.emit('astro:before-swap');
+      const diagrams = document.replaceBody(sources);
+      document.emit('astro:after-swap');
+      document.emit('astro:page-load');
+      return diagrams;
+    },
+  };
+}
+
+describe('site-owned Mermaid runtime', () => {
+  it('coalesces readiness, page-load and same-theme notifications before and during rendering', async () => {
+    const fixture = await mermaidRuntime({ loading: true });
+    const { document, mermaid, imported, diagrams, importMermaid, logger } = fixture;
+    expect(importMermaid).not.toHaveBeenCalled();
+    document.emit('DOMContentLoaded');
+    document.emit('astro:page-load');
+    fixture.theme('light');
+    await flush();
+    expect(importMermaid).toHaveBeenCalledOnce();
+    const render = deferred<{ svg: string }>();
+    mermaid.render.mockReturnValueOnce(render.promise);
+    imported.resolve({ default: mermaid });
+    await flush();
+    document.emit('astro:after-swap');
+    document.emit('astro:page-load');
+    fixture.theme('light');
+    await flush();
+    expect(mermaid.render).toHaveBeenCalledOnce();
+    render.resolve({ svg: '<svg>first</svg>' });
+    await flush();
+    expect(mermaid.render).toHaveBeenCalledTimes(2);
+    expect(mermaid.initialize).toHaveBeenCalledTimes(1);
+    expect(diagrams.map((diagram) => diagram.getAttribute('data-processed'))).toEqual([
+      'true',
+      'true',
+    ]);
+    expect(mermaid.registerIconPacks).toHaveBeenCalledOnce();
+    expect(mermaid.registerIconPacks.mock.calls[0][0].map((pack) => pack.name)).toEqual(
+      fixture.iconPacks.map((pack) => pack.name)
+    );
+    expect(logger.log).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+
+  it('keeps imports lazy on empty pages and renders two diagrams once on each return visit', async () => {
+    const fixture = await mermaidRuntime({ sources: [] });
+    await flush();
+    expect(fixture.importMermaid).not.toHaveBeenCalled();
+    fixture.imported.resolve({ default: fixture.mermaid });
+    for (let visit = 1; visit <= 3; visit++) {
+      fixture.swap(['graph TD; A-->B', 'graph TD; C-->D']);
+      await flush();
+      expect(fixture.mermaid.render).toHaveBeenCalledTimes(visit * 2);
+      fixture.swap([]);
+      await flush();
+    }
+    expect(fixture.importMermaid).toHaveBeenCalledOnce();
+  });
+
+  it('ignores equivalent attribute churn and rerenders only for effective theme changes', async () => {
+    const fixture = await mermaidRuntime();
+    fixture.imported.resolve({ default: fixture.mermaid });
+    await flush();
+    fixture.document.documentElement.removeAttribute('data-theme');
+    fixture.theme('light');
+    fixture.theme('dark', fixture.document.body);
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledTimes(2);
+    fixture.theme('dark');
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledTimes(4);
+    expect(fixture.mermaid.initialize.mock.calls.map(([config]) => config.theme)).toEqual([
+      'default',
+      'dark',
+    ]);
+    expect(fixture.mermaid.render.mock.calls.map(([, source]) => source)).toEqual([
+      'graph TD; A-->B',
+      'graph TD; C-->D',
+      'graph TD; A-->B',
+      'graph TD; C-->D',
+    ]);
+  });
+
+  it('serializes global theme configuration and discards superseded in-flight SVGs', async () => {
+    const fixture = await mermaidRuntime({ sources: ['graph TD; A-->B'] });
+    const render = deferred<{ svg: string }>();
+    fixture.mermaid.render.mockReturnValueOnce(render.promise);
+    fixture.imported.resolve({ default: fixture.mermaid });
+    await flush();
+    fixture.theme('dark');
+    fixture.theme('light');
+    fixture.theme('dark');
+    await flush();
+    expect(fixture.mermaid.initialize).toHaveBeenCalledOnce();
+    expect(fixture.mermaid.render).toHaveBeenCalledOnce();
+    const latest = deferred<{ svg: string }>();
+    fixture.mermaid.render.mockReturnValueOnce(latest.promise);
+    render.resolve({ svg: '<svg>obsolete light</svg>' });
+    await flush();
+    expect(fixture.diagrams[0].innerHTML).toBe('');
+    expect(fixture.mermaid.initialize.mock.calls.map(([config]) => config.theme)).toEqual([
+      'default',
+      'dark',
+    ]);
+    latest.resolve({ svg: '<svg>latest dark</svg>' });
+    await flush();
+    expect(fixture.diagrams[0].innerHTML).toBe('<svg>latest dark</svg>');
+  });
+
+  it('abandons imports owned by a replaced page and observes the new body, not the old body', async () => {
+    const fixture = await mermaidRuntime();
+    await flush();
+    const oldBody = fixture.document.body;
+    const next = fixture.swap(['graph TD; New-->Page']);
+    fixture.imported.resolve({ default: fixture.mermaid });
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledExactlyOnceWith(
+      expect.any(String),
+      'graph TD; New-->Page'
+    );
+    expect(fixture.diagrams.every((diagram) => diagram.innerHTML === '')).toBe(true);
+    expect(fixture.mutation.instances[0].targets.has(oldBody)).toBe(false);
+    fixture.theme('dark');
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledTimes(2);
+    expect(next[0].getAttribute('data-processed')).toBe('true');
+  });
+
+  it.each(['resolve', 'reject'] as const)(
+    'does not write stale %s completions after a swap',
+    async (outcome) => {
+      const fixture = await mermaidRuntime();
+      const render = deferred<{ svg: string }>();
+      fixture.mermaid.render.mockReturnValueOnce(render.promise);
+      fixture.imported.resolve({ default: fixture.mermaid });
+      await flush();
+      const next = fixture.swap(['graph TD; New-->Page']);
+      await flush();
+      expect(fixture.mermaid.initialize).toHaveBeenCalledOnce();
+      if (outcome === 'resolve') render.resolve({ svg: '<svg>stale</svg>' });
+      else render.reject(new Error('obsolete render failed'));
+      await flush();
+      expect(fixture.diagrams[0].innerHTML).toBe('');
+      expect(fixture.diagrams[0].children).toHaveLength(0);
+      expect(fixture.diagrams[0].hasAttribute('data-processed')).toBe(false);
+      expect(next[0].innerHTML).toContain('New-->Page');
+      expect(fixture.mermaid.render).toHaveBeenCalledTimes(2);
+      expect(fixture.logger.error).toHaveBeenCalledTimes(outcome === 'reject' ? 1 : 0);
+    }
+  );
+
+  it('keeps current work alive when navigation preparation is canceled', async () => {
+    const fixture = await mermaidRuntime();
+    fixture.document.emit('astro:before-preparation');
+    fixture.imported.resolve({ default: fixture.mermaid });
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledTimes(2);
+    fixture.theme('dark');
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledTimes(4);
+  });
+
+  it('preserves visible escaped errors and source without retrying an unchanged failed diagram', async () => {
+    const fixture = await mermaidRuntime({ sources: ['invalid <diagram>'] });
+    fixture.mermaid.render.mockRejectedValueOnce(new Error('<img src=x onerror=alert(1)>'));
+    fixture.imported.resolve({ default: fixture.mermaid });
+    await flush();
+    const [diagram] = fixture.diagrams;
+    expect(fixture.logger.error).toHaveBeenCalledOnce();
+    expect(diagram.getAttribute('data-diagram')).toBe('invalid <diagram>');
+    expect(diagram.textContent).toBe('Unable to render diagram: <img src=x onerror=alert(1)>');
+    expect(diagram.classList.contains('mermaid-error')).toBe(true);
+    expect(diagram.innerHTML).toBe('');
+    fixture.document.emit('astro:page-load');
+    await flush();
+    expect(fixture.mermaid.render).toHaveBeenCalledOnce();
+    fixture.theme('dark');
+    await flush();
+    expect(fixture.mermaid.render.mock.calls[1][1]).toBe('invalid <diagram>');
+  });
+
+  it('logs import failures, clears the failed import promise and retries on the next page load', async () => {
+    const fixture = await mermaidRuntime();
+    fixture.imported.reject(new Error('import failed'));
+    await flush();
+    expect(fixture.logger.error).toHaveBeenCalled();
+    fixture.importMermaid.mockResolvedValueOnce({ default: fixture.mermaid });
+    fixture.document.emit('astro:page-load');
+    await flush();
+    expect(fixture.importMermaid).toHaveBeenCalledTimes(2);
+    expect(fixture.mermaid.render).toHaveBeenCalledTimes(2);
+  });
+
+  it('loads configured icon packs lazily and reports failed responses', async () => {
+    const fixture = await mermaidRuntime();
+    fixture.imported.resolve({ default: fixture.mermaid });
+    await flush();
+    expect(fixture.fetch).not.toHaveBeenCalled();
+    const pack = fixture.mermaid.registerIconPacks.mock.calls[0][0][0];
+    await expect(pack.loader()).resolves.toEqual(fixture.icons);
+    expect(fixture.fetch).toHaveBeenCalledWith(fixture.iconPacks[0].url);
+    fixture.fetch.mockResolvedValueOnce(new Response('', { status: 503 }));
+    await expect(pack.loader()).rejects.toThrow('HTTP 503');
+  });
+});
+
+function scrollRuntime({ reducedMotion = false } = {}) {
+  vi.useFakeTimers();
+  const document = new Document();
+  const window = Object.assign(new EventTarget(), {
+    scrollY: 500,
+    innerHeight: 900,
+    innerWidth: 1440,
+    outerWidth: 1440,
+    scrollTo: vi.fn(),
+    matchMedia: () => ({ matches: reducedMotion }),
+    requestAnimationFrame: (callback: () => void) => setTimeout(callback, 16),
+    cancelAnimationFrame: clearTimeout,
+  });
+  type ScrollElement = Element & { connectedCallback(): void; disconnectedCallback(): void };
+  let Constructor: (new () => ScrollElement) | undefined;
+  runInNewContext(compile(scrollSource!), {
+    document,
+    window,
+    HTMLElement: Element,
+    AbortController,
+    customElements: {
+      define: (_name: string, value: new () => ScrollElement) => {
+        Constructor = value;
+      },
+    },
+  });
+  if (!Constructor) throw new Error('Scroll-to-top custom element was not registered.');
+  const root = document.body.appendChild(new Constructor());
+  const button = root.appendChild(new Element('button'));
+  button.id = 'scroll-to-top-button';
+  button.type = 'button';
+  root.connectedCallback();
+  return { document, window, root, button: () => button };
+}
+
+describe('site-owned scroll-to-top control', () => {
+  afterEach(() => vi.useRealTimers());
+
+  it('mounts once per connection without document readiness or keyboard handlers', () => {
+    const fixture = scrollRuntime();
+    fixture.root.connectedCallback();
+    fixture.document.emit('DOMContentLoaded');
+    fixture.document.emit('astro:page-load');
+    expect(vi.getTimerCount()).toBe(1);
+    vi.runAllTimers();
+    const button = fixture.button();
+    fixture.document.emit('astro:page-load');
+    vi.runAllTimers();
+    expect(fixture.button()).toBe(button);
+    expect(fixture.document.querySelectorAll('#scroll-to-top-button')).toHaveLength(1);
+    expect(getEventListeners(fixture.document, 'keydown')).toHaveLength(0);
+    expect(getEventListeners(fixture.document, 'DOMContentLoaded')).toHaveLength(0);
+  });
+
+  it.each([false, true])(
+    'uses only native click activation (reduced motion: %s)',
+    (reducedMotion) => {
+      const fixture = scrollRuntime({ reducedMotion });
+      vi.runAllTimers();
+      const button = fixture.button();
+      expect(button.type).toBe('button');
+      for (const name of ['touchstart', 'touchend', 'keydown']) {
+        expect(getEventListeners(button, name)).toHaveLength(0);
+      }
+      const click = new Event('click', { cancelable: true });
+      button.dispatchEvent(click);
+      expect(click.defaultPrevented).toBe(false);
+      expect(fixture.window.scrollTo).toHaveBeenCalledExactlyOnceWith({
+        top: 0,
+        behavior: reducedMotion ? 'auto' : 'smooth',
+      });
+      expect(scrollComponent).toContain('button:focus-visible');
+    }
+  );
+
+  it('disposes element/window handlers and pending frames when disconnected', () => {
+    const fixture = scrollRuntime();
+    fixture.root.disconnectedCallback();
+    expect(vi.getTimerCount()).toBe(0);
+    vi.runAllTimers();
+    for (let visit = 0; visit < 3; visit++) {
+      fixture.root.connectedCallback();
+      vi.runAllTimers();
+      expect(getEventListeners(fixture.document, 'keydown')).toHaveLength(0);
+      expect(getEventListeners(fixture.window, 'scroll')).toHaveLength(1);
+      fixture.window.dispatchEvent(new Event('scroll'));
+      expect(vi.getTimerCount()).toBe(1);
+      fixture.root.disconnectedCallback();
+      expect(vi.getTimerCount()).toBe(0);
+      expect(getEventListeners(fixture.document, 'keydown')).toHaveLength(0);
+      expect(getEventListeners(fixture.window, 'scroll')).toHaveLength(0);
+      expect(getEventListeners(fixture.window, 'resize')).toHaveLength(0);
+      expect(getEventListeners(fixture.button(), 'click')).toHaveLength(0);
+    }
+  });
+
+  it('survives canceled preparation and updates scroll/zoom visibility in one frame', () => {
+    const fixture = scrollRuntime();
+    vi.runAllTimers();
+    const button = fixture.button();
+    fixture.document.emit('astro:before-preparation');
+    expect(fixture.button()).toBe(button);
+    expect(getEventListeners(fixture.document, 'keydown')).toHaveLength(0);
+    fixture.window.outerWidth = 6000;
+    fixture.window.dispatchEvent(new Event('resize'));
+    vi.runAllTimers();
+    expect(button.classList.contains('visible')).toBe(false);
+    fixture.window.outerWidth = 1440;
+    fixture.window.dispatchEvent(new Event('resize'));
+    vi.runAllTimers();
+    expect(button.classList.contains('visible')).toBe(true);
+    fixture.window.dispatchEvent(new Event('scroll'));
+    fixture.window.scrollY = 0;
+    fixture.window.dispatchEvent(new Event('scroll'));
+    vi.runAllTimers();
+    expect(button.classList.contains('visible')).toBe(false);
+  });
+});