From aca327391573abd6569792ac1e3cb95d08a45fde Mon Sep 17 00:00:00 2001
From: AJ Matthews <alistair.matthews@civica.co.uk>
Date: Tue, 31 Mar 2026 17:26:39 +0100
Subject: [PATCH 1/2] Initial attempt.

---
 src/frontend/astro.config.mjs                 |   1 +
 src/frontend/config/icon-packs.mjs            |  13 +-
 .../starlight/TableOfContents.astro           | 402 ++++++++++++++++++
 .../src/components/starlight/TocList.astro    |  55 +++
 .../docs/get-started/prerequisites.mdx        |   6 +-
 5 files changed, 470 insertions(+), 7 deletions(-)
 create mode 100644 src/frontend/src/components/starlight/TableOfContents.astro
 create mode 100644 src/frontend/src/components/starlight/TocList.astro

diff --git a/src/frontend/astro.config.mjs b/src/frontend/astro.config.mjs
index 98cf1de7c..8fe74c2ab 100644
--- a/src/frontend/astro.config.mjs
+++ b/src/frontend/astro.config.mjs
@@ -52,6 +52,7 @@ export default defineConfig({
       components: {
         Banner: './src/components/starlight/Banner.astro',
         EditLink: './src/components/starlight/EditLink.astro',
+        TableOfContents: './src/components/starlight/TableOfContents.astro',
         Footer: './src/components/starlight/Footer.astro',
         Head: './src/components/starlight/Head.astro',
         Header: './src/components/starlight/Header.astro',
diff --git a/src/frontend/config/icon-packs.mjs b/src/frontend/config/icon-packs.mjs
index 3e852800a..85aaaef9a 100644
--- a/src/frontend/config/icon-packs.mjs
+++ b/src/frontend/config/icon-packs.mjs
@@ -1,21 +1,22 @@
 // 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.
+// astro-mermaid@1.3.1 serializes each pack's `loader` function to a string at
+// build time and reconstructs it on the client with `new Function(...)()`, so
+// each pack must expose a `loader` arrow function (not a `url` string).
 
 export const iconPacks = [
   {
     // Search: https://icon-sets.iconify.design/logos/?keyword=svg+logos
     name: 'logos',
-    url: 'https://unpkg.com/@iconify-json/logos@1/icons.json',
+    loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((r) => r.json()),
   },
   {
     // Search: https://icon-sets.iconify.design/iconoir/?keyword=iconoir
     name: 'iconoir',
-    url: 'https://unpkg.com/@iconify-json/iconoir@1/icons.json',
+    loader: () => fetch('https://unpkg.com/@iconify-json/iconoir@1/icons.json').then((r) => r.json()),
   },
   {
-    // Custom Aspire icons are served from the public folder for safe serialization.
+    // Custom Aspire icons are served from the public folder.
     name: 'aspire',
-    url: '/icons/aspire.json',
+    loader: () => fetch('/icons/aspire.json').then((r) => r.json()),
   },
 ];
diff --git a/src/frontend/src/components/starlight/TableOfContents.astro b/src/frontend/src/components/starlight/TableOfContents.astro
new file mode 100644
index 000000000..eb6da4352
--- /dev/null
+++ b/src/frontend/src/components/starlight/TableOfContents.astro
@@ -0,0 +1,402 @@
+---
+/**
+ * Override of @astrojs/starlight TableOfContents.
+ *
+ * Adds an AppHost language selector (C# / TypeScript) to the top of the TOC.
+ * The selector is only shown on pages that contain `[data-pivot-block="csharp"]`
+ * or `[data-pivot-block="typescript"]` elements (authored with the <Pivot> component).
+ *
+ * When active:
+ * - TOC entries whose target heading lives inside a hidden pivot block are hidden.
+ * - Changing the selector delegates to PivotSelector's button click (when present),
+ *   keeping the existing PivotSelector behavior completely intact.
+ * - A MutationObserver watches pivot-block visibility changes driven by PivotSelector
+ *   and keeps the TOC dropdown and filtered entries in sync.
+ */
+import TocList from './TocList.astro';
+
+interface TocItem {
+  slug: string;
+  text: string;
+  children: TocItem[];
+  depth: number;
+}
+
+const { toc } = Astro.locals.starlightRoute;
+---
+
+{
+  toc && (
+    <starlight-toc data-min-h={toc.minHeadingLevel} data-max-h={toc.maxHeadingLevel}>
+      <nav aria-labelledby="starlight__on-this-page">
+        <div class="toc-header">
+          <h2 id="starlight__on-this-page">{Astro.locals.t('tableOfContents.onThisPage')}</h2>
+          <div class="apphost-lang-filter" id="apphost-lang-filter" hidden>
+            <label for="apphost-lang-select" class="sr-only">AppHost language</label>
+            <div class="select-wrap">
+              <svg
+                aria-hidden="true"
+                width="12"
+                height="12"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <polyline points="16 18 22 12 16 6" />
+                <polyline points="8 6 2 12 8 18" />
+              </svg>
+              <select id="apphost-lang-select" aria-label="AppHost language">
+                <option value="csharp">C#</option>
+                <option value="typescript">TypeScript</option>
+              </select>
+              <svg
+                class="caret"
+                aria-hidden="true"
+                width="10"
+                height="10"
+                viewBox="0 0 16 16"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2.5"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+              >
+                <path d="M4 6L8 10L12 6" />
+              </svg>
+            </div>
+          </div>
+        </div>
+        <TocList toc={toc.items as TocItem[]} />
+      </nav>
+    </starlight-toc>
+  )
+}
+
+<style>
+  .toc-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .toc-header h2 {
+    /* Prevent the heading from being squeezed by the filter */
+    flex-shrink: 1;
+    min-width: 0;
+  }
+
+  .apphost-lang-filter {
+    flex-shrink: 0;
+  }
+
+  .select-wrap {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    position: relative;
+    background: var(--sl-color-bg-sidebar);
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.375rem;
+    padding: 0.125rem 0.25rem 0.125rem 0.375rem;
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-2);
+    transition: border-color 0.15s ease;
+  }
+
+  .select-wrap:hover,
+  .select-wrap:focus-within {
+    border-color: var(--sl-color-gray-3);
+    color: var(--sl-color-white);
+  }
+
+  .select-wrap select {
+    appearance: none;
+    background: transparent;
+    border: none;
+    padding: 0;
+    padding-inline-end: 0.125rem;
+    font-size: var(--sl-text-xs);
+    color: inherit;
+    cursor: pointer;
+    outline: none;
+    font-family: var(--sl-font);
+    line-height: 1.5;
+    /* Expose the native select for keyboard navigation */
+    position: relative;
+    z-index: 1;
+  }
+
+  .select-wrap .caret {
+    pointer-events: none;
+  }
+</style>
+
+<script>
+  /**
+   * Extended StarlightTOC custom element.
+   *
+   * Includes 100% of the original Starlight TOC highlighting logic plus the
+   * AppHost language filter. The original `starlight-toc.ts` from Starlight is
+   * NOT bundled when this override is active, so we must include it here.
+   */
+
+  const PAGE_TITLE_ID = '_top';
+
+  class StarlightTOC extends HTMLElement {
+    private _current = this.querySelector<HTMLAnchorElement>('a[aria-current="true"]');
+    private minH = parseInt(this.dataset.minH || '2', 10);
+    private maxH = parseInt(this.dataset.maxH || '3', 10);
+
+    /**
+     * CSS selector matching only headings that can appear in the TOC.
+     * Mirrors the selector built in Starlight's original starlight-toc.ts.
+     */
+    private tocHeadingSelector =
+      `h1#${PAGE_TITLE_ID},` +
+      `:where(${[
+        ...Array.from({ length: 1 + this.maxH - this.minH }).map(
+          (_, index) => `h${this.minH + index}`
+        ),
+      ].join()})[id]`;
+
+    protected set current(link: HTMLAnchorElement) {
+      if (link === this._current) return;
+      if (this._current) this._current.removeAttribute('aria-current');
+      link.setAttribute('aria-current', 'true');
+      this._current = link;
+    }
+
+    private onIdle = (cb: IdleRequestCallback) =>
+      (window.requestIdleCallback || ((cb) => setTimeout(cb, 1)))(cb);
+
+    constructor() {
+      super();
+      this.onIdle(() => this.init());
+      this.initLangFilter();
+    }
+
+    // -------------------------------------------------------------------------
+    // Original Starlight TOC highlighting logic (copied verbatim)
+    // -------------------------------------------------------------------------
+
+    private init = (): void => {
+      const links = [...this.querySelectorAll('a')];
+
+      const isHeading = (el: Element): el is HTMLHeadingElement =>
+        el.matches(this.tocHeadingSelector);
+
+      const getElementHeading = (el: Element | null): HTMLHeadingElement | null => {
+        if (!el) return null;
+        const origin = el;
+        while (el) {
+          if (el.matches('.sl-markdown-content, main > *')) {
+            return document.getElementById(PAGE_TITLE_ID) as HTMLHeadingElement;
+          }
+          if (isHeading(el)) return el;
+          const childHeading = el.querySelector<HTMLHeadingElement>(this.tocHeadingSelector);
+          if (childHeading) return childHeading;
+          el = el.previousElementSibling;
+          while (el?.lastElementChild) {
+            el = el.lastElementChild;
+          }
+          const h = getElementHeading(el);
+          if (h) return h;
+        }
+        return getElementHeading(origin.parentElement);
+      };
+
+      const setCurrent: IntersectionObserverCallback = (entries) => {
+        for (const { isIntersecting, target } of entries) {
+          if (!isIntersecting) continue;
+          const heading = getElementHeading(target);
+          if (!heading) continue;
+          const link = links.find(
+            (link) => link.hash === '#' + encodeURIComponent(heading.id)
+          );
+          if (link) {
+            this.current = link;
+            break;
+          }
+        }
+      };
+
+      const toObserve = document.querySelectorAll(
+        [
+          `main :where(${this.tocHeadingSelector})`,
+          `main :where(${this.tocHeadingSelector}, .sl-heading-wrapper) ~ *:not(:has(${this.tocHeadingSelector}))`,
+          `main .sl-markdown-content > *:not(:has(${this.tocHeadingSelector}))`,
+          `main > *:not(:has(${this.tocHeadingSelector}))`,
+        ].join()
+      );
+
+      let observer: IntersectionObserver | undefined;
+      const observe = () => {
+        if (observer) return;
+        observer = new IntersectionObserver(setCurrent, {
+          rootMargin: this.getRootMargin(),
+        });
+        toObserve.forEach((h) => observer!.observe(h));
+      };
+      observe();
+
+      let timeout: ReturnType<typeof setTimeout>;
+      window.addEventListener('resize', () => {
+        if (observer) {
+          observer.disconnect();
+          observer = undefined;
+        }
+        clearTimeout(timeout);
+        timeout = setTimeout(() => this.onIdle(observe), 200);
+      });
+    };
+
+    private getRootMargin(): `-${number}px 0% ${number}px` {
+      const navBarHeight =
+        document.querySelector('header')?.getBoundingClientRect().height || 0;
+      const mobileTocHeight =
+        this.querySelector('summary')?.getBoundingClientRect().height || 0;
+      const top = navBarHeight + mobileTocHeight + 32;
+      const bottom = top + 53;
+      const height = document.documentElement.clientHeight;
+      return `-${top}px 0% ${bottom - height}px`;
+    }
+
+    // -------------------------------------------------------------------------
+    // AppHost language filter
+    // -------------------------------------------------------------------------
+
+    private initLangFilter(): void {
+      const run = () => {
+        const filterEl = this.querySelector<HTMLElement>('.apphost-lang-filter');
+        const select = this.querySelector<HTMLSelectElement>('#apphost-lang-select');
+        if (!filterEl || !select) return;
+
+        // Only activate on pages that use apphost pivot blocks.
+        const hasApphostPivots = !!document.querySelector(
+          '[data-pivot-block="csharp"], [data-pivot-block="typescript"]'
+        );
+        if (!hasApphostPivots) return;
+
+        // Determine initial value: query string → localStorage → default 'csharp'.
+        const qs = new URLSearchParams(window.location.search);
+        const qsVal = qs.get('apphost');
+        const stored = localStorage.getItem('apphost');
+        const initial: string =
+          qsVal === 'csharp' || qsVal === 'typescript'
+            ? qsVal
+            : stored === 'csharp' || stored === 'typescript'
+              ? stored
+              : 'csharp';
+
+        select.value = initial;
+        filterEl.removeAttribute('hidden');
+        this.filterToc();
+
+        // When the user changes the selector:
+        // - Delegate to the existing PivotSelector button click when available
+        //   so PivotSelector continues to own all content visibility logic.
+        // - Fall back to applying pivot blocks directly when PivotSelector is
+        //   not present on the current page.
+        select.addEventListener('change', () => {
+          const lang = select.value;
+
+          const pivotBtn = document.querySelector<HTMLButtonElement>(
+            `#pivot-selector-apphost [data-pivot-option="${lang}"]`
+          );
+
+          if (pivotBtn) {
+            // PivotSelector is on the page — delegate entirely to it.
+            pivotBtn.click();
+          } else {
+            // No PivotSelector — apply pivot blocks directly.
+            localStorage.setItem('apphost', lang);
+            const url = new URL(window.location.href);
+            url.searchParams.set('apphost', lang);
+            window.history.replaceState({}, '', url.toString());
+
+            document.querySelectorAll<HTMLElement>('[data-pivot-block]').forEach((el) => {
+              const blockIds = (el.dataset.pivotBlock ?? '')
+                .split(/[,;]/)
+                .map((s) => s.trim());
+              el.style.display = blockIds.includes(lang) ? '' : 'none';
+            });
+          }
+
+          this.filterToc();
+        });
+
+        // Watch for pivot-block visibility changes triggered by PivotSelector.
+        // When PivotSelector applies a selection it sets inline `style.display`
+        // on the blocks — the MutationObserver picks that up here.
+        const pivotBlocks = document.querySelectorAll('[data-pivot-block]');
+        if (pivotBlocks.length > 0) {
+          const mo = new MutationObserver(() => {
+            const current = localStorage.getItem('apphost');
+            if (
+              (current === 'csharp' || current === 'typescript') &&
+              select.value !== current
+            ) {
+              select.value = current;
+            }
+            this.filterToc();
+          });
+          pivotBlocks.forEach((el) =>
+            mo.observe(el, { attributes: true, attributeFilter: ['style'] })
+          );
+        }
+      };
+
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', run, { once: true });
+      } else {
+        run();
+      }
+    }
+
+    /**
+     * Show/hide TOC `<li>` items based on whether their target heading is
+     * inside a currently-hidden `[data-pivot-block]` element.
+     * Headings outside any pivot block are always shown.
+     */
+    private filterToc(): void {
+      const links = [...this.querySelectorAll<HTMLAnchorElement>('nav a')];
+      for (const link of links) {
+        const href = link.getAttribute('href');
+        if (!href?.startsWith('#')) continue;
+        const id = decodeURIComponent(href.slice(1));
+        const heading = document.getElementById(id);
+        if (!heading) continue;
+        const listItem = link.closest('li');
+        if (!listItem) continue;
+        listItem.hidden = this.isInsideHiddenPivotBlock(heading);
+      }
+    }
+
+    /**
+     * Returns true when `el` has an ancestor `[data-pivot-block]` element
+     * whose `style.display` is `'none'`.
+     */
+    private isInsideHiddenPivotBlock(el: Element): boolean {
+      let parent = el.parentElement;
+      while (parent) {
+        if (
+          parent.hasAttribute('data-pivot-block') &&
+          (parent as HTMLElement).style.display === 'none'
+        ) {
+          return true;
+        }
+        parent = parent.parentElement;
+      }
+      return false;
+    }
+  }
+
+  if (!customElements.get('starlight-toc')) {
+    customElements.define('starlight-toc', StarlightTOC);
+  }
+</script>
diff --git a/src/frontend/src/components/starlight/TocList.astro b/src/frontend/src/components/starlight/TocList.astro
new file mode 100644
index 000000000..15e02b95b
--- /dev/null
+++ b/src/frontend/src/components/starlight/TocList.astro
@@ -0,0 +1,55 @@
+---
+/**
+ * Replicates @astrojs/starlight TableOfContentsList for the desktop TOC.
+ * The mobile TOC (MobileTableOfContents) is not overridden and continues to
+ * use Starlight's original implementation.
+ */
+interface TocItem {
+  slug: string;
+  text: string;
+  children: TocItem[];
+  depth: number;
+}
+
+interface Props {
+  toc: TocItem[];
+  depth?: number;
+}
+
+const { toc, depth = 0 } = Astro.props;
+---
+
+<ul>
+  {
+    toc.map((heading) => (
+      <li>
+        <a href={'#' + heading.slug}>
+          <span>{heading.text}</span>
+        </a>
+        {heading.children.length > 0 && (
+          <Astro.self toc={heading.children} depth={depth + 1} />
+        )}
+      </li>
+    ))
+  }
+</ul>
+
+<style define:vars={{ depth }}>
+  @layer starlight.core {
+    ul {
+      padding: 0;
+      list-style: none;
+    }
+    a {
+      --pad-inline: 0.5rem;
+      display: block;
+      border-radius: 0.25rem;
+      padding-block: 0.25rem;
+      padding-inline: calc(1rem * var(--depth) + var(--pad-inline)) var(--pad-inline);
+      line-height: 1.25;
+    }
+    a[aria-current='true'] {
+      color: var(--sl-color-text-accent);
+    }
+  }
+</style>
diff --git a/src/frontend/src/content/docs/get-started/prerequisites.mdx b/src/frontend/src/content/docs/get-started/prerequisites.mdx
index f0624a11a..c333764f3 100644
--- a/src/frontend/src/content/docs/get-started/prerequisites.mdx
+++ b/src/frontend/src/content/docs/get-started/prerequisites.mdx
@@ -4,7 +4,7 @@ description: Learn about essential tooling concepts for Aspire.
 giscus: false
 tableOfContents:
   minHeadingLevel: 1
-  maxHeadingLevel: 4
+  maxHeadingLevel: 5
 lastUpdated: true
 ---
 
@@ -33,6 +33,8 @@ Ready to dive into Aspire? Before you begin, make sure your development environm
 
     <Pivot id="csharp">
 
+    ##### .NET SDK
+
     Aspire's C# AppHost is built on .NET, a free, open-source, cross-platform framework for building modern apps and cloud services. You'll need the [.NET 10.0 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) installed—no prior C# experience is required.
 
     <Aside type="tip" title="Important">
@@ -44,6 +46,8 @@ Ready to dive into Aspire? Before you begin, make sure your development environm
     </Pivot>
     <Pivot id="typescript">
 
+    ##### Node.js
+
     Aspire's TypeScript AppHost requires [Node.js](https://nodejs.org/) 20 or later (LTS recommended) and a package manager such as npm or pnpm.
 
     Follow the [Node.js installation instructions](https://nodejs.org/) for your operating system (Windows, macOS, or Linux) to complete the setup.

From f186c8e07ea978f479f999332a99d11c0880c572 Mon Sep 17 00:00:00 2001
From: AJ Matthews <alistair.matthews@civica.co.uk>
Date: Wed, 1 Apr 2026 14:49:48 +0100
Subject: [PATCH 2/2] Modified so that the list of titles in the On This Page
 TOC gets successfully filtered.

---
 .../starlight/TableOfContents.astro           | 345 +++++-------------
 1 file changed, 101 insertions(+), 244 deletions(-)

diff --git a/src/frontend/src/components/starlight/TableOfContents.astro b/src/frontend/src/components/starlight/TableOfContents.astro
index eb6da4352..322cadfe9 100644
--- a/src/frontend/src/components/starlight/TableOfContents.astro
+++ b/src/frontend/src/components/starlight/TableOfContents.astro
@@ -138,265 +138,122 @@ const { toc } = Astro.locals.starlightRoute;
 
 <script>
   /**
-   * Extended StarlightTOC custom element.
+   * AppHost language filter for the TOC.
    *
-   * Includes 100% of the original Starlight TOC highlighting logic plus the
-   * AppHost language filter. The original `starlight-toc.ts` from Starlight is
-   * NOT bundled when this override is active, so we must include it here.
+   * NOTE: We do NOT define or extend the `starlight-toc` custom element here.
+   * MobileTableOfContents.astro imports starlight-toc.ts which registers
+   * `StarlightTOC` for `starlight-toc`. Attempting to override that registration
+   * is blocked by the custom-elements API (`customElements.define` throws if the
+   * name is already taken). Instead we run a plain script that adds filter
+   * behaviour directly to the already-existing `<starlight-toc>` DOM element.
+   * The original scroll-spy logic continues to work untouched.
    */
 
-  const PAGE_TITLE_ID = '_top';
+  /** The two apphost pivot language values we filter on. */
+  const APPHOST_LANGS = ['csharp', 'typescript'] as const;
+  type ApphostLang = (typeof APPHOST_LANGS)[number];
 
-  class StarlightTOC extends HTMLElement {
-    private _current = this.querySelector<HTMLAnchorElement>('a[aria-current="true"]');
-    private minH = parseInt(this.dataset.minH || '2', 10);
-    private maxH = parseInt(this.dataset.maxH || '3', 10);
-
-    /**
-     * CSS selector matching only headings that can appear in the TOC.
-     * Mirrors the selector built in Starlight's original starlight-toc.ts.
-     */
-    private tocHeadingSelector =
-      `h1#${PAGE_TITLE_ID},` +
-      `:where(${[
-        ...Array.from({ length: 1 + this.maxH - this.minH }).map(
-          (_, index) => `h${this.minH + index}`
-        ),
-      ].join()})[id]`;
-
-    protected set current(link: HTMLAnchorElement) {
-      if (link === this._current) return;
-      if (this._current) this._current.removeAttribute('aria-current');
-      link.setAttribute('aria-current', 'true');
-      this._current = link;
-    }
-
-    private onIdle = (cb: IdleRequestCallback) =>
-      (window.requestIdleCallback || ((cb) => setTimeout(cb, 1)))(cb);
+  function isApphostLang(value: string | null): value is ApphostLang {
+    return value === 'csharp' || value === 'typescript';
+  }
 
-    constructor() {
-      super();
-      this.onIdle(() => this.init());
-      this.initLangFilter();
+  /**
+   * Query DOWN from each non-selected apphost pivot block to collect the IDs
+   * of all elements inside it, then hide matching TOC entries.
+   *
+   * Querying down (pivot block → children) is more reliable than walking up
+   * (heading → ancestor) because it does not depend on intermediate wrapper
+   * elements (e.g. `.sl-heading-wrapper`) being transparent.
+   */
+  function filterToc(selectedLang: ApphostLang): void {
+    const toc = document.querySelector<HTMLElement>('starlight-toc');
+    if (!toc) return;
+
+    // Collect IDs that live inside a non-selected apphost pivot block.
+    const excluded = new Set<string>();
+    for (const lang of APPHOST_LANGS) {
+      if (lang === selectedLang) continue;
+      document
+        .querySelectorAll<HTMLElement>(`[data-pivot-block="${lang}"] [id]`)
+        .forEach((el) => excluded.add(el.id));
     }
 
-    // -------------------------------------------------------------------------
-    // Original Starlight TOC highlighting logic (copied verbatim)
-    // -------------------------------------------------------------------------
-
-    private init = (): void => {
-      const links = [...this.querySelectorAll('a')];
-
-      const isHeading = (el: Element): el is HTMLHeadingElement =>
-        el.matches(this.tocHeadingSelector);
-
-      const getElementHeading = (el: Element | null): HTMLHeadingElement | null => {
-        if (!el) return null;
-        const origin = el;
-        while (el) {
-          if (el.matches('.sl-markdown-content, main > *')) {
-            return document.getElementById(PAGE_TITLE_ID) as HTMLHeadingElement;
-          }
-          if (isHeading(el)) return el;
-          const childHeading = el.querySelector<HTMLHeadingElement>(this.tocHeadingSelector);
-          if (childHeading) return childHeading;
-          el = el.previousElementSibling;
-          while (el?.lastElementChild) {
-            el = el.lastElementChild;
-          }
-          const h = getElementHeading(el);
-          if (h) return h;
-        }
-        return getElementHeading(origin.parentElement);
-      };
-
-      const setCurrent: IntersectionObserverCallback = (entries) => {
-        for (const { isIntersecting, target } of entries) {
-          if (!isIntersecting) continue;
-          const heading = getElementHeading(target);
-          if (!heading) continue;
-          const link = links.find(
-            (link) => link.hash === '#' + encodeURIComponent(heading.id)
-          );
-          if (link) {
-            this.current = link;
-            break;
-          }
-        }
-      };
-
-      const toObserve = document.querySelectorAll(
-        [
-          `main :where(${this.tocHeadingSelector})`,
-          `main :where(${this.tocHeadingSelector}, .sl-heading-wrapper) ~ *:not(:has(${this.tocHeadingSelector}))`,
-          `main .sl-markdown-content > *:not(:has(${this.tocHeadingSelector}))`,
-          `main > *:not(:has(${this.tocHeadingSelector}))`,
-        ].join()
-      );
-
-      let observer: IntersectionObserver | undefined;
-      const observe = () => {
-        if (observer) return;
-        observer = new IntersectionObserver(setCurrent, {
-          rootMargin: this.getRootMargin(),
-        });
-        toObserve.forEach((h) => observer!.observe(h));
-      };
-      observe();
+    // Show/hide TOC list items based on whether their href is in the excluded set.
+    toc.querySelectorAll<HTMLAnchorElement>('nav a').forEach((link) => {
+      const href = link.getAttribute('href');
+      if (!href?.startsWith('#')) return;
+      const id = decodeURIComponent(href.slice(1));
+      const li = link.closest<HTMLElement>('li');
+      if (!li) return;
+      li.style.display = excluded.has(id) ? 'none' : '';
+    });
+  }
 
-      let timeout: ReturnType<typeof setTimeout>;
-      window.addEventListener('resize', () => {
-        if (observer) {
-          observer.disconnect();
-          observer = undefined;
-        }
-        clearTimeout(timeout);
-        timeout = setTimeout(() => this.onIdle(observe), 200);
-      });
-    };
+  function initApphostFilter(): void {
+    const toc = document.querySelector<HTMLElement>('starlight-toc');
+    const filterEl = document.querySelector<HTMLElement>('#apphost-lang-filter');
+    const select = document.querySelector<HTMLSelectElement>('#apphost-lang-select');
+    if (!toc || !filterEl || !select) return;
 
-    private getRootMargin(): `-${number}px 0% ${number}px` {
-      const navBarHeight =
-        document.querySelector('header')?.getBoundingClientRect().height || 0;
-      const mobileTocHeight =
-        this.querySelector('summary')?.getBoundingClientRect().height || 0;
-      const top = navBarHeight + mobileTocHeight + 32;
-      const bottom = top + 53;
-      const height = document.documentElement.clientHeight;
-      return `-${top}px 0% ${bottom - height}px`;
+    // Only activate on pages that actually use apphost pivot blocks.
+    if (!document.querySelector('[data-pivot-block="csharp"], [data-pivot-block="typescript"]')) {
+      return;
     }
 
-    // -------------------------------------------------------------------------
-    // AppHost language filter
-    // -------------------------------------------------------------------------
-
-    private initLangFilter(): void {
-      const run = () => {
-        const filterEl = this.querySelector<HTMLElement>('.apphost-lang-filter');
-        const select = this.querySelector<HTMLSelectElement>('#apphost-lang-select');
-        if (!filterEl || !select) return;
-
-        // Only activate on pages that use apphost pivot blocks.
-        const hasApphostPivots = !!document.querySelector(
-          '[data-pivot-block="csharp"], [data-pivot-block="typescript"]'
-        );
-        if (!hasApphostPivots) return;
-
-        // Determine initial value: query string → localStorage → default 'csharp'.
-        const qs = new URLSearchParams(window.location.search);
-        const qsVal = qs.get('apphost');
-        const stored = localStorage.getItem('apphost');
-        const initial: string =
-          qsVal === 'csharp' || qsVal === 'typescript'
-            ? qsVal
-            : stored === 'csharp' || stored === 'typescript'
-              ? stored
-              : 'csharp';
-
-        select.value = initial;
-        filterEl.removeAttribute('hidden');
-        this.filterToc();
-
-        // When the user changes the selector:
-        // - Delegate to the existing PivotSelector button click when available
-        //   so PivotSelector continues to own all content visibility logic.
-        // - Fall back to applying pivot blocks directly when PivotSelector is
-        //   not present on the current page.
-        select.addEventListener('change', () => {
-          const lang = select.value;
-
-          const pivotBtn = document.querySelector<HTMLButtonElement>(
-            `#pivot-selector-apphost [data-pivot-option="${lang}"]`
-          );
-
-          if (pivotBtn) {
-            // PivotSelector is on the page — delegate entirely to it.
-            pivotBtn.click();
-          } else {
-            // No PivotSelector — apply pivot blocks directly.
-            localStorage.setItem('apphost', lang);
-            const url = new URL(window.location.href);
-            url.searchParams.set('apphost', lang);
-            window.history.replaceState({}, '', url.toString());
-
-            document.querySelectorAll<HTMLElement>('[data-pivot-block]').forEach((el) => {
-              const blockIds = (el.dataset.pivotBlock ?? '')
-                .split(/[,;]/)
-                .map((s) => s.trim());
-              el.style.display = blockIds.includes(lang) ? '' : 'none';
-            });
-          }
-
-          this.filterToc();
-        });
-
-        // Watch for pivot-block visibility changes triggered by PivotSelector.
-        // When PivotSelector applies a selection it sets inline `style.display`
-        // on the blocks — the MutationObserver picks that up here.
-        const pivotBlocks = document.querySelectorAll('[data-pivot-block]');
-        if (pivotBlocks.length > 0) {
-          const mo = new MutationObserver(() => {
-            const current = localStorage.getItem('apphost');
-            if (
-              (current === 'csharp' || current === 'typescript') &&
-              select.value !== current
-            ) {
-              select.value = current;
-            }
-            this.filterToc();
-          });
-          pivotBlocks.forEach((el) =>
-            mo.observe(el, { attributes: true, attributeFilter: ['style'] })
-          );
-        }
-      };
+    // Determine the initial language: QS → localStorage → 'csharp'.
+    const qs = new URLSearchParams(window.location.search);
+    const initial: ApphostLang = isApphostLang(qs.get('apphost'))
+      ? (qs.get('apphost') as ApphostLang)
+      : isApphostLang(localStorage.getItem('apphost'))
+        ? (localStorage.getItem('apphost') as ApphostLang)
+        : 'csharp';
+
+    select.value = initial;
+    filterEl.removeAttribute('hidden');
+    filterToc(initial);
+
+    // When the user changes the dropdown, delegate to PivotSelector if present
+    // (so PivotSelector continues to own content visibility, localStorage, and
+    // URL state), then update the TOC.
+    select.addEventListener('change', () => {
+      const lang = select.value;
+      if (!isApphostLang(lang)) return;
+
+      const pivotBtn = document.querySelector<HTMLButtonElement>(
+        `#pivot-selector-apphost [data-pivot-option="${lang}"]`
+      );
 
-      if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', run, { once: true });
+      if (pivotBtn) {
+        // PivotSelector is present — let it handle everything.
+        pivotBtn.click();
       } else {
-        run();
+        // No PivotSelector on this page — apply blocks and state directly.
+        localStorage.setItem('apphost', lang);
+        const url = new URL(window.location.href);
+        url.searchParams.set('apphost', lang);
+        window.history.replaceState({}, '', url.toString());
+        document.querySelectorAll<HTMLElement>('[data-pivot-block]').forEach((el) => {
+          const ids = (el.dataset.pivotBlock ?? '').split(/[,;]/).map((s) => s.trim());
+          el.style.display = ids.includes(lang) ? '' : 'none';
+        });
       }
-    }
 
-    /**
-     * Show/hide TOC `<li>` items based on whether their target heading is
-     * inside a currently-hidden `[data-pivot-block]` element.
-     * Headings outside any pivot block are always shown.
-     */
-    private filterToc(): void {
-      const links = [...this.querySelectorAll<HTMLAnchorElement>('nav a')];
-      for (const link of links) {
-        const href = link.getAttribute('href');
-        if (!href?.startsWith('#')) continue;
-        const id = decodeURIComponent(href.slice(1));
-        const heading = document.getElementById(id);
-        if (!heading) continue;
-        const listItem = link.closest('li');
-        if (!listItem) continue;
-        listItem.hidden = this.isInsideHiddenPivotBlock(heading);
-      }
-    }
-
-    /**
-     * Returns true when `el` has an ancestor `[data-pivot-block]` element
-     * whose `style.display` is `'none'`.
-     */
-    private isInsideHiddenPivotBlock(el: Element): boolean {
-      let parent = el.parentElement;
-      while (parent) {
-        if (
-          parent.hasAttribute('data-pivot-block') &&
-          (parent as HTMLElement).style.display === 'none'
-        ) {
-          return true;
-        }
-        parent = parent.parentElement;
-      }
-      return false;
-    }
+      filterToc(lang);
+    });
+
+    // Watch for PivotSelector-driven display changes on pivot blocks so the TOC
+    // dropdown and entries stay in sync when the user clicks PivotSelector directly.
+    const mo = new MutationObserver(() => {
+      const stored = localStorage.getItem('apphost');
+      const lang: ApphostLang = isApphostLang(stored) ? stored : 'csharp';
+      if (select.value !== lang) select.value = lang;
+      filterToc(lang);
+    });
+    document
+      .querySelectorAll('[data-pivot-block]')
+      .forEach((el) => mo.observe(el, { attributes: true, attributeFilter: ['style'] }));
   }
 
-  if (!customElements.get('starlight-toc')) {
-    customElements.define('starlight-toc', StarlightTOC);
-  }
+  // Astro defers module scripts until after HTML parsing, so the DOM is ready.
+  initApphostFilter();
 </script>