blume 0.0.0 → 0.1.0

package/src/components/layout/PageActions.astro

@@ -0,0 +1,438 @@
+---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { GITHUB_MARK } from "../github-mark.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  route: string;
+  editUrl?: string | null;
+  askEnabled?: boolean;
+  /** Show the "Export to PDF" action (native browser print). */
+  exportPdf?: boolean;
+  /** Show the "Export to EPUB" action (client-side, current page). */
+  exportEpub?: boolean;
+  /** Absolute URL of the hosted MCP server, when enabled and a site is set. */
+  mcpUrl?: string | null;
+  /** Display name of the MCP server (defaults to the site title). */
+  mcpName?: string | null;
+  /** Localized action labels. */
+  strings?: UIStrings["actions"];
+}
+
+const {
+  route,
+  editUrl,
+  askEnabled,
+  exportPdf,
+  exportEpub,
+  mcpUrl,
+  mcpName,
+  strings,
+} = Astro.props;
+const a = strings ?? EN_UI.actions;
+const mdPath = route === "/" ? "/index.md" : `${route}.md`;
+
+const GITHUB_LOGO = `<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">${GITHUB_MARK}</svg>`;
+
+/** Brand logos for the "Open in chat" providers (monochrome, currentColor). */
+const LOGOS: Record<string, string> = {
+  chatgpt:
+    '<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M22.2819 9.8211a5.9847 5.9847 0 0 0-.5157-4.9108 6.0462 6.0462 0 0 0-6.5098-2.9A6.0651 6.0651 0 0 0 4.9807 4.1818a5.9847 5.9847 0 0 0-3.9977 2.9 6.0462 6.0462 0 0 0 .7427 7.0966 5.98 5.98 0 0 0 .511 4.9107 6.051 6.051 0 0 0 6.5146 2.9001A5.9847 5.9847 0 0 0 13.2599 24a6.0557 6.0557 0 0 0 5.7718-4.2058 5.9894 5.9894 0 0 0 3.9977-2.9001 6.0557 6.0557 0 0 0-.7475-7.0729zm-9.022 12.6081a4.4755 4.4755 0 0 1-2.8764-1.0408l.1419-.0804 4.7783-2.7582a.7948.7948 0 0 0 .3927-.6813v-6.7369l2.02 1.1686a.071.071 0 0 1 .038.052v5.5826a4.504 4.504 0 0 1-4.4945 4.4944zm-9.6607-4.1254a4.4708 4.4708 0 0 1-.5346-3.0137l.142.0852 4.783 2.7582a.7712.7712 0 0 0 .7806 0l5.8428-3.3685v2.3324a.0804.0804 0 0 1-.0332.0615L9.74 19.9502a4.4992 4.4992 0 0 1-6.1408-1.6464zM2.3408 7.8956a4.485 4.485 0 0 1 2.3655-1.9728V11.6a.7664.7664 0 0 0 .3879.6765l5.8144 3.3543-2.0201 1.1685a.0757.0757 0 0 1-.071 0l-4.8303-2.7865A4.504 4.504 0 0 1 2.3408 7.872zm16.5963 3.8558L13.1038 8.364 15.1192 7.2a.0757.0757 0 0 1 .071 0l4.8303 2.7913a4.4944 4.4944 0 0 1-.6765 8.1042v-5.6772a.79.79 0 0 0-.407-.667zm2.0107-3.0231l-.142-.0852-4.7735-2.7818a.7759.7759 0 0 0-.7854 0L9.409 9.2297V6.8974a.0662.0662 0 0 1 .0284-.0615l4.8303-2.7866a4.4992 4.4992 0 0 1 6.6802 4.66zM8.3065 12.863l-2.02-1.1638a.0804.0804 0 0 1-.038-.0567V6.0742a4.4992 4.4992 0 0 1 7.3757-3.4537l-.142.0805L8.704 5.459a.7948.7948 0 0 0-.3927.6813zm1.0976-2.3654l2.602-1.4998 2.6069 1.4998v2.9994l-2.5974 1.4997-2.6067-1.4997Z"/></svg>',
+  claude:
+    '<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 12 12" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" fill-rule="evenodd" d="M2.3545 7.9775L4.7145 6.654L4.7545 6.539L4.7145 6.475H4.6L4.205 6.451L2.856 6.4145L1.6865 6.366L0.5535 6.305L0.268 6.2445L0 5.892L0.0275 5.716L0.2675 5.5555L0.6105 5.5855L1.3705 5.637L2.5095 5.716L3.3355 5.7645L4.56 5.892H4.7545L4.782 5.8135L4.715 5.7645L4.6635 5.716L3.4845 4.918L2.2085 4.074L1.5405 3.588L1.1785 3.3425L0.9965 3.1115L0.9175 2.6075L1.2455 2.2465L1.686 2.2765L1.7985 2.307L2.245 2.65L3.199 3.388L4.4445 4.3045L4.627 4.4565L4.6995 4.405L4.709 4.3685L4.627 4.2315L3.9495 3.0085L3.2265 1.7635L2.9045 1.2475L2.8195 0.938C2.78711 0.819128 2.76965 0.696687 2.7675 0.5735L3.1415 0.067L3.348 0L3.846 0.067L4.056 0.249L4.366 0.956L4.867 2.0705L5.6445 3.5855L5.8725 4.0345L5.994 4.4505L6.0395 4.578H6.1185V4.505L6.1825 3.652L6.301 2.6045L6.416 1.257L6.456 0.877L6.644 0.422L7.0175 0.176L7.3095 0.316L7.5495 0.6585L7.516 0.8805L7.373 1.806L7.0935 3.2575L6.9115 4.2285H7.0175L7.139 4.1075L7.6315 3.4545L8.4575 2.4225L8.8225 2.0125L9.2475 1.5605L9.521 1.345H10.0375L10.4175 1.9095L10.2475 2.4925L9.7155 3.166L9.275 3.737L8.643 4.587L8.248 5.267L8.2845 5.322L8.3785 5.312L9.8065 5.009L10.578 4.869L11.4985 4.7115L11.915 4.9055L11.9605 5.103L11.7965 5.5065L10.812 5.7495L9.6575 5.9805L7.938 6.387L7.917 6.402L7.9415 6.4325L8.716 6.5055L9.047 6.5235H9.858L11.368 6.636L11.763 6.897L12 7.216L11.9605 7.4585L11.353 7.7685L10.533 7.574L8.6185 7.119L7.9625 6.9545H7.8715V7.0095L8.418 7.5435L9.421 8.4485L10.6755 9.6135L10.739 9.9025L10.578 10.13L10.408 10.1055L9.3055 9.277L8.88 8.9035L7.917 8.0935H7.853V8.1785L8.075 8.503L9.2475 10.2635L9.3085 10.8035L9.2235 10.98L8.9195 11.0865L8.5855 11.0255L7.8985 10.063L7.191 8.9795L6.6195 8.008L6.5495 8.048L6.2125 11.675L6.0545 11.86L5.69 12L5.3865 11.7695L5.2255 11.396L5.3865 10.658L5.581 9.696L5.7385 8.931L5.8815 7.981L5.9665 7.665L5.9605 7.644L5.8905 7.653L5.1735 8.6365L4.0835 10.109L3.2205 11.0315L3.0135 11.1135L2.655 10.9285L2.6885 10.5975L2.889 10.303L4.083 8.785L4.803 7.844L5.268 7.301L5.265 7.222H5.2375L2.066 9.28L1.501 9.353L1.2575 9.125L1.288 8.752L1.4035 8.6305L2.3575 7.9745L2.3545 7.9775Z"/></svg>',
+  cursor:
+    '<svg class="size-4 shrink-0" viewBox="0 0 466.73 532.09" xmlns="http://www.w3.org/2000/svg"><path d="M457.43,125.94L244.42,2.96c-6.84-3.95-15.28-3.95-22.12,0L9.3,125.94c-5.75,3.32-9.3,9.46-9.3,16.11v247.99c0,6.65,3.55,12.79,9.3,16.11l213.01,122.98c6.84,3.95,15.28,3.95,22.12,0l213.01-122.98c5.75-3.32,9.3-9.46,9.3-16.11v-247.99c0-6.65-3.55-12.79-9.3-16.11h-.01ZM444.05,151.99l-205.63,356.16c-1.39,2.4-5.06,1.42-5.06-1.36v-233.21c0-4.66-2.49-8.97-6.53-11.31L24.87,145.67c-2.4-1.39-1.42-5.06,1.36-5.06h411.26c5.84,0,9.49,6.33,6.57,11.39h-.01Z" fill="currentColor"/></svg>',
+  scira:
+    '<svg class="size-4 shrink-0" fill="none" viewBox="0 0 910 934" xmlns="http://www.w3.org/2000/svg"><path d="M647.664 197.775C569.13 189.049 525.5 145.419 516.774 66.8849C508.048 145.419 464.418 189.049 385.884 197.775C464.418 206.501 508.048 250.131 516.774 328.665C525.5 250.131 569.13 206.501 647.664 197.775Z" fill="currentColor" stroke="currentColor" stroke-linejoin="round" stroke-width="8"/><path d="M857.5 508.116C763.259 497.644 710.903 445.288 700.432 351.047C689.961 445.288 637.605 497.644 543.364 508.116C637.605 518.587 689.961 570.943 700.432 665.184C710.903 570.943 763.259 518.587 857.5 508.116Z" stroke="currentColor" stroke-linejoin="round" stroke-width="20"/><path d="M889.949 121.237C831.049 114.692 798.326 81.9698 791.782 23.0692C785.237 81.9698 752.515 114.692 693.614 121.237C752.515 127.781 785.237 160.504 791.782 219.404C798.326 160.504 831.049 127.781 889.949 121.237Z" fill="currentColor" stroke="currentColor" stroke-linejoin="round" stroke-width="8"/><path d="M760.632 764.337C720.719 814.616 669.835 855.1 611.872 882.692C553.91 910.285 490.404 924.255 426.213 923.533C362.022 922.812 298.846 907.419 241.518 878.531C184.19 849.643 134.228 808.026 95.4548 756.863C56.6815 705.7 30.1238 646.346 17.8129 583.343C5.50207 520.339 7.76433 455.354 24.4266 393.359C41.089 331.364 71.7099 274.001 113.947 225.658C156.184 177.315 208.919 139.273 268.117 114.442" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="30"/></svg>',
+  t3: '<svg class="size-4 shrink-0" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z"/></svg>',
+  v0: '<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 147 70" xmlns="http://www.w3.org/2000/svg"><path d="M56 50.2031V14H70V60.1562C70 65.5928 65.5928 70 60.1562 70C57.5605 70 54.9982 68.9992 53.1562 67.1573L0 14H19.7969L56 50.2031Z"/><path d="M147 56H133V23.9531L100.953 56H133V70H96.6875C85.8144 70 77 61.1856 77 50.3125V14H91V46.1562L123.156 14H91V0H127.312C138.186 0 147 8.81439 147 19.6875V56Z"/></svg>',
+};
+
+const PROVIDERS = [
+  { key: "v0", label: "Open in v0" },
+  { key: "chatgpt", label: "Open in ChatGPT" },
+  { key: "claude", label: "Open in Claude" },
+  { key: "t3", label: "Open in T3 Chat" },
+  { key: "scira", label: "Open in Scira" },
+  { key: "cursor", label: "Open in Cursor" },
+];
+
+// Top-level actions match the ToC links: flat, no background/padding, color
+// shift on hover only.
+const rowClass =
+  "flex w-full items-center gap-2.5 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:text-foreground";
+
+// Items inside the floating popovers keep menu affordances (padding + hover
+// background).
+const menuRowClass =
+  "flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground";
+---
+
+<div
+  class="mt-8 space-y-0.5 border-border border-t pt-4"
+  data-blume-page-actions
+  data-i18n-copied={a.copied}
+  data-mcp-name={mcpName ?? undefined}
+  data-mcp-url={mcpUrl ?? undefined}
+  data-md={mdPath}
+>
+  {
+    editUrl && (
+      <a class={rowClass} href={editUrl} rel="noreferrer" target="_blank">
+        <span set:html={GITHUB_LOGO} />
+        {a.edit}
+      </a>
+    )
+  }
+
+  <button class={rowClass} data-blume-scroll-top type="button">
+    <Icon name="arrow-up" size={16} />
+    {a.scrollToTop}
+  </button>
+
+  <button class={rowClass} data-blume-copy-page type="button">
+    <Icon name="copy" size={16} />
+    <span data-blume-copy-label>{a.copyMarkdown}</span>
+  </button>
+
+  {
+    (exportPdf || exportEpub) && (
+      <details class="group relative">
+        <summary
+          class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
+        >
+          <Icon name="download" size={16} />
+          Export
+          <Icon
+            class="ms-auto transition-transform group-open:rotate-180"
+            name="chevron-down"
+            size={14}
+          />
+        </summary>
+        <div class="absolute right-0 left-0 z-50 mt-1 rounded-blume border border-border bg-background p-1 shadow-xl">
+          {exportPdf && (
+            <button class={menuRowClass} data-blume-export-pdf type="button">
+              <Icon name="file" size={16} />
+              <span class="flex-1">Export to PDF</span>
+            </button>
+          )}
+          {exportEpub && (
+            <button class={menuRowClass} data-blume-export-epub type="button">
+              <Icon name="book-open" size={16} />
+              <span class="flex-1" data-blume-epub-label>
+                Export to EPUB
+              </span>
+            </button>
+          )}
+        </div>
+      </details>
+    )
+  }
+
+  {
+    askEnabled && (
+      <button class={rowClass} data-blume-ask-ai type="button">
+        <Icon name="message-circle" size={16} />
+        {a.askAI}
+      </button>
+    )
+  }
+
+  <details class="group relative">
+    <summary
+      class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
+    >
+      <Icon name="external-link" size={16} />
+      {a.openInChat}
+      <Icon
+        class="ms-auto transition-transform group-open:rotate-180"
+        name="chevron-down"
+        size={14}
+      />
+    </summary>
+    <div class="absolute right-0 left-0 z-50 mt-1 rounded-blume border border-border bg-background p-1 shadow-xl">
+      {
+        PROVIDERS.map((provider, index) => (
+          <>
+            {index === 1 && <hr class="my-1 border-border border-t" />}
+            <a
+              class={menuRowClass}
+              data-open-in={provider.key}
+              rel="noreferrer"
+              target="_blank"
+            >
+              <span set:html={LOGOS[provider.key]} />
+              <span class="flex-1">{provider.label}</span>
+              <Icon name="external-link" size={13} />
+            </a>
+          </>
+        ))
+      }
+    </div>
+  </details>
+
+  {
+    mcpUrl && (
+      <details class="group relative">
+        <summary
+          class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
+        >
+          <Icon name="plug" size={16} />
+          {a.connectMcp}
+          <Icon
+            class="ms-auto transition-transform group-open:rotate-180"
+            name="chevron-down"
+            size={14}
+          />
+        </summary>
+        <div class="absolute right-0 left-0 z-50 mt-1 rounded-blume border border-border bg-background p-1 shadow-xl">
+          <button class={menuRowClass} data-mcp-copy-url type="button">
+            <Icon name="link" size={16} />
+            <span class="flex-1" data-mcp-url-label>
+              {a.copyServerUrl}
+            </span>
+          </button>
+          <button class={menuRowClass} data-mcp-copy-claude type="button">
+            <span set:html={LOGOS.claude} />
+            <span class="flex-1" data-mcp-claude-label>
+              {a.copyClaudeCode}
+            </span>
+          </button>
+          <hr class="my-1 border-border border-t" />
+          <a class={menuRowClass} data-mcp-cursor rel="noreferrer">
+            <span set:html={LOGOS.cursor} />
+            <span class="flex-1">{a.addToCursor}</span>
+            <Icon name="external-link" size={13} />
+          </a>
+          <a class={menuRowClass} data-mcp-vscode rel="noreferrer">
+            <Icon name="code" size={16} />
+            <span class="flex-1">{a.addToVscode}</span>
+            <Icon name="external-link" size={13} />
+          </a>
+        </div>
+      </details>
+    )
+  }
+</div>
+
+<script>
+  const CHAT_URLS: Record<string, (q: string) => string> = {
+    chatgpt: (q) => `https://chatgpt.com/?hints=search&prompt=${q}`,
+    claude: (q) => `https://claude.ai/new?q=${q}`,
+    cursor: (q) => `https://cursor.com/link/prompt?text=${q}`,
+    scira: (q) => `https://scira.ai/?q=${q}`,
+    t3: (q) => `https://t3.chat/new?q=${q}`,
+    v0: (q) => `https://v0.app?q=${q}`,
+  };
+
+  // Self-contained e-reader stylesheet for the EPUB. None of Blume's theme CSS
+  // ships inside the .epub, so the chapter HTML must stand on its own.
+  const EPUB_STYLES = `
+body { line-height: 1.6; }
+h1, h2, h3, h4, h5, h6 { line-height: 1.25; margin: 1.4em 0 0.6em; }
+h1 { font-size: 1.8em; } h2 { font-size: 1.4em; } h3 { font-size: 1.15em; }
+p, ul, ol { margin: 0.8em 0; }
+a { color: #0b63c4; }
+img { max-width: 100%; height: auto; }
+pre {
+  background: #f4f4f5; padding: 0.85em 1em; border-radius: 6px;
+  overflow-x: auto; white-space: pre-wrap; word-wrap: break-word;
+  font-size: 0.85em; line-height: 1.45;
+}
+pre, code { font-family: "SF Mono", Menlo, Consolas, monospace; }
+:not(pre) > code {
+  background: #f0f0f1; padding: 0.1em 0.3em; border-radius: 3px; font-size: 0.9em;
+}
+blockquote { margin: 1em 0; padding-left: 1em; border-left: 3px solid #ddd; color: #555; }
+table { border-collapse: collapse; width: 100%; }
+th, td { border: 1px solid #ddd; padding: 0.4em 0.6em; text-align: left; }
+hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
+
+  // Turn the live, JS/CSS-dependent article DOM into clean, self-contained HTML
+  // for the EPUB: drop decorative SVGs and interactive controls (which render as
+  // broken boxes in a reader), flatten Shiki's variable-colored code to plain
+  // monospace text, and reveal panels the tab scripts would otherwise hide.
+  const buildEpubChapterHtml = (article: Element): string => {
+    const clone = article.cloneNode(true) as Element;
+    for (const el of clone.querySelectorAll(
+      "svg, button, select, script, style, link, noscript, template"
+    )) {
+      el.remove();
+    }
+    for (const pre of clone.querySelectorAll("pre")) {
+      const code = document.createElement("code");
+      code.textContent = pre.textContent ?? "";
+      pre.replaceChildren(code);
+      pre.removeAttribute("style");
+      pre.removeAttribute("class");
+      pre.removeAttribute("tabindex");
+    }
+    for (const el of clone.querySelectorAll(".hidden")) {
+      el.classList.remove("hidden");
+    }
+    return clone.innerHTML;
+  };
+
+  const root = document.querySelector("[data-blume-page-actions]");
+  if (root) {
+    const md = root.getAttribute("data-md") ?? "";
+    const copiedLabel = root.getAttribute("data-i18n-copied") || "Copied!";
+    const absolute = new URL(md, location.origin).href;
+    const query = encodeURIComponent(
+      `Read ${absolute} so I can ask you questions about this page.`
+    );
+
+    for (const link of root.querySelectorAll("[data-open-in]")) {
+      const build = CHAT_URLS[link.getAttribute("data-open-in") ?? ""];
+      if (build) {
+        link.setAttribute("href", build(query));
+      }
+    }
+
+    root
+      .querySelector("[data-blume-scroll-top]")
+      ?.addEventListener("click", () =>
+        window.scrollTo({ behavior: "smooth", top: 0 })
+      );
+
+    root
+      .querySelector("[data-blume-ask-ai]")
+      ?.addEventListener("click", () =>
+        window.dispatchEvent(new CustomEvent("blume:open-ask-ai"))
+      );
+
+    const mcpUrl = root.getAttribute("data-mcp-url");
+    if (mcpUrl) {
+      const rawName = root.getAttribute("data-mcp-name") || "docs";
+      const id =
+        rawName
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/gu, "-")
+          .replace(/^-+|-+$/gu, "") || "docs";
+
+      const cursorConfig = btoa(JSON.stringify({ url: mcpUrl }));
+      root
+        .querySelector("[data-mcp-cursor]")
+        ?.setAttribute(
+          "href",
+          `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(id)}&config=${cursorConfig}`
+        );
+      root
+        .querySelector("[data-mcp-vscode]")
+        ?.setAttribute(
+          "href",
+          `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: id, type: "http", url: mcpUrl }))}`
+        );
+
+      const flash = (el: Element | null, text: string, reset: string) => {
+        if (el) {
+          el.textContent = text;
+          setTimeout(() => {
+            el.textContent = reset;
+          }, 1500);
+        }
+      };
+      const copy = async (value: string, el: Element | null) => {
+        // Restore the element's own label, so localized text round-trips.
+        const reset = el?.textContent ?? "";
+        try {
+          await navigator.clipboard.writeText(value);
+          flash(el, copiedLabel, reset);
+        } catch {
+          // Clipboard unavailable; nothing to do.
+        }
+      };
+      root
+        .querySelector("[data-mcp-copy-url]")
+        ?.addEventListener("click", () =>
+          copy(mcpUrl, root.querySelector("[data-mcp-url-label]"))
+        );
+      root
+        .querySelector("[data-mcp-copy-claude]")
+        ?.addEventListener("click", () =>
+          copy(
+            `claude mcp add --transport http ${id} ${mcpUrl}`,
+            root.querySelector("[data-mcp-claude-label]")
+          )
+        );
+    }
+
+    const label = root.querySelector("[data-blume-copy-label]");
+    root
+      .querySelector("[data-blume-copy-page]")
+      ?.addEventListener("click", async () => {
+        const original = label?.textContent ?? "";
+        try {
+          const response = await fetch(md);
+          await navigator.clipboard.writeText(await response.text());
+          if (label) {
+            label.textContent = copiedLabel;
+            setTimeout(() => {
+              label.textContent = original;
+            }, 1500);
+          }
+        } catch {
+          // Clipboard or fetch unavailable; nothing to do.
+        }
+      });
+
+    root
+      .querySelector("[data-blume-export-pdf]")
+      ?.addEventListener("click", () => window.print());
+
+    const epubButton = root.querySelector("[data-blume-export-epub]");
+    const epubLabel = root.querySelector("[data-blume-epub-label]");
+    epubButton?.addEventListener("click", async () => {
+      const article = document.querySelector("#blume-content article");
+      if (!article) {
+        return;
+      }
+      const heading = document.querySelector("#blume-content h1");
+      const title = heading?.textContent?.trim() || document.title;
+      const reset = epubLabel?.textContent ?? "Export to EPUB";
+      if (epubLabel) {
+        epubLabel.textContent = "Generating…";
+      }
+      try {
+        // Browser bundle: avoids Node built-ins and returns a Blob. Lazy-loaded
+        // so it never ships in the main bundle. The browserified UMD nests its
+        // callable under `.default`, which Vite's dev (esbuild) and build
+        // (rollup) interops expose at slightly different depths — unwrap both.
+        const epubModule = await import("epub-gen-memory/bundle");
+        const epub = epubModule.default?.default ?? epubModule.default;
+        // The article HTML already opens with the page's <h1>, so don't let the
+        // generator prepend a second chapter-title heading.
+        const result = await epub(
+          { css: EPUB_STYLES, prependChapterTitles: false, title },
+          [{ content: buildEpubChapterHtml(article), title }]
+        );
+        const blob =
+          result instanceof Blob
+            ? result
+            : new Blob([result], { type: "application/epub+zip" });
+        const slug =
+          md
+            .replace(/\.md$/u, "")
+            .replace(/^\//u, "")
+            .replace(/\//gu, "-") || "index";
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement("a");
+        link.download = `${slug}.epub`;
+        link.href = url;
+        document.body.append(link);
+        link.click();
+        link.remove();
+        // Revoke later: revoking synchronously after click can cancel the
+        // download before the browser has finished reading the blob.
+        setTimeout(() => URL.revokeObjectURL(url), 10_000);
+      } catch (error) {
+        console.error("[blume] EPUB export failed", error);
+      } finally {
+        if (epubLabel) {
+          epubLabel.textContent = reset;
+        }
+      }
+    });
+  }
+</script>

package/src/components/layout/PageFeedback.astro

@@ -0,0 +1,58 @@
+---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  /** Localized feedback labels. */
+  strings?: UIStrings["feedback"];
+}
+
+const { strings } = Astro.props;
+const f = strings ?? EN_UI.feedback;
+
+const buttonClass =
+  "inline-flex items-center gap-2 rounded-full border border-border px-4 py-2 text-foreground text-sm transition-colors hover:border-foreground";
+---
+
+<section
+  aria-label={f.question}
+  class="mx-auto mt-12 flex max-w-[42rem] items-center justify-between gap-4 border-border border-t pt-6"
+  data-blume-page-feedback
+>
+  <p class="text-muted-foreground text-sm">{f.question}</p>
+  <div class="flex items-center gap-2" data-feedback-actions>
+    <button class={buttonClass} data-feedback-value="yes" type="button">
+      <Icon name="thumbs-up" size={16} />
+      {f.yes}
+    </button>
+    <button class={buttonClass} data-feedback-value="no" type="button">
+      <Icon name="thumbs-down" size={16} />
+      {f.no}
+    </button>
+  </div>
+  <p class="hidden text-muted-foreground text-sm" data-feedback-thanks>
+    {f.thanks}
+  </p>
+</section>
+
+<script>
+  import { track } from "./analytics-client.ts";
+
+  const root = document.querySelector("[data-blume-page-feedback]");
+  if (root) {
+    const actions = root.querySelector("[data-feedback-actions]");
+    const thanks = root.querySelector("[data-feedback-thanks]");
+    for (const button of root.querySelectorAll("[data-feedback-value]")) {
+      button.addEventListener("click", () => {
+        track("feedback", {
+          helpful: button.getAttribute("data-feedback-value") ?? "",
+          path: location.pathname,
+          title: document.title,
+        });
+        actions?.classList.add("hidden");
+        thanks?.classList.remove("hidden");
+      });
+    }
+  }
+</script>

package/src/components/layout/Pagination.astro

@@ -0,0 +1,56 @@
+---
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import type { FlatPage } from "./nav-utils.ts";
+import Icon from "../Icon.astro";
+
+interface Props {
+  /** Previous page in reading order, or `null` at the start. */
+  prev: FlatPage | null;
+  /** Next page in reading order, or `null` at the end. */
+  next: FlatPage | null;
+  /** Localized page-level strings (`previous`, `next`). */
+  strings: UIStrings["page"];
+}
+
+const { prev, next, strings } = Astro.props;
+---
+
+{
+  (prev || next) && (
+    <nav
+      aria-label="Pagination"
+      class="mx-auto mt-12 flex max-w-[42rem] justify-between gap-4 border-border border-t pt-6 max-md:flex-col"
+    >
+      {prev ? (
+        <a
+          class="flex max-w-[48%] flex-1 items-center gap-2 rounded-full border border-border px-4 py-3 text-foreground transition-colors hover:border-foreground max-md:max-w-full"
+          href={prev.route}
+        >
+          <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
+          <span>
+            <span class="block text-muted-foreground text-xs">
+              {strings.previous}
+            </span>
+            <span class="block font-medium">{prev.label}</span>
+          </span>
+        </a>
+      ) : (
+        <span />
+      )}
+      {next && (
+        <a
+          class="ms-auto flex max-w-[48%] flex-1 items-center justify-end gap-2 rounded-full border border-border px-4 py-3 text-end text-foreground transition-colors hover:border-foreground max-md:max-w-full"
+          href={next.route}
+        >
+          <span>
+            <span class="block text-muted-foreground text-xs">
+              {strings.next}
+            </span>
+            <span class="block font-medium">{next.label}</span>
+          </span>
+          <Icon class="rtl:-scale-x-100" name="arrow-right" size={16} />
+        </a>
+      )}
+    </nav>
+  )
+}

package/src/components/layout/ReferenceLayout.astro

@@ -0,0 +1,102 @@
+---
+import "blume:theme";
+import type { Navigation } from "../../core/types.ts";
+import Analytics from "./Analytics.astro";
+import Banner from "./Banner.astro";
+import Favicon from "./Favicon.astro";
+import Fonts from "./Fonts.astro";
+import Header from "./Header.astro";
+
+// A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
+// on top, then a full-height region the reference mounts into. Unlike RootLayout
+// it has no docs sidebar/TOC/prose column, so the reference renders edge to edge.
+interface Props {
+  site: { title: string; description?: string };
+  logo?: {
+    svg?: string;
+    light?: string;
+    dark?: string;
+    alt: string;
+    href: string;
+  } | null;
+  favicon?: {
+    href: string;
+    type?: string;
+  } | null;
+  banner?: {
+    content: string;
+    link?: { text: string; href: string };
+    dismissible: boolean;
+    key: string;
+  } | null;
+  analytics?: {
+    posthog?: { host?: string; key: string };
+    scripts?: {
+      attributes?: Record<string, string>;
+      content?: string;
+      src?: string;
+      strategy?: "async" | "defer";
+    }[];
+    vercel?: boolean;
+  } | null;
+  navigation: Navigation;
+  route: string;
+  themeMode: "system" | "light" | "dark";
+  fontCssVars?: string[];
+  searchEnabled: boolean;
+  pageTitle: string;
+}
+
+const {
+  site,
+  logo,
+  favicon,
+  banner,
+  analytics,
+  navigation,
+  route,
+  themeMode,
+  fontCssVars,
+  searchEnabled,
+  pageTitle,
+} = Astro.props;
+
+// Set the theme before paint so the navbar never flashes the wrong colors
+// (mirrors RootLayout's pre-paint script).
+const initialThemeScript = `(()=>{const m=${JSON.stringify(themeMode)};const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
+
+// Pre-paint: hide a previously-dismissed banner before it flashes in.
+const bannerScript = banner?.dismissible
+  ? `(()=>{if(localStorage.getItem("blume-banner:"+${JSON.stringify(banner.key)}))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`
+  : null;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{pageTitle}</title>
+    <Favicon favicon={favicon} />
+    <Fonts cssVars={fontCssVars ?? []} />
+    {bannerScript && <script is:inline set:html={bannerScript} />}
+    <script is:inline set:html={initialThemeScript} />
+    <Analytics analytics={analytics} />
+  </head>
+  <body class="bg-background font-sans text-foreground antialiased">
+    <Banner banner={banner} />
+    <Header
+      hasSidebar={false}
+      logo={logo}
+      navigation={navigation}
+      route={route}
+      searchEnabled={searchEnabled}
+      site={site}
+    />
+    <div
+      class="h-[calc(100dvh-4rem)] overflow-auto border-border border-t [&>[data-scalar-client]]:h-full"
+    >
+      <slot />
+    </div>
+  </body>
+</html>