starlight-theme-bejamas 0.1.18 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # starlight-theme-bejamas
 
+## 0.2.0
+
+### Minor Changes
+
+- [#102](https://github.com/bejamas/ui/pull/102) [`25987b8`](https://github.com/bejamas/ui/commit/25987b872d38280dfe47f820019f86c1cb00eb6d) Thanks [@thomkrupa](https://github.com/thomkrupa)! - Improve the Starlight Bejamas theme runtime and expose the shared theme-choice helpers for consumers that need to integrate with theme state directly.
+  - Unify light, dark, and auto theme choice handling across the theme picker, page chrome, and preview surfaces so theme state stays in sync more reliably.
+  - Refresh browser theme-color metadata and the active theme stylesheet more consistently when theme state or presets change.
+  - Sync semantic icon updates as part of the theme runtime so icon-library changes propagate cleanly with preset-driven theme updates.
+  - Export `starlight-theme-bejamas/lib/theme-choice` as a public entrypoint for consumers that want to read, apply, or react to the shared theme-choice state.
+
 ## 0.1.18
 
 ### Patch Changes

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "starlight-theme-bejamas",
   "author": "Bejamas",
-  "version": "0.1.18",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "A Starlight theme using bejamas/ui",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./config": "./src/config.ts",
+    "./lib/theme-choice": "./src/lib/theme-choice.ts",
     "./styles/theme.css": "./src/styles/theme.css",
     "./overrides/Header.astro": "./src/overrides/Header.astro",
     "./overrides/PageFrame.astro": "./src/overrides/PageFrame.astro",
@@ -41,6 +42,7 @@
     "astro": ">=5.5.0"
   },
   "dependencies": {
+    "@bejamas/semantic-icons": "workspace:*",
     "@expressive-code/plugin-line-numbers": "^0.41.3",
     "@fontsource-variable/inter": "^5.2.8",
     "@fontsource/inter": "^5.2.8",

package/src/config.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+
+import { StarlightThemeBejamasConfigSchema } from "./config";
+
+describe("starlight-theme-bejamas config schema", () => {
+  test("parses nav and component maps under zod v4", () => {
+    const result = StarlightThemeBejamasConfigSchema.safeParse({
+      nav: [
+        {
+          label: {
+            en: "Docs",
+            fr: "Documentation",
+          },
+          href: "/docs/introduction",
+          attrs: {
+            rel: "prefetch",
+            "data-track": "docs-link",
+          },
+        },
+      ],
+      components: {
+        ThemeSelect: "./src/components/ThemeSwitcher.astro",
+        PageTitle: "./src/components/PageTitle.astro",
+      },
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) {
+      throw result.error;
+    }
+
+    expect(result.data.nav?.[0]?.label).toEqual({
+      en: "Docs",
+      fr: "Documentation",
+    });
+    expect(result.data.components?.ThemeSelect).toBe(
+      "./src/components/ThemeSwitcher.astro",
+    );
+  });
+});

package/src/config.ts

@@ -3,7 +3,8 @@ import type { HTMLAttributes } from "astro/types";
 import { z } from "astro/zod";
 
 const linkHTMLAttributesSchema = z.record(
-  z.union([z.string(), z.number(), z.boolean(), z.undefined()])
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean(), z.undefined()]),
 ) as z.Schema<
   Omit<HTMLAttributes<"a">, keyof AstroBuiltinAttributes | "children">
 >;
