blume 1.0.3 → 1.0.4

package/src/components/layout/Pagination.astro

@@ -30,15 +30,15 @@ const s = { ...EN_UI.page, ...strings };
     >
       {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"
+          class="flex max-w-[48%] flex-1 items-center gap-2 rounded-blume border border-border px-4 py-3 text-foreground transition-colors hover:border-foreground max-md:max-w-full"
           href={withBase(prev.route)}
         >
           <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
-          <span>
+          <span class="min-w-0">
             <span class="block text-muted-foreground text-xs max-md:hidden">
               {s.previous}
             </span>
-            <span class="block font-medium">{prev.label}</span>
+            <span class="block truncate font-medium">{prev.label}</span>
           </span>
         </a>
       ) : (
@@ -46,14 +46,14 @@ const s = { ...EN_UI.page, ...strings };
       )}
       {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"
+          class="ms-auto flex max-w-[48%] flex-1 items-center justify-end gap-2 rounded-blume border border-border px-4 py-3 text-end text-foreground transition-colors hover:border-foreground max-md:max-w-full"
           href={withBase(next.route)}
         >
-          <span>
+          <span class="min-w-0">
             <span class="block text-muted-foreground text-xs max-md:hidden">
               {s.next}
             </span>
-            <span class="block font-medium">{next.label}</span>
+            <span class="block truncate font-medium">{next.label}</span>
           </span>
           <Icon class="rtl:-scale-x-100" name="arrow-right" size={16} />
         </a>

package/src/components/layout/RootLayout.astro

@@ -27,10 +27,10 @@ import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
+  activeTabForRoute,
   findBreadcrumbs,
   flattenPages,
   getPagination,
-  isUnderPath,
   sidebarForRoute,
 } from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
@@ -307,6 +307,7 @@ const mcpUrl =
 // active tab's section, so a multi-section site drills each tab into its own
 // pages. Without tabs — or on a route under none — this is the full sidebar.
 const sidebar = sidebarForRoute(navigation.sidebar, navigation.tabs, page.route);
+const activeTab = activeTabForRoute(navigation.tabs, page.route);
 const crumbs = findBreadcrumbs(sidebar, page.route);
 const { prev, next } = getPagination(flattenPages(sidebar), page.route);
 
@@ -526,14 +527,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
                 {navigation.tabs.map((tab) => (
                   <li>
                     <a
-                      aria-current={
-                        page.route === tab.path ||
-                        (tab.path !== "/" && isUnderPath(page.route, tab.path))
-                          ? "page"
-                          : undefined
-                      }
+                      aria-current={tab === activeTab ? "page" : undefined}
                       class="block rounded-[0.65rem] px-2.5 py-1.5 font-medium text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground aria-[current=page]:bg-muted aria-[current=page]:text-foreground"
-                      href={withBase(tab.path)}
+                      href={withBase(tab.href ?? tab.path)}
                     >
                       {tab.label}
                     </a>

package/src/components/layout/Search.astro

@@ -58,7 +58,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
   <dialog
     aria-label={s.label}
-    class="m-auto h-[min(480px,90vh)] w-[min(62.5rem,94vw)] flex-col overflow-hidden rounded-blume border border-border bg-background/80 p-0 text-foreground shadow-2xl outline-none backdrop-blur-xl backdrop:bg-black/30 open:flex"
+    class="mx-auto mt-[8vh] mb-auto h-[min(480px,90dvh)] w-[min(62.5rem,94vw)] flex-col overflow-hidden rounded-blume border border-border bg-background/80 p-0 text-foreground shadow-2xl outline-none backdrop-blur-xl backdrop:bg-black/30 open:flex sm:mt-auto"
     data-blume-search-dialog
   >
     <div

package/src/components/layout/nav-utils.ts

@@ -80,14 +80,16 @@ export const isUnderPath = (route: string, base: string): boolean =>
   base === "/" || route === base || route.startsWith(`${base}/`);
 
 /**
- * The tab whose `path` is the longest prefix of `route`, mirroring the header's
- * active-tab highlight. The root tab (`/`) is skipped — it spans everything and
- * so never scopes the sidebar.
+ * The tab whose `path` is the longest prefix of `route`. The root tab (`/`)
+ * acts as the fallback when no more specific tab matches.
  */
-const activeTab = (tabs: NavTab[], route: string): NavTab | null => {
+export const activeTabForRoute = (
+  tabs: NavTab[],
+  route: string
+): NavTab | null => {
   let match: NavTab | null = null;
   for (const tab of tabs) {
-    if (tab.path === "/" || !isUnderPath(route, tab.path)) {
+    if (!isUnderPath(route, tab.path)) {
       continue;
     }
     if (!match || tab.path.length > match.path.length) {
@@ -187,8 +189,8 @@ export const sidebarForRoute = (
   tabs: NavTab[],
   route: string
 ): NavNode[] => {
-  const tab = activeTab(tabs, route);
-  if (tab) {
+  const tab = activeTabForRoute(tabs, route);
+  if (tab && tab.path !== "/") {
     return sectionChildren(sidebar, tab.path) ?? [];
   }
   const scoped = withoutTabSections(sidebar, tabs);

package/src/core/config-input.ts

@@ -711,6 +711,34 @@ export interface RssConfig {
   types?: string[];
 }
 
+/** Colors used by generated Open Graph cards. Values must be hex colors. */
+export interface OgPaletteConfig {
+  /** Fallback mark color. Defaults to the light theme accent. */
+  accent?: string;
+  /** Card background. */
+  background?: string;
+  /** Footer divider. */
+  border?: string;
+  /** Headline and `currentColor` logo color. */
+  foreground?: string;
+  /** Description and footer text. */
+  muted?: string;
+}
+
+/** Per-page Open Graph image generation. */
+export interface OgConfig {
+  /**
+   * Generate an OG image per page. Defaults to on once a deployment `site`
+   * URL is known and off otherwise (`og:image` must be absolute). An explicit
+   * value always wins.
+   */
+  enabled?: boolean;
+  /** Local SVG used in the generated card instead of the site logo. */
+  logo?: string;
+  /** Optional generated-card colors. */
+  palette?: OgPaletteConfig;
+}
+
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
   /**
@@ -721,14 +749,7 @@ export interface SeoConfig {
   /** robots.txt `Content-Signal` usage declaration. Defaults to `true`. */
   contentSignals?: ContentSignalsConfig;
   /** Per-page Open Graph image generation. */
-  og?: {
-    /**
-     * Generate an OG image per page. Defaults to on once a deployment `site`
-     * URL is known and off otherwise (`og:image` must be absolute). An explicit
-     * value always wins.
-     */
-    enabled?: boolean;
-  };
+  og?: OgConfig;
   /** Generate robots.txt (with a Sitemap reference when available). Defaults to `true`. */
   robots?: boolean;
   /** RSS/Atom feeds. */

package/src/core/data.ts

@@ -15,6 +15,10 @@ export interface BlumeLogo {
   svg?: string;
   light?: string;
   dark?: string;
+  dimensions?: {
+    dark?: { height: number; width: number };
+    light?: { height: number; width: number };
+  };
   alt: string;
   href: string;
   /** Wordmark text beside the mark; `undefined` falls back to the site title. */
@@ -109,7 +113,11 @@ export interface BlumeDataConfig {
   /** Hosted MCP server, or `null` when MCP is off. */
   mcp: { name: string; route: string } | null;
   /** Open Graph image generation. */
-  og: { enabled: boolean };
+  og: {
+    enabled: boolean;
+    logo?: string;
+    palette?: ResolvedConfig["seo"]["og"]["palette"];
+  };
   /** Repository URL for header/edit links, or `null`. */
   repoUrl: string | null;
   search: { enabled: boolean; provider: SearchProvider };

package/src/core/navigation.ts

@@ -433,6 +433,43 @@ const buildConfigSidebar = (
   return nodes;
 };
 
+/**
+ * Resolve a tab's clickable target. A tab's `path` scopes its sidebar section
+ * but need not be a real route — a section with no index page would 404 if the
+ * tab linked straight to it. Prefer an exact page/group at the path; otherwise
+ * fall back to the first linkable route in the section (sidebar order).
+ */
+const resolveTabHref = (sidebar: NavNode[], path: string): string => {
+  let first: string | undefined;
+  const walk = (nodes: NavNode[]): boolean => {
+    for (const node of nodes) {
+      const { route } = node;
+      if (route === path) {
+        return true;
+      }
+      if (
+        first === undefined &&
+        route !== undefined &&
+        route.startsWith(`${path}/`)
+      ) {
+        first = route;
+      }
+      if (node.kind === "group" && walk(node.children)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  return walk(sidebar) ? path : (first ?? path);
+};
+
+/** Attach a resolved `href` to each tab whose section has no index page. */
+const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
+  tabs.map((tab) => {
+    const href = resolveTabHref(sidebar, tab.path);
+    return href === tab.path ? tab : { ...tab, href };
+  });
+
 /** Build the complete navigation model from pages, meta, and config. */
 export const buildNavigation = (
   pages: PageRecord[],
@@ -519,11 +556,17 @@ export const buildNavigation = (
   }
 
   if (options.sidebar) {
+    const sidebar = buildConfigSidebar(
+      options.sidebar,
+      byRoute,
+      display,
+      basePath
+    );
     return {
       featured,
       selectors,
-      sidebar: buildConfigSidebar(options.sidebar, byRoute, display, basePath),
-      tabs,
+      sidebar,
+      tabs: withTabHrefs(tabs, sidebar),
     };
   }
 
@@ -534,19 +577,18 @@ export const buildNavigation = (
   // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
   // under a base, falsely scope a group named like the prefix).
   const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
+  const sidebar = buildFileSystemSidebar(
+    pages,
+    options.folderMeta,
+    sharedFolderMeta,
+    metaPrefix,
+    display,
+    new Set(tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path])))
+  );
   return {
     featured,
     selectors,
-    sidebar: buildFileSystemSidebar(
-      pages,
-      options.folderMeta,
-      sharedFolderMeta,
-      metaPrefix,
-      display,
-      new Set(
-        tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
-      )
-    ),
-    tabs,
+    sidebar,
+    tabs: withTabHrefs(tabs, sidebar),
   };
 };

package/src/core/schema.ts

@@ -672,7 +672,7 @@ const navigationConfigSchema = z.strictObject({
     .transform((value) =>
       Array.isArray(value) ? { display: "flat" as const, items: value } : value
     ),
-  tabs: z.array(navTabSchema).optional(),
+  tabs: z.array(navTabSchema).default([]),
 });
 
 export type AskAiProvider = (typeof askAiProviders)[number];
@@ -802,6 +802,18 @@ const xConfigSchema = z.strictObject({
   handle: xHandleSchema,
 });
 
+const ogColorSchema = z
+  .string()
+  .regex(/^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/iu);
+
+const ogPaletteSchema = z.strictObject({
+  accent: ogColorSchema.optional(),
+  background: ogColorSchema.optional(),
+  border: ogColorSchema.optional(),
+  foreground: ogColorSchema.optional(),
+  muted: ogColorSchema.optional(),
+});
+
 const ogConfigSchema = z.strictObject({
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
@@ -810,6 +822,10 @@ const ogConfigSchema = z.strictObject({
    * `loadConfig`. An explicit value here always wins.
    */
   enabled: z.boolean().optional(),
+  /** Local SVG used in the generated card instead of the site logo. */
+  logo: z.string().optional(),
+  /** Optional generated-card colors. */
+  palette: ogPaletteSchema.optional(),
 });
 
 const rssConfigSchema = z.strictObject({

package/src/core/sources/watch.ts

@@ -23,6 +23,11 @@ import type { WatchListener } from "node:fs";
  */
 export const BLUME_IGNORE_DIRS = [
   ".blume",
+  // The isolated `blume check --isolated` runtime. A sibling of `.blume`, it is
+  // written while a dev server runs; without this the content-layer watcher (or
+  // a `.`-rooted fs.watch) would treat its generation as a content change and
+  // reload — the very thing `--isolated` promises not to do.
+  ".blume-verify",
   ".cache",
   ".git",
   ".next",

package/src/core/types.ts

@@ -159,7 +159,17 @@ export type NavNode =
 /** Top-level tab/section. */
 export interface NavTab {
   label: string;
+  /**
+   * The tab's section prefix, used to scope the sidebar and match the active
+   * tab. Not necessarily a linkable route — a section may have no index page.
+   */
   path: string;
+  /**
+   * The clickable target. Equals `path` when the section has an index page;
+   * otherwise it's resolved to the section's first page so the tab never links
+   * to a 404. Absent when it matches `path`.
+   */
+  href?: string;
   icon?: string;
   items?: NavSelectorItem[];
 }

package/src/markdown/index.ts

@@ -17,6 +17,7 @@ import { languageIconTransformer } from "./language-icon.ts";
 import { mathPlugin } from "./math.ts";
 import { mermaidPlugin } from "./mermaid.ts";
 import { packageInstallPlugin } from "./package-install.ts";
+import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
@@ -58,6 +59,7 @@ type HastPlugin = NonNullable<
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
   const plugins: HastPlugin[] = [
     inlineCodeHighlightPlugin(options.codeThemes) as unknown as HastPlugin,
+    tableWrapPlugin() as unknown as HastPlugin,
   ];
   if (options.headingAnchors !== false) {
     plugins.push(headingAnchorPlugin() as unknown as HastPlugin);

package/src/markdown/language-icon.ts

@@ -7,7 +7,8 @@
  * hex colors are skipped because dark-on-dark logos (Next.js, Rust…) vanish.
  *
  * The theme styles `.blume-lang-icon` and shifts the language label
- * (`pre[data-icon]::before`) to make room.
+ * (`pre[data-language][data-icon]::before`) to make room — gated on
+ * `data-language` so the icon only shows when a header bar exists to hold it.
  */
 
 import {

package/src/markdown/table-wrap.ts

@@ -0,0 +1,43 @@
+/**
+ * Wraps each `<table>` in a scroll container. Satteri does not re-descend into a
+ * visitor's returned replacement, so the wrapped table is not re-visited.
+ *
+ * The wrapper carries `tabindex="0"` so a horizontally scrolling table is
+ * reachable and scrollable by keyboard, not just pointer (WCAG 2.1.1; axe's
+ * `scrollable-region-focusable`). It's added unconditionally — whether a given
+ * table overflows isn't known at build time — which costs a tab stop on tables
+ * that happen to fit; no ARIA label is set to avoid an untranslated string.
+ */
+
+/** A minimal hast node (avoids a hast type dependency). */
+interface HastNode {
+  children?: HastNode[];
+  properties?: Record<string, unknown>;
+  tagName?: string;
+  type: string;
+  value?: string;
+}
+
+/** A Satteri hast plugin, typed structurally to avoid a Satteri dep. */
+export interface TableWrapPlugin {
+  name: string;
+  element: {
+    filter: string[];
+    visit: (node: HastNode) => HastNode;
+  };
+}
+
+export const tableWrapPlugin = (): TableWrapPlugin => ({
+  element: {
+    filter: ["table"],
+    visit(node) {
+      return {
+        children: [node],
+        properties: { className: ["blume-table-scroll"], tabIndex: 0 },
+        tagName: "div",
+        type: "element",
+      };
+    },
+  },
+  name: "blume:table-wrap",
+});

package/src/og/card.ts

@@ -35,6 +35,17 @@ const resolveAccent = (accent: string): string => {
   return HEX_COLOR.test(accent) ? accent : "#3b82f6";
 };
 
+const resolveColor = (color: string | undefined, fallback: string): string =>
+  color && HEX_COLOR.test(color) ? color : fallback;
+
+export interface OgCardPalette {
+  accent?: string;
+  background?: string;
+  border?: string;
+  foreground?: string;
+  muted?: string;
+}
+
 export interface OgCardOptions {
   /** Large headline — the page title. */
   title: string;
@@ -45,10 +56,12 @@ export interface OgCardOptions {
   /** Muted subtitle under the headline (usually the site description). */
   description?: string;
   /**
-   * Inlined SVG markup of the configured logo (`config.logo.svg`), painted into
+   * Inlined SVG markup of the configured logo, painted into
    * the brand lockup. Falls back to an accent mark when absent.
    */
   logo?: string;
+  /** Optional colors for the generated card. */
+  palette?: OgCardPalette;
   /** Footer-left repository slug, e.g. `owner/repo`. */
   repo?: string;
   /** Footer-right site host, e.g. `docs.acme.com`. */
@@ -67,6 +80,17 @@ const MUTED = "#737373";
 const FAINT = "#a3a3a3";
 const BORDER = "#e5e5e5";
 
+const resolvePalette = (
+  options: OgCardOptions
+): Required<OgCardPalette> & { faint: string } => ({
+  accent: resolveAccent(options.palette?.accent ?? options.accent ?? "blue"),
+  background: resolveColor(options.palette?.background, BG),
+  border: resolveColor(options.palette?.border, BORDER),
+  faint: resolveColor(options.palette?.muted, FAINT),
+  foreground: resolveColor(options.palette?.foreground, FOREGROUND),
+  muted: resolveColor(options.palette?.muted, MUTED),
+});
+
 /**
  * Truncate to `max` code points with an ellipsis. Slices by code points, not
  * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
@@ -103,8 +127,8 @@ const logoAspect = (svg: string): number | null => {
 // Render the configured logo as the brand mark. A `currentColor` logo carries
 // no intrinsic color, so it is painted in the foreground to read on the light
 // card, then handed to Takumi as a data URI sized from the SVG's aspect ratio.
-const logoMark = (svg: string): Node => {
-  const painted = svg.replaceAll("currentColor", FOREGROUND);
+const logoMark = (svg: string, foreground: string): Node => {
+  const painted = svg.replaceAll("currentColor", foreground);
   const aspect = logoAspect(painted);
   let height = MARK_HEIGHT;
   let width = aspect ? MARK_HEIGHT * aspect : MARK_HEIGHT;
@@ -151,7 +175,8 @@ const titleSize = (title: string): number => {
 
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
 export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
-  const accent = resolveAccent(options.accent ?? "blue");
+  const { accent, background, border, faint, foreground, muted } =
+    resolvePalette(options);
   const brand = options.brand?.trim();
   const logo = options.logo?.trim();
   // Slice by code point, not code unit — `charAt(0)` would split a leading
@@ -166,14 +191,16 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   // ("Ultracite  Ultracite"). Without a logo, the accent tile with the brand
   // initial stands in.
   const header = container({
-    children: [logo ? logoMark(logo) : initialMark(accent, initial)],
+    children: [
+      logo ? logoMark(logo, foreground) : initialMark(accent, initial),
+    ],
     style: { alignItems: "center", display: "flex" },
   });
 
   const body = container({
     children: [
       text(truncate(options.title, 64), {
-        color: FOREGROUND,
+        color: foreground,
         fontSize: titleSize(options.title),
         fontWeight: 600,
         letterSpacing: "-0.03em",
@@ -183,7 +210,7 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
       }),
       description
         ? text(truncate(description, 140), {
-            color: MUTED,
+            color: muted,
             fontSize: 30,
             lineHeight: 1.4,
             marginTop: 28,
@@ -200,15 +227,15 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
       ? container({
           children: [
             container({
-              style: { backgroundColor: BORDER, height: 1, width: "100%" },
+              style: { backgroundColor: border, height: 1, width: "100%" },
             }),
             container({
               children: [
                 repo
-                  ? text(repo, { color: MUTED, fontSize: 22 })
+                  ? text(repo, { color: muted, fontSize: 22 })
                   : container({}),
                 site
-                  ? text(site, { color: FAINT, fontSize: 22 })
+                  ? text(site, { color: faint, fontSize: 22 })
                   : container({}),
               ],
               style: {
@@ -227,8 +254,8 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const node = container({
     children: [header, body, footer],
     style: {
-      backgroundColor: BG,
-      color: FOREGROUND,
+      backgroundColor: background,
+      color: foreground,
       display: "flex",
       flexDirection: "column",
       height: HEIGHT,

package/src/og/index.ts

@@ -1,2 +1,2 @@
 export { renderOgImage } from "./card.ts";
-export type { OgCardOptions } from "./card.ts";
+export type { OgCardOptions, OgCardPalette } from "./card.ts";

package/src/og/logo.ts

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from "node:fs";
+
+import { join } from "pathe";
+
+import type { BlumeProject } from "../core/project-graph.ts";
+
+/** Resolve a configured local SVG for use in generated Open Graph cards. */
+export const resolveOgLogo = (
+  project: BlumeProject,
+  source: string | undefined
+): string | undefined => {
+  if (!source?.toLowerCase().endsWith(".svg")) {
+    return;
+  }
+  const relative = source.replace(/^\//u, "");
+  const file = [
+    join(project.context.root, "public", relative),
+    join(project.context.root, relative),
+  ].find((path) => existsSync(path));
+  return file ? readFileSync(file, "utf-8") : undefined;
+};

package/src/openapi/references.ts

@@ -1,14 +1,13 @@
 import { withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar, trimEnd } from "../core/trim.ts";
-import type { NavTab } from "../core/types.ts";
 
 /**
  * Pure resolution of the configured API reference blocks into concrete routes,
- * labels, and a renderer choice — no file IO, so the content source, the nav
- * tabs, the Scalar page generator, and the `blume:openapi` data module all share
- * one source of truth. Kept free of any Astro/template imports so `core` can
- * depend on it without a cycle.
+ * labels, and a renderer choice — no file IO, so the content source, the
+ * nav-target validation, the Scalar page generator, and the `blume:openapi`
+ * data module all share one source of truth. Kept free of any Astro/template
+ * imports so `core` can depend on it without a cycle.
  */
 
 export type ReferenceKind = "openapi" | "asyncapi";
@@ -155,18 +154,22 @@ export const resolveReferences = (
   ),
 ];
 
-/** Nav tabs (header links) for every reference, regardless of renderer. */
-export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
-  resolveReferences(config).map((ref) => ({
-    label: ref.label,
+/**
+ * Mounted route for every reference, regardless of renderer. References no
+ * longer add a header tab automatically — authors point a `navigation.tabs`
+ * entry at one of these routes to surface it (and, for Blume-rendered specs, to
+ * scope its operations sidebar). These routes are whitelisted as valid nav
+ * targets so such a tab doesn't read as a broken link.
+ */
+export const referenceRoutes = (config: ResolvedConfig): string[] =>
+  resolveReferences(config).map((ref) =>
     // Blume-rendered operation pages flow through the content pipeline and are
-    // mounted under `basePath`, so their tab must be too. Scalar references are
-    // a single embedded page injected at the raw `route`, left root-anchored.
-    path:
-      ref.renderer === "blume"
-        ? withBasePath(config.basePath, ref.route)
-        : ref.route,
-  }));
+    // mounted under `basePath`. Scalar references are a single embedded page
+    // injected at the raw `route`, left root-anchored.
+    ref.renderer === "blume"
+      ? withBasePath(config.basePath, ref.route)
+      : ref.route
+  );
 
 /**
  * Accept one resolved reference into the deduped Blume-rendered set, or return