blume 1.4.2 → 1.5.0

package/src/components/islands/ask-ai.tsx

@@ -1,10 +1,11 @@
 import DOMPurify from "dompurify";
-import { marked } from "marked";
+import { Marked } from "marked";
 import { useEffect, useRef, useState } from "react";
 import type { FormEvent, KeyboardEvent as ReactKeyboardEvent } from "react";
 import { createPortal } from "react-dom";
 
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { copyText } from "../copy-feedback.ts";
 import { joinBase, prefixBase } from "./base-path.ts";
 import { useAskAI } from "./hooks.ts";
 
@@ -57,12 +58,15 @@ const DEFAULT_ASK: UIStrings["ask"] = {
 const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
 // GitHub-flavored markdown with soft line breaks, matching how the docs read.
-marked.setOptions({ breaks: true, gfm: true });
-
-// The model cites pages as base-less logical routes (`[Title](/route)`); rewrite
-// link targets to served URLs so citations resolve under `deployment.base`.
-// `prefixBase` leaves external URLs and fragments untouched and is idempotent.
-marked.use({
+// A dedicated instance, not the shared `marked` singleton: `setOptions`/`use`
+// on the singleton would leak `breaks` and the link rewriter into any other
+// consumer of `marked` on the page (user components included).
+const markdown = new Marked({
+  breaks: true,
+  gfm: true,
+  // The model cites pages as base-less logical routes (`[Title](/route)`); rewrite
+  // link targets to served URLs so citations resolve under `deployment.base`.
+  // `prefixBase` leaves external URLs and fragments untouched and is idempotent.
   walkTokens: (token) => {
     if (token.type === "link") {
       token.href = prefixBase(import.meta.env.BASE_URL, token.href);
@@ -71,7 +75,7 @@ marked.use({
 });
 
 const renderMarkdown = (content: string): string =>
-  DOMPurify.sanitize(marked.parse(content, { async: false }));
+  DOMPurify.sanitize(markdown.parse(content, { async: false }));
 
 const Glyph = ({ path, size = 16 }: { path: string; size?: number }) => (
   <svg
@@ -96,12 +100,21 @@ const Glyph = ({ path, size = 16 }: { path: string; size?: number }) => (
 const EMPTY_SUGGESTIONS: Suggestion[] = [];
 
 // The toggle shortcut accepts both ⌘I and Ctrl+I; show the right modifier per
-// platform (same detection Search.astro uses for its ⌘K hint). Guarded so the
-// island still server-renders, where `navigator` doesn't exist; the hint itself
-// only renders client-side, inside the portaled panel.
+// platform (same detection Search.astro uses for its ⌘K hint). Guarded via
+// `globalThis` so the island still server-renders where `navigator` doesn't
+// exist; the hint itself only renders client-side, inside the portaled panel.
 const IS_APPLE =
-  typeof navigator !== "undefined" &&
-  /mac|iphone|ipad|ipod/iu.test(navigator.platform);
+  globalThis.navigator !== undefined &&
+  /mac|iphone|ipad|ipod/iu.test(globalThis.navigator.platform);
+
+// Duck-typed (`closest` presence) rather than `instanceof Element`, which
+// needs a DOM global the test environment doesn't provide.
+const isElementLike = (target: EventTarget | null): target is Element => {
+  // SAFETY: the cast only names the probed surface; `closest` is verified to
+  // exist before the caller uses it.
+  const candidate = target as Partial<Element> | null;
+  return typeof candidate?.closest === "function";
+};
 
 // Ghost icon button, matching the header's theme toggle and repo link.
 const TRIGGER_CLASS =
@@ -146,6 +159,8 @@ const AskAI = ({
   const inputRef = useRef<HTMLTextAreaElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const triggerRef = useRef<HTMLButtonElement>(null);
+  // The portaled panel root, excluded from the overlay-mode inert sweep.
+  const panelRef = useRef<HTMLElement>(null);
   // Where focus came from when the panel opened, restored on close.
   const returnFocusRef = useRef<HTMLElement | null>(null);
 
@@ -157,6 +172,8 @@ const AskAI = ({
   // The search modal forwards its query so "Ask AI: <query>" carries straight in.
   useEffect(() => {
     const handler = (event: Event) => {
+      // SAFETY: `blume:open-ask-ai` is only ever dispatched as a CustomEvent
+      // whose optional detail carries the search query.
       const query = (event as CustomEvent<{ query?: string }>).detail?.query;
       if (query) {
         setInput(query);
@@ -184,11 +201,8 @@ const AskAI = ({
         // An Escape aimed at a modal surface stacked on top (the search
         // dialog traps focus inside itself) dismisses that surface only —
         // this window listener still fires for it, and closing the panel
-        // underneath too would eat the user's conversation view. Duck-typed
-        // (`closest` presence) rather than `instanceof Element`, which needs
-        // a DOM global the test environment doesn't provide.
-        const target = event.target as Partial<Element> | null;
-        if (typeof target?.closest === "function" && target.closest("dialog")) {
+        // underneath too would eat the user's conversation view.
+        if (isElementLike(event.target) && event.target.closest("dialog")) {
           return;
         }
         setOpen(false);
@@ -225,6 +239,68 @@ const AskAI = ({
     };
   }, [open]);
 
+  // Below the desktop dock breakpoint the open panel is a full-width overlay,
+  // so Tab must not escape into the page it covers: every other child of
+  // <body> (the panel portals to body) turns inert until close. The desktop
+  // dock keeps the page interactive on purpose — it's a non-modal side panel,
+  // so no sweep runs at ≥1024px. Elements that were already inert are left
+  // alone so closing doesn't accidentally re-enable them.
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    const media = window.matchMedia("(min-width: 1024px)");
+    let inerted: Element[] = [];
+    const release = () => {
+      for (const el of inerted) {
+        el.removeAttribute("inert");
+      }
+      inerted = [];
+    };
+    const apply = () => {
+      release();
+      if (media.matches) {
+        return;
+      }
+      inerted = [...document.body.children].filter(
+        (el) => el !== panelRef.current && !el.hasAttribute("inert")
+      );
+      for (const el of inerted) {
+        el.setAttribute("inert", "");
+      }
+    };
+    apply();
+    // The sweep snapshots body's children at open time, but overlays keep
+    // arriving afterwards — medium-zoom's backdrop, a mermaid render, another
+    // island's portal all append to <body> — and an unswept latecomer is a
+    // tab stop hiding behind the overlay. Fold additions into the sweep for
+    // as long as it is active.
+    const observer = new MutationObserver((records) => {
+      if (media.matches) {
+        return;
+      }
+      for (const record of records) {
+        for (const node of record.addedNodes) {
+          if (
+            node instanceof HTMLElement &&
+            node !== panelRef.current &&
+            !node.hasAttribute("inert")
+          ) {
+            node.setAttribute("inert", "");
+            inerted.push(node);
+          }
+        }
+      }
+    });
+    observer.observe(document.body, { childList: true });
+    media.addEventListener("change", apply);
+    return () => {
+      observer.disconnect();
+      media.removeEventListener("change", apply);
+      release();
+    };
+  }, [open]);
+
   // Keep the newest message in view as it streams in.
   useEffect(() => {
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
@@ -265,7 +341,7 @@ const AskAI = ({
     const text = messages
       .map((m) => `${m.role === "user" ? t.you : t.ai}: ${m.content}`)
       .join("\n\n");
-    void navigator.clipboard?.writeText(text);
+    void copyText(text);
   };
 
   const hasMessages = messages.length > 0;
@@ -274,15 +350,16 @@ const AskAI = ({
     <aside
       aria-hidden={open ? undefined : "true"}
       aria-label={t.title}
+      ref={panelRef}
       // The closed panel is only translated off-screen; `inert` drops its
       // buttons/textarea from the tab order and the accessibility tree.
       inert={!open}
-      className={`fixed inset-y-0 end-0 z-[60] flex w-[var(--blume-ask-width)] flex-col border-border border-s bg-background shadow-2xl transition-transform duration-200 ease-out ${
+      className={`border-border bg-background fixed inset-y-0 end-0 z-[60] flex w-[var(--blume-ask-width)] flex-col border-s shadow-2xl transition-transform duration-200 ease-out ${
         open ? "translate-x-0" : "translate-x-full rtl:-translate-x-full"
       }`}
     >
-      <header className="flex h-16 shrink-0 items-center justify-between gap-2 border-border border-b px-4">
-        <span className="font-semibold text-foreground">{t.title}</span>
+      <header className="border-border flex h-16 shrink-0 items-center justify-between gap-2 border-b px-4">
+        <span className="text-foreground font-semibold">{t.title}</span>
         <div className="flex items-center gap-0.5">
           <button
             aria-label={t.copy}
@@ -314,7 +391,7 @@ const AskAI = ({
       </header>
 
       <div
-        className="flex flex-1 flex-col scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto"
+        className="scrollbar-thumb-border flex flex-1 scrollbar-thin scrollbar-track-transparent flex-col overflow-y-auto"
         ref={scrollRef}
       >
         {hasMessages ? (
@@ -324,7 +401,7 @@ const AskAI = ({
             {messages.map((message, index) =>
               message.role === "user" ? (
                 <div
-                  className="max-w-[85%] self-end whitespace-pre-wrap rounded-blume bg-muted px-3 py-2 text-foreground text-sm"
+                  className="rounded-blume bg-muted text-foreground max-w-[85%] self-end px-3 py-2 text-sm whitespace-pre-wrap"
                   // oxlint-disable-next-line react/no-array-index-key -- append-only list, see above
                   key={index}
                 >
@@ -343,7 +420,7 @@ const AskAI = ({
                       }}
                     />
                   ) : (
-                    <span className="animate-pulse text-muted-foreground">
+                    <span className="text-muted-foreground animate-pulse">
                       …
                     </span>
                   )}
@@ -354,18 +431,18 @@ const AskAI = ({
         ) : (
           <div className="mt-auto flex flex-col gap-0.5 p-4">
             {suggestions.length === 0 && (
-              <p className="px-2 text-muted-foreground text-sm">{t.empty}</p>
+              <p className="text-muted-foreground px-2 text-sm">{t.empty}</p>
             )}
             {suggestions.map((suggestion) => (
               <button
-                className="flex cursor-pointer items-center gap-2.5 rounded-blume px-2 py-2 text-start text-foreground text-sm transition-colors hover:bg-muted"
+                className="rounded-blume text-foreground hover:bg-muted flex cursor-pointer items-center gap-2.5 px-2 py-2 text-start text-sm transition-colors"
                 key={suggestion.label}
                 onClick={() => runQuestion(suggestion.label)}
                 type="button"
               >
                 {suggestion.icon && (
                   <span
-                    className="shrink-0 text-muted-foreground [&_svg]:h-[18px] [&_svg]:w-[18px]"
+                    className="text-muted-foreground shrink-0 [&_svg]:h-[18px] [&_svg]:w-[18px]"
                     // oxlint-disable-next-line react/no-danger -- trusted server-resolved inline SVG glyph
                     dangerouslySetInnerHTML={{ __html: suggestion.icon }}
                   />
@@ -373,12 +450,12 @@ const AskAI = ({
                 <span>{suggestion.label}</span>
               </button>
             ))}
-            <p className="mt-3 flex items-center gap-1.5 px-2 text-muted-foreground text-sm">
+            <p className="text-muted-foreground mt-3 flex items-center gap-1.5 px-2 text-sm">
               {t.tip}
-              <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-xs">
+              <kbd className="border-border bg-muted rounded border px-1.5 py-0.5 font-sans text-xs">
                 {IS_APPLE ? "⌘" : "Ctrl"}
               </kbd>
-              <kbd className="rounded border border-border bg-muted px-1.5 py-0.5 font-sans text-xs">
+              <kbd className="border-border bg-muted rounded border px-1.5 py-0.5 font-sans text-xs">
                 I
               </kbd>
             </p>
@@ -387,12 +464,12 @@ const AskAI = ({
       </div>
 
       <form
-        className="relative shrink-0 border-border border-t"
+        className="border-border relative shrink-0 border-t"
         onSubmit={onSubmit}
       >
         <textarea
           aria-label={t.label}
-          className="max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-foreground text-sm pointer-coarse:text-base outline-none placeholder:text-muted-foreground"
+          className="text-foreground placeholder:text-muted-foreground max-h-48 min-h-[5rem] w-full resize-none bg-transparent px-4 py-3.5 pe-14 text-sm outline-none pointer-coarse:text-base"
           onChange={(event) => setInput(event.target.value)}
           onKeyDown={onInputKeyDown}
           placeholder={t.placeholder}
@@ -402,7 +479,7 @@ const AskAI = ({
         />
         <button
           aria-label={t.send}
-          className="absolute end-3 bottom-3 inline-flex h-8 w-8 cursor-pointer items-center justify-center rounded-blume bg-foreground text-background transition-opacity disabled:cursor-not-allowed disabled:opacity-40"
+          className="rounded-blume bg-foreground text-background absolute end-3 bottom-3 inline-flex h-8 w-8 cursor-pointer items-center justify-center transition-opacity disabled:cursor-not-allowed disabled:opacity-40"
           disabled={busy || input.trim().length === 0}
           type="submit"
         >

package/src/components/islands/hooks.ts

@@ -29,7 +29,9 @@ const readClientData = (): BlumeClientData | null => {
   if (cachedData) {
     return cachedData;
   }
-  if (typeof document === "undefined") {
+  // `document` is undeclared on the server; probing `globalThis` avoids both
+  // the bare-reference ReferenceError and a `typeof` sniff.
+  if (!("document" in globalThis)) {
     return null;
   }
   const element = document.querySelector("#blume-client-data");
@@ -37,6 +39,8 @@ const readClientData = (): BlumeClientData | null => {
     return null;
   }
   try {
+    // SAFETY: the layout serialized this script tag's JSON from the same
+    // `BlumeClientData` snapshot this reads back.
     cachedData = JSON.parse(element.textContent) as BlumeClientData;
     return cachedData;
   } catch {

package/src/components/islands/webmcp.ts

@@ -16,11 +16,36 @@ interface WebMcpResult {
   isError?: boolean;
 }
 
+/** A JSON value as a WebMCP agent may supply it in a tool call. */
+export type WebMcpJsonValue =
+  | boolean
+  | number
+  | string
+  | null
+  | WebMcpJsonValue[]
+  | { [key: string]: WebMcpJsonValue };
+
+/**
+ * Tool arguments exactly as the calling agent supplied them. WebMCP doesn't
+ * guarantee schema validation, so each tool checks its own fields at runtime.
+ */
+export interface WebMcpToolArgs {
+  query?: WebMcpJsonValue;
+  route?: WebMcpJsonValue;
+}
+
+/** The JSON Schema subset these string-argument tools declare. */
+export interface WebMcpInputSchema {
+  properties: Record<string, { description: string; type: "string" }>;
+  required?: string[];
+  type: "object";
+}
+
 export interface WebMcpTool {
   annotations: { openWorldHint: boolean; readOnlyHint: boolean };
   description: string;
-  execute: (input: Record<string, unknown>) => Promise<WebMcpResult>;
-  inputSchema: Record<string, unknown>;
+  execute: (input: WebMcpToolArgs) => Promise<WebMcpResult>;
+  inputSchema: WebMcpInputSchema;
   name: string;
 }
 
@@ -31,14 +56,26 @@ export interface WebMcpTool {
  * individually via `registerTool`.
  */
 export interface ModelContext {
-  provideContext?: (context: { tools: WebMcpTool[] }) => unknown;
-  registerTool?: (tool: WebMcpTool) => unknown;
+  provideContext?: (context: { tools: WebMcpTool[] }) => void;
+  registerTool?: (tool: WebMcpTool) => void;
 }
 
-const text = (value: string, isError = false): WebMcpResult => ({
-  content: [{ text: value, type: "text" }],
-  ...(isError ? { isError: true } : {}),
-});
+const text = (value: string, isError = false): WebMcpResult => {
+  const result: WebMcpResult = { content: [{ text: value, type: "text" }] };
+  if (isError) {
+    result.isError = true;
+  }
+  return result;
+};
+
+/** Validates an agent-supplied tool argument before it is used as a string. */
+const isString = (value: WebMcpJsonValue | undefined): value is string =>
+  typeof value === "string";
+
+/** Detects which registration surface a model context actually implements. */
+const isCallable = <T extends (...args: never[]) => void>(
+  value: T | undefined
+): value is T => typeof value === "function";
 
 const TAG = /<[^>]*>?/gu;
 
@@ -89,7 +126,7 @@ export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
       description:
         "Full-text search across this documentation site. Returns matching pages with their title, URL, and a short excerpt.",
       async execute(input) {
-        const query = typeof input.query === "string" ? input.query : "";
+        const query = isString(input.query) ? input.query : "";
         if (!query.trim()) {
           return text("Provide a non-empty `query` string.", true);
         }
@@ -128,7 +165,7 @@ export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
     description:
       "Fetch a page of this site as plain Markdown. Pass the page's root-relative route, e.g. `/quickstart`.",
     async execute(input) {
-      const route = typeof input.route === "string" ? input.route : "";
+      const route = isString(input.route) ? input.route : "";
       if (!route.startsWith("/")) {
         return text("Pass a root-relative route, e.g. `/quickstart`.", true);
       }
@@ -189,11 +226,11 @@ export const registerWebMcpTools = (
   if (!context) {
     return false;
   }
-  if (typeof context.provideContext === "function") {
+  if (isCallable(context.provideContext)) {
     context.provideContext({ tools });
     return true;
   }
-  if (typeof context.registerTool === "function") {
+  if (isCallable(context.registerTool)) {
     for (const tool of tools) {
       context.registerTool(tool);
     }

package/src/components/layout/Header.astro

@@ -5,7 +5,11 @@ import { withBase } from "../islands/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";
-import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
+import type {
+  LocaleSwitchOption,
+  Navigation,
+  NavSelector as NavSelectorConfig,
+} from "../../core/types.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
@@ -50,8 +54,16 @@ interface Props {
   /** Localized chrome labels (nav toggle, sections, GitHub, theme toggle). */
   navStrings?: UIStrings["nav"];
   localeSwitch?: LocaleSwitchOption[];
+  /**
+   * Auto-populated version switcher, rendered ahead of the configured
+   * selectors. `null`/absent when versioning is off — or when the user
+   * declares their own `kind: "version"` selector, which then owns the UI.
+   */
+  versionSelector?: NavSelectorConfig | null;
   /** Active locale for per-language search filtering. */
   searchLocale?: string;
+  /** Viewed docs version for search filtering (`""` = current; `null`/absent = off). */
+  searchVersion?: string | null;
   /**
    * Layout-slot overrides forwarded from the root layout. The header honors
    * `Logo` and `Search` here so those pieces can be replaced without swapping
@@ -77,7 +89,9 @@ const {
   switcherStrings,
   navStrings,
   localeSwitch,
+  versionSelector,
   searchLocale,
+  searchVersion = null,
   layout = {},
 } = Astro.props;
 
@@ -167,6 +181,15 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
     )
   }
   <div class="flex-1"></div>
+  {
+    /* Right-aligned next to the language switcher: the spacer absorbs its
+       width, so pages without a version selector (blog, generated references)
+       keep the logo, tabs, and the rest of this cluster in place — no layout
+       shift when crossing into the docs. */
+    versionSelector && (
+      <NavSelector align="end" route={route} selector={versionSelector} />
+    )
+  }
   {
     localeSwitch && localeSwitch.length > 1 && (
       <LanguageSwitcher
@@ -184,6 +207,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
         navigation={navigation}
         popularPages={data.config.search.popular}
         strings={searchStrings}
+        version={searchVersion}
       />
     )
   }

package/src/components/layout/NavSelector.astro

@@ -11,9 +11,16 @@ import { isUnderPath } from "./nav-utils.ts";
 interface Props {
   selector: NavSelector;
   route: string;
+  /**
+   * Which edge the dropdown panel anchors to. `start` (the default) suits the
+   * header's leading selector group; the version selector sits at the trailing
+   * edge next to the language switcher, where a start-anchored panel would
+   * overflow the viewport — pass `end` there.
+   */
+  align?: "start" | "end";
 }
 
-const { selector, route } = Astro.props;
+const { selector, route, align = "start" } = Astro.props;
 
 // The active item is the deepest path the current route sits under (on a path
 // boundary, so `/api` never claims `/api-reference` routes), falling back to
@@ -46,7 +53,9 @@ const menuRowClass =
           size={14}
         />
       </summary>
-      <div class="absolute start-0 z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl">
+      <div
+        class={`absolute z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl ${align === "end" ? "end-0" : "start-0"}`}
+      >
         {selector.items.map((item) => (
           <a
             aria-current={item.path === active?.path ? "true" : undefined}

package/src/components/layout/NavTree.astro

@@ -45,8 +45,8 @@ 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 badges (from an OpenAPI reference's sidebar) are color-coded;
-// every other badge keeps the neutral style.
+// 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",
@@ -55,6 +55,8 @@ const METHOD_BADGE: Record<string, string> = {
   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()];

package/src/components/layout/PageActions.astro

@@ -224,7 +224,9 @@ const menuRowClass =
 </div>
 
 <script>
+  import { copyText, flashLabel } from "../copy-feedback.ts";
   import { prefixBase } from "../islands/base-path.ts";
+  import { rafThrottle } from "../raf-throttle.ts";
 
   const CHAT_URLS: Record<string, (q: string) => string> = {
     chatgpt: (q) => `https://chatgpt.com/?hints=search&prompt=${q}`,
@@ -318,12 +320,17 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         placeMenu(details);
       });
     }
-    window.addEventListener("resize", () => {
-      const open = dropdowns.find((details) => details.open);
-      if (open) {
-        placeMenu(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.
+    window.addEventListener(
+      "resize",
+      rafThrottle(() => {
+        const open = dropdowns.find((details) => details.open);
+        if (open) {
+          placeMenu(open);
+        }
+      })
+    );
 
     // `data-md` is the base-less logical route; the raw-markdown endpoint is a
     // generated page route, so it's served under the deployment base like any
@@ -376,24 +383,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
           `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: id, type: "http", url: mcpUrl }))}`
         );
 
-      const flash = (el: Element | null, text: string) => {
-        if (!(el instanceof HTMLElement)) {
-          return;
-        }
-        // Remember the element's own (localized) label once — capturing it at
-        // click time would capture "Copied!" on a double-click and stick.
-        el.dataset.blumeLabel ??= el.textContent ?? "";
-        el.textContent = text;
-        setTimeout(() => {
-          el.textContent = el.dataset.blumeLabel ?? "";
-        }, 1500);
-      };
       const copy = async (value: string, el: Element | null) => {
-        try {
-          await navigator.clipboard.writeText(value);
-          flash(el, copiedLabel);
-        } catch {
-          // Clipboard unavailable; nothing to do.
+        if ((await copyText(value)) && el instanceof HTMLElement) {
+          flashLabel(el, copiedLabel);
         }
       };
       root
@@ -420,9 +412,6 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     }
 
     const label = root.querySelector("[data-blume-copy-label]");
-    // Captured once — inside the handler a double-click would capture and
-    // permanently restore "Copied!".
-    const original = label?.textContent ?? "";
     root
       .querySelector("[data-blume-copy-page]")
       ?.addEventListener("click", async () => {
@@ -431,12 +420,11 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
           if (!response.ok) {
             throw new Error(`Fetching ${md} failed (${response.status})`);
           }
-          await navigator.clipboard.writeText(await response.text());
-          if (label) {
-            label.textContent = copiedLabel;
-            setTimeout(() => {
-              label.textContent = original;
-            }, 1500);
+          if (
+            (await copyText(await response.text())) &&
+            label instanceof HTMLElement
+          ) {
+            flashLabel(label, copiedLabel);
           }
         } catch (error) {
           // Clipboard or fetch unavailable; don't flash "Copied!" untruthfully.