starlight-theme-bejamas 0.2.0 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # starlight-theme-bejamas
 
+## 0.2.4
+
+### Patch Changes
+
+- Updated dependencies [[`0cac89c`](https://github.com/bejamas/ui/commit/0cac89cf39e0414933d6cacff4e00b29cc8996e9), [`6d9ff06`](https://github.com/bejamas/ui/commit/6d9ff061ba4771e7956f5179c4b15d7e02c0bb64), [`a7eb35f`](https://github.com/bejamas/ui/commit/a7eb35fb24b5a19e4f8aa41d857e93a8005e10ae)]:
+  - @bejamas/semantic-icons@0.3.0
+
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [[`d8abe23`](https://github.com/bejamas/ui/commit/d8abe237f179cc6a5be73823a134a6221c62cca5)]:
+  - @bejamas/semantic-icons@0.2.0
+
+## 0.2.2
+
+### Patch Changes
+
+- [#159](https://github.com/bejamas/ui/pull/159) [`d9fb503`](https://github.com/bejamas/ui/commit/d9fb50331b2692cad08f1653611b952312e6d7fe) Thanks [@Tadzik-2](https://github.com/Tadzik-2)! - Point sidebar group carets down when collapsed and up when expanded.
+
+## 0.2.1
+
+### Patch Changes
+
+- [#143](https://github.com/bejamas/ui/pull/143) [`94b6e69`](https://github.com/bejamas/ui/commit/94b6e698d22920f974d263709828cb9cfaa1bce5) Thanks [@Tadzik-2](https://github.com/Tadzik-2)! - Publish semantic icons publicly and validate packed release manifests so the theme installs without workspace protocol or private runtime dependencies.
+
+- Updated dependencies [[`94b6e69`](https://github.com/bejamas/ui/commit/94b6e698d22920f974d263709828cb9cfaa1bce5)]:
+  - @bejamas/semantic-icons@0.1.1
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-theme-bejamas",
   "author": "Bejamas",
-  "version": "0.2.0",
+  "version": "0.2.4",
   "license": "MIT",
   "description": "A Starlight theme using bejamas/ui",
   "type": "module",
@@ -38,14 +38,13 @@
   },
   "bugs": "https://github.com/bejamas/ui/issues",
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.33.0",
-    "astro": ">=5.5.0"
+    "@astrojs/starlight": "^0.42.3",
+    "astro": "^7.3.4"
   },
   "dependencies": {
-    "@bejamas/semantic-icons": "workspace:*",
-    "@expressive-code/plugin-line-numbers": "^0.41.3",
-    "@fontsource-variable/inter": "^5.2.8",
-    "@fontsource/inter": "^5.2.8",
-    "@lucide/astro": "^0.545.0"
+    "@bejamas/semantic-icons": "0.3.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource/inter": "^5.3.0",
+    "@lucide/astro": "^1.47.0"
   }
 }

package/src/index.ts

@@ -11,7 +11,6 @@ import {
   type StarlightThemeBejamasUserConfig,
 } from "./config";
 import { vitePluginStarlightThemeBejamas } from "./lib/vite";
-// import { pluginLineNumbers } from "@expressive-code/plugin-line-numbers";
 
 export default function starlightThemeBejamas(
   userConfig: StarlightThemeBejamasUserConfig,
@@ -48,12 +47,6 @@ export default function starlightThemeBejamas(
             ? {}
             : starlightConfig.expressiveCode;
 
-        // starlightConfig.plugins?.push(
-        //   pluginLineNumbers({
-        //     showLineNumbers: true,
-        //   }),
-        // );
-
         const componentOverrides: typeof config.components = {};
 
         type OverridableComponent =

package/src/lib/theme-stylesheet-runtime.test.ts

@@ -0,0 +1,246 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { refreshCurrentThemeStylesheet } from "./theme-stylesheet";
+
+const ACTIVE_SELECTOR = "link[data-current-theme-stylesheet]";
+const PENDING_SELECTOR = "link[data-pending-current-theme-stylesheet]";
+
+type Listener = (event: Event) => void;
+
+class FakeLinkElement {
+  href = "";
+  rel = "stylesheet";
+  private attributes = new Map<string, string>();
+  private listeners = new Map<string, Set<Listener>>();
+
+  constructor(
+    private readonly document: FakeDocument,
+    href = "",
+  ) {
+    this.href = href;
+  }
+
+  cloneNode() {
+    const clone = new FakeLinkElement(this.document, this.href);
+    clone.rel = this.rel;
+
+    for (const [name, value] of this.attributes) {
+      clone.attributes.set(name, value);
+    }
+
+    return clone;
+  }
+
+  setAttribute(name: string, value: string) {
+    this.attributes.set(name, value);
+  }
+
+  removeAttribute(name: string) {
+    this.attributes.delete(name);
+  }
+
+  hasAttribute(name: string) {
+    return this.attributes.has(name);
+  }
+
+  addEventListener(type: string, listener: Listener) {
+    const listeners = this.listeners.get(type) ?? new Set<Listener>();
+    listeners.add(listener);
+    this.listeners.set(type, listeners);
+  }
+
+  removeEventListener(type: string, listener: Listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  dispatchEvent(event: Event) {
+    this.listeners.get(event.type)?.forEach((listener) => listener(event));
+    return true;
+  }
+
+  insertAdjacentElement(position: InsertPosition, element: FakeLinkElement) {
+    if (position !== "afterend") {
+      throw new Error(`Unsupported insert position: ${position}`);
+    }
+
+    this.document.insertAfter(this, element);
+    return element;
+  }
+
+  remove() {
+    this.document.remove(this);
+  }
+}
+
+class FakeDocument {
+  links: FakeLinkElement[] = [];
+
+  querySelector<T extends FakeLinkElement>(selector: string) {
+    return (this.querySelectorAll(selector)[0] ?? null) as T | null;
+  }
+
+  querySelectorAll<T extends FakeLinkElement>(selector: string) {
+    if (selector === ACTIVE_SELECTOR) {
+      return this.links.filter((link) =>
+        link.hasAttribute("data-current-theme-stylesheet"),
+      ) as T[];
+    }
+
+    if (selector === PENDING_SELECTOR) {
+      return this.links.filter((link) =>
+        link.hasAttribute("data-pending-current-theme-stylesheet"),
+      ) as T[];
+    }
+
+    if (selector === "link") {
+      return [...this.links] as T[];
+    }
+
+    return [] as T[];
+  }
+
+  append(link: FakeLinkElement) {
+    this.links.push(link);
+  }
+
+  insertAfter(target: FakeLinkElement, link: FakeLinkElement) {
+    const index = this.links.indexOf(target);
+    if (index === -1) {
+      this.links.push(link);
+      return;
+    }
+
+    this.links.splice(index + 1, 0, link);
+  }
+
+  remove(link: FakeLinkElement) {
+    this.links = this.links.filter((entry) => entry !== link);
+  }
+}
+
+const originalDocument = globalThis.document;
+const originalWindow = globalThis.window;
+
+function createEnvironment() {
+  const document = new FakeDocument();
+  const window = {
+    location: { origin: "https://ui.bejamas.com" },
+    requestAnimationFrame: (callback: FrameRequestCallback) => {
+      callback(0);
+      return 1;
+    },
+    setTimeout,
+  } as unknown as Window & typeof globalThis;
+
+  globalThis.document = document as unknown as Document;
+  globalThis.window = window;
+
+  return { document };
+}
+
+function appendActiveStylesheet(document: FakeDocument, href?: string) {
+  const stylesheet = new FakeLinkElement(
+    document,
+    href ?? "https://ui.bejamas.com/r/themes/current-theme.css",
+  );
+  stylesheet.setAttribute("data-current-theme-stylesheet", "");
+  document.append(stylesheet);
+  return stylesheet;
+}
+
+describe("refreshCurrentThemeStylesheet", () => {
+  beforeEach(() => {
+    createEnvironment();
+  });
+
+  afterEach(() => {
+    globalThis.document = originalDocument;
+    globalThis.window = originalWindow;
+  });
+
+  test("keeps the current stylesheet active until the replacement loads", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    const currentStylesheet = appendActiveStylesheet(document);
+
+    const refreshPromise = refreshCurrentThemeStylesheet();
+    const pendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    expect(refreshPromise).toBeInstanceOf(Promise);
+    expect(document.querySelectorAll("link")).toHaveLength(2);
+    expect(document.querySelector(ACTIVE_SELECTOR)).toBe(currentStylesheet);
+    expect(pendingStylesheet).not.toBeNull();
+    expect(pendingStylesheet?.href).not.toBe(currentStylesheet.href);
+
+    pendingStylesheet?.dispatchEvent(new Event("load"));
+    await refreshPromise;
+
+    const activeStylesheet =
+      document.querySelector<FakeLinkElement>(ACTIVE_SELECTOR);
+    expect(document.querySelectorAll("link")).toHaveLength(1);
+    expect(document.querySelector(PENDING_SELECTOR)).toBeNull();
+    expect(activeStylesheet).toBe(pendingStylesheet);
+    expect(activeStylesheet?.href).toContain("/r/themes/current-theme.css?v=");
+  });
+
+  test("keeps the current stylesheet when the replacement fails to load", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    const currentStylesheet = appendActiveStylesheet(document);
+
+    const refreshPromise = refreshCurrentThemeStylesheet();
+    const pendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    pendingStylesheet?.dispatchEvent(new Event("error"));
+    await refreshPromise;
+
+    expect(document.querySelectorAll("link")).toHaveLength(1);
+    expect(document.querySelector(ACTIVE_SELECTOR)).toBe(currentStylesheet);
+    expect(document.querySelector(PENDING_SELECTOR)).toBeNull();
+  });
+
+  test("uses a unique cache-busting version for each refresh", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    appendActiveStylesheet(document);
+
+    const firstRefresh = refreshCurrentThemeStylesheet();
+    const firstHref =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR)?.href;
+
+    // A second refresh in the same tick (same Date.now()) must still produce a
+    // distinct URL, otherwise the browser can reuse a stale cached response.
+    const secondRefresh = refreshCurrentThemeStylesheet();
+    const secondPending =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    expect(secondPending?.href).toContain("/r/themes/current-theme.css?v=");
+    expect(secondPending?.href).not.toBe(firstHref);
+
+    secondPending?.dispatchEvent(new Event("load"));
+    await Promise.all([firstRefresh, secondRefresh]);
+  });
+
+  test("cancels an older pending swap when a newer one starts", async () => {
+    const document = globalThis.document as unknown as FakeDocument;
+    appendActiveStylesheet(document);
+
+    const firstRefresh = refreshCurrentThemeStylesheet();
+    const firstPendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    const secondRefresh = refreshCurrentThemeStylesheet();
+    const secondPendingStylesheet =
+      document.querySelector<FakeLinkElement>(PENDING_SELECTOR);
+
+    expect(secondPendingStylesheet).not.toBe(firstPendingStylesheet);
+    expect(document.querySelectorAll(PENDING_SELECTOR)).toHaveLength(1);
+
+    secondPendingStylesheet?.dispatchEvent(new Event("load"));
+    await Promise.all([firstRefresh, secondRefresh]);
+
+    expect(document.querySelectorAll("link")).toHaveLength(1);
+    expect(document.querySelector(ACTIVE_SELECTOR)).toBe(
+      secondPendingStylesheet,
+    );
+    expect(document.querySelector(PENDING_SELECTOR)).toBeNull();
+  });
+});

package/src/lib/theme-stylesheet.ts

@@ -1,5 +1,5 @@
 export const CURRENT_THEME_STYLESHEET_SELECTOR =
-  'link[data-current-theme-stylesheet]';
+  "link[data-current-theme-stylesheet]";
 
 export function buildCurrentThemeStylesheetHref(
   href: string,
@@ -9,5 +9,115 @@ export function buildCurrentThemeStylesheetHref(
   url.searchParams.set("v", String(version));
 
   const isAbsolute = /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(href);
-  return isAbsolute ? url.toString() : `${url.pathname}${url.search}${url.hash}`;
+  return isAbsolute
+    ? url.toString()
+    : `${url.pathname}${url.search}${url.hash}`;
+}
+
+const PENDING_THEME_STYLESHEET_SELECTOR =
+  "link[data-pending-current-theme-stylesheet]";
+
+let stylesheetSwapToken = 0;
+let stylesheetVersionCounter = 0;
+let cancelPendingThemeStylesheetSwap: (() => void) | null = null;
+
+function getAnimationFrame() {
+  if (typeof window !== "undefined" && window.requestAnimationFrame) {
+    return window.requestAnimationFrame.bind(window);
+  }
+
+  return (callback: FrameRequestCallback) =>
+    window.setTimeout(() => callback(performance.now()), 0);
+}
+
+export function refreshCurrentThemeStylesheet() {
+  const currentStylesheet = document.querySelector<HTMLLinkElement>(
+    "link[data-current-theme-stylesheet]",
+  );
+
+  if (!currentStylesheet) {
+    return Promise.resolve();
+  }
+
+  cancelPendingThemeStylesheetSwap?.();
+
+  // Strictly-monotonic version so two refreshes in the same millisecond can
+  // never collide on a cached response (which would swap in a stale theme).
+  const nextHref = buildCurrentThemeStylesheetHref(
+    currentStylesheet.href,
+    `${Date.now()}-${++stylesheetVersionCounter}`,
+  );
+  const nextStylesheet = currentStylesheet.cloneNode(true) as HTMLLinkElement;
+  const swapToken = ++stylesheetSwapToken;
+  const requestAnimationFrame = getAnimationFrame();
+
+  nextStylesheet.href = nextHref;
+  nextStylesheet.removeAttribute("data-current-theme-stylesheet");
+  nextStylesheet.setAttribute("data-pending-current-theme-stylesheet", "");
+
+  document
+    .querySelectorAll<HTMLLinkElement>(PENDING_THEME_STYLESHEET_SELECTOR)
+    .forEach((link) => {
+      if (link !== nextStylesheet) {
+        link.remove();
+      }
+    });
+
+  return new Promise<void>((resolve) => {
+    let settled = false;
+
+    const settle = () => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      if (cancelPendingThemeStylesheetSwap === cancel) {
+        cancelPendingThemeStylesheetSwap = null;
+      }
+      resolve();
+    };
+
+    const cleanup = () => {
+      nextStylesheet.removeEventListener("load", onLoad);
+      nextStylesheet.removeEventListener("error", onError);
+    };
+
+    const cancel = () => {
+      cleanup();
+      nextStylesheet.remove();
+      settle();
+    };
+
+    const onError = () => {
+      cancel();
+    };
+
+    const onLoad = () => {
+      cleanup();
+
+      if (swapToken !== stylesheetSwapToken) {
+        nextStylesheet.remove();
+        settle();
+        return;
+      }
+
+      currentStylesheet.removeAttribute("data-current-theme-stylesheet");
+      nextStylesheet.removeAttribute("data-pending-current-theme-stylesheet");
+      nextStylesheet.setAttribute("data-current-theme-stylesheet", "");
+
+      requestAnimationFrame(() => {
+        if (swapToken === stylesheetSwapToken) {
+          currentStylesheet.remove();
+        }
+
+        settle();
+      });
+    };
+
+    cancelPendingThemeStylesheetSwap = cancel;
+    nextStylesheet.addEventListener("load", onLoad, { once: true });
+    nextStylesheet.addEventListener("error", onError, { once: true });
+    currentStylesheet.insertAdjacentElement("afterend", nextStylesheet);
+  });
 }

package/src/overrides/PageFrame.astro

@@ -28,83 +28,44 @@ const isSplashTemplate = template === "splash";
         aria-label={Astro.locals.t("sidebarNav.accessibleLabel")}
       >
         <MobileMenuToggle />
-        <div id="starlight__sidebar" class="sidebar-pane">
+        <script>
+          if (!customElements.get("sl-sidebar-pane")) {
+            class StarlightSidebarPane extends HTMLElement {
+              constructor() {
+                super();
+
+                const desktopMediaQuery = matchMedia("(min-width: 64rem)");
+                const updatePopover = () => {
+                  this.popover = desktopMediaQuery.matches ? null : "auto";
+                };
+                updatePopover();
+                desktopMediaQuery.addEventListener("change", updatePopover);
+
+                this.addEventListener("toggle", () => {
+                  const isOpen = this.matches(":popover-open");
+                  document
+                    .querySelectorAll<HTMLElement>(".main-frame, .sl-skip-link")
+                    .forEach((element) => element.toggleAttribute("inert", isOpen));
+
+                  if (isOpen && this.closest(".sidebar-splash")) {
+                    this.scrollTop = 0;
+                  }
+                });
+              }
+            }
+
+            customElements.define("sl-sidebar-pane", StarlightSidebarPane);
+          }
+        </script>
+        <sl-sidebar-pane popover="" id="starlight__sidebar" class="sidebar-pane">
           <div class="sidebar-content sl-flex">
             <slot name="sidebar" />
           </div>
-        </div>
+        </sl-sidebar-pane>
       </nav>
     )
   }
 
-  {
-    isSplashTemplate && (
-      <script is:inline>
-        (() => {
-          const installReset = () => {
-            const nav = document.querySelector("nav.sidebar-splash");
-            if (!(nav instanceof HTMLElement)) return () => {};
-
-            const pane = nav.querySelector("#starlight__sidebar");
-            const toggle = nav.querySelector("starlight-menu-button");
-
-            if (!(pane instanceof HTMLElement)) return () => {};
-
-            const resetToTop = () => {
-              pane.scrollTop = 0;
-            };
-
-            // Avoid opening splash menus at a persisted offset.
-            resetToTop();
-
-            if (!(toggle instanceof HTMLElement)) return () => {};
-
-            const onToggleChange = () => {
-              if (toggle.getAttribute("aria-expanded") === "true") {
-                requestAnimationFrame(resetToTop);
-              }
-            };
-
-            const onToggleClick = () => {
-              requestAnimationFrame(onToggleChange);
-            };
-
-            toggle.addEventListener("click", onToggleClick);
-
-            const observer = new MutationObserver(onToggleChange);
-            observer.observe(toggle, {
-              attributes: true,
-              attributeFilter: ["aria-expanded"],
-            });
-
-            return () => {
-              toggle.removeEventListener("click", onToggleClick);
-              observer.disconnect();
-            };
-          };
-
-          let cleanup = installReset();
-
-          const onAstroPageLoad = () => {
-            cleanup();
-            cleanup = installReset();
-          };
-
-          document.addEventListener("astro:page-load", onAstroPageLoad);
-
-          addEventListener(
-            "pagehide",
-            () => {
-              cleanup();
-              document.removeEventListener("astro:page-load", onAstroPageLoad);
-            },
-            { once: true },
-          );
-        })();
-      </script>
-    )
-  }
-
   <div class:list={["main-frame", isSplashTemplate && "main-frame-splash"]}>
     {
       template === "splash" ? (
@@ -182,15 +143,17 @@ const isSplashTemplate = template === "splash";
     }
 
     .sidebar-pane {
-      visibility: var(--sl-sidebar-visibility, hidden);
+      border: 0;
+      margin: 0;
+      color: inherit;
+      display: none;
       position: fixed;
       z-index: var(--sl-z-index-menu);
       inset-block: var(--sl-nav-height) 0;
       inset-inline-start: 0;
       width: 100%;
       background-color: var(--background);
-      height: 100svh;
-      overflow: scroll;
+      height: calc(100svh - var(--sl-nav-height));
       overflow-y: scroll;
       overflow-x: hidden;
       scrollbar-width: none;
@@ -198,12 +161,11 @@ const isSplashTemplate = template === "splash";
       -webkit-overflow-scrolling: touch;
       overscroll-behavior: contain;
       overscroll-behavior-y: contain;
-      top: 0;
-      padding-top: calc(var(--spacing) * 18);
+      padding: 0;
     }
 
-    :global([aria-expanded="true"]) ~ .sidebar-pane {
-      --sl-sidebar-visibility: visible;
+    .sidebar-pane:popover-open {
+      display: block;
     }
 
     .sidebar-content {
@@ -219,11 +181,6 @@ const isSplashTemplate = template === "splash";
         content: "";
         padding-bottom: 1px;
       }
-
-      .sidebar-pane {
-        padding-top: 0;
-        margin-top: calc(var(--spacing) * 18);
-      }
     }
 
     .main-frame {
@@ -315,7 +272,7 @@ const isSplashTemplate = template === "splash";
         padding-inline-end: var(--sl-nav-pad-x);
       }
       .sidebar-pane {
-        --sl-sidebar-visibility: visible;
+        display: block;
         width: var(--sl-sidebar-width);
         background-color: var(--sl-color-bg-sidebar);
         border-inline-end: 1px solid var(--sl-color-hairline-shade);

package/src/overrides/PageTitle.astro

@@ -100,7 +100,7 @@ const isRtl = dir === "rtl";
       display: flex;
       justify-content: space-between;
       flex-wrap: wrap;
-      margin-top: 0.5rem;
+      margin-top: 0;
       align-items: center;
     }
     .sl-bejamas-docs-title-buttons {

package/src/overrides/ThemeProvider.astro

@@ -128,15 +128,11 @@ const themeChoiceBootstrapScript = buildThemeChoiceBootstrapInlineScript();
 
 <script>
   import { syncSemanticIconsInRoot } from "@bejamas/semantic-icons/browser";
-  import {
-    buildCurrentThemeStylesheetHref,
-    CURRENT_THEME_STYLESHEET_SELECTOR,
-  } from "../lib/theme-stylesheet";
+  import { refreshCurrentThemeStylesheet } from "../lib/theme-stylesheet";
 
   const PRESET_CHANGE_EVENT = "bejamas:preset-change";
   const SETUP_KEY = "__bejamasCurrentThemeStylesheetSync";
   let reloadFrame = 0;
-  let reloadVersion = 0;
   let pendingIconLibrary = null;
 
   function syncDocumentIconLibrary() {
@@ -152,68 +148,21 @@ const themeChoiceBootstrapScript = buildThemeChoiceBootstrapInlineScript();
     }
   }
 
-  function refreshCurrentThemeStylesheet() {
-    const links = Array.from(
-      document.head.querySelectorAll(CURRENT_THEME_STYLESHEET_SELECTOR),
-    ).filter(
-      (link): link is HTMLLinkElement => link instanceof HTMLLinkElement,
-    );
-    const currentLink = links.at(-1);
-
-    if (!currentLink) {
-      window.StarlightThemeProvider?.refreshThemeColors?.();
+  const scheduleCurrentThemeStylesheetRefresh = () => {
+    if (reloadFrame) {
       return;
     }
 
-    reloadVersion += 1;
-
-    const replacement = currentLink.cloneNode(false) as HTMLLinkElement;
-    const sourceHref = currentLink.getAttribute("href") ?? currentLink.href;
-    replacement.href = buildCurrentThemeStylesheetHref(sourceHref, `${Date.now()}-${reloadVersion}`);
-
-    replacement.addEventListener(
-      "load",
-      () => {
-        links.forEach((link) => {
-          if (link !== replacement) {
-            link.remove();
-          }
-        });
-        if (pendingIconLibrary) {
-          document.documentElement.dataset.iconLibrary = pendingIconLibrary;
-          syncSemanticIconsInRoot(document, pendingIconLibrary);
-          pendingIconLibrary = null;
-        }
-        window.StarlightThemeProvider?.refreshThemeColors?.();
-      },
-      { once: true },
-    );
-
-    replacement.addEventListener(
-      "error",
-      () => {
-        replacement.remove();
+    reloadFrame = requestAnimationFrame(() => {
+      reloadFrame = 0;
+      void refreshCurrentThemeStylesheet().then(() => {
         if (pendingIconLibrary) {
           document.documentElement.dataset.iconLibrary = pendingIconLibrary;
           syncSemanticIconsInRoot(document, pendingIconLibrary);
           pendingIconLibrary = null;
         }
         window.StarlightThemeProvider?.refreshThemeColors?.();
-      },
-      { once: true },
-    );
-
-    currentLink.after(replacement);
-  }
-
-  const scheduleCurrentThemeStylesheetRefresh = () => {
-    if (reloadFrame) {
-      return;
-    }
-
-    reloadFrame = requestAnimationFrame(() => {
-      reloadFrame = 0;
-      refreshCurrentThemeStylesheet();
+      });
     });
   };
 

package/src/styles/theme.css

@@ -89,6 +89,7 @@
     /* --sl-nav-height: auto; */
     --sl-nav-pad-y: calc(var(--spacing) * 4.5);
     --sl-content-pad-x: calc(var(--spacing) * 5);
+    --sl-docs-top-space: calc(var(--spacing) * 12);
     --sl-nav-pad-x: calc(var(--spacing) * 1 + var(--sl-content-pad-x));
     --sl-main-frame-inner-background: var(--background);
     --sl-main-frame-inner-border: var(--border);
@@ -150,7 +151,7 @@
 
   .right-sidebar-panel {
     --sl-sidebar-item-padding-inline: 1rem;
-    padding-top: calc(var(--spacing) * 14);
+    padding-top: var(--sl-docs-top-space);
   }
 
   .right-sidebar-panel a {
@@ -195,6 +196,14 @@
     font-size: 1rem;
   }
 
+  .sidebar-content details > summary .caret {
+    transform: rotate(90deg);
+  }
+
+  .sidebar-content details[open] > summary .caret {
+    transform: rotate(-90deg);
+  }
+
   .sidebar-content a > span {
     color: var(--foreground);
     padding-inline: 0.5rem;
@@ -224,6 +233,16 @@
     margin-bottom: 1px;
   }
 
+  @media (min-width: 64rem) {
+    .sidebar-pane .sidebar-content {
+      padding-top: var(--sl-docs-top-space);
+    }
+
+    .sidebar-content::before {
+      display: none;
+    }
+  }
+
   @media (max-width: 49.99rem) {
     .sidebar-pane .sidebar-content {
       --sl-sidebar-item-padding-inline: 0.5rem;
@@ -271,7 +290,7 @@
 
   @media (min-width: 50rem) {
     .content-panel:first-child {
-      padding-top: calc(var(--spacing) * 12);
+      padding-top: var(--sl-docs-top-space);
     }
   }
 
@@ -453,6 +472,19 @@
     z-index: 10;
   }
 
+  /* Draw the border on the wrapper so the collapse overlay and expanded
+     scrolling don't cover or scroll away the pre's own border. */
+  .expressive-code:has(> .ec-collapse) {
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    overflow: hidden;
+  }
+
+  .expressive-code:has(> .ec-collapse) pre {
+    border: 0;
+    border-radius: 0;
+  }
+
   .sl-bejamas-component-preview + .expressive-code {
     margin-top: 0;
   }
@@ -704,7 +736,7 @@
     max-width: calc(var(--spacing) * 150);
   }
 
-  starlight-menu-button button {
+  .sl-menu-button {
     box-shadow: none;
     padding: 0;
     width: calc(var(--spacing) * 6);
@@ -712,18 +744,18 @@
     color: var(--foreground);
   }
 
-  starlight-menu-button button svg {
+  .sl-menu-button svg {
     width: calc(var(--spacing) * 8);
     height: calc(var(--spacing) * 8);
     font-size: calc(var(--spacing) * 8);
   }
 
   @media (min-width: 50rem) and (max-width: calc(64rem - 0.01rem)) {
-    starlight-menu-button button {
+    .sl-menu-button {
       display: flex;
     }
 
-    [data-mobile-menu-expanded] {
+    body:has(#starlight__sidebar:popover-open) {
       overflow: hidden;
     }
   }