@@ -25,7 +26,7 @@ const navLinkSchema = z.object({
    * The value can be a string, or for multilingual sites, an object with values for each different locale. When using
    * the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).
    */
-  label: z.union([z.string(), z.record(z.string())]),
+  label: z.union([z.string(), z.record(z.string(), z.string())]),
   /**
    * The link to the topic’s content which an be a relative link to local files or the full URL of an external page.
    *
@@ -39,7 +40,7 @@ const navLinkSchema = z.object({
 
 export const StarlightThemeBejamasConfigSchema = z.object({
   nav: z.array(navLinkSchema).optional(),
-  components: z.record(z.string()).optional(),
+  components: z.record(z.string(), z.string()).optional(),
 });
 
 export type StarlightThemeBejamasUserConfig = z.input<

package/src/global.d.ts

@@ -1,12 +1,14 @@
 declare global {
   interface Window {
     StarlightThemeProvider?: {
-      updatePickers: (theme?: string) => void;
+      refreshThemeColors?: (theme?: string) => void;
+      updatePickers?: (theme?: string) => void;
     };
   }
 
   const StarlightThemeProvider: {
-    updatePickers: (theme?: string) => void;
+    refreshThemeColors?: (theme?: string) => void;
+    updatePickers?: (theme?: string) => void;
   };
 
   namespace App {

package/src/lib/theme-choice.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "bun:test";
+import {
+  STARLIGHT_THEME_STORAGE_KEY,
+  THEME_TOGGLE_CHANGED_EVENT,
+  applyThemeModeToRoot,
+  buildThemeChoiceBootstrapInlineScript,
+  getThemeChoiceFromRoot,
+  getThemeModeFromRoot,
+  loadStoredThemeChoice,
+  parseStoredThemeChoice,
+  resolveThemeMode,
+  setThemeChoice,
+  storeThemeChoice,
+  syncThemeChoiceControls,
+} from "./theme-choice";
+
+function createThemeRoot() {
+  const classes = new Set<string>();
+
+  return {
+    classes,
+    root: {
+      dataset: {} as Record<string, string | undefined>,
+      classList: {
+        add: (...tokens: string[]) => {
+          for (const token of tokens) {
+            classes.add(token);
+          }
+        },
+        remove: (...tokens: string[]) => {
+          for (const token of tokens) {
+            classes.delete(token);
+          }
+        },
+        contains: (token: string) => classes.has(token),
+      },
+    },
+  };
+}
+
+describe("theme choice runtime", () => {
+  it("parses only supported stored theme choices", () => {
+    expect(parseStoredThemeChoice("light")).toBe("light");
+    expect(parseStoredThemeChoice("dark")).toBe("dark");
+    expect(parseStoredThemeChoice("auto")).toBe("auto");
+    expect(parseStoredThemeChoice("")).toBe("auto");
+    expect(parseStoredThemeChoice("system")).toBe("auto");
+    expect(parseStoredThemeChoice(undefined)).toBe("auto");
+  });
+
+  it("loads the stored theme choice from localStorage-compatible storage", () => {
+    expect(
+      loadStoredThemeChoice({
+        getItem: (key) =>
+          key === STARLIGHT_THEME_STORAGE_KEY ? "dark" : null,
+      }),
+    ).toBe("dark");
+
+    expect(
+      loadStoredThemeChoice({
+        getItem: () => "unexpected",
+      }),
+    ).toBe("auto");
+
+    expect(
+      loadStoredThemeChoice({
+        getItem: () => {
+          throw new Error("storage unavailable");
+        },
+      }),
+    ).toBe("auto");
+  });
+
+  it("resolves auto against the preferred color scheme", () => {
+    expect(resolveThemeMode("light", false)).toBe("light");
+    expect(resolveThemeMode("dark", true)).toBe("dark");
+    expect(resolveThemeMode("auto", true)).toBe("light");
+    expect(resolveThemeMode("auto", false)).toBe("dark");
+  });
+
+  it("applies theme attributes and class state to the target root", () => {
+    const { root, classes } = createThemeRoot();
+
+    classes.add("dark");
+    applyThemeModeToRoot(root, "auto", "light");
+
+    expect(root.dataset.theme).toBe("light");
+    expect(root.dataset.themeChoice).toBe("auto");
+    expect(classes.has("light")).toBe(true);
+    expect(classes.has("dark")).toBe(false);
+  });
+
+  it("stores explicit theme choices and clears auto to the empty localStorage value", () => {
+    const stored = new Map<string, string>();
+    const storage = {
+      setItem: (key: string, value: string) => {
+        stored.set(key, value);
+      },
+    };
+
+    storeThemeChoice(storage, "dark");
+    storeThemeChoice(storage, "auto");
+
+    expect(stored.get(STARLIGHT_THEME_STORAGE_KEY)).toBe("");
+  });
+
+  it("reads theme choice and effective mode from the document root", () => {
+    const { root, classes } = createThemeRoot();
+
+    root.dataset.themeChoice = "auto";
+    root.dataset.theme = "";
+    classes.add("dark");
+
+    expect(getThemeChoiceFromRoot(root)).toBe("auto");
+    expect(getThemeModeFromRoot(root, "light")).toBe("dark");
+  });
+
+  it("syncs tabs-based and legacy select-based controls to the requested choice", () => {
+    let tabsValue = "";
+    let selectValue = "";
+    const nativeSelect = { value: "" };
+    const tabsRoot = {
+      dataset: {} as Record<string, string | undefined>,
+      dispatchEvent: (event: Event) => {
+        tabsValue =
+          (event as CustomEvent<{ value?: string }>).detail?.value ?? "";
+        return true;
+      },
+    };
+    const selectRoot = {
+      dataset: {} as Record<string, string | undefined>,
+      dispatchEvent: (event: Event) => {
+        selectValue =
+          (event as CustomEvent<{ value?: string }>).detail?.value ?? "";
+        return true;
+      },
+    };
+    const picker = {
+      querySelector: (selector: string) => {
+        if (selector === '[data-slot="tabs"][data-theme-choice-tabs]') {
+          return tabsRoot;
+        }
+
+        if (selector === "select") {
+          return nativeSelect;
+        }
+
+        if (selector === '#starlight-theme-select, [data-slot="select"]') {
+          return selectRoot;
+        }
+
+        return null;
+      },
+      querySelectorAll: () => [] as unknown as NodeListOf<Element>,
+    };
+    const root = {
+      querySelectorAll: (selector: string) => {
+        if (selector === "starlight-theme-select") {
+          return [picker] as unknown as NodeListOf<Element>;
+        }
+
+        if (selector === '[data-slot="tabs"][data-theme-choice-tabs]') {
+          return [tabsRoot] as unknown as NodeListOf<Element>;
+        }
+
+        return [] as unknown as NodeListOf<Element>;
+      },
+    };
+
+    syncThemeChoiceControls("light", root as unknown as ParentNode);
+
+    expect(tabsRoot.dataset.defaultValue).toBe("light");
+    expect(tabsRoot.dataset.value).toBe("light");
+    expect(tabsValue).toBe("light");
+    expect(nativeSelect.value).toBe("light");
+    expect(selectRoot.dataset.defaultValue).toBe("light");
+    expect(selectRoot.dataset.value).toBe("light");
+    expect(selectValue).toBe("light");
+  });
+
+  it("applies the shared global theme choice path including storage, controls, and event dispatch", () => {
+    const { root, classes } = createThemeRoot();
+    const stored = new Map<string, string>();
+    const dispatched: Array<{ theme: string; themeChoice: string }> = [];
+    let tabsValue = "";
+    const tabsRoot = {
+      dataset: {} as Record<string, string | undefined>,
+      dispatchEvent: (event: Event) => {
+        tabsValue =
+          (event as CustomEvent<{ value?: string }>).detail?.value ?? "";
+        return true;
+      },
+    };
+    const controlsRoot = {
+      querySelectorAll: (selector: string) => {
+        if (selector === '[data-slot="tabs"][data-theme-choice-tabs]') {
+          return [tabsRoot] as unknown as NodeListOf<Element>;
+        }
+
+        return [] as unknown as NodeListOf<Element>;
+      },
+    };
+    const dispatchTarget = {
+      dispatchEvent: (event: Event) => {
+        const customEvent = event as CustomEvent<{
+          theme?: string;
+          themeChoice?: string;
+        }>;
+
+        if (event.type === THEME_TOGGLE_CHANGED_EVENT) {
+          dispatched.push({
+            theme: customEvent.detail?.theme ?? "",
+            themeChoice: customEvent.detail?.themeChoice ?? "",
+          });
+        }
+
+        return true;
+      },
+    };
+
+    const effectiveTheme = setThemeChoice("dark", {
+      root,
+      prefersLight: true,
+      storage: {
+        setItem: (key, value) => {
+          stored.set(key, value);
+        },
+      },
+      controlsRoot: controlsRoot as unknown as ParentNode,
+      dispatchTarget: dispatchTarget as unknown as EventTarget,
+    });
+
+    expect(effectiveTheme).toBe("dark");
+    expect(root.dataset.themeChoice).toBe("dark");
+    expect(root.dataset.theme).toBe("dark");
+    expect(classes.has("dark")).toBe(true);
+    expect(stored.get(STARLIGHT_THEME_STORAGE_KEY)).toBe("dark");
+    expect(tabsValue).toBe("dark");
+    expect(dispatched).toEqual([{ theme: "dark", themeChoice: "dark" }]);
+  });
+
+  it("builds an inline bootstrap script that owns root state and control sync", () => {
+    const script = buildThemeChoiceBootstrapInlineScript();
+
+    expect(script).toContain(STARLIGHT_THEME_STORAGE_KEY);
+    expect(script).toContain("dataset.themeChoice");
+    expect(script).toContain('[data-slot="tabs"][data-theme-choice-tabs]');
+    expect(script).toContain(THEME_TOGGLE_CHANGED_EVENT);
+    expect(script).toContain("prefers-color-scheme: light");
+  });
+});

package/src/lib/theme-choice.ts

@@ -0,0 +1,346 @@
+export const STARLIGHT_THEME_STORAGE_KEY = "starlight-theme";
+export const THEME_TOGGLE_CHANGED_EVENT = "theme-toggle-changed";
+
+export type ThemeChoice = "auto" | "dark" | "light";
+export type ThemeMode = "dark" | "light";
+
+export interface ThemeRoot {
+  dataset: Record<string, string | undefined>;
+  classList: {
+    add: (...tokens: string[]) => void;
+    remove: (...tokens: string[]) => void;
+  };
+}
+
+type ThemeClassList = ThemeRoot["classList"] & {
+  contains?: (token: string) => boolean;
+};
+
+type ThemeRootElement = ThemeRoot & {
+  classList: ThemeClassList;
+};
+
+type ThemeStorageReader = Pick<Storage, "getItem"> | null | undefined;
+type ThemeStorageWriter = Pick<Storage, "setItem"> | null | undefined;
+
+const THEME_CHOICE_TAB_SELECTOR = '[data-slot="tabs"][data-theme-choice-tabs]';
+
+function getElementsWithSelf<T extends Element>(
+  root: ParentNode,
+  selector: string,
+): T[] {
+  const matches: T[] = [];
+
+  if (
+    typeof Element !== "undefined" &&
+    root instanceof Element &&
+    root.matches(selector)
+  ) {
+    matches.push(root as T);
+  }
+
+  matches.push(...Array.from(root.querySelectorAll<T>(selector)));
+
+  return matches;
+}
+
+export function parseStoredThemeChoice(value: unknown): ThemeChoice {
+  return value === "auto" || value === "dark" || value === "light"
+    ? value
+    : "auto";
+}
+
+export function loadStoredThemeChoice(storage: ThemeStorageReader): ThemeChoice {
+  try {
+    return parseStoredThemeChoice(
+      storage?.getItem(STARLIGHT_THEME_STORAGE_KEY),
+    );
+  } catch {
+    return "auto";
+  }
+}
+
+export function resolveThemeMode(
+  themeChoice: ThemeChoice,
+  prefersLight: boolean,
+): ThemeMode {
+  if (themeChoice === "light" || themeChoice === "dark") {
+    return themeChoice;
+  }
+
+  return prefersLight ? "light" : "dark";
+}
+
+export function applyThemeModeToRoot(
+  root: ThemeRoot,
+  themeChoice: ThemeChoice,
+  themeMode: ThemeMode,
+): void {
+  root.dataset.theme = themeMode;
+  root.dataset.themeChoice = themeChoice;
+  root.classList.remove("light", "dark");
+  root.classList.add(themeMode);
+}
+
+export function storeThemeChoice(
+  storage: ThemeStorageWriter,
+  themeChoice: ThemeChoice,
+): void {
+  try {
+    storage?.setItem(
+      STARLIGHT_THEME_STORAGE_KEY,
+      themeChoice === "light" || themeChoice === "dark" ? themeChoice : "",
+    );
+  } catch {}
+}
+
+export function getThemeChoiceFromRoot(
+  root: Pick<ThemeRoot, "dataset">,
+): ThemeChoice {
+  return parseStoredThemeChoice(root.dataset.themeChoice);
+}
+
+export function getThemeModeFromRoot(
+  root: ThemeRootElement,
+  fallbackMode: ThemeMode,
+): ThemeMode {
+  if (root.dataset.theme === "light" || root.dataset.theme === "dark") {
+    return root.dataset.theme;
+  }
+
+  if (root.classList.contains?.("dark")) {
+    return "dark";
+  }
+
+  if (root.classList.contains?.("light")) {
+    return "light";
+  }
+
+  return fallbackMode;
+}
+
+function syncThemeChoiceTabControls(
+  themeChoice: ThemeChoice,
+  root: ParentNode,
+): void {
+  const tabsRoots = new Set<HTMLElement>();
+
+  for (const tabsRoot of getElementsWithSelf<HTMLElement>(
+    root,
+    THEME_CHOICE_TAB_SELECTOR,
+  )) {
+    tabsRoots.add(tabsRoot);
+  }
+
+  for (const picker of getElementsWithSelf<HTMLElement>(
+    root,
+    "starlight-theme-select",
+  )) {
+    const tabsRoot = picker.querySelector<HTMLElement>(THEME_CHOICE_TAB_SELECTOR);
+    if (tabsRoot) {
+      tabsRoots.add(tabsRoot);
+    }
+  }
+
+  for (const tabsRoot of tabsRoots) {
+    tabsRoot.dataset.defaultValue = themeChoice;
+    tabsRoot.dataset.value = themeChoice;
+    tabsRoot.dispatchEvent(
+      new CustomEvent("tabs:set", { detail: { value: themeChoice } }),
+    );
+  }
+}
+
+function syncLegacyThemeChoiceSelectControls(
+  themeChoice: ThemeChoice,
+  root: ParentNode,
+): void {
+  for (const picker of getElementsWithSelf<HTMLElement>(
+    root,
+    "starlight-theme-select",
+  )) {
+    const nativeSelect = picker.querySelector<HTMLSelectElement>("select");
+    if (nativeSelect) {
+      nativeSelect.value = themeChoice;
+    }
+
+    const selectRoot = picker.querySelector<HTMLElement>(
+      '#starlight-theme-select, [data-slot="select"]',
+    );
+    if (!selectRoot) {
+      continue;
+    }
+
+    selectRoot.dataset.defaultValue = themeChoice;
+    selectRoot.dataset.value = themeChoice;
+    selectRoot.dispatchEvent(
+      new CustomEvent("select:set", { detail: { value: themeChoice } }),
+    );
+  }
+}
+
+export function syncThemeChoiceControls(
+  themeChoice: ThemeChoice,
+  root: ParentNode = document,
+): void {
+  syncThemeChoiceTabControls(themeChoice, root);
+  syncLegacyThemeChoiceSelectControls(themeChoice, root);
+}
+
+export function dispatchThemeToggleChange(
+  target: EventTarget,
+  themeMode: ThemeMode,
+  themeChoice: ThemeChoice,
+): void {
+  target.dispatchEvent(
+    new CustomEvent(THEME_TOGGLE_CHANGED_EVENT, {
+      detail: {
+        theme: themeMode,
+        themeChoice,
+      },
+    }),
+  );
+}
+
+export function setThemeChoice(
+  themeChoice: ThemeChoice,
+  options: {
+    storage?: ThemeStorageWriter;
+    root?: ThemeRootElement;
+    prefersLight?: boolean;
+    controlsRoot?: ParentNode;
+    dispatchTarget?: EventTarget;
+    emitEvent?: boolean;
+  } = {},
+): ThemeMode {
+  const root = options.root ?? (document.documentElement as HTMLElement);
+  const effectiveTheme = resolveThemeMode(
+    themeChoice,
+    options.prefersLight ??
+      window.matchMedia("(prefers-color-scheme: light)").matches,
+  );
+
+  applyThemeModeToRoot(root, themeChoice, effectiveTheme);
+  storeThemeChoice(options.storage ?? localStorage, themeChoice);
+  syncThemeChoiceControls(themeChoice, options.controlsRoot ?? document);
+
+  if (options.emitEvent !== false) {
+    dispatchThemeToggleChange(
+      options.dispatchTarget ?? window,
+      effectiveTheme,
+      themeChoice,
+    );
+  }
+
+  return effectiveTheme;
+}
+
+export function buildThemeChoiceBootstrapInlineScript(): string {
+  return `(function () {
+  const storageKey = ${JSON.stringify(STARLIGHT_THEME_STORAGE_KEY)};
+  const eventName = ${JSON.stringify(THEME_TOGGLE_CHANGED_EVENT)};
+  const parseStoredThemeChoice = (value) =>
+    value === "auto" || value === "dark" || value === "light" ? value : "auto";
+  const loadStoredThemeChoice = () => {
+    try {
+      return parseStoredThemeChoice(
+        typeof localStorage !== "undefined" ? localStorage.getItem(storageKey) : null,
+      );
+    } catch {
+      return "auto";
+    }
+  };
+  const resolveThemeMode = (themeChoice, prefersLight) => {
+    if (themeChoice === "light" || themeChoice === "dark") {
+      return themeChoice;
+    }
+
+    return prefersLight ? "light" : "dark";
+  };
+  const applyThemeModeToRoot = (themeChoice) => {
+    const themeMode = resolveThemeMode(
+      themeChoice,
+      matchMedia("(prefers-color-scheme: light)").matches,
+    );
+    const root = document.documentElement;
+
+    root.dataset.theme = themeMode;
+    root.dataset.themeChoice = themeChoice;
+    root.classList.remove("light", "dark");
+    root.classList.add(themeMode);
+
+    return themeMode;
+  };
+  const syncThemeChoiceControls = (themeChoice) => {
+    document
+      .querySelectorAll('[data-slot="tabs"][data-theme-choice-tabs]')
+      .forEach((tabsRoot) => {
+        tabsRoot.dataset.defaultValue = themeChoice;
+        tabsRoot.dataset.value = themeChoice;
+        tabsRoot.dispatchEvent(
+          new CustomEvent("tabs:set", { detail: { value: themeChoice } }),
+        );
+      });
+
+    document.querySelectorAll("starlight-theme-select").forEach((picker) => {
+      const nativeSelect = picker.querySelector("select");
+      if (nativeSelect instanceof HTMLSelectElement) {
+        nativeSelect.value = themeChoice;
+      }
+
+      const selectRoot = picker.querySelector(
+        '#starlight-theme-select, [data-slot="select"]',
+      );
+      if (!(selectRoot instanceof HTMLElement)) {
+        return;
+      }
+
+      selectRoot.dataset.defaultValue = themeChoice;
+      selectRoot.dataset.value = themeChoice;
+      selectRoot.dispatchEvent(
+        new CustomEvent("select:set", { detail: { value: themeChoice } }),
+      );
+    });
+  };
+  const dispatchThemeToggleChange = (themeMode, themeChoice) => {
+    window.dispatchEvent(
+      new CustomEvent(eventName, {
+        detail: {
+          theme: themeMode,
+          themeChoice,
+        },
+      }),
+    );
+  };
+  const syncThemeChoice = (themeChoice, emitEvent) => {
+    const themeMode = applyThemeModeToRoot(themeChoice);
+    syncThemeChoiceControls(themeChoice);
+    if (emitEvent) {
+      dispatchThemeToggleChange(themeMode, themeChoice);
+    }
+  };
+  const syncStoredThemeChoice = (emitEvent) => {
+    syncThemeChoice(loadStoredThemeChoice(), emitEvent);
+  };
+  const mediaQuery = matchMedia("(prefers-color-scheme: light)");
+  const onMediaChange = () => {
+    if (loadStoredThemeChoice() === "auto") {
+      syncThemeChoice("auto", true);
+    }
+  };
+
+  syncStoredThemeChoice(false);
+
+  window.addEventListener("storage", (event) => {
+    if (event.key === storageKey) {
+      syncStoredThemeChoice(true);
+    }
+  });
+
+  if (typeof mediaQuery.addEventListener === "function") {
+    mediaQuery.addEventListener("change", onMediaChange);
+  } else if (typeof mediaQuery.addListener === "function") {
+    mediaQuery.addListener(onMediaChange);
+  }
+})();`;
+}

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

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { buildCurrentThemeStylesheetHref } from "./theme-stylesheet";
+
+describe("current theme stylesheet helpers", () => {
+  test("adds a cache-busting query param to relative hrefs", () => {
+    expect(
+      buildCurrentThemeStylesheetHref("/r/themes/current-theme.css", 123),
+    ).toBe("/r/themes/current-theme.css?v=123");
+  });
+
+  test("preserves existing query params when cache-busting", () => {
+    expect(
+      buildCurrentThemeStylesheetHref("/r/themes/current-theme.css?foo=bar", 123),
+    ).toBe("/r/themes/current-theme.css?foo=bar&v=123");
+  });
+});

package/src/lib/theme-stylesheet.ts

@@ -0,0 +1,13 @@
+export const CURRENT_THEME_STYLESHEET_SELECTOR =
+  'link[data-current-theme-stylesheet]';
+
+export function buildCurrentThemeStylesheetHref(
+  href: string,
+  version: string | number,
+) {
+  const url = new URL(href, "https://ui.bejamas.com");
+  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}`;
+}

package/src/overrides/MobileTableOfContents.astro

@@ -87,12 +87,12 @@ const { toc } = Astro.locals.starlightRoute;
       align-items: center;
       justify-content: space-between;
       border: 1px solid var(--sl-color-gray-5);
-      border-radius: 0.5rem;
+      border-radius: calc(var(--radius) - 2px);
       padding-block: 0.5rem;
       padding-inline-start: 0.75rem;
       padding-inline-end: 0.5rem;
       line-height: 1;
-      background-color: var(--sl-color-black);
+      background-color: var(--background);
       user-select: none;
       cursor: pointer;
       font-weight: 500;
@@ -133,11 +133,11 @@ const { toc } = Astro.locals.starlightRoute;
       transition: background 200ms ease-out;
     }
     details[open] .toggle {
-      color: var(--sl-color-white);
+      color: var(--foreground);
       border-color: var(--sl-color-accent);
     }
     details .toggle:hover {
-      color: var(--sl-color-white);
+      color: var(--foreground);
       border-color: var(--sl-color-gray-2);
     }
 
@@ -152,7 +152,7 @@ const { toc } = Astro.locals.starlightRoute;
       white-space: nowrap;
       text-overflow: ellipsis;
       overflow: hidden;
-      color: var(--sl-color-white);
+      color: var(--foreground);
     }
 
     .dropdown {
@@ -164,7 +164,7 @@ const { toc } = Astro.locals.starlightRoute;
         85vh - var(--sl-nav-height) - var(--sl-mobile-toc-height)
       );
       overflow-y: auto;
-      background-color: var(--sl-color-black);
+      background-color: var(--popover);
       box-shadow: var(--sl-shadow-md);
       overscroll-behavior: contain;
     }

package/src/overrides/PageTitle.astro

@@ -129,7 +129,7 @@ const isRtl = dir === "rtl";
       font-size: 1.875rem;
       line-height: 1.2;
       font-weight: 500;
-      color: var(--sl-color-white);
+      color: var(--foreground);
     }
 
     @media (min-width: 50rem) {

package/src/overrides/TableOfContents/TableOfContentsList.astro

@@ -70,7 +70,7 @@ const { toc, isMobile = false, depth = 0 } = Astro.props;
     .isMobile a[aria-current="true"],
     .isMobile a[aria-current="true"]:hover,
     .isMobile a[aria-current="true"]:focus {
-      color: var(--sl-color-white);
+      color: var(--foreground);
       background-color: unset;
     }
     .isMobile a[aria-current="true"]::after {

package/src/overrides/ThemeProvider.astro

@@ -1,7 +1,14 @@
+---
+import { buildThemeChoiceBootstrapInlineScript } from "../lib/theme-choice";
+
+const themeChoiceBootstrapScript = buildThemeChoiceBootstrapInlineScript();
+---
+
+<script is:inline set:html={themeChoiceBootstrapScript} />
+
 {/* This is intentionally inlined to avoid FOUC. */}
 <script is:inline>
   window.StarlightThemeProvider = (() => {
-    const storageKey = "starlight-theme";
     const themeMetaMedias = [
       "(prefers-color-scheme: light)",
       "(prefers-color-scheme: dark)",
@@ -14,12 +21,12 @@
       theme === "auto" || theme === "dark" || theme === "light"
         ? theme
         : "auto";
-    const getStoredThemeChoice = () =>
-      parseTheme(
-        typeof localStorage !== "undefined" && localStorage.getItem(storageKey),
-      );
+    const getPreferredColorScheme = () =>
+      window.matchMedia("(prefers-color-scheme: light)").matches
+        ? "light"
+        : "dark";
 
-    const themeColors = (() => {
+    const readThemeColors = () => {
       const html = document.documentElement;
       const prevTheme = html.dataset.theme;
       const prevDark = html.classList.contains("dark");
@@ -45,7 +52,7 @@
       }
 
       return { light, dark };
-    })();
+    };
 
     function ensureThemeMeta(head, media) {
       const baseSelector = `meta[name="theme-color"][media="${media}"]`;
@@ -67,6 +74,7 @@
     }
 
     function syncThemeColor(theme) {
+      const themeColors = readThemeColors();
       const color = themeColors[theme];
       const head = document.head;
       if (!color || !head) return;
@@ -77,23 +85,25 @@
       });
     }
 
