blume 1.2.0 → 1.3.0

package/src/cli/commands/build.ts

@@ -1,12 +1,29 @@
 import { existsSync } from "node:fs";
-import { readdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 
 import { build } from "astro";
 import { defineCommand } from "citty";
-import { join } from "pathe";
+import { dirname, join, resolve } from "pathe";
 
 import { buildAgentReadability } from "../../ai/agent-readability.ts";
+import {
+  API_CATALOG_PATH,
+  API_CATALOG_TYPE,
+  buildApiCatalog,
+  hasApiCatalog,
+} from "../../ai/api-catalog.ts";
+import { buildHomeLinkHeader } from "../../ai/link-headers.ts";
 import { buildLlmsFiles } from "../../ai/llms.ts";
+import {
+  AGENT_SKILLS_DIR,
+  buildSkillsIndex,
+  collectSkills,
+} from "../../ai/skills.ts";
+import {
+  buildSignaturesDirectory,
+  SIGNATURES_DIRECTORY_PATH,
+  SIGNATURES_DIRECTORY_TYPE,
+} from "../../ai/web-bot-auth.ts";
 import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeProject } from "../../core/project-graph.ts";
 import type { ResolvedConfig } from "../../core/schema.ts";
@@ -26,6 +43,7 @@ import {
 } from "../../deploy/redirects.ts";
 import { buildRobots } from "../../deploy/robots.ts";
 import { buildSitemap } from "../../deploy/sitemap.ts";
+import { injectNegotiationRoutes } from "../../deploy/vercel-negotiation.ts";
 import { buildSearchIndex } from "../../search/build.ts";
 import { syncSearchProvider } from "../../search/sync/index.ts";
 import { refuseIfDevRunning } from "../dev-lock.ts";
@@ -107,14 +125,17 @@ const emitRedirectFiles = async (
  * hosts serve the raw AI-ready endpoints (`*.md`, `*.mdx`, `*.txt`) with an
  * explicit `charset=utf-8`. Without it those hosts send `text/markdown` /
  * `text/plain` with no charset and browsers fall back to Windows-1252, garbling
- * any non-ASCII docs (#82). A `_headers` shipped in `public/` (copied into dist
- * by Astro before this runs) wins, exactly like `_redirects`. Server adapters
- * set the Content-Type on the Response directly, so this is static-only.
+ * any non-ASCII docs (#82). The same file also stamps the homepage
+ * agent-discovery `Link` header (RFC 8288, see `ai/link-headers.ts`). A
+ * `_headers` shipped in `public/` (copied into dist by Astro before this runs)
+ * wins, exactly like `_redirects`. Server adapters set the Content-Type on the
+ * Response directly, so this is static-only.
  */
 const emitHeaderFiles = async (
-  config: ResolvedConfig,
+  project: BlumeProject,
   distDir: string
 ): Promise<void> => {
+  const { config } = project;
   if (
     config.deployment.output !== "static" ||
     existsSync(join(distDir, "_headers"))
@@ -123,10 +144,147 @@ const emitHeaderFiles = async (
   }
   await writeFile(
     join(distDir, "_headers"),
-    buildNetlifyHeaders(config),
+    buildNetlifyHeaders(
+      config,
+      buildHomeLinkHeader(
+        config,
+        project.manifest.routes.map((route) => route.path)
+      )
+    ),
     "utf-8"
   );
-  logger.success("Emitted _headers (UTF-8 Content-Type for raw endpoints)");
+  logger.success(
+    "Emitted _headers (UTF-8 Content-Type + homepage Link header)"
+  );
+};
+
+/**
+ * Publish the configured Agent Skills: copy each skill artifact under
+ * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
+ * `public/.well-known/agent-skills/index.json` takes over the whole surface,
+ * matching every other generated artifact.
+ */
+const emitAgentSkills = async (
+  project: BlumeProject,
+  distDir: string
+): Promise<void> => {
+  const configured = project.config.ai.skills;
+  if (!configured) {
+    return;
+  }
+  const dir = resolve(project.context.root, configured);
+  if (!existsSync(dir)) {
+    logger.warn(
+      `ai.skills points at "${configured}" (${dir}), which does not exist; no skills published.`
+    );
+    return;
+  }
+  const outDir = join(distDir, AGENT_SKILLS_DIR.slice(1));
+  if (existsSync(join(outDir, "index.json"))) {
+    return;
+  }
+  const { skills, warnings } = await collectSkills(dir);
+  for (const warning of warnings) {
+    logger.warn(warning);
+  }
+  if (skills.length === 0) {
+    logger.warn(`ai.skills: no publishable skills found in "${configured}".`);
+    return;
+  }
+  await Promise.all(
+    skills.map(async (skill) => {
+      const target = join(outDir, skill.path);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, skill.content);
+    })
+  );
+  await writeFile(
+    join(outDir, "index.json"),
+    buildSkillsIndex(skills, project.config),
+    "utf-8"
+  );
+  logger.success(
+    `Published ${skills.length} agent skill(s) (.well-known/agent-skills/index.json)`
+  );
+};
+
+/**
+ * Emit the generated `.well-known` discovery files — the RFC 9727 API catalog
+ * and the Web Bot Auth signature directory — each skipped when the feature is
+ * off or when the user ships their own copy via public/ (already in dist by
+ * the time this runs).
+ */
+const emitWellKnownFiles = async (
+  config: ResolvedConfig,
+  distDir: string
+): Promise<void> => {
+  const files = [
+    {
+      content: buildSignaturesDirectory(config),
+      label: "Web Bot Auth",
+      path: SIGNATURES_DIRECTORY_PATH,
+    },
+    {
+      content: buildApiCatalog(config),
+      label: "RFC 9727",
+      path: API_CATALOG_PATH,
+    },
+  ];
+  for (const file of files) {
+    const target = join(distDir, file.path.slice(1));
+    if (!file.content || existsSync(target)) {
+      continue;
+    }
+    // Sequential by nature: both files share the .well-known dir creation.
+    // oxlint-disable-next-line no-await-in-loop
+    await mkdir(join(distDir, ".well-known"), { recursive: true });
+    // oxlint-disable-next-line no-await-in-loop
+    await writeFile(target, file.content, "utf-8");
+    logger.success(`Generated ${file.path.slice(1)} (${file.label})`);
+  }
+};
+
+/**
+ * Splice `Accept: text/markdown` negotiation routes into the Vercel adapter's
+ * Build Output config, so a content-page request that prefers Markdown gets the
+ * page's prerendered `.md` mirror (content pages are prerendered even in server
+ * output, so Astro middleware never sees them — the routing layer is the only
+ * request-time hook). Vercel server builds only; the adapter writes the config
+ * straight to the project root (see `withAdapterRoot`).
+ */
+const emitVercelNegotiation = async (
+  config: ResolvedConfig,
+  routePaths: string[],
+  root: string
+): Promise<void> => {
+  const configPath = join(root, ".vercel", "output", "config.json");
+  if (!existsSync(configPath)) {
+    return;
+  }
+  const overrides: Record<string, string> = {
+    ...(hasApiCatalog(config)
+      ? { [API_CATALOG_PATH.slice(1)]: API_CATALOG_TYPE }
+      : {}),
+    ...(config.ai.webBotAuth.keys.length > 0
+      ? { [SIGNATURES_DIRECTORY_PATH.slice(1)]: SIGNATURES_DIRECTORY_TYPE }
+      : {}),
+  };
+  const injected = injectNegotiationRoutes(
+    await readFile(configPath, "utf-8"),
+    routePaths,
+    buildHomeLinkHeader(config, routePaths),
+    overrides
+  );
+  if (injected === null) {
+    logger.warn(
+      "Could not wire Accept: text/markdown negotiation into .vercel/output/config.json — raw Markdown stays available at the .md URLs."
+    );
+    return;
+  }
+  await writeFile(configPath, injected, "utf-8");
+  logger.success(
+    "Wired Accept: text/markdown negotiation into the Vercel routing config"
+  );
 };
 
 const formatBytes = (bytes: number): string => {
@@ -375,8 +533,11 @@ const publishBuildArtifacts = async (
     logger.success("Generated agent-readability.json");
   }
 
+  await emitWellKnownFiles(project.config, distDir);
+  await emitAgentSkills(project, distDir);
+
   await emitRedirectFiles(project.config, distDir);
-  await emitHeaderFiles(project.config, distDir);
+  await emitHeaderFiles(project, distDir);
 
   const { config } = project;
   const features = serverFeatures(config);
@@ -547,6 +708,14 @@ export const buildCommand = defineCommand({
       logger.success(`Surfaced ${adapter} output to ${surfaced.to}`);
     }
 
+    if (project.config.deployment.output === "server" && adapter === "vercel") {
+      await emitVercelNegotiation(
+        project.config,
+        project.manifest.routes.map((route) => route.path),
+        root
+      );
+    }
+
     await publishBuildArtifacts(
       project,
       deployStaticDir(project.config, project.context),

package/src/cli/init/scaffold.ts

@@ -287,7 +287,7 @@ export default defineConfig({
 /** SDK dependencies required by the selected remote sources. */
 const extraDepsFor = (sources: SourceKind[]): Record<string, string> => ({
   ...(sources.includes("notion") && { "@notionhq/client": "^2.2.15" }),
-  ...(sources.includes("sanity") && { "@sanity/client": "^6.21.0" }),
+  ...(sources.includes("sanity") && { "@sanity/client": "^7.25.0" }),
 });
 
 /** Every file `init` should write for the given answers, package.json first. */

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

@@ -392,7 +392,10 @@ const AskAI = ({
         </div>
       </header>
 
-      <div className="flex flex-1 flex-col overflow-y-auto" ref={scrollRef}>
+      <div
+        className="flex flex-1 flex-col scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto"
+        ref={scrollRef}
+      >
         {hasMessages ? (
           <div className="flex flex-col gap-4 p-4">
             {messages.map((message) =>

package/src/components/islands/webmcp.ts

@@ -0,0 +1,203 @@
+import type { SearchFn } from "../layout/search/types.ts";
+import { joinBase, prefixBase } from "./base-path.ts";
+
+/**
+ * WebMCP (W3C Web Machine Learning CG): in-page tools an agentic browser can
+ * call, registered on the page's model context. Blume exposes the same
+ * read-only surface its hosted MCP server has — search, page Markdown, the
+ * docs index — so an agent driving the browser needs no separate connection.
+ * The module is inert everywhere else: registration is attempted only when
+ * the page exposes a model context.
+ */
+
+/** MCP-style tool result: text content, with `isError` on failures. */
+interface WebMcpResult {
+  content: { text: string; type: "text" }[];
+  isError?: boolean;
+}
+
+export interface WebMcpTool {
+  annotations: { openWorldHint: boolean; readOnlyHint: boolean };
+  description: string;
+  execute: (input: Record<string, unknown>) => Promise<WebMcpResult>;
+  inputSchema: Record<string, unknown>;
+  name: string;
+}
+
+/**
+ * The registration surface, in either of the shapes the moving spec has
+ * shipped: Chrome's early preview exposes `navigator.modelContext` with
+ * `provideContext({ tools })`, while the editor's draft registers tools
+ * individually via `registerTool`.
+ */
+export interface ModelContext {
+  provideContext?: (context: { tools: WebMcpTool[] }) => unknown;
+  registerTool?: (tool: WebMcpTool) => unknown;
+}
+
+const text = (value: string, isError = false): WebMcpResult => ({
+  content: [{ text: value, type: "text" }],
+  ...(isError ? { isError: true } : {}),
+});
+
+const TAG = /<[^>]*>?/gu;
+
+/**
+ * Drop the `<mark>` highlighting (and any other markup) search hits carry.
+ * The closing `>` is optional so every `<` starts a strip: a dangling
+ * `<script` fragment can't survive the way it would if a full `<...>` pair
+ * were required. The input is HTML, where a literal `<` is `&lt;`, so
+ * consuming from every raw `<` loses nothing legitimate. Stripping repeats
+ * to a fixed point so the no-fragment guarantee is explicit rather than an
+ * artifact of the regex shape.
+ */
+const plain = (html: string): string => {
+  let stripped = html;
+  let previous: string;
+  do {
+    previous = stripped;
+    stripped = stripped.replaceAll(TAG, "");
+  } while (stripped !== previous);
+  return stripped;
+};
+
+export interface WebMcpToolOptions {
+  /** The deployment base (`import.meta.env.BASE_URL`). */
+  base: string;
+  /** Injectable for tests; defaults to the page's `fetch`. */
+  fetchFn?: typeof fetch;
+  /** Lazy provider-specific search loader (`blume:search-client`). */
+  loadSearch: () => Promise<SearchFn>;
+  /** Whether the site publishes llms.txt (gates the list tool). */
+  llms: boolean;
+  /** Whether site search is configured (gates the search tool). */
+  search: boolean;
+}
+
+/** Build the tool set. Pure — registration is the caller's business. */
+export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
+  const fetchFn = options.fetchFn ?? fetch;
+  const readOnly = { openWorldHint: false, readOnlyHint: true };
+  const tools: WebMcpTool[] = [];
+
+  if (options.search) {
+    // One search instance per page; a transient load failure retries on the
+    // next call rather than latching broken.
+    let searchFn: SearchFn | null = null;
+    tools.push({
+      annotations: readOnly,
+      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 : "";
+        if (!query.trim()) {
+          return text("Provide a non-empty `query` string.", true);
+        }
+        try {
+          searchFn ??= await options.loadSearch();
+          const { hits } = await searchFn(query);
+          if (hits.length === 0) {
+            return text(`No results for "${query}".`);
+          }
+          return text(
+            hits
+              .map(
+                (hit) =>
+                  `${plain(hit.title)} — ${prefixBase(options.base, hit.url)}\n${plain(hit.excerpt)}`
+              )
+              .join("\n\n")
+          );
+        } catch {
+          searchFn = null;
+          return text("Search is unavailable right now.", true);
+        }
+      },
+      inputSchema: {
+        properties: {
+          query: { description: "The search query.", type: "string" },
+        },
+        required: ["query"],
+        type: "object",
+      },
+      name: "search_docs",
+    });
+  }
+
+  tools.push({
+    annotations: readOnly,
+    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 : "";
+      if (!route.startsWith("/")) {
+        return text("Pass a root-relative route, e.g. `/quickstart`.", true);
+      }
+      const trimmed = route.length > 1 ? route.replace(/\/+$/u, "") : route;
+      const target = trimmed === "/" ? "/index" : trimmed;
+      const response = await fetchFn(
+        `${prefixBase(options.base, target)}.md`
+      ).catch(() => null);
+      if (!response?.ok) {
+        return text(`No Markdown found for ${route}.`, true);
+      }
+      return text(await response.text());
+    },
+    inputSchema: {
+      properties: {
+        route: {
+          description: "Root-relative page route, e.g. `/quickstart`.",
+          type: "string",
+        },
+      },
+      required: ["route"],
+      type: "object",
+    },
+    name: "get_page",
+  });
+
+  if (options.llms) {
+    tools.push({
+      annotations: readOnly,
+      description:
+        "List this site's pages: the llms.txt index of every page with its URL and summary, organized by section.",
+      async execute() {
+        const response = await fetchFn(
+          joinBase(options.base, "llms.txt")
+        ).catch(() => null);
+        if (!response?.ok) {
+          return text("The page index (llms.txt) is unavailable.", true);
+        }
+        return text(await response.text());
+      },
+      inputSchema: { properties: {}, type: "object" },
+      name: "list_pages",
+    });
+  }
+
+  return tools;
+};
+
+/**
+ * Register the tools on whichever model context the page exposes. Returns
+ * whether a registration surface was found — false in every browser that
+ * doesn't implement WebMCP, which is the common, silent case.
+ */
+export const registerWebMcpTools = (
+  tools: WebMcpTool[],
+  context?: ModelContext | null
+): boolean => {
+  if (!context) {
+    return false;
+  }
+  if (typeof context.provideContext === "function") {
+    context.provideContext({ tools });
+    return true;
+  }
+  if (typeof context.registerTool === "function") {
+    for (const tool of tools) {
+      context.registerTool(tool);
+    }
+    return true;
+  }
+  return false;
+};

package/src/components/layout/NavTree.astro

@@ -137,7 +137,7 @@ const initialId =
             <div class="mb-3 flex items-center gap-0.5">
               <button
                 aria-label={n.back}
-                class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
                 data-nav-back={panel.parentId}
                 type="button"
               >
@@ -145,7 +145,7 @@ const initialId =
               </button>
               <a
                 aria-current={panel.route === currentRoute ? "page" : undefined}
-                class="flex-1 truncate rounded px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+                class="flex-1 truncate rounded-[0.65rem] px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                 href={withBase(panel.route)}
               >
                 {panel.label}
@@ -154,7 +154,7 @@ const initialId =
           ) : (
             <button
               aria-label={`${n.back}: ${panel.label}`}
-              class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+              class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
               data-nav-back={panel.parentId}
               type="button"
             >
@@ -317,7 +317,7 @@ const initialId =
               {item.route ? (
                 <a
                   aria-current={item.route === currentRoute ? "page" : undefined}
-                  class="-ml-1 flex flex-1 items-center gap-1.5 rounded px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted"
+                  class="-ml-1 flex flex-1 items-center gap-1.5 rounded-[0.65rem] px-1 py-0.5 text-foreground transition-colors hover:bg-muted aria-[current=page]:bg-muted"
                   href={withBase(item.route)}
                 >
                   {item.icon && (

package/src/components/layout/PageLayout.astro

@@ -40,6 +40,7 @@ import Fonts from "./Fonts.astro";
 import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import { activeTabForRoute } from "./nav-utils.ts";
+import WebMcp from "./WebMcp.astro";
 
 interface Props {
   site: { title: string; description?: string };
@@ -254,6 +255,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     />
     <main id="blume-content"><slot /></main>
     <slot name="footer" />
+    <WebMcp />
     {
       // Mobile nav for chrome-only pages: the header's inline tab bar is hidden
       // below `lg` and there's no sidebar drawer, so surface the tabs in a

package/src/components/layout/ReferenceLayout.astro

@@ -4,6 +4,7 @@ import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
 import Analytics from "./Analytics.astro";
+import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
@@ -126,5 +127,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     >
       <slot />
     </div>
+    <WebMcp />
   </body>
 </html>

package/src/components/layout/RootLayout.astro

@@ -20,6 +20,7 @@ import { buildStructuredData, toIso } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
 import Analytics from "./Analytics.astro";
+import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
 import Breadcrumbs from "./Breadcrumbs.astro";
 import Empty from "./Empty.astro";
@@ -448,6 +449,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     class="bg-background font-sans text-foreground antialiased"
     data-blume-code-wrap={codeWrap ? "" : undefined}
     data-blume-image-zoom={imageZoom ? "" : undefined}
+    data-i18n-copied={actionStrings.copied}
     data-i18n-copy-code={actionStrings.copyCode}
     data-i18n-diagram-error={contentStrings.diagramError}
   >
@@ -479,7 +481,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         aria-label={navStrings.primary}
         data-blume-nav-drawer
         class:list={[
-          "fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4",
+          "fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:scrollbar-thin lg:scrollbar-thumb-border lg:scrollbar-track-transparent lg:border-e-0 lg:bg-transparent lg:px-4",
           // A "bare" landing (the changelog index) has no sidebar column on
           // desktop, but the header hamburger still needs a drawer to open on
           // mobile — without it the toggle only locked page scroll.
@@ -630,7 +632,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         showToc && (
           <aside
             aria-label={strings.toc.title}
-            class="sticky top-16 hidden h-[calc(100dvh-4rem)] overflow-y-auto px-4 pt-6 pb-10 text-sm xl:block"
+            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
@@ -707,17 +709,30 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         });
       }
 
-      const svg = (name: string) =>
-        `<svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${icons[name]}</svg>`;
+      const svg = (name: string, cls = "") =>
+        `<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"${cls ? ` class="${cls}"` : ""}>${icons[name]}</svg>`;
 
+      // Opaque icon chip over the code (in the style of Lina's code block),
+      // with the check icon scale-swapping in over the copy icon after a copy.
       const buttonClass =
-        "absolute right-3 inline-flex size-7 items-center justify-center rounded-full bg-transparent text-muted-foreground opacity-70 transition hover:bg-muted hover:text-foreground hover:opacity-100 focus-visible:opacity-100";
+        "absolute right-3 z-[2] inline-flex size-[1.875rem] select-none items-center justify-center rounded-md text-muted-foreground bg-background transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0";
+      const idleClasses = ["hover:bg-muted", "hover:text-foreground"];
 
-      // Localized copy-button label, stamped on <body> by the layout markup
+      // Localized copy-button labels, stamped on <body> by the layout markup
       // (the Search.astro data-attribute channel) since this bundled script
       // can't interpolate server values directly.
       const copyCodeLabel =
         document.body.getAttribute("data-i18n-copy-code") || "Copy code";
+      const copiedLabel =
+        document.body.getAttribute("data-i18n-copied") || "Copied!";
+
+      // Shared polite live region: the icon swap is invisible to screen
+      // readers, so copy success is announced here. Cleared when a button's
+      // checked state resets so the next copy re-announces.
+      const copyStatus = document.createElement("span");
+      copyStatus.className = "sr-only";
+      copyStatus.setAttribute("aria-live", "polite");
+      document.body.appendChild(copyStatus);
 
       const languageLabels: Record<string, string> = {
         astro: "Astro",
@@ -757,6 +772,16 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           );
         }
         pre.classList.add("group", "relative");
+        // The code element is the scroll container (see the theme entry), but
+        // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
+        // stop to the code so keyboard users can actually scroll the block
+        // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
+        // API-panel blocks keep the pre as their scroller, so theirs stays.
+        const scroller = pre.querySelector("code");
+        if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
+          scroller.setAttribute("tabindex", "0");
+          pre.removeAttribute("tabindex");
+        }
         const button = document.createElement("button");
         button.type = "button";
         // The language-label bar (prose) vs flush code (tabs) need a different
@@ -764,10 +789,31 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         const topClass = pre.closest("blume-tabs, .not-prose")
           ? "top-2.5"
           : "top-2";
-        button.className = `${buttonClass} ${topClass}`;
+        button.className = `${buttonClass} ${idleClasses.join(" ")} ${topClass}`;
         button.setAttribute("data-blume-copy", "");
         button.setAttribute("aria-label", copyCodeLabel);
-        button.innerHTML = svg("copy");
+        button.innerHTML =
+          svg(
+            "check",
+            "scale-0 text-green-600 transition-transform dark:text-green-500"
+          ) + svg("copy", "absolute transition-transform");
+        const [checkIcon, copyIcon] = button.querySelectorAll("svg");
+        // While checked the button drops its idle hover tint so the green
+        // check reads as a steady confirmation, mirroring Lina's copied state.
+        // The accessible name tracks the visual state for anyone probing the
+        // button mid-confirmation.
+        const setChecked = (checked: boolean) => {
+          checkIcon?.classList.toggle("scale-0", !checked);
+          copyIcon?.classList.toggle("scale-0", checked);
+          button.setAttribute(
+            "aria-label",
+            checked ? copiedLabel : copyCodeLabel
+          );
+          for (const cls of idleClasses) {
+            button.classList.toggle(cls, !checked);
+          }
+        };
+        let resetTimeout: number | undefined;
         button.addEventListener("click", async () => {
           const code = pre.querySelector("code");
           let text = code?.textContent ?? "";
@@ -788,9 +834,14 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           } catch {
             return;
           }
-          button.innerHTML = svg("check");
-          setTimeout(() => {
-            button.innerHTML = svg("copy");
+          if (resetTimeout) {
+            window.clearTimeout(resetTimeout);
+          }
+          setChecked(true);
+          copyStatus.textContent = copiedLabel;
+          resetTimeout = window.setTimeout(() => {
+            setChecked(false);
+            copyStatus.textContent = "";
           }, 1500);
         });
         pre.appendChild(button);
@@ -912,5 +963,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         }
       }
     </script>
+    <WebMcp />
   </body>
 </html>