blume 1.5.3 → 1.6.1

package/src/components/content/Component.astro

@@ -10,6 +10,10 @@
 // examples are all supported. The source is highlighted with the same Shiki
 // setup as ordinary code fences.
 import data from "blume:data";
+import {
+  CODE_PADDING_BLOCK_REM,
+  FLUSH_CODE_PADDING_TOP_REM,
+} from "../../theme/code-block-padding.ts";
 
 import { highlightCode } from "../../markdown/index.ts";
 import { withBase } from "../islands/base-path.ts";
@@ -58,7 +62,12 @@ const codeHtml = entry
 // whose collapse to the measured height no transition could hide. No-JS
 // readers aren't hurt by the cap, since the source scrolls at any height.
 const LINE_PX = 21;
-const PADDING_PX = 36;
+const REM_PX = 16;
+// The pre's vertical padding, from the same constants the theme emits: the
+// copy-button strip on top (the pane is a flush block inside tabs) and the
+// plain inset below. The tab panel and the pre carry no border of their own.
+const PADDING_PX =
+  (FLUSH_CODE_PADDING_TOP_REM + CODE_PADDING_BLOCK_REM) * REM_PX;
 const ESTIMATE_MAX_PX = 400;
 // The floor also clamps the measured height client-side; it rides along on the
 // iframe as `data-blume-min-pane` so the script and this estimate can't drift.

package/src/components/content/GithubInfo.astro

@@ -3,6 +3,7 @@
 // at build time (no client JS). Pass `owner`/`repo`, or omit them to use the
 // repo from blume.config. A `GITHUB_TOKEN` env var lifts the API rate limit.
 // If the API is unreachable the card still renders, just without counts.
+import { apiUrl, PUBLIC_HOST_URL } from "../../core/github.ts";
 import { resolveIcon } from "../../theme/icons.ts";
 import data from "blume:data";
 import { GITHUB_MARK } from "../github-mark.ts";
@@ -15,22 +16,40 @@ const starIcon = resolveIcon("star")?.body ?? "";
 const forkIcon = resolveIcon("git-fork")?.body ?? "";
 
 interface Props {
+  /**
+   * Origin of the GitHub instance the card's repo lives on. Defaults to the
+   * configured `github.host`, so a card on an Enterprise site reads that
+   * instance; set it to point one card elsewhere — `https://github.com` for a
+   * public project from an Enterprise-hosted docs site, say. The REST base is
+   * derived from it the same way `github.api` is derived from `github.host`.
+   */
+  host?: string;
   owner?: string;
   repo?: string;
   token?: string;
 }
 
-// The resolved config exposes the repo as `repoUrl`, not `github`; parse the
-// owner/repo back out so <GithubInfo /> can default to the configured repo.
-const repoMatch = data.config.repoUrl?.match(
-  /github\.com\/(?<owner>[^/]+)\/(?<repo>[^/]+)/u
-);
-const owner = Astro.props.owner ?? repoMatch?.groups?.owner;
-const repo = Astro.props.repo ?? repoMatch?.groups?.repo;
+// `data.config.github` carries the configured repo's coordinates, so the card
+// defaults to it and addresses the right instance — an Enterprise host serves
+// both the link and the API from somewhere other than github.com. Explicit
+// `owner`/`repo` props are read against that same instance unless `host`
+// points them somewhere else; with no `github` configured at all, they fall
+// back to the public one.
+const configured = data.config.github;
+const owner = Astro.props.owner ?? configured?.owner;
+const repo = Astro.props.repo ?? configured?.repo;
 const token = Astro.props.token ?? process.env.GITHUB_TOKEN;
+// A `host` prop is reduced to its origin, as the config field is, so a
+// trailing slash or a path never lands mid-link.
+const host = Astro.props.host
+  ? new URL(Astro.props.host).origin
+  : (configured?.host ?? PUBLIC_HOST_URL);
+const baseUrl = Astro.props.host ? apiUrl({ host }) : configured?.api;
 
 const info =
