blume 2.2.1 → 2.2.3

package/src/ai/relative-links.ts

@@ -11,12 +11,15 @@ import { localePrefix } from "../core/i18n.ts";
 import {
   buildFileRouteIndex,
   isIndexFileName,
+  resolveRawRelativeHref,
   resolveRelativeHref,
   resolveRootFileHref,
+  routeOfLinkedEntry,
   routeOfLinkedFile,
 } from "../core/links.ts";
-import type { RelativeLinkBase } from "../core/links.ts";
+import type { FileRouteIndex, RelativeLinkBase } from "../core/links.ts";
 import { localizeHref, servesRoute } from "../core/locale-links.ts";
+import type { LocalizeHrefOptions } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { resolveDocsCollection } from "../core/sources/collection.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
@@ -28,7 +31,9 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * link lands on `/install`; the rendered page rewrites it to the route it
  * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
  * the same rewrite from the same resolver (`resolveRelativeHref`), so both
- * point at one page. Root-relative links (`[x](/guide)`,
+ * point at one page. A raw HTML `<a href>` ships as written, so a relative
+ * one lands where the browser takes it from the page's URL
+ * (`resolveRawRelativeHref`). Root-relative links (`[x](/guide)`,
  * `<Card href="/guide">`, `![logo](/logo.png)`) get what the rendered page
  * gives them too (`markdown/base-links.ts`,
  * `components/content/base-href.ts`): a page link the `deployment.base` +
@@ -40,10 +45,17 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * (`resolveRootFileHref`). Inline links, images, component
  * `href`s, and reference definitions are rewritten; fenced and inline code,
  * relative images and asset links, and external URLs are left as written.
+ * The assistant's snapshot takes the links that name a page by its path or
+ * file alone, as the routes it keys pages by (`assistant`).
  */
 
 /** The page a Markdown text was written for. */
 export interface LinkedPage {
+  /**
+   * A staged page's path under its staging dir, which its links resolve from
+   * when it has no `sourcePath` (a remote or CMS source).
+   */
+  entryId?: string;
   route: string;
   sourcePath?: string;
 }
@@ -51,6 +63,20 @@ export interface LinkedPage {
 /** Rewrite a page's relative page links to the routes they mean. */
 export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
 
+/** Who reads the rewritten links. */
+export interface RelativeLinkOptions {
+  /**
+   * The assistant's snapshot, rather than a page an agent fetches by URL.
+   * Only a link that names a page by its relative path or its content file
+   * changes, to the route the snapshot keys that page by: without the
+   * `deployment.base`, since the chat panel mounts every link it renders
+   * under it, and a locale's fallback copy as the page it renders, since the
+   * snapshot holds that page instead. Root page links and images stay as
+   * written.
+   */
+  assistant?: boolean;
+}
+
 /**
  * Whether a text could hold a relative page link at all: an inline link, a
  * reference definition, or a component `href` whose target isn't a URL with
@@ -123,16 +149,79 @@ const collectSplices = (
   return splices;
 };
 
+/** What a project's links resolve through, whoever reads them. */
+interface LinkIndex {
+  fileRoutes: FileRouteIndex;
+  localeByRoute: Map<string, string>;
+  navPathBySource: Map<string | undefined, string>;
+  routes: Set<string>;
+}
+
+// The mirrors, llms-full.txt and the assistant's snapshot each build a
+// rewriter for the same project, so the lookups behind them are built once.
+const linkIndexes = new WeakMap<BlumeProject, LinkIndex>();
+
+/**
+ * The file → route lookup a `.md`/`.mdx` link resolves through, and the
+ * routes a link can land on. A file shared by every locale publishes once
+ * per locale, and the default locale's route stands for it; fallback copies
+ * render another locale's file, so they never stand for one.
+ */
+const linkIndex = (project: BlumeProject): LinkIndex => {
+  let index = linkIndexes.get(project);
+  if (!index) {
+    const { config, graph, manifest } = project;
+    index = {
+      fileRoutes: buildFileRouteIndex(graph.pages, config.i18n ?? null),
+      localeByRoute: new Map(
+        manifest.routes.map((route) => [route.path, route.locale])
+      ),
+      navPathBySource: new Map(
+        graph.pages.map((page) => [page.sourcePath, page.navPath])
+      ),
+      routes: new Set(manifest.routes.map((route) => route.path)),
+    };
+    linkIndexes.set(project, index);
+  }
+  return index;
+};
+
+/**
+ * A resolved route as the assistant's snapshot keys it. A locale's fallback
+ * copy (`/fr/guides/install` with no French page there) renders another
+ * locale's page, which the snapshot holds in its place, so the route becomes
+ * that page's; every other route is kept, `?query#hash` and all.
+ */
+const snapshotRoute = (project: BlumeProject): ((route: string) => string) => {
+  const pageRoutes = new Map(
+    project.graph.pages.map((page) => [page.id, page.route])
+  );
+  const rendered = new Map<string, string>();
+  for (const route of project.manifest.routes) {
+    const page = route.fallback ? pageRoutes.get(route.id) : undefined;
+    if (page !== undefined) {
+      rendered.set(route.path, page);
+    }
+  }
+  return (route) => {
+    const suffixAt = route.search(/[?#]/u);
+    const path = suffixAt === -1 ? route : route.slice(0, suffixAt);
+    const page = rendered.get(path);
+    return page === undefined ? route : `${page}${route.slice(path.length)}`;
+  };
+};
+
 /**
- * Build the rewriter for a project: the file → route lookup a `.md`/`.mdx`
- * link resolves through is built once. A file shared by every locale
- * publishes once per locale, and the default locale's route stands for it;
- * fallback copies render another locale's file, so they never stand for one.
+ * Build the rewriter for a project, for an agent reading a page by URL or,
+ * with `assistant`, for the assistant's snapshot.
  */
 export const relativeLinkRewriter = (
-  project: BlumeProject
+  project: BlumeProject,
+  options: RelativeLinkOptions = {}
 ): RelativeLinkRewriter => {
   const { basePath, deployment, i18n } = project.config;
+  // Links are read under the real deployment base whoever reads them, so a
+  // root link to a content file that carries it is still recognized.
   const deployBase = normalizeBasePath(deployment.options.base);
   const contentRoot = resolveDocsCollection(
     project.config,
@@ -141,17 +230,38 @@ export const relativeLinkRewriter = (
   const localeTokens = i18n
     ? ["$", ...i18n.locales.map((locale) => locale.code)]
     : [];
-  const fileRoutes = buildFileRouteIndex(project.graph.pages, i18n ?? null);
-  const navPathBySource = new Map(
-    project.graph.pages.map((graphPage) => [
-      graphPage.sourcePath,
-      graphPage.navPath,
-    ])
-  );
-  const routes = new Set(project.manifest.routes.map((route) => route.path));
-  const localeByRoute = new Map(
-    project.manifest.routes.map((route) => [route.path, route.locale])
-  );
+  const { fileRoutes, localeByRoute, navPathBySource, routes } =
+    linkIndex(project);
+  const hasRoute = (path: string): boolean => routes.has(path);
+
+  // Where a resolved route lands for its reader. A route Blume serves takes
+  // the deployment base unconditionally — even over a route that starts with
+  // the base's name — except in the assistant's snapshot.
+  const land = options.assistant
+    ? snapshotRoute(project)
+    : (route: string): string => mountBasePath(deployBase, route);
+
+  /**
+   * How a page's root-relative links change, if they do: when the site is
+   * mounted under a prefix, or the page reads in a prefixed locale, whose
+   * copy of a route they move to. The assistant's snapshot keeps them as
+   * written.
+   */
+  const rootLinksOf = (
+    route: string
+  ): { localize?: LocalizeHrefOptions } | undefined => {
+    if (options.assistant) {
+      return undefined;
+    }
+    const locale = localeByRoute.get(route);
+    const localize =
+      i18n && locale !== undefined && localePrefix(locale, i18n) !== ""
+        ? { basePath, deployBase, i18n, locale, routes }
+        : undefined;
+    return deployBase !== "" || basePath !== "" || localize !== undefined
+      ? { localize }
+      : undefined;
+  };
 
   /**
    * A page's relative-link resolver; `undefined` when the page has no file
@@ -160,43 +270,36 @@ export const relativeLinkRewriter = (
   const relativeRoute = (
     page: LinkedPage
   ): ((target: string) => string | undefined) | undefined => {
-    const { sourcePath } = page;
-    if (!sourcePath) {
+    const { entryId, sourcePath } = page;
+    const file = sourcePath ?? entryId;
+    if (!file) {
       return;
     }
     const from: RelativeLinkBase = {
-      isIndex: isIndexFileName(basename(sourcePath), localeTokens),
+      isIndex: isIndexFileName(basename(file), localeTokens),
       route: page.route,
     };
-    const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
-    const resolveFile = (path: string): string | undefined =>
-      routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
-    // A resolved route is one Blume serves, so the deployment base goes on
-    // unconditionally — even over a route that starts with the base's name.
-    return (target) => {
-      const route = resolveRelativeHref(target, from, resolveFile, (path) =>
-        routes.has(path)
-      );
-      return route === undefined ? undefined : mountBasePath(deployBase, route);
-    };
+    // A staged page (a remote or CMS source) has no file on disk: it
+    // resolves a sibling by its entry id, as `blume validate` does.
+    let resolveFile: (path: string) => string | undefined;
+    if (sourcePath) {
+      const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
+      resolveFile = (path) =>
+        routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
+    } else {
+      resolveFile = (path) => routeOfLinkedEntry(fileRoutes, file, path);
+    }
+    return (target) => resolveRelativeHref(target, from, resolveFile, hasRoute);
   };
 
   /** Whether a page is served at a based, fragment-less path. */
   const servesPage = (route: string): boolean => servesRoute(routes, route);
 
   return (text, page) => {
-    const locale = localeByRoute.get(page.route);
-    // The page's locale moves root links only when it has a URL prefix.
-    const localize =
-      i18n && locale !== undefined && localePrefix(locale, i18n) !== ""
-        ? { basePath, deployBase, i18n, locale, routes }
-        : undefined;
-    // A root-relative link only changes when the site is mounted under a
-    // prefix or the page reads in a prefixed locale.
-    const rootLinks =
-      deployBase !== "" || basePath !== "" || localize !== undefined;
+    const rootLinks = rootLinksOf(page.route);
+    const localize = rootLinks?.localize;
     if (
-      !(page.sourcePath || rootLinks) ||
+      !(page.sourcePath || page.entryId || rootLinks) ||
       !(
         (rootLinks ? MAYBE_PAGE_LINK : MAYBE_RELATIVE).test(text) ||
         MAYBE_ROOT_FILE.test(text)
@@ -230,20 +333,24 @@ export const relativeLinkRewriter = (
       if (route === undefined) {
         return undefined;
       }
-      const based = mountBasePath(deployBase, route);
-      return localize ? localizeHref(based, localize) : based;
+      const landed = land(route);
+      return localize ? localizeHref(landed, localize) : landed;
     };
     const routed = (target: string, raw: boolean): string | undefined => {
       if (!isInternalPath(target)) {
-        return relative?.(target);
+        const route = raw
+          ? resolveRawRelativeHref(target, page.route, hasRoute)
+          : relative?.(target);
+        return route === undefined ? undefined : land(route);
       }
-      return (raw ? undefined : rootFile(target)) ?? rooted(target);
+      const file = raw ? undefined : rootFile(target);
+      return file ?? (rootLinks ? rooted(target) : undefined);
     };
     // An image is always a file: `public/` (or a generated asset endpoint),
     // served under the deployment base but never `basePath`. A relative one
     // is left to `core/content-assets.ts`.
     const imaged = (target: string): string | undefined => {
-      const based = withBasePath(deployBase, target);
+      const based = rootLinks ? withBasePath(deployBase, target) : target;
       return based === target ? undefined : based;
     };
 

package/src/ai/site-skill.ts

@@ -14,6 +14,7 @@ import type { NavNode, PageRecord } from "../core/types.ts";
 import { resolveReferences } from "../openapi/references.ts";
 import { docsPhrase } from "./ai-catalog.ts";
 import { API_PAGES_PATH } from "./api/paths.ts";
+import { linkText } from "./link-text.ts";
 import { asciiSlugify } from "./mcp/discovery.ts";
 import {
   SKILL_DESCRIPTION_MAX,
@@ -54,10 +55,6 @@ export const siteSkillName = (project: BlumeProject): string => {
   return name.slice(0, NAME_MAX).replace(/-+$/u, "");
 };
 
-/** A title as Markdown link text (brackets escaped, as in llms.txt). */
-const linkText = (title: string): string =>
-  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
-
 /**
  * Current-version, default-locale pages worth listing: not API operations,
  * and not changelog entries, which the changelog index covers in one line.

package/src/astro/generate.ts

@@ -88,6 +88,7 @@ import type { Diagnostic, Navigation } from "../core/types.ts";
 import { getBlumeVersion } from "../core/version.ts";
 import { servedFiles } from "../deploy/generated-files.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { hreflangAlternates } from "../deploy/sitemap.ts";
 import {
   languageIconCss,
   languageIconSlugsIn,
@@ -1204,6 +1205,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     i18n?.defaultLocale
   );
 
+  const hreflang = hreflangAlternates(project);
+
   const navigationByLocale = i18n
     ? Object.fromEntries(
         i18n.locales.map(({ code }) => [
@@ -1273,6 +1276,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             }
           : null,
       imageZoom: config.markdown.imageZoom,
+      jsonLd: config.seo.jsonLd,
       logo,
       mcp: config.agents.mcp.enabled
         ? {
@@ -1293,6 +1297,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       og: {
         description: resolveOgDescription(config),
         enabled: config.seo.og.enabled ?? false,
+        image: config.seo.og.image,
         logo: ogLogo,
         palette: config.seo.og.palette,
         site: resolveOgSite(config),
@@ -1353,12 +1358,14 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       entryId: route.entryId,
       fallback: route.fallback ?? false,
       hidden: route.hidden,
+      hreflang: hreflang.get(route.path) ?? [],
       id: route.id,
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
       locale: route.locale,
       monolingual: route.monolingual ?? false,
       path: route.path,
+      published: route.published ?? null,
       title: route.title,
       version: route.version,
       versionAlternates: route.versionAlternates,

package/src/astro/templates.ts

@@ -2512,6 +2512,7 @@ import RootLayout from "blume/components/layout/RootLayout.astro";
 import { withBase, withMountedBase } from "blume/components/islands/base-path.ts";
 import { mountBasePath, stripBasePath } from "blume/core/base-path.ts";
 import { routeSetFor, servesRoute } from "blume/core/locale-links.ts";
+import { resolveLocalizable } from "blume/core/localizable.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${componentImports}
 import data from "blume:data";
@@ -2536,8 +2537,10 @@ export function getStaticPaths() {
       editUrl: route.editUrl,
       entryId: route.entryId,
       fallback: route.fallback,
+      hreflang: route.hreflang,
       indexable: route.indexable,
       lastModified: route.lastModified,
+      published: route.published,
       locale: route.locale,
       monolingual: route.monolingual,
       route: route.path,
@@ -2548,7 +2551,7 @@ export function getStaticPaths() {
   }));
 }
 
-const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, monolingual, version, versionAlternates } = Astro.props;
+const { entryId, collection, route, title, indexable, editUrl, lastModified, published, locale, alternates, hreflang, fallback, monolingual, version, versionAlternates } = Astro.props;
 const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
@@ -2598,19 +2601,23 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const ogPath = data.config.og.enabled
   ? encodeURI(\`/og/\${route === "/" ? "index" : route.slice(1)}.png\`)
   : null;
-// Absolute URLs also carry the deployment base (the page is served under it):
-// \`site + base + path\`. Only absolutize root-relative paths: \`seo.image\` may be
+// Root-relative paths carry the deployment base (the page is served under it),
+// and the site too once it's known: \`site + base + path\`. \`seo.image\` may be
 // an external URL, which passes through verbatim (mirrors PageLayout). An
-// authored \`seo.image\` keeps a base written by hand; the generated card is
-// always mounted under it.
+// authored image keeps a base written by hand; the generated card is always
+// mounted under it.
 const absoluteOg = (path: string, based: (path: string) => string) =>
-  base && path.startsWith("/") ? \`\${base}\${based(path)}\` : path;
-const ogImage = seo.image
-  ? absoluteOg(seo.image, withBase)
+  path.startsWith("/") ? \`\${base ?? ""}\${based(path)}\` : path;
+// The page's own image, else the site's default for its locale.
+const selectedOgImage =
+  seo.image ??
+  (data.config.og.image && resolveLocalizable(data.config.og.image, locale, data.config.i18n?.defaultLocale));
+const ogImage = selectedOgImage
+  ? absoluteOg(selectedOgImage, withBase)
   : ogPath && absoluteOg(ogPath, withMountedBase);
-// Blume's generated card has known dimensions the layout can declare; a user's
-// \`seo.image\` could be any size or format, so it gets none.
-const ogGenerated = !seo.image && Boolean(ogPath);
+// Blume's generated card has known dimensions the layout can declare; an
+// authored image could be any size or format, so it gets none.
+const ogGenerated = !selectedOgImage && Boolean(ogPath);
 
 // X attribution: the site's account, plus a creator the page can claim for
 // itself (a guest post crediting its own author) over the configured default.
@@ -2706,11 +2713,12 @@ const canonical =
       : null);
 const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
 
+// hreflang names only indexable translations (see \`hreflangAlternates\`).
 const localeAlternates =
   i18n && base
-    ? (alternates ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
+    ? (hreflang ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
     : [];
-const defaultAlt = i18n ? (alternates ?? []).find((alt) => alt.locale === i18n.defaultLocale) : null;
+const defaultAlt = i18n ? (hreflang ?? []).find((alt) => alt.locale === i18n.defaultLocale) : null;
 const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 
 // \`route\` arrives with \`basePath\` already applied, so the locale segment it
@@ -2874,7 +2882,8 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   pageType={frontmatter.type}
   apiRail={remarkPluginFrontmatter?.${API_RAIL_KEY} === true}
   pageMode={frontmatter.mode}
-  published={frontmatter.date ?? frontmatter.changelog?.date ?? null}
+  published={frontmatter.date ?? frontmatter.changelog?.date ?? published}
+  authors={frontmatter.authors}
   lastModified={lastModified}
   noindex={effectiveNoindex}
   structuredDataEnabled={data.config.structuredData}
@@ -2922,8 +2931,9 @@ export const changelogIndexTemplate = (options: {
 // Generated by Blume. Do not edit.
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Changelog from "blume/components/content/Changelog.astro";
-import { withMountedBase } from "blume/components/islands/base-path.ts";
+import { withBase, withMountedBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
+import { resolveLocalizable } from "blume/core/localizable.ts";
 import { layoutOverrides } from "../generated/components.ts";
 import data from "blume:data";
 
@@ -2945,11 +2955,17 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const basedRoute = withMountedBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
-// The generated OG card for this route (the /og endpoint emits it alongside
-// the content-route cards), absolutized like the catch-all's so crawlers get
-// a full URL when the site is known.
+// The site's default image, else the generated OG card for this route (the /og
+// endpoint emits it alongside the content-route cards), absolutized like the
+// catch-all's so crawlers get a full URL when the site is known.
+const defaultOgImage =
+  data.config.og.image && resolveLocalizable(data.config.og.image, htmlLang, i18n?.defaultLocale);
 const ogPath = data.config.og.enabled ? withMountedBase("/og/changelog.png") : null;
-const ogImage = ogPath && base ? base + ogPath : ogPath;
+const ogImage = defaultOgImage
+  ? defaultOgImage.startsWith("/")
+    ? (base ?? "") + withBase(defaultOgImage)
+    : defaultOgImage
+  : ogPath && base ? base + ogPath : ogPath;
 
 // The page chrome (h1, title, description) comes from the translatable
 // \`changelog\` group, which carries the \`changelog\` config's title and
@@ -2997,7 +3013,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   searchEnabled={data.config.search.enabled}
   indexable={true}
   ogImage={ogImage}
-  ogGenerated={Boolean(ogImage)}
+  ogGenerated={!defaultOgImage && Boolean(ogImage)}
   x={data.config.x}
   canonical={canonical}
   exportPdf={${options.exportPdf}}

package/src/components/layout/PageActions.astro

@@ -115,11 +115,17 @@ 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).
+// background). Their icons sit in a box one line tall, so a label that wraps
+// keeps them beside its first line.
 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";
+  "flex w-full items-start 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";
+const menuIconClass = "flex h-lh shrink-0 items-center";
+// At most out to the rail's edge, past its padding (`--blume-rail-inset`, set
+// by the layout), less 2px so the border never lands on the edge: the rail
+// scrolls, so it clips anything wider. Longer labels wrap instead. The minimum
+// width gives way to that cap in a narrower rail.
 const panelClass =
-  "absolute top-full right-2 z-50 mt-1 w-max min-w-[14rem] max-w-[22rem] rounded-blume border border-border bg-background p-1 shadow-xl";
+  "absolute top-full end-0 z-50 mt-1 w-max [--blume-menu-room:calc(100%+var(--blume-rail-inset,1rem)-2px)] min-w-[min(14rem,var(--blume-menu-room))] max-w-(--blume-menu-room) wrap-anywhere rounded-blume border border-border bg-background p-1 shadow-xl";
 ---
 
 <div
@@ -172,13 +178,17 @@ const panelClass =
         <div class={panelClass} data-blume-menu>
           {exportPdf && (
             <button class={menuRowClass} data-blume-export-pdf type="button">
-              <Icon name="file" size={16} />
+              <span class={menuIconClass}>
+                <Icon name="file" size={16} />
+              </span>
               <span class="flex-1">{a.exportPdf}</span>
             </button>
           )}
           {exportEpub && (
             <button class={menuRowClass} data-blume-export-epub type="button">
-              <Icon name="book-open" size={16} />
+              <span class={menuIconClass}>
+                <Icon name="book-open" size={16} />
+              </span>
               <span class="flex-1" data-blume-epub-label>
                 {a.exportEpub}
               </span>
@@ -214,9 +224,11 @@ const panelClass =
                 data-open-in={provider.key}
                 {...NEW_TAB_ATTRS}
               >
-                <span set:html={LOGOS[provider.key]} />
+                <span class={menuIconClass} set:html={LOGOS[provider.key]} />
                 <span class="flex-1">{provider.label}</span>
-                <Icon name="external-link" size={13} />
+                <span class={menuIconClass}>
+                  <Icon name="external-link" size={13} />
+                </span>
               </a>
             </>
           ))}
@@ -241,7 +253,9 @@ const panelClass =
         </summary>
         <div class={panelClass} data-blume-menu>
           <button class={menuRowClass} data-mcp-copy-url type="button">
-            <Icon name="link" size={16} />
+            <span class={menuIconClass}>
+              <Icon name="link" size={16} />
+            </span>
             <span class="flex-1" data-mcp-url-label>
               {a.copyServerUrl}
             </span>
@@ -255,7 +269,7 @@ const panelClass =
                   data-mcp-copy-claude
                   type="button"
                 >
-                  <span set:html={LOGOS.claude} />
+                  <span class={menuIconClass} set:html={LOGOS.claude} />
                   <span class="flex-1" data-mcp-claude-label>
                     {a.copyClaudeCode}
                   </span>
@@ -263,7 +277,7 @@ const panelClass =
               )}
               {client === "codex" && (
                 <button class={menuRowClass} data-mcp-copy-codex type="button">
-                  <span set:html={LOGOS.codex} />
+                  <span class={menuIconClass} set:html={LOGOS.codex} />
                   <span class="flex-1" data-mcp-codex-label>
                     {a.copyCodex}
                   </span>
@@ -271,16 +285,22 @@ const panelClass =
               )}
               {client === "cursor" && (
                 <a class={menuRowClass} data-mcp-cursor rel="noreferrer">
-                  <span set:html={LOGOS.cursor} />
+                  <span class={menuIconClass} set:html={LOGOS.cursor} />
                   <span class="flex-1">{a.addToCursor}</span>
-                  <Icon name="external-link" size={13} />
+                  <span class={menuIconClass}>
+                    <Icon name="external-link" size={13} />
+                  </span>
                 </a>
               )}
               {client === "vscode" && (
                 <a class={menuRowClass} data-mcp-vscode rel="noreferrer">
-                  <Icon name="code" size={16} />
+                  <span class={menuIconClass}>
+                    <Icon name="code" size={16} />
+                  </span>
                   <span class="flex-1">{a.addToVscode}</span>
-                  <Icon name="external-link" size={13} />
+                  <span class={menuIconClass}>
+                    <Icon name="external-link" size={13} />
+                  </span>
                 </a>
               )}
               {!isBuiltInMcpClient(client) && (
@@ -289,7 +309,9 @@ const panelClass =
                   data-mcp-copy-command={client.command}
                   type="button"
                 >
-                  <Icon name={client.icon ?? "terminal"} size={16} />
+                  <span class={menuIconClass}>
+                    <Icon name={client.icon ?? "terminal"} size={16} />
+                  </span>
                   <span class="flex-1" data-mcp-command-label>
                     {client.label}
                   </span>
@@ -442,10 +464,15 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
       return;
     }
     const rect = summary.getBoundingClientRect();
+    // The rail scrolls, so it clips the menu at its own edges: its top sits
+    // under the sticky header, below the viewport's.
+    const room = details
+      .closest("[data-blume-toc]")
+      ?.getBoundingClientRect() ?? { bottom: window.innerHeight, top: 0 };
     const margin = 8;
     const flipUp =
-      rect.bottom + menu.offsetHeight + margin > window.innerHeight &&
-      rect.top - menu.offsetHeight - margin > 0;
+      rect.bottom + menu.offsetHeight + margin > room.bottom &&
+      rect.top - menu.offsetHeight - margin > room.top;
     menu.classList.toggle("top-full", !flipUp);
     menu.classList.toggle("mt-1", !flipUp);
     menu.classList.toggle("bottom-full", flipUp);
@@ -513,7 +540,7 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     }
     // The action dropdowns are native <details>. Make them behave like a proper
     // menu: only one open at a time, and flip above the trigger when opening
-    // downward would run past the viewport bottom.
+    // downward would run past the rail's bottom and there's room above.
     const dropdowns = [...root.querySelectorAll<HTMLDetailsElement>("details")];
     for (const details of dropdowns) {
       details.addEventListener("toggle", () => {