-    const themeChoice = getStoredThemeChoice();
     const effectiveTheme =
-      themeChoice === "auto"
-        ? window.matchMedia("(prefers-color-scheme: light)").matches
-          ? "light"
-          : "dark"
-        : themeChoice;
-    document.documentElement.dataset.theme = effectiveTheme;
-    document.documentElement.dataset.themeChoice = themeChoice;
-    document.documentElement.classList.toggle(
-      "dark",
-      effectiveTheme === "dark",
-    );
+      document.documentElement.dataset.theme === "light" ||
+      document.documentElement.dataset.theme === "dark"
+        ? document.documentElement.dataset.theme
+        : getPreferredColorScheme();
     syncThemeColor(effectiveTheme);
     return {
+      refreshThemeColors(theme) {
+        const themeChoice = parseTheme(
+          theme ?? document.documentElement.dataset.themeChoice,
+        );
+        const effectiveTheme =
+          themeChoice === "auto" ? getPreferredColorScheme() : themeChoice;
+        syncThemeColor(effectiveTheme);
+      },
       updatePickers(theme) {
-        const themeChoice = parseTheme(theme ?? getStoredThemeChoice());
+        const themeChoice = parseTheme(
+          theme ?? document.documentElement.dataset.themeChoice,
+        );
         document
           .querySelectorAll("starlight-theme-select")
           .forEach((picker) => {
@@ -110,19 +120,130 @@
                 new CustomEvent("select:set", { detail: { value: themeChoice } }),
               );
             }
-
-            /** @type {HTMLTemplateElement | null} */
-            const tmpl = document.querySelector(`#theme-icons`);
-            const newIcon =
-              tmpl && tmpl.content.querySelector("." + themeChoice);
-            if (newIcon) {
-              const oldIcon = picker.querySelector("svg.label-icon");
-              if (oldIcon) {
-                oldIcon.replaceChildren(...newIcon.cloneNode(true).childNodes);
-              }
-            }
           });
       },
     };
   })();
 </script>
+
+<script>
+  import { syncSemanticIconsInRoot } from "@bejamas/semantic-icons/browser";
+  import {
+    buildCurrentThemeStylesheetHref,
+    CURRENT_THEME_STYLESHEET_SELECTOR,
+  } 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() {
+    const renderedIcon = document.querySelector("[data-icon-library]");
+    const iconLibrary =
+      renderedIcon instanceof SVGElement
+        ? renderedIcon.dataset.iconLibrary
+        : document.documentElement.dataset.iconLibrary;
+
+    if (iconLibrary) {
+      document.documentElement.dataset.iconLibrary = iconLibrary;
+      syncSemanticIconsInRoot(document, iconLibrary);
+    }
+  }
+
+  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?.();
+      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();
+        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();
+    });
+  };
+
+  if (!(SETUP_KEY in window)) {
+    window[SETUP_KEY] = true;
+    syncDocumentIconLibrary();
+
+    window.addEventListener("theme-toggle-changed", (event) => {
+      const themeChoice =
+        event instanceof CustomEvent && typeof event.detail?.themeChoice === "string"
+          ? event.detail.themeChoice
+          : undefined;
+
+      window.StarlightThemeProvider?.refreshThemeColors?.(themeChoice);
+    });
+
+    window.addEventListener(PRESET_CHANGE_EVENT, (event) => {
+      const presetChange = event;
+
+      pendingIconLibrary =
+        presetChange instanceof CustomEvent &&
+        typeof presetChange.detail?.iconLibrary === "string"
+          ? presetChange.detail.iconLibrary
+          : null;
+
+      scheduleCurrentThemeStylesheetRefresh();
+    });
+    document.addEventListener("astro:after-swap", () => {
+      window.StarlightThemeProvider?.refreshThemeColors?.();
+      syncDocumentIconLibrary();
+    });
+  }
+</script>

package/src/overrides/ThemeSelect.astro

@@ -36,61 +36,46 @@ import { SunIcon, MoonIcon, LaptopIcon } from "@lucide/astro";
   </div>
 </starlight-theme-select>
 
-<script is:inline>
-  StarlightThemeProvider.updatePickers();
-</script>
-
 <script>
-  type Theme = "auto" | "dark" | "light";
-  const storageKey = "starlight-theme";
-
-  const parseTheme = (theme: unknown): Theme =>
-    theme === "auto" || theme === "dark" || theme === "light" ? theme : "auto";
-
-  const loadTheme = (): Theme =>
-    parseTheme(
-      typeof localStorage !== "undefined" && localStorage.getItem(storageKey),
-    );
-
-  function storeTheme(theme: Theme): void {
-    if (typeof localStorage !== "undefined") {
-      localStorage.setItem(
-        storageKey,
-        theme === "light" || theme === "dark" ? theme : "",
-      );
-    }
-  }
+  import {
+    getThemeChoiceFromRoot,
+    parseStoredThemeChoice,
+    setThemeChoice,
+    syncThemeChoiceControls,
+  } from "../lib/theme-choice";
 
-  const getPreferredColorScheme = (): Theme =>
-    matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+  class StarlightThemeSelect extends HTMLElement {
+    private selectRoot: HTMLElement | null = null;
 
-  function onThemeChange(theme: Theme): void {
-    const resolved = theme === "auto" ? getPreferredColorScheme() : theme;
-    StarlightThemeProvider.updatePickers(theme);
-    document.documentElement.dataset.theme = resolved;
-    document.documentElement.dataset.themeChoice = theme;
-    document.documentElement.classList.toggle("dark", resolved === "dark");
-    storeTheme(theme);
-  }
+    private onSelectChange = (event: Event) => {
+      const value = (event as CustomEvent<{ value?: unknown }>).detail?.value;
+      if (typeof value !== "string") return;
 
-  matchMedia("(prefers-color-scheme: light)").addEventListener("change", () => {
-    if (loadTheme() === "auto") onThemeChange("auto");
-  });
+      const nextTheme = parseStoredThemeChoice(value);
+      const currentTheme = getThemeChoiceFromRoot(document.documentElement);
+      if (nextTheme === currentTheme) return;
 
-  class StarlightThemeSelect extends HTMLElement {
-    constructor() {
-      super();
-      onThemeChange(loadTheme());
-      const select = this.querySelector("#starlight-theme-select");
-      select?.addEventListener("select:change", (e) => {
-        if (e.detail.value) {
-          onThemeChange(parseTheme(e.detail.value));
-        }
-      });
+      setThemeChoice(nextTheme);
+    };
+
+    connectedCallback() {
+      this.selectRoot = this.querySelector<HTMLElement>("#starlight-theme-select");
+      syncThemeChoiceControls(
+        getThemeChoiceFromRoot(document.documentElement),
+        this,
+      );
+      this.selectRoot?.addEventListener("select:change", this.onSelectChange);
+    }
+
+    disconnectedCallback() {
+      this.selectRoot?.removeEventListener("select:change", this.onSelectChange);
+      this.selectRoot = null;
     }
   }
 
-  customElements.define("starlight-theme-select", StarlightThemeSelect);
+  if (!customElements.get("starlight-theme-select")) {
+    customElements.define("starlight-theme-select", StarlightThemeSelect);
+  }
 </script>
 
 <style>

package/src/styles/theme.css

@@ -49,10 +49,8 @@
   }
 
   :root {
-    --sl-font: "Inter Variable", sans-serif;
-    --sl-font-mono: "Geist Mono", monospace;
-
-    --radius: 0.5rem;
+    --sl-font: var(--font-sans);
+    --sl-font-mono: var(--font-mono);
 
     --sl-color-text-accent: var(--accent-foreground);
 
@@ -74,8 +72,7 @@
 
     --sl-color-gray-2: var(--input);
 
-    --default-font-family: "Inter Variable", sans-serif;
-    --font-sans: "Inter Variable", sans-serif;
+    --default-font-family: var(--font-sans);
 
     --sl-color-bg: var(--background);
     --sl-color-fg: var(--foreground);
@@ -107,6 +104,7 @@
     --ec-frm-inlBtnBgHoverOrFocusOpa: 1;
     --ec-frm-trmIcon: url(data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBMaWNlbnNlOiBNSVQuIE1hZGUgYnkgcGhvc3Bob3I6IGh0dHBzOi8vZ2l0aHViLmNvbS9waG9zcGhvci1pY29ucy9waG9zcGhvci1pY29ucyAtLT4KPHN2ZyBmaWxsPSIjMDAwMDAwIiB3aWR0aD0iMThweCIgaGVpZ2h0PSIxOHB4IiB2aWV3Qm94PSIwIDAgMjU2IDI1NiIgaWQ9IkZsYXQiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CiAgPHBhdGggZD0iTTExNy4zMTQ5NCwxMzMuOTc5NDlsLTcyLDY0YTguMDAwMTgsOC4wMDAxOCwwLDAsMS0xMC42Mjk4OC0xMS45NTlMOTkuOTU4NSwxMjgsMzQuNjg1MDYsNjkuOTc5NDlhOC4wMDAxOCw4LjAwMDE4LDAsMCwxLDEwLjYyOTg4LTExLjk1OWw3Miw2NGE4LjAwMDU0LDguMDAwNTQsMCwwLDEsMCwxMS45NTlaTTIxNS45OTQxNCwxODRoLTk2YTgsOCwwLDAsMCwwLDE2aDk2YTgsOCwwLDEsMCwwLTE2WiIvPgo8L3N2Zz4=);
     --ecGtrBrdWd: 5px;
+    --sl-nav-gap: calc(var(--spacing) * 2);
   }
 
   @media (min-width: 50em) {
@@ -284,15 +282,6 @@
     padding-inline: 0.5rem;
   }
 
-  site-search button {
-    --tw-shadow: var(--shadow-sm);
-    box-shadow:
-      var(--tw-inset-shadow), var(--tw-inset-ring-shadow),
-      var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow);
-    border-radius: calc(var(--radius) - 2px);
-    max-width: calc(var(--spacing) * 50);
-  }
-
   .expressive-code .frame {
     box-shadow: none;
   }
@@ -421,21 +410,6 @@
     text-underline-offset: 4px;
   }
 
-  button[data-open-modal] {
-    border-color: var(--border);
-    color: var(--foreground);
-    box-shadow: none;
-    background-color: var(--background);
-    height: calc(var(--spacing) * 9);
-  }
-
-  button[data-open-modal] kbd {
-    background-color: var(--muted);
-    color: var(--muted-foreground);
-    border-radius: calc(var(--radius) - 4px);
-    gap: 0;
-  }
-
   .tablist-wrapper ~ [role="tabpanel"] {
     margin-top: calc(var(--spacing) * 2.5);
   }