-  owner && repo ? await fetchRepositoryInfo({ owner, repo, token }) : null;
+  owner && repo
+    ? await fetchRepositoryInfo({ baseUrl, owner, repo, token })
+    : null;
 
 // Compact notation matches GitHub's own counts (e.g. 1.2k, 34.5k).
 const numbers = new Intl.NumberFormat("en", {
@@ -46,7 +65,7 @@ const statIcon =
   owner && repo && (
     <a
       class="not-prose my-6 flex flex-col gap-2 rounded-blume border border-border p-4 no-underline! transition-colors hover:border-foreground/30 hover:bg-muted/40"
-      href={`https://github.com/${owner}/${repo}`}
+      href={`${host}/${owner}/${repo}`}
       rel="noreferrer"
       target="_blank"
     >

package/src/components/content/Tabs.astro

@@ -19,6 +19,13 @@ interface Props {
    */
   param?: string;
   sync?: boolean;
+  /**
+   * Sync tab selection only with other groups sharing the same key. Groups
+   * without a key form one page-wide pool (the default); keyed groups — like
+   * the generated ts2js dialect pairs — sync among themselves, so picking a
+   * tab there can't drag along an authored group with a same-titled tab.
+   */
+  syncKey?: string;
 }
 
 const {
@@ -29,6 +36,7 @@ const {
   inline = false,
   param,
   sync = true,
+  syncKey,
 } = Astro.props;
 
 // MDX string attributes (`hash="false"` from generated markup) must read as
@@ -52,6 +60,7 @@ const useDropdown = dropdown && !inline;
   data-hash={hashEnabled ? "true" : "false"}
   data-param={param}
   data-sync={sync ? "true" : "false"}
+  data-sync-key={syncKey}
 >
   <div
     class:list={[
@@ -116,9 +125,12 @@ const useDropdown = dropdown && !inline;
 
     connectedCallback() {
       const list = this.querySelector<HTMLElement>("[data-blume-tablist]");
+      // Nested groups (a generated ts2js pair inside a CodeGroup, say) own
+      // their panels; adopting a descendant group's panels here would leave
+      // both groups toggling the same elements.
       let panels = Array.from(
         this.querySelectorAll<HTMLElement>("[data-blume-tab-panel]")
-      );
+      ).filter((panel) => panel.closest("blume-tabs") === this);
       // CodeGroup passes raw code fences instead of <Tab> elements, so adopt
       // the content wrapper's direct code blocks as panels. The tab label comes
       // from each block's title (the text after the language in the fence).
@@ -251,7 +263,10 @@ const useDropdown = dropdown && !inline;
       if (sync && this.#syncEnabled()) {
         document.dispatchEvent(
           new CustomEvent(SYNC_EVENT, {
-            detail: { title: panelTitle(activePanel, index) },
+            detail: {
+              key: this.#syncKey(),
+              title: panelTitle(activePanel, index),
+            },
           })
         );
       }
@@ -339,6 +354,10 @@ const useDropdown = dropdown && !inline;
       return this.dataset.sync !== "false";
     }
 
+    #syncKey() {
+      return this.dataset.syncKey ?? "";
+    }
+
     #hashEnabled() {
       return this.dataset.hash !== "false";
     }
@@ -358,9 +377,12 @@ const useDropdown = dropdown && !inline;
     }
 
     #sync = (event: Event) => {
-      const title = (event as CustomEvent<{ title?: string }>).detail?.title;
-      if (title) {
-        this.activateByTitle(title, false);
+      const detail = (event as CustomEvent<{ key?: string; title?: string }>)
+        .detail;
+      // Only same-key groups sync: keyless groups form one page-wide pool,
+      // keyed groups (generated dialect pairs) their own.
+      if (detail?.title && (detail.key ?? "") === this.#syncKey()) {
+        this.activateByTitle(detail.title, false);
       }
     };
 

package/src/components/content/github-info.ts

@@ -7,6 +7,8 @@
  * than throwing, so a card never breaks the build when the API is unreachable.
  */
 
+import { PUBLIC_API_URL } from "../../core/github.ts";
+
 export interface RepositoryInfo {
   description: string | null;
   forks: number;
@@ -20,18 +22,31 @@ export interface FetchRepositoryOptions {
   token?: string;
 }
 
-const DEFAULT_BASE_URL = "https://api.github.com";
-
 /** In-process dedupe so the same repo is fetched once per build. */
 const cache = new Map<string, Promise<RepositoryInfo | null>>();
 
+/** Cleartext bases already warned about, so a site of cards logs once. */
+const warnedCleartext = new Set<string>();
+
 const load = async (
   options: FetchRepositoryOptions
 ): Promise<RepositoryInfo | null> => {
-  const { baseUrl = DEFAULT_BASE_URL, owner, repo, token } = options;
+  const { baseUrl = PUBLIC_API_URL, owner, repo, token } = options;
   const headers = new Headers({ Accept: "application/vnd.github+json" });
+  // An Enterprise instance can be configured on plain HTTP; a bearer token is
+  // never worth putting on the wire in cleartext, so it is dropped rather than
+  // sent. The request still goes out — a public repo's counts render either way
+  // — but a private repo's card comes back bare, which looks exactly like a
+  // network failure, so say why once per base.
   if (token) {
-    headers.set("Authorization", `Bearer ${token}`);
+    if (new URL(baseUrl).protocol === "https:") {
+      headers.set("Authorization", `Bearer ${token}`);
+    } else if (!warnedCleartext.has(baseUrl)) {
+      warnedCleartext.add(baseUrl);
+      console.warn(
+        `[blume] <GithubInfo> is not sending its token to ${baseUrl}: the API base is plain HTTP, so the bearer token would travel in cleartext. Counts for a private repository will be missing; serve the API over https to authenticate.`
+      );
+    }
   }
 
   const response = await fetch(`${baseUrl}/repos/${owner}/${repo}`, {
@@ -69,7 +84,7 @@ const loadSafe = async (
 export const fetchRepositoryInfo = (
   options: FetchRepositoryOptions
 ): Promise<RepositoryInfo | null> => {
-  const key = `${options.baseUrl ?? DEFAULT_BASE_URL}/${options.owner}/${options.repo}`;
+  const key = `${options.baseUrl ?? PUBLIC_API_URL}/${options.owner}/${options.repo}`;
   const existing = cache.get(key);
   if (existing) {
     return existing;

package/src/components/copy-feedback.ts

@@ -3,13 +3,14 @@
  * blocks, page actions, color swatches, prompts, API panels, Ask AI). One
  * implementation owns the invariants each site used to hand-roll:
  *
- * - the clipboard write is guarded, and nothing flashes on failure — a
- *   confirmation must never lie;
+ * - the clipboard write is guarded and a confirmation must never lie: a
+ *   site either shows nothing on failure or (the page actions) shows a
+ *   failure label, but never a false "Copied";
  * - repeat copies restart the hold instead of stacking timers, so the copied
  *   state never reverts early after a double-click;
- * - every successful copy is announced to a shared polite live region, so the
- *   confirmation is audible, not just visual (previously only the code-block
- *   button announced).
+ * - every flash is announced to a shared polite live region, so the
+ *   confirmation — or the failure — is audible, not just visual (previously
+ *   only the code-block button announced).
  */
 
 /** How long the copied confirmation holds before reverting. */
@@ -35,17 +36,100 @@ export const announceCopied = (message: string): void => {
 };
 
 /**
- * Copy `text` to the clipboard. Returns whether the write succeeded; failures
- * (insecure context, permissions) are swallowed so callers can simply skip
- * their confirmation.
+ * The legacy copy path: select `text` in an off-screen textarea and run the
+ * `copy` editing command. It needs no clipboard permission, only the user
+ * activation the click already provides, so it covers the places the async
+ * Clipboard API doesn't reach — in-app browsers and WebViews that ship no
+ * `navigator.clipboard`, insecure origins, and a denied permission prompt.
+ */
+const copyViaCommand = (text: string): boolean => {
+  const previous = document.activeElement;
+  const textarea = document.createElement("textarea");
+  textarea.value = text;
+  textarea.setAttribute("readonly", "");
+  textarea.setAttribute("aria-hidden", "true");
+  // Off-screen rather than `display: none`: hidden controls can't be selected.
+  textarea.style.position = "fixed";
+  textarea.style.top = "0";
+  textarea.style.left = "-9999px";
+  textarea.style.opacity = "0";
+  // Beside the focused control, not on `<body>`: `select()` moves focus to the
+  // textarea, and a copy button inside a light-dismissed `<details>` menu (the
+  // MCP actions) would otherwise see focus leave the panel — closing the menu
+  // mid-click and hiding the label the outcome is about to flash on.
+  const host =
+    previous instanceof HTMLElement && previous.parentElement
+      ? previous.parentElement
+      : document.body;
+  host.append(textarea);
+  textarea.select();
+  // iOS WebKit has been known to ignore `select()` on a readonly textarea;
+  // an explicit range covers it (the same belt-and-braces clipboard.js uses).
+  textarea.setSelectionRange(0, text.length);
+  let copied = false;
+  try {
+    copied = document.execCommand("copy");
+  } catch {
+    // Some engines throw instead of returning false; either way it failed.
+  }
+  textarea.remove();
+  // `select()` moved focus to the textarea; put it back on the button so a
+  // keyboard user isn't dropped at the top of the document.
+  if (previous instanceof HTMLElement) {
+    previous.focus();
+  }
+  return copied;
+};
+
+/**
+ * Copy `text` to the clipboard. Returns whether the write succeeded. The async
+ * Clipboard API is tried first; when it is missing (in-app browsers, insecure
+ * contexts) or rejects (a denied permission), the legacy `copy` command is
+ * tried before giving up, so callers only see `false` when nothing worked and
+ * can show a failure instead of silently doing nothing.
  */
 export const copyText = async (text: string): Promise<boolean> => {
   try {
     await navigator.clipboard.writeText(text);
     return true;
   } catch {
-    return false;
+    return copyViaCommand(text);
+  }
+};
+
+/**
+ * Copy text that still has to be loaded — the page's Markdown mirror, fetched
+ * on click. Safari and Firefox only honor a clipboard write issued inside the
+ * click's own task: awaiting the load first lands the write outside the user
+ * activation, so `writeText` rejects and the legacy command returns `false`
+ * even though the clipboard is perfectly available. `ClipboardItem` accepts a
+ * promise for its payload, so the write is issued synchronously with the
+ * load still in flight and the activation intact. Engines without it (or a
+ * write that rejects for any reason, a failed load included) fall back to the
+ * awaited {@link copyText}, which is what Chrome's longer activation window
+ * already tolerated. A load failure still throws, so the caller can report
+ * it rather than a clipboard problem.
+ */
+export const copyDeferredText = async (
+  load: () => Promise<string>
+): Promise<boolean> => {
+  const text = load();
+  if ("ClipboardItem" in globalThis) {
+    try {
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          "text/plain": text.then(
+            (value) => new Blob([value], { type: "text/plain" })
+          ),
+        }),
+      ]);
+      return true;
+    } catch {
+      // Fall through to the awaited write; if the load itself failed, the
+      // `await` below rethrows that error for the caller.
+    }
   }
+  return copyText(await text);
 };
 
 /**

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/islands/ask-ai.tsx

@@ -176,7 +176,7 @@ const AskAI = ({
   useEffect(() => {
     // The initial null→body flip is deliberate (there is no body during SSR);
     // it is the same one-time post-mount cascade the old `mounted` flag had.
-    // oxlint-disable-next-line react/react-compiler -- deliberate post-mount portal-target initialization
+    // oxlint-disable-next-line react/react-compiler, react/set-state-in-effect -- deliberate post-mount portal-target initialization
     setPortalTarget(document.body);
     const onSwap = () => setPortalTarget(document.body);
     document.addEventListener("astro:after-swap", onSwap);
@@ -263,6 +263,7 @@ const AskAI = ({
     if (open && portalTarget) {
       document.body.dataset.blumeAsk = "open";
     }
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies -- see above
   }, [open, portalTarget]);
 
   // Below the desktop dock breakpoint the open panel is a full-width overlay,
@@ -328,12 +329,14 @@ const AskAI = ({
     // portalTarget: each swap installs a new <body>, so the sweep and its
     // observer must re-run against the new children (the old ones are
     // detached).
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies -- see above
   }, [open, portalTarget]);
 
   // Keep the newest message in view as it streams in — and after a swap, when
   // the re-portaled panel's scroll container is reborn at the top.
   useEffect(() => {
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies -- both deps are triggers, not values read here: re-run per streamed message and per re-portaled panel
   }, [messages, portalTarget]);
 
   const runQuestion = (raw: string) => {

package/src/components/islands/hooks.ts

@@ -57,7 +57,7 @@ const useClientData = (): BlumeClientData | null => {
   // Intentional post-mount hydration guard: `null` on the server and first
   // client render so hydration matches, then the snapshot once mounted. The
   // extra render is required; do not seed the initial value from the DOM.
-  // oxlint-disable-next-line react/react-compiler, react-doctor/no-initialize-state -- deliberate SSR hydration guard
+  // oxlint-disable-next-line react/react-compiler, react/set-state-in-effect, react-doctor/no-initialize-state -- deliberate SSR hydration guard
   useEffect(() => setData(readClientData()), []);
   return data;
 };
@@ -109,6 +109,7 @@ export const useSearch = (): UseSearch => {
     // Before the lazy client import: the first search's heaviest phase is
     // creating the provider client (index download), and it must show loading.
     setLoading(true);
+    // oxlint-disable-next-line react/todo -- React Compiler cannot lower try/finally; the hook stays manually memoized above
     try {
       if (!searchFn.current) {
         const { createSearch } = await import("blume:search-client");
@@ -250,6 +251,7 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
           assistant.content = errorMessage;
           setMessages([...history, { ...assistant }]);
         }
+        // oxlint-disable-next-line react/todo -- React Compiler cannot lower try/finally; the hook stays manually memoized above
       } finally {
         if (live()) {
           setLoading(false);

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>