blume 1.5.3 → 1.6.0

package/src/components/dropdown-dismiss.ts

@@ -0,0 +1,122 @@
+/**
+ * Light-dismiss for the site's `<details>`-based dropdowns: the page actions
+ * (Export / Open in chat / Connect to MCP), the header language switcher and
+ * the nav selectors all render the same floating `<details>` + absolute panel,
+ * and a native `<details>` only closes when its own `<summary>` is clicked
+ * again, leaving the panel hanging over the page. Any dropdown that opts in
+ * with `data-blume-dropdown` gets the four legs of a real menu:
+ *
+ * - a pointer press outside the open panel closes it;
+ * - Escape closes it, restoring focus to the trigger when the keypress
+ *   originated inside the panel;
+ * - keyboard focus leaving the panel closes it;
+ * - the window losing focus closes it — the only signal the parent document
+ *   gets when a press lands inside an `<iframe>` embed, since pointer events
+ *   in a child browsing context never propagate up.
+ *
+ * Every listener sits on `document`/`window` once per real page load and
+ * queries the DOM live, so client-router swaps (which rebuild the dropdown
+ * markup) need no re-init and never stack duplicate listeners. Per-component
+ * behavior — one-open-at-a-time within a group, viewport flipping — stays in
+ * the component that owns it.
+ */
+
+const OPEN_DROPDOWN = "details[data-blume-dropdown][open]";
+
+/**
+ * Every dropdown currently open. Each component group keeps itself to one
+ * open panel, but a page holds several groups (the header selectors and the
+ * page actions), and a browser that doesn't focus a `<summary>` on click lets
+ * a keyboard-opened panel join a pointer-opened one — so the dismissal rules
+ * apply to all of them, never just the first in DOM order.
+ */
+const openDropdowns = (): HTMLDetailsElement[] => [
+  ...document.querySelectorAll<HTMLDetailsElement>(OPEN_DROPDOWN),
+];
+
+/**
+ * Close `open`. `restoreFocus` moves focus back to its trigger, which a
+ * keyboard dismissal wants and a pointer or focus-driven one does not.
+ */
+const dismiss = (open: HTMLDetailsElement, restoreFocus: boolean): void => {
+  open.open = false;
+  if (restoreFocus) {
+    open.querySelector<HTMLElement>("summary")?.focus();
+  }
+};
+
+const isInside = (
+  dropdown: HTMLDetailsElement,
+  target: EventTarget | null
+): boolean => target instanceof Node && dropdown.contains(target);
+
+const onPointerDown = (event: PointerEvent): void => {
+  for (const open of openDropdowns()) {
+    if (!isInside(open, event.target)) {
+      dismiss(open, false);
+    }
+  }
+};
+
+const onKeyDown = (event: KeyboardEvent): void => {
+  // `isComposing`: an IME cancel arrives as Escape and isn't a dismissal.
+  if (event.key !== "Escape" || event.isComposing) {
+    return;
+  }
+  // An Escape aimed at a modal surface stacked on top (the search dialog
+  // traps focus inside itself) dismisses that surface only — the same guard
+  // the Ask panel applies. Everything outside the modal is inert, so a focus
+  // restore here could not land anyway.
+  if (event.target instanceof Element && event.target.closest("dialog")) {
+    return;
+  }
+  // Only a keypress that originated inside a panel gets its focus returned
+  // to that trigger; yanking focus from an unrelated control the user had
+  // moved on to would be a surprise.
+  for (const open of openDropdowns()) {
+    dismiss(open, isInside(open, event.target));
+  }
+};
+
+const onFocusOut = (event: FocusEvent): void => {
+  // Only focus *leaving a panel* counts: a move between two unrelated controls
+  // (a dialog handing focus back to its trigger, say) must not close a panel
+  // that never held focus. And a null `relatedTarget` means focus went
+  // nowhere focusable (a click on plain content, the panel being hidden, the
+  // window blurring) — the pointer and blur legs own those, and closing here
+  // would hide a panel item before its own click lands in browsers that
+  // don't focus buttons on press.
+  const { relatedTarget } = event;
+  if (!(relatedTarget instanceof Node)) {
+    return;
+  }
+  for (const open of openDropdowns()) {
+    if (isInside(open, event.target) && !open.contains(relatedTarget)) {
+      dismiss(open, false);
+    }
+  }
+};
+
+const onWindowBlur = (): void => {
+  for (const open of openDropdowns()) {
+    dismiss(open, false);
+  }
+};
+
+let installed = false;
+
+/**
+ * Register the document/window listeners. Idempotent: every component that
+ * renders a dropdown calls this from its own script, and a page may render
+ * several of them.
+ */
+export const installDropdownDismiss = (): void => {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  document.addEventListener("pointerdown", onPointerDown);
+  document.addEventListener("keydown", onKeyDown);
+  document.addEventListener("focusout", onFocusOut);
+  window.addEventListener("blur", onWindowBlur);
+};

package/src/components/layout/Fonts.astro

@@ -2,7 +2,8 @@
 // Emits the optimized @font-face declarations + preload links for each
 // configured font (Astro's Fonts API). Renders nothing when no fonts are set;
 // the CSS variables match the astro.config `fonts:` entries. Preloads are
-// narrowed to the weights above-the-fold text renders in (see
+// narrowed to the weights above-the-fold text renders in and, for providers
+// that split faces by subset, to the subsets the site's locales need (see
 // `theme/fonts.ts`); a bare string entry — an older generated template — keeps
 // the previous preload-everything behavior.
 import { Font } from "astro:assets";
@@ -14,16 +15,22 @@ interface Props {
 
 const { cssVars } = Astro.props;
 
+/** The preload filters for one head entry: every weight × every subset. */
+const preloadFilters = (head: FontHead) =>
+  head.preloadWeights.flatMap((weight) =>
+    head.preloadSubsets
+      ? head.preloadSubsets.map((subset) => ({
+          style: "normal" as const,
+          subset,
+          weight,
+        }))
+      : [{ style: "normal" as const, weight }]
+  );
+
 const entries = cssVars.map((value) =>
   typeof value === "string"
     ? { cssVariable: value, preload: true as const }
-    : {
-        cssVariable: value.cssVariable,
-        preload: value.preloadWeights.map((weight) => ({
-          style: "normal" as const,
-          weight,
-        })),
-      }
+    : { cssVariable: value.cssVariable, preload: preloadFilters(value) }
 );
 ---
 

package/src/components/layout/Header.astro

@@ -2,6 +2,7 @@
 import Ask from "blume:ask";
 import data from "blume:data";
 import { withBase } from "../islands/base-path.ts";
+import { isExternalUrl } from "../../core/base-path.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
@@ -120,6 +121,19 @@ const tabsNavClass = hasSidebar
 const iconButton =
   "inline-flex size-9 cursor-pointer items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground";
 
+// Header links: plain actions are secondary and hide below `sm`, where the
+// header has room for the logo and the drawer toggle and nothing else. The one
+// call to action hides there too — but only when a drawer toggle is actually
+// competing for the space. A page with no drawer (a PageLayout landing page
+// with no tabs) has nowhere else to surface it, so it stays. `withBase` passes
+// external, protocol-relative and fragment hrefs through untouched.
+const actionClass =
+  "hidden rounded-full px-3 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:text-foreground sm:inline-flex";
+const ctaClass = [
+  showNavToggle ? "hidden sm:inline-flex" : "inline-flex",
+  "items-center gap-1 rounded-full bg-accent px-3.5 py-1.5 font-medium text-accent-foreground text-sm transition-opacity hover:opacity-90",
+].join(" ");
+
 // Delegated handlers for the theme toggle, mobile nav drawer, and banner
 // dismiss. Living with the header means every page that renders it — docs pages
 // and custom pages alike — gets identical behavior from one source.
@@ -212,6 +226,36 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
     )
   }
   <div class="flex items-center gap-2">
+    {
+      /* Plain links first, then the one filled button: the reader's eye lands
+         on the button because nothing beside it competes. */
+      (navigation.actions ?? []).map((action) => {
+        const external = isExternalUrl(action.href);
+        return (
+          <a
+            class={actionClass}
+            href={withBase(action.href)}
+            rel={external ? "noreferrer" : undefined}
+            target={external ? "_blank" : undefined}
+          >
+            {action.label}
+          </a>
+        );
+      })
+    }
+    {
+      navigation.cta && (
+        <a
+          class={ctaClass}
+          href={withBase(navigation.cta.href)}
+          rel={isExternalUrl(navigation.cta.href) ? "noreferrer" : undefined}
+          target={isExternalUrl(navigation.cta.href) ? "_blank" : undefined}
+        >
+          {navigation.cta.label}
+          <Icon name="chevron-right" size={14} />
+        </a>
+      )
+    }
     {
       navigation.repoUrl && (
         <a

package/src/components/layout/LanguageSwitcher.astro

@@ -20,7 +20,7 @@ const menuRowClass =
 
 {
   options.length > 1 && (
-    <details class="group relative">
+    <details class="group relative" data-blume-dropdown>
       <summary
         aria-label={label}
         class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
@@ -56,3 +56,11 @@ const menuRowClass =
     </details>
   )
 }
+
+<script>
+  import { installDropdownDismiss } from "../dropdown-dismiss.ts";
+
+  // Outside-click / Escape / focus-out dismissal, shared with the nav
+  // selectors and the page actions.
+  installDropdownDismiss();
+</script>

package/src/components/layout/NavSelector.astro

@@ -2,8 +2,9 @@
 import { withBase } from "../islands/base-path.ts";
 // A top-level navigation selector: a dropdown that switches
 // between partitions of the site — a product, a version, or any grouped set of
-// destinations (`navigation.selectors` in the config). Zero-JS, built on
-// <details>/<summary> like the language switcher.
+// destinations (`navigation.selectors` in the config). Built on
+// <details>/<summary> like the language switcher; the only script is the
+// shared light-dismiss so an open panel doesn't linger over the page.
 import type { NavSelector } from "../../core/types.ts";
 import Icon from "../Icon.astro";
 import { isUnderPath } from "../../core/navigation.ts";
@@ -40,7 +41,7 @@ const menuRowClass =
 
 {
   selector.items.length > 0 && (
-    <details class="group relative">
+    <details class="group relative" data-blume-dropdown>
       <summary
         aria-label={selector.label}
         class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
@@ -85,3 +86,11 @@ const menuRowClass =
     </details>
   )
 }
+
+<script>
+  import { installDropdownDismiss } from "../dropdown-dismiss.ts";
+
+  // Outside-click / Escape / focus-out dismissal, shared with the language
+  // switcher and the page actions.
+  installDropdownDismiss();
+</script>

package/src/components/layout/NavTree.astro

@@ -2,6 +2,7 @@
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { NavNode } from "../../core/types.ts";
+import { methodColor } from "../colors.ts";
 import Icon from "../Icon.astro";
 import { withBase } from "../islands/base-path.ts";
 import Self from "./NavTree.astro";
@@ -44,24 +45,11 @@ const n = { ...EN_UI.nav, ...strings };
 
 const badgeBase =
   "shrink-0 rounded-full px-1.5 py-0.5 font-medium text-[0.65rem] leading-none";
-const badgeClass = `${badgeBase} bg-muted text-muted-foreground`;
-// HTTP-method and AsyncAPI-action badges (from a reference's sidebar) are
-// color-coded to match MethodBadge; every other badge keeps the neutral style.
-const METHOD_BADGE: Record<string, string> = {
-  DELETE: "bg-red-500/15 text-red-700 dark:text-red-300",
-  GET: "bg-green-500/15 text-green-700 dark:text-green-300",
-  HEAD: "bg-muted text-muted-foreground",
-  OPTIONS: "bg-muted text-muted-foreground",
-  PATCH: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
-  POST: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
-  PUT: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
-  RECEIVE: "bg-teal-500/15 text-teal-700 dark:text-teal-300",
-  SEND: "bg-violet-500/15 text-violet-700 dark:text-violet-300",
-};
-const badgeClassFor = (badge: string): string => {
-  const method = METHOD_BADGE[badge.toUpperCase()];
-  return method ? `${badgeBase} ${method}` : badgeClass;
-};
+// HTTP-method, AsyncAPI-action, and GraphQL operation-kind badges (from a
+// reference's sidebar) share MethodBadge's table; every other badge falls
+// through to the same neutral style.
+const badgeClassFor = (badge: string): string =>
+  `${badgeBase} ${methodColor(badge)}`;
 const deprecatedClass =
   "shrink-0 rounded-full bg-amber-500/10 px-1.5 py-0.5 font-medium text-[0.65rem] text-amber-700 leading-none dark:text-amber-300";
 

package/src/components/layout/PageActions.astro

@@ -24,6 +24,12 @@ interface Props {
   openInChat?: readonly OpenInChatProvider[];
   /** Localized action labels. */
   strings?: UIStrings["actions"];
+  /**
+   * Draw the top rule and spacing that separate the block from the table of
+   * contents above it. The rail passes `false` when no contents rendered, so
+   * the block does not open an otherwise empty column with a divider.
+   */
+  divider?: boolean;
 }
 
 const {
@@ -35,6 +41,7 @@ const {
   mcpName,
   openInChat,
   strings,
+  divider = true,
 } = Astro.props;
 // Merge over the English defaults so a label missing from a translation (or from
 // a not-yet-regenerated snapshot) still renders instead of coming out blank.
@@ -93,8 +100,9 @@ const menuRowClass =
 ---
 
 <div
-  class="mt-8 space-y-0.5 border-border border-t pt-4"
+  class:list={["space-y-0.5", divider && "mt-8 border-border border-t pt-4"]}
   data-blume-page-actions
+  data-i18n-chat-prompt={a.openInChatPrompt}
   data-i18n-copied={a.copied}
   data-i18n-generating={a.generating}
   data-mcp-name={mcpName ?? undefined}
@@ -122,7 +130,7 @@ const menuRowClass =
 
   {
     (exportPdf || exportEpub) && (
-      <details class="group relative">
+      <details class="group relative" data-blume-dropdown>
         <summary
           class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
         >
@@ -159,7 +167,7 @@ const menuRowClass =
 
   {
     providers.length > 0 && (
-      <details class="group relative">
+      <details class="group relative" data-blume-dropdown>
         <summary
           class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
         >
@@ -199,7 +207,7 @@ const menuRowClass =
 
   {
     mcpUrl && (
-      <details class="group relative">
+      <details class="group relative" data-blume-dropdown>
         <summary
           class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
         >
@@ -252,6 +260,7 @@ const menuRowClass =
 
 <script>
   import { copyText, flashLabel } from "../copy-feedback.ts";
+  import { installDropdownDismiss } from "../dropdown-dismiss.ts";
   import { prefixBase } from "../islands/base-path.ts";
   import { rafThrottle } from "../raf-throttle.ts";
 
@@ -329,6 +338,11 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     menu.classList.toggle("mb-1", flipUp);
   };
 
+  const openDropdown = () =>
+    document.querySelector<HTMLDetailsElement>(
+      "[data-blume-page-actions] details[open]"
+    );
+
   // rAF-coalesced so a live resize drag re-reads layout once per frame, not
   // once per event, while the open menu still tracks the viewport. Registered
   // once at module scope (this bundle runs once per real page load) and
@@ -336,15 +350,17 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
   window.addEventListener(
     "resize",
     rafThrottle(() => {
-      const open = document.querySelector<HTMLDetailsElement>(
-        "[data-blume-page-actions] details[open]"
-      );
+      const open = openDropdown();
       if (open) {
         placeMenu(open);
       }
     })
   );
 
+  // Outside-click / Escape / focus-out dismissal is the shared <details>
+  // dropdown behavior (also the header language switcher and nav selectors).
+  installDropdownDismiss();
+
   // Per-page setup, run on the initial load and again after every
   // client-router swap: the swap rebuilds the actions menu from
   // server-rendered markup, so every handler below binds to fresh elements.
@@ -379,9 +395,14 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     const copiedLabel = root.getAttribute("data-i18n-copied") || "Copied!";
     const generatingLabel =
       root.getAttribute("data-i18n-generating") || "Generating…";
+    // Always stamped: the frontmatter merges `EN_UI.actions` under any
+    // override, so the English default lives only in core/i18n-ui.ts.
+    const promptTemplate = root.getAttribute("data-i18n-chat-prompt") ?? "";
     const absolute = new URL(md, location.origin).href;
+    // Replacer function, not a string: a URL may contain `$`, which a string
+    // replacement would interpret as a substitution pattern.
     const query = encodeURIComponent(
-      `Read ${absolute} so I can ask you questions about this page.`
+      promptTemplate.replaceAll("{url}", () => absolute)
     );
 
     for (const link of root.querySelectorAll("[data-open-in]")) {

package/src/components/layout/PageLayout.astro

@@ -22,6 +22,7 @@ import type {
   BlumeFavicon,
   BlumeLogo,
 } from "../../core/data.ts";
+import data from "blume:data";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { FontHead } from "../../theme/fonts.ts";
@@ -217,6 +218,7 @@ const structuredData =
       base: import.meta.env.BASE_URL,
       breadcrumbs: [],
       description,
+      identity: data.config.identity,
       locale,
       route,
       siteName: site.title,

package/src/components/layout/ReferenceLayout.astro

@@ -10,7 +10,11 @@ import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
+import {
+  BANNER_INIT_SCRIPT,
+  SCALAR_THEME_INIT_SCRIPT,
+  THEME_INIT_SCRIPT,
+} from "./head-scripts.ts";
 import Header from "./Header.astro";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
@@ -129,6 +133,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       id="blume-content"
     >
       <slot />
+      <script is:inline set:html={SCALAR_THEME_INIT_SCRIPT} />
     </div>
     <WebMcp />
   </body>

package/src/components/layout/RootLayout.astro

@@ -1,4 +1,5 @@
 ---
+import data from "blume:data";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import { resolveDateFormatOptions } from "../../core/date-format.ts";
@@ -12,6 +13,15 @@ import type {
   NavSelector as NavSelectorType,
 } from "../../core/types.ts";
 import "blume:theme";
+// medium-zoom's default build injects its stylesheet into <head> as a bare
+// <style> the moment the module evaluates — once per document. The client
+// router's head swap drops every non-persisted head element on the first
+// navigation, and the cached module never re-injects, so the zoom cursor
+// vanished and `close()` hung forever waiting for a `transitionend` its
+// (now absent) transition rule never fires. Importing the stylesheet here
+// puts it in the page CSS the router carries across swaps; the script below
+// loads the `pure` build, which ships no injection.
+import "medium-zoom/dist/style.css";
 import { ClientRouter } from "astro:transitions";
 import type { FontHead } from "../../theme/fonts.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
@@ -23,6 +33,7 @@ import {
 import { buildStructuredData, toIso } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
+import { isExternalUrl } from "../../core/base-path.ts";
 import Analytics from "./Analytics.astro";
 import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
@@ -295,6 +306,9 @@ const tocHeadings =
   toc.enabled && showToc
     ? headings.filter((h) => h.depth >= toc.minLevel && h.depth <= toc.maxLevel)
     : [];
+// One predicate for both the outline and the page-actions divider under it,
+// so the rail cannot draw a rule under contents that were never rendered.
+const hasToc = tocHeadings.length > 0;
 let gridClass =
   "lg:grid-cols-[17.5rem_minmax(0,1fr)] xl:grid-cols-[17.5rem_minmax(0,1fr)_17.5rem]";
 if (isBare) {
@@ -387,6 +401,7 @@ const structuredData =
       base: import.meta.env.BASE_URL,
       breadcrumbs: crumbs,
       description,
+      identity: data.config.identity,
       locale,
       modified: lastModified,
       pageType,
@@ -524,6 +539,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
   </head>
   <body
     class="bg-background font-sans text-foreground antialiased"
+    data-blume-code-copy=""
     data-blume-code-wrap={codeWrap ? "" : undefined}
     data-blume-image-zoom={imageZoom ? "" : undefined}
     data-i18n-copied={actionStrings.copied}
@@ -579,7 +595,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             >
               <ul class="m-0 list-none p-0">
                 {navigation.featured.map((link) => {
-                  const external = /^https?:\/\//u.test(link.href);
+                  const external = isExternalUrl(link.href);
                   return (
                     <li>
                       <a
@@ -680,11 +696,15 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           strings={navStrings}
           wide={isApiOperation}
         />
-        <TableOfContentsSlot
-          headings={tocHeadings}
-          title={strings.toc.title}
-          variant="mobile"
-        />
+        {
+          hasToc && (
+            <TableOfContentsSlot
+              headings={tocHeadings}
+              title={strings.toc.title}
+              variant="mobile"
+            />
+          )
+        }
         <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
         <article class:list={[articleClass]} dir={contentDir}>
           <slot />
@@ -715,12 +735,15 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             class="sticky top-16 hidden h-[calc(100dvh-4rem)] scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto px-4 pt-6 pb-10 text-sm xl:block"
             data-blume-toc
           >
-            <TableOfContentsSlot
-              headings={tocHeadings}
-              title={strings.toc.title}
-              variant="desktop"
-            />
+            {hasToc && (
+              <TableOfContentsSlot
+                headings={tocHeadings}
+                title={strings.toc.title}
+                variant="desktop"
+              />
+            )}
             <PageActions
+              divider={hasToc}
               editUrl={editUrl}
               exportEpub={exportEpub}
               exportPdf={exportPdf}
@@ -910,7 +933,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           if (zoomTargets.length > 0) {
             // Lazy: pages without a zoomable image never load the library,
             // matching how mermaid is only fetched on pages with a diagram.
-            const { default: mediumZoom } = await import("medium-zoom");
+            const { default: mediumZoom } = await import(
+              "medium-zoom/dist/pure"
+            );
             mediumZoom(zoomTargets, {
               background:
                 "color-mix(in oklab, var(--color-background) 80%, transparent)",
@@ -927,7 +952,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     </script>
     <style is:global>
       /* medium-zoom ships no z-index; lift the lightbox above the chrome
-         (header/sidebar) the way the previous z-[100] overlay sat. */
+         (header/sidebar) the way the previous z-[100] overlay sat. Its own
+         rules come from the `medium-zoom/dist/style.css` import in the
+         frontmatter, not runtime injection. */
       .medium-zoom-overlay {
         backdrop-filter: blur(4px);
         z-index: 100;
@@ -936,8 +963,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         z-index: 101;
       }
       @media (prefers-reduced-motion: reduce) {
-        /* html prefix outranks the library's injected rules regardless of
-           insertion order; its transition declarations carry !important. */
+        /* html prefix outranks the library's rules regardless of sheet
+           order; its transition declarations carry !important. */
         html .medium-zoom-image,
         html .medium-zoom-overlay {
           transition: none !important;