blume 1.6.0 → 1.6.1

package/src/astro/templates.ts

@@ -22,6 +22,7 @@ import type { ExampleSpec } from "./examples.ts";
 import type { BlumePageRoute } from "./integration.ts";
 import type { IslandSpec } from "./islands.ts";
 import type { OgCustomRoute } from "./pages.ts";
+import { RUNTIME_MODULE_FILES } from "./runtime-modules.ts";
 
 const WORKSPACE_MARKERS = [
   ".git",
@@ -290,9 +291,38 @@ const adapterRoot = (context: ProjectContext): string =>
  * re-optimization. A blanket `/node_modules/` exclude would instead switch the
  * React Compiler off for Blume's own components in published installs (they
  * resolve under `node_modules/blume/src`, and exclude beats include in the
- * plugin's filter), so only the pre-bundle cache is excluded.
+ * plugin's filter), so only the pre-bundle cache is excluded. The hidden runtime
+ * relocates that cache to `<runtime>/.cache/vite` (see `cacheOptions`), so both
+ * the default and the relocated path are excluded.
  */
-const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//]`;
+const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//, /\/\.cache\/vite\//]`;
+
+/**
+ * The `cacheDir` entries for the generated config's top level and its `vite`
+ * block. The hidden runtime's `node_modules` is a junction into Blume's own
+ * package directory, and Astro (`node_modules/.astro`: the content data store,
+ * the fonts cache) and Vite (`node_modules/.vite`: pre-bundled deps) both
+ * default their caches under the project's `node_modules`. Two Blume projects
+ * that resolve the same package (a monorepo building docs and a sandbox in
+ * parallel) would therefore share one data store, and each build would serve
+ * the other's content — or 404 on entries the other cleared. Keep every cache
+ * inside the runtime dir instead. An ejected project (`generatedModulesDir`
+ * set) has real `node_modules`, so it keeps the defaults.
+ */
+const runtimeCacheOptions = (
+  context: ProjectContext,
+  generatedModulesDir: string | undefined
+) => {
+  if (generatedModulesDir !== undefined) {
+    return { astro: "", vite: "" };
+  }
+  return {
+    astro: `
+  cacheDir: ${JSON.stringify(`${context.outDir}/.cache/astro`)},`,
+    vite: `
+    cacheDir: ${JSON.stringify(`${context.outDir}/.cache/vite`)},`,
+  };
+};
 
 /**
  * The `react()` integration call. When `compilerPath` is set (the resolved
@@ -394,6 +424,40 @@ const resolveOptimizeDeps = (options: {
   return { optimizeDepsEntries, optimizeDepsInclude };
 };
 
+/**
+ * How the generated config reaches the runtime data modules (`blume:data`,
+ * the search index, …): served from memory by `runtimeModulesPlugin` in the
+ * hidden runtime, or aliased to JSON files under `generatedModulesDir` for an
+ * ejected project, which has no CLI to publish them (see `runtime-modules.ts`).
+ */
+interface RuntimeModuleWiring {
+  /** `resolve.alias` entries (one per module), empty in the in-memory form. */
+  aliasLines: string;
+  /** Extra `blume/astro` imports the wiring needs. */
+  imports: string[];
+  /** Leading `vite.plugins` entry, empty in the file-alias form. */
+  pluginEntry: string;
+}
+
+const renderRuntimeModuleWiring = (
+  generatedModulesDir: string | undefined
+): RuntimeModuleWiring => {
+  if (generatedModulesDir === undefined) {
+    return {
+      aliasLines: "",
+      imports: ["runtimeModulesPlugin"],
+      pluginEntry: "runtimeModulesPlugin(), ",
+    };
+  }
+  const aliasLines = [...RUNTIME_MODULE_FILES]
+    .map(
+      ([id, file]) =>
+        `\n        ${JSON.stringify(id)}: ${JSON.stringify(`${generatedModulesDir}/${file}`)},`
+    )
+    .join("");
+  return { aliasLines, imports: [], pluginEntry: "" };
+};
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -404,13 +468,18 @@ export const astroConfigTemplate = (options: {
   contentRoutes: string[];
   /** The generated Ask trigger (`blume:ask`); renders nothing when Ask is off. */
   askPath: string;
-  dataPath: string;
   examplesPath: string;
   /** The example-preview Tailwind entry (`blume:examples-theme`). */
   examplesThemePath: string;
   themePath: string;
   searchClientPath: string;
-  openapiPath: string;
+  /**
+   * Where the runtime data modules (`blume:data`, the search index, …) live as
+   * JSON files, for a project with no CLI to publish them in memory (eject):
+   * each id is aliased to its file under this directory. Absent, the modules
+   * are served from memory by `runtimeModulesPlugin` — the hidden runtime.
+   */
+  generatedModulesDir?: string;
   /**
    * Absolute path to `babel-plugin-react-compiler` when the React Compiler is
    * enabled (resolved from Blume's package root by the caller); null/absent
@@ -427,17 +496,27 @@ export const astroConfigTemplate = (options: {
   /** Bridge used to load configured integrations without serializing them. */
   integrationBridge?: IntegrationBridgeOptions;
 }): string => {
-  const { context, config, needsReact, pages, dataPath, themePath } = options;
+  const { context, config, needsReact, pages, themePath } = options;
+
+  const { astro: cacheOptions, vite: viteCacheOption } = runtimeCacheOptions(
+    context,
+    options.generatedModulesDir
+  );
   const {
     askPath,
     contentRoutes,
     examplesPath,
     examplesThemePath,
+    generatedModulesDir,
     needsSvelte,
     needsVue,
-    openapiPath,
     searchClientPath,
   } = options;
+  const {
+    aliasLines: runtimeModuleAliasLines,
+    imports: runtimeModuleImports,
+    pluginEntry: runtimeModulesPluginEntry,
+  } = renderRuntimeModuleWiring(generatedModulesDir);
   const { deployment } = config;
   const userAliasLines = renderUserAliases(options.aliases);
   const server = deployment.output === "server";
@@ -588,6 +667,7 @@ export const astroConfigTemplate = (options: {
     "blumeIntegration",
     "includeHmrPlugin",
     "prerenderDepsPlugin",
+    ...runtimeModuleImports,
     ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
   ];
   const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
@@ -655,7 +735,7 @@ ${userConfigSetup}export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
   outDir: ${JSON.stringify(astroOutDir(context))},
-  publicDir: ${JSON.stringify(`${context.root}/public`)},
+  publicDir: ${JSON.stringify(`${context.root}/public`)},${cacheOptions}
   output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${imageOption}${redirectsOption}${i18nOption}${fontsOption}
   integrations: [${integrations.join(", ")}${userIntegrationSpread}],
   markdown: {
@@ -683,8 +763,8 @@ ${userConfigSetup}export default defineConfig({
   // request latency behind the user's intent, so most navigations swap
   // instantly.
   prefetch: { prefetchAll: true },
-  vite: {
-    plugins: [tailwindcss(), includeHmrPlugin(${JSON.stringify(
+  vite: {${viteCacheOption}
+    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${JSON.stringify(
       `${context.outDir}/src/generated/includes.json`
     )}), prerenderDepsPlugin()],
     // Everything hydration can reach must be part of the dev dep optimizer's
@@ -733,12 +813,10 @@ ${userConfigSetup}export default defineConfig({
     resolve: {
       alias: {
         "blume:ask": ${JSON.stringify(askPath)},
-        "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
         "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
-        "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
-        "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
+        "blume:theme": ${JSON.stringify(themePath)},${runtimeModuleAliasLines}${userAliasLines}
       },
     },
     server: {
@@ -932,7 +1010,7 @@ export const askEndpointTemplate = (
   if (grounded) {
     imports.push(
       'import { createAskContext } from "blume/ai/ask-context.ts";',
-      'import askData from "../../generated/ask-data.json";'
+      'import askData from "blume:ask-data";'
     );
     const groundFields: string[] = [];
     if (instructions) {
@@ -1080,7 +1158,7 @@ const { strings } = Astro.props;
 /** Generate the static search index endpoint (`/blume-search.json`). */
 export const searchEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
-import documents from "../generated/search.json";
+import documents from "blume:search-index";
 
 export const prerender = true;
 
@@ -1258,7 +1336,7 @@ export const POST: APIRoute = async ({ request }) => {
  */
 export const rawMarkdownEndpointTemplate = (kind: "md" | "mdx"): string =>
   `// Generated by Blume. Do not edit.
-import raw from "../generated/raw-markdown.json";
+import raw from "blume:raw-markdown";
 
 export const prerender = true;
 
@@ -1308,7 +1386,7 @@ import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import type { APIRoute } from "astro";
-import assets from "../../generated/content-assets.json";
+import assets from "blume:content-assets";
 
 export const prerender = true;
 
@@ -1400,22 +1478,18 @@ export const mcpPageFile = (route: string): string =>
  * generated data snapshot. Runs server-side (no prerender) so agents can query
  * the docs over Streamable HTTP.
  */
-export const mcpEndpointTemplate = (route: string): string => {
-  const clean = trimChar(route, "/");
-  const up = "../".repeat(clean.split("/").length);
-  return `// Generated by Blume. Do not edit.
+export const mcpEndpointTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
 import { createMcpFetchHandler } from "blume/ai/mcp/server.ts";
-import type { McpData } from "blume/ai/mcp/data.ts";
-import data from "${up}generated/mcp-data.json";
+import data from "blume:mcp-data";
 
 export const prerender = false;
 
-const handler = createMcpFetchHandler(data as McpData);
+const handler = createMcpFetchHandler(data);
 
 export const ALL: APIRoute = ({ request }) => handler(request);
 `;
-};
 
 /**
  * Generate the playground's CORS proxy endpoint
@@ -1464,7 +1538,7 @@ export function GET() {
  */
 export const rssEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
-import feeds from "../../generated/rss.json";
+import feeds from "blume:rss";
 
 export const prerender = true;
 
@@ -1486,7 +1560,16 @@ export function GET({ props }: { props: { section: string } }) {
 /** Generate the OG image endpoint (`.blume/src/pages/og/[...slug].png.ts`). */
 export const ogEndpointTemplate = (
   customRoutes: OgCustomRoute[] = [],
-  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {},
+  og: {
+    families?: OgFontFamilies;
+    fonts?: OgFont[];
+    /**
+     * Whether a page's own description may replace the site-wide subtitle.
+     * `false` when `seo.og.description` is `false`, which hides the subtitle
+     * on every card, page text included. Defaults to `true`.
+     */
+    pageDescriptions?: boolean;
+  } = {},
   includeChangelog = false
 ): string =>
   `// Generated by Blume. Do not edit.
@@ -1510,28 +1593,52 @@ const families: OgFontFamilies | undefined = ${
     og.families ? JSON.stringify(og.families) : "undefined"
   };
 
+// A page's own description (its \`seo.description\`, else \`description\`) is
+// the card subtitle, so the image says what the page's og:description says.
+// Pages without one fall back to the site-wide subtitle at render time.
+// \`seo.og.description: false\` hides the subtitle on every card, page text
+// included, which is what switches this off.
+const pageDescriptions = ${og.pageDescriptions !== false};
+
+interface CardProps {
+  title: string;
+  description: string | null;
+}
+
 export function getStaticPaths() {
   const seen = new Set<string>();
-  const paths: { params: { slug: string }; props: { title: string } }[] = [];
-  const add = (slug: string, title: string) => {
+  const paths: { params: { slug: string }; props: CardProps }[] = [];
+  const add = (slug: string, title: string, description: string | null) => {
     if (seen.has(slug)) {
       return;
     }
     seen.add(slug);
-    paths.push({ params: { slug }, props: { title } });
+    paths.push({
+      params: { slug },
+      props: { title, description: pageDescriptions ? description : null },
+    });
   };
   // A custom page wins over a content route sharing its path, so add it first.
+  // Its description is unknown at generate time, so it takes the site subtitle.
   for (const route of customRoutes) {
-    add(route.slug, route.title);
+    add(route.slug, route.title, null);
   }
   for (const route of data.routes) {
-    add(route.path === "/" ? "index" : route.path.slice(1), route.title);
+    add(
+      route.path === "/" ? "index" : route.path.slice(1),
+      route.title,
+      route.description
+    );
   }${
     includeChangelog
       ? `
   // The generated changelog index is not a content route, so it needs its own
   // card. Added last: a custom page or content route owning /changelog wins.
-  add("changelog", data.ui.changelog?.title ?? "Changelog");`
+  add(
+    "changelog",
+    data.ui.changelog?.title ?? "Changelog",
+    data.ui.changelog?.description ?? null
+  );`
       : ""
   }
   return paths;
@@ -1544,11 +1651,11 @@ const repoSlug = data.config.github
   ? \`\${data.config.github.owner}/\${data.config.github.repo}\`
   : undefined;
 
-export async function GET({ props }: { props: { title: string } }) {
+export async function GET({ props }: { props: CardProps }) {
   const png = await renderOgImage({
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
-    description: data.config.og.description,
+    description: props.description ?? data.config.og.description,
     families,
     fonts,
     logo: data.config.og.logo,
@@ -1572,13 +1679,11 @@ export async function GET({ props }: { props: { title: string } }) {
  * but mounted inside Blume's {@link ReferenceLayout} so the page keeps Blume's
  * navbar on top. `renderMode: "client"` mounts the reference into a container
  * element (rather than emitting a full HTML document), which is what lets it
- * live inside our shell. `dataImport` is the route-depth-aware relative path to
- * the generated data module the layout reads.
+ * live inside our shell.
  */
 export const scalarReferenceTemplate = <Configuration extends object>(options: {
   /** Scalar options forwarded verbatim (spec/theme config plus the author's `scalar` escape hatch). */
   configuration: Configuration;
-  dataImport: string;
   noindex?: boolean;
   route: string;
   title: string;
@@ -1587,7 +1692,7 @@ export const scalarReferenceTemplate = <Configuration extends object>(options: {
 // Generated by Blume. Do not edit.
 import { ScalarComponent } from "@scalar/astro";
 import ReferenceLayout from "blume/components/layout/ReferenceLayout.astro";
-import data from ${JSON.stringify(options.dataImport)};
+import data from "blume:data";
 
 export const prerender = true;
 
@@ -2411,6 +2516,74 @@ const suggestions = [
 </PageLayout>
 `;
 
+/**
+ * Generate `.blume/src/pages/404.md.ts`: the Markdown twin of the default 404
+ * page, prerendered to `dist/404.md`. An agent that asked for a missing page
+ * with `Accept: text/markdown` — or fetched a `.md` URL no page backs — gets
+ * this body with the 404 status instead of the HTML shell; Vercel server
+ * builds wire that into the routing config (`deploy/vercel-negotiation.ts`).
+ * Same recovery links as the HTML page, absolute when the site URL is known:
+ * the body is read out of context, so a relative link would leave the reader
+ * guessing the host. Written alongside `404.astro` and skipped under the same
+ * rule, so a project that owns `/404` owns both variants.
+ */
+export const notFoundMarkdownTemplate =
+  (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import { withBase } from "blume/components/islands/base-path.ts";
+import { absoluteUrl } from "blume/core/site-url.ts";
+import data from "blume:data";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+
+// Absolute for internal routes when the site is known; an external tab href
+// passes through untouched.
+const href = (path: string): string => {
+  const based = withBase(path);
+  return data.config.site && based.startsWith("/") && !based.startsWith("//")
+    ? absoluteUrl(data.config.site, based)
+    : based;
+};
+
+// The recovery set of 404.astro: home, every top-level section (a tab links to
+// its resolved target), then the machine-readable indexes that exist.
+const links = [
+  { href: href("/"), label: nf.home },
+  ...data.navigation.tabs.map((tab) => ({
+    href: href(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: href("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: href("/llms.txt"), label: nf.llms }]
+    : []),
+];
+
+const body = [
+  "# " + nf.title,
+  "",
+  nf.description,
+  "",
+  "## " + nf.suggestions,
+  "",
+  ...links.map((link) => "- [" + link.label + "](" + link.href + ")"),
+  "",
+].join("\\n");
+
+export function GET() {
+  return new Response(body, {
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      // ~4 characters per token; keep in sync with markdownTokenCount.
+      "x-markdown-tokens": String(Math.ceil(body.length / 4)),
+    },
+  });
+}
+`;
+
 /** The literal Astro hydration directive for an island's client mode. */
 const islandDirective = (spec: IslandSpec): string =>
   spec.client === "only"
@@ -2692,6 +2865,36 @@ declare module "blume:data" {
   export default data;
 }
 
+declare module "blume:ask-data" {
+  const askData: import("blume/ai/ask-context.ts").AskData;
+  export default askData;
+}
+
+declare module "blume:content-assets" {
+  const assets: Record<string, string>;
+  export default assets;
+}
+
+declare module "blume:mcp-data" {
+  const data: import("blume/ai/mcp/data.ts").McpData;
+  export default data;
+}
+
+declare module "blume:raw-markdown" {
+  const raw: Record<string, import("blume/ai/markdown.ts").RawMarkdownEntry>;
+  export default raw;
+}
+
+declare module "blume:rss" {
+  const feeds: Record<string, string>;
+  export default feeds;
+}
+
+declare module "blume:search-index" {
+  const documents: import("blume/search/documents.ts").SearchDocument[];
+  export default documents;
+}
+
 declare module "blume:examples" {
   type Examples = typeof import("./generated/examples.ts").examples;
   export const examples: Record<string, Examples[keyof Examples]>;

package/src/cli/commands/build.ts

@@ -334,12 +334,18 @@ const emitVercelNegotiation = async (
   // endpoint stamps it on dev/server-rendered responses itself.
   const rawMarkdown = await buildRawMarkdown(project);
   const home = rawMarkdown["/"];
+  // The Markdown 404 routes point at the prerendered `404.md`; only wire them
+  // when the build actually emitted it (a project that owns `/404` gets none).
+  const notFoundMarkdown = existsSync(
+    join(root, ".vercel", "output", "static", "404.md")
+  );
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
     buildHomeLinkHeader(config, routePaths),
     overrides,
-    home ? markdownTokenCount(agentMarkdown(home)) : undefined
+    home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+    notFoundMarkdown
   );
   if (injected === null) {
     logger.warn(

package/src/cli/commands/dev.ts

@@ -19,8 +19,9 @@ import { prepareProject } from "../prepare.ts";
 
 /**
  * Resolve a `--host` flag value into what Astro/Vite's `server.host` expects.
- * citty (0.1) has no mixed string/boolean arg type, so `host` is declared as a
- * string and a bare `--host` parses as `""` — Node would bind all interfaces
+ * citty has no mixed string/boolean arg type, so `host` is declared as a
+ * string and a bare `--host` parses as `""` (the CLI entry rewrites it to
+ * `--host=` first; see `host-args.ts`) — Node would bind all interfaces
  * for `""`, but Vite's `resolveHostname` treats it as a literal hostname and
  * prints malformed URLs like `http://:4321/`. Match Astro's own `--host`
  * semantics instead: bare flag → `true` (bind all interfaces), `--host
@@ -219,7 +220,9 @@ export const devCommand = defineCommand({
     }).on("all", regenerate);
     const disposers = [
       ...project.sources.map((source) => source.watch?.(regenerate)),
-      () => void projectWatcher.close(),
+      () => {
+        void projectWatcher.close();
+      },
     ].filter((dispose) => dispose !== undefined);
 
     const shutdown = async () => {

package/src/cli/host-args.ts

@@ -0,0 +1,18 @@
+/**
+ * Rewrite a bare `--host` in the raw argv to `--host=` before citty parses it.
+ *
+ * `host` is a string arg (citty has no mixed string/boolean type), and citty
+ * 0.2 parses with `node:util.parseArgs`, where a string option consumes the
+ * next token as its value even when that token is another flag: `blume dev
+ * --host --open` would bind the literal hostname "--open" and drop `--open`.
+ * The `--host=` spelling parses as `""` without touching its neighbor, which
+ * `normalizeHost` then maps to Astro's "bind all interfaces".
+ */
+export const normalizeHostArgs = (rawArgs: readonly string[]): string[] =>
+  rawArgs.map((arg, index) => {
+    if (arg !== "--host") {
+      return arg;
+    }
+    const next = rawArgs[index + 1];
+    return next === undefined || next.startsWith("-") ? "--host=" : arg;
+  });

package/src/cli/index.ts

@@ -17,6 +17,7 @@ import { translateCommand } from "./commands/translate.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { versionCommand } from "./commands/version.ts";
 import { loadEnvFiles } from "./env.ts";
+import { normalizeHostArgs } from "./host-args.ts";
 import { reportInternalError } from "./internal-error.ts";
 
 const main = defineCommand({
@@ -60,4 +61,4 @@ process.on("unhandledRejection", (error) => {
   process.exit(1);
 });
 
-runMain(main);
+runMain(main, { rawArgs: normalizeHostArgs(process.argv.slice(2)) });

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);
 };
 
 /**