blume 0.6.0 → 0.6.2

package/src/core/sources/cache.ts

@@ -27,14 +27,32 @@ export const entriesDigest = (entries: SourceEntry[]): string =>
  * Build an opt-in polling watcher for a remote source: re-`load()` on an
  * interval and fire `onChange` only when the entry digest changes, so a remote
  * source can hot-reload in dev without refetching the world on every keystroke.
+ *
+ * `load` must fetch fresh (bypassing the cache-first dev path) — polling the
+ * cache-first loader would serve the identical snapshot on every tick and
+ * never observe a remote change. `seed` (the source's regular, cache-first
+ * loader) establishes the baseline digest from what dev actually served, so a
+ * remote change landing before the first tick still fires.
  */
 export const pollingWatch =
   (
     load: () => Promise<SourceLoadResult>,
-    intervalSeconds: number
+    intervalSeconds: number,
+    seed?: () => Promise<SourceLoadResult>
   ): ((onChange: () => void) => () => void) =>
   (onChange) => {
     let last = "";
+    if (seed) {
+      const seedBaseline = async (): Promise<void> => {
+        try {
+          const { entries } = await seed();
+          last ||= entriesDigest(entries);
+        } catch {
+          // Fall back to first-tick seeding.
+        }
+      };
+      void seedBaseline();
+    }
     const tick = async (): Promise<void> => {
       try {
         const { entries } = await load();

package/src/core/sources/github-releases.ts

@@ -145,7 +145,9 @@ export const githubReleasesSource = (
     return collected.slice(0, max);
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     try {
       const result = await loadWithCache(
         options.name,
@@ -154,7 +156,7 @@ export const githubReleasesSource = (
           const releases = await fetchReleases();
           return releases.map(releaseToEntry);
         },
-        ctx.refresh ?? true
+        refresh
       );
       snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
       return result;
@@ -194,7 +196,11 @@ export const githubReleasesSource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/mdx-remote.ts

@@ -45,10 +45,14 @@ const globToRegExp = (pattern: string): RegExp => {
     const char = pattern[i] ?? "";
     if (char === "*") {
       if (pattern[i + 1] === "*") {
-        source += ".*";
         i += 2;
+        // `**/` spans zero or more whole segments — `docs/**/guide.md` must
+        // match `docs/guide.md` and `docs/a/guide.md` but not `docs/subguide.md`.
         if (pattern[i] === "/") {
           i += 1;
+          source += "(?:.*/)?";
+        } else {
+          source += ".*";
         }
         continue;
       }
@@ -205,7 +209,9 @@ export const mdxRemoteSource = (
     };
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     const skipped: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,
@@ -245,7 +251,7 @@ export const mdxRemoteSource = (
         }
         return entries;
       },
-      ctx.refresh ?? true
+      refresh
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return {
@@ -271,7 +277,11 @@ export const mdxRemoteSource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/normalize.ts

@@ -81,7 +81,9 @@ const mapRoute = (
 };
 
 const CODE_FENCE = /^```/u;
-const ATX_HEADING = /^(?<hashes>#{1,6})\s+(?<text>.+?)\s*#*$/u;
+// A closing hash sequence must be preceded by whitespace (CommonMark), so a
+// heading like `## What is C#` keeps its trailing `#`.
+const ATX_HEADING = /^(?<hashes>#{1,6})\s+(?<text>.+?)(?:\s+#+)?\s*$/u;
 
 /**
  * Extract ATX headings from a markdown body, skipping fenced code blocks. Each
@@ -260,6 +262,16 @@ export const normalizeEntry = (
 
   const meta = result.data;
 
+  // Top-level `hidden`/`noindex` are accepted as shorthands for their nested
+  // equivalents — the schema declares them, so silently ignoring them would
+  // strand authors with no diagnostic.
+  if (meta.hidden) {
+    meta.sidebar.hidden = true;
+  }
+  if (meta.noindex) {
+    meta.seo.noindex = true;
+  }
+
   // Locale and the locale-stripped nav path come from the entry's ref (a leading
   // dir, or a filename suffix under the `dot` parser), not the slug — the slug is
   // the logical, locale-agnostic path within a locale. A shared `$` file maps to

package/src/core/sources/notion.ts

@@ -335,10 +335,40 @@ export const notionSource = (
     blocks: NotionBlock[]
   ): Promise<string> => {
     const parts = await Promise.all(
-      blocks.map(
-        (block) =>
-          renderLeaf(block) ?? renderContainer(client, block, renderBlocks)
-      )
+      blocks.map(async (block) => {
+        const leaf = renderLeaf(block);
+        if (leaf === null) {
+          return renderContainer(client, block, renderBlocks);
+        }
+        // Leaf blocks can still carry children (nested list items, indented
+        // paragraphs); dropping them would silently lose content.
+        if (!block.has_children) {
+          return leaf;
+        }
+        const nested = await renderBlocks(
+          client,
+          await childrenOf(client, block.id)
+        );
+        if (!nested) {
+          return leaf;
+        }
+        if (isListItem(block)) {
+          // Indent past the list marker so the children belong to the item
+          // (`1. ` needs three columns, `- `/`- [x] ` two).
+          const indent = " ".repeat(
+            block.type === "numbered_list_item" ? 3 : 2
+          );
+          const indented = nested
+            .split("\n")
+            .map((line) => (line ? `${indent}${line}` : line))
+            .join("\n");
+          return `${leaf}\n${indented}`;
+        }
+        // Other leaves (paragraph, quote) keep their children as following
+        // sibling blocks — the indentation semantics are lost but the content
+        // survives.
+        return `${leaf}\n\n${nested}`;
+      })
     );
     // Join with a blank line, except between consecutive list items, which stay
     // tight so they render as a single list rather than separate loose ones.
@@ -430,7 +460,9 @@ export const notionSource = (
     };
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx?.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     const assetDiagnostics: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,
@@ -453,7 +485,7 @@ export const notionSource = (
         }
         return built.map((item) => item.entry);
       },
-      ctx?.refresh ?? true
+      refresh
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return {
@@ -478,7 +510,11 @@ export const notionSource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/resolve.ts

@@ -1,4 +1,4 @@
-import { join } from "pathe";
+import { isAbsolute, join, resolve } from "pathe";
 
 import { blumeReferences } from "../../openapi/references.ts";
 import { openApiSource } from "../../openapi/source.ts";
@@ -125,6 +125,49 @@ const buildSource = (
   );
 };
 
+/** Resolve a source `root` against the project root (absolute passes through). */
+const resolveRoot = (projectRoot: string, root: string): string =>
+  isAbsolute(root) ? root : join(resolve(projectRoot), root);
+
+/**
+ * The generated `docs` glob collection: its base directory and the include /
+ * exclude globs applied under it. Astro's glob loader ids each entry by its path
+ * relative to `base`, and a filesystem source ids each entry relative to its own
+ * root — so the two only agree when the collection is rooted at that source. A
+ * project with exactly one filesystem source therefore roots the collection at
+ * *that* source (honoring a non-default `root`), rather than the global
+ * `content.root`. With no sources (the implicit source) or several, the base
+ * stays `content.root`; a second filesystem source rooted elsewhere can't share
+ * one base and is caught by the entry-id guard in `scanProject`.
+ */
+export interface DocsCollection {
+  base: string;
+  include: string[];
+  exclude: string[];
+}
+
+export const resolveDocsCollection = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): DocsCollection => {
+  const filesystem = (config.content.sources ?? []).filter(
+    (def) => def.type === "filesystem"
+  );
+  const only = filesystem.length === 1 ? filesystem[0] : undefined;
+  if (only) {
+    return {
+      base: resolveRoot(context.root, only.root),
+      exclude: only.exclude,
+      include: only.include,
+    };
+  }
+  return {
+    base: context.contentRoot,
+    exclude: config.content.exclude,
+    include: config.content.include,
+  };
+};
+
 /** The base name to allocate for a source config (before deduplication). */
 const baseName = (def: ContentSourceConfig): string => {
   if (def.type === "custom") {

package/src/core/sources/sanity.ts

@@ -183,7 +183,9 @@ export const sanitySource = (
     };
   };
 
-  const load = async (): Promise<SourceLoadResult> => {
+  const load = async (
+    refresh = ctx?.refresh ?? true
+  ): Promise<SourceLoadResult> => {
     const result = await loadWithCache(
       options.name,
       cache,
@@ -194,7 +196,7 @@ export const sanitySource = (
         );
         return docs.map(toEntry);
       },
-      ctx?.refresh ?? true
+      refresh
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
     return result;
@@ -216,7 +218,11 @@ export const sanitySource = (
     read,
     staged: true,
     watch: options.pollInterval
-      ? pollingWatch(load, options.pollInterval)
+      ? pollingWatch(
+          () => load(true),
+          options.pollInterval,
+          () => load()
+        )
       : undefined,
   };
 };

package/src/core/sources/types.ts

@@ -84,6 +84,12 @@ export interface ContentSource {
   readonly staged: boolean;
   /** Optional route prefix; the source's routes namespace under `/<prefix>/`. */
   readonly prefix?: string;
+  /**
+   * Resolved on-disk root, set by filesystem-backed sources only. Drives
+   * folder-meta discovery (scan under this root) and the docs-collection base;
+   * omitted by remote/CMS/staged sources that have no local tree.
+   */
+  readonly contentRoot?: string;
   /** Pull every entry. Called once per scan. */
   load: () => Promise<SourceLoadResult>;
   /** Validate the source is usable; throws a BlumeError when not. */

package/src/deploy/adapter-output.ts

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+
+import { dirname, join } from "pathe";
+
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { ProjectContext } from "../core/types.ts";
+
+type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
+
+/**
+ * Server adapters whose deploy bundle lands *outside* Astro's `outDir`, at a
+ * path relative to the Astro project root. Blume points the Astro root at the
+ * hidden `<root>/.blume` runtime, so these adapters write their bundle to
+ * `<root>/.blume/<path>` — where the deploy platform never looks. Each value is
+ * the sub-path to surface up to the real project root.
+ *
+ * `vercel` writes a Build Output API v3 tree at `.vercel/output`; only that
+ * subtree is moved, so a `vercel pull`-ed `.vercel/project.json` sitting at the
+ * project root survives the relocation. `netlify` owns its whole `.netlify`
+ * dir. `node` and `cloudflare` emit into `dist/` (already at the project root),
+ * so they are absent here and need no relocation.
+ */
+export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
+  netlify: ".netlify",
+  vercel: ".vercel/output",
+};
+
+/**
+ * Directory whose contents the deploy platform serves as static files. Build
+ * artifacts (robots.txt, sitemap.xml, llms.txt, …) must be written here to be
+ * served. For a Vercel server build that is the adapter's
+ * `.vercel/output/static`; every other build serves `dist/`.
+ */
+export const deployStaticDir = (
+  config: ResolvedConfig,
+  context: ProjectContext
+): string => {
+  const { adapter, output } = config.deployment;
+  if (output === "server" && adapter === "vercel") {
+    return join(context.root, ".vercel", "output", "static");
+  }
+  return context.distDir ?? join(context.root, "dist");
+};
+
+/** Outcome of {@link surfaceAdapterOutput}, for logging and `.gitignore`. */
+export type SurfaceResult =
+  | { moved: false }
+  | { from: string; ignore: string; moved: true; to: string };
+
+/**
+ * Move a server adapter's deploy bundle out of the hidden `.blume` runtime and
+ * up to the project root, where the deploy platform (and `vercel deploy
+ * --prebuilt`) expects it. A no-op for static builds, for adapters that emit
+ * into `dist/`, and when the expected output is absent.
+ */
+export const surfaceAdapterOutput = async (
+  config: ResolvedConfig,
+  context: ProjectContext
+): Promise<SurfaceResult> => {
+  const { adapter, output } = config.deployment;
+  if (output !== "server" || !adapter) {
+    return { moved: false };
+  }
+  const rel = ADAPTER_OUTPUT_PATHS[adapter];
+  if (!rel) {
+    return { moved: false };
+  }
+  const from = join(context.outDir, rel);
+  const to = join(context.root, rel);
+  if (!existsSync(from)) {
+    return { moved: false };
+  }
+  await mkdir(dirname(to), { recursive: true });
+  await rm(to, { force: true, recursive: true });
+  await cp(from, to, { recursive: true });
+  await rm(from, { force: true, recursive: true });
+  // The `.gitignore` entry is the surfaced top-level dir (`.vercel`/`.netlify`),
+  // never the moved sub-path — Vercel's own `.vercel/project.json` lives there
+  // too and must also be ignored.
+  return { from, ignore: `${rel.split("/")[0]}/`, moved: true, to };
+};

package/src/deploy/rss.ts

@@ -68,7 +68,9 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
       .map((page) => ({
         date: pageDate(page),
         description: page.description,
-        link: `${base}${page.route}`,
+        // Encode like the sitemap does: a route with spaces or non-ASCII
+        // must still yield a valid <link>/<guid> URL after XML decoding.
+        link: encodeURI(`${base}${page.route}`),
         title: page.title,
       }))
       .toSorted((a, b) => (b.date?.getTime() ?? 0) - (a.date?.getTime() ?? 0))

package/src/index.ts

@@ -22,8 +22,8 @@ export type {
   FolderMetaFactory,
 } from "./core/define-meta.ts";
 export type { UIStrings } from "./core/i18n-ui.ts";
+export type { BlumeConfig } from "./core/config-input.ts";
 export type {
-  BlumeConfig,
   FolderMeta,
   HydrationMode,
   ResolvedConfig,

package/src/markdown/code-title.ts

@@ -26,9 +26,16 @@ export interface CodeTitleTransformer {
 }
 
 // The body excludes only the delimiting quote, so `title="foo's file.ts"`
-// (an apostrophe inside double quotes) still matches.
-const TITLE_ATTR = /title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
+// (an apostrophe inside double quotes) still matches. The left boundary stops
+// `subtitle="..."` (or any `*title=` attr) from reading as a title.
+const TITLE_ATTR = /(?:^|\s)title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
 const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
+// Any quoted `key="..."` attr — blanked before keyword/bare-token scans so a
+// quoted value can't leak tokens (`title="enable lineNumbers later"`).
+const QUOTED_ATTR = /[\w-]+=(?:"[^"]*"|'[^']*')/gu;
+
+const withoutQuotedAttrs = (raw: string): string =>
+  raw.replace(QUOTED_ATTR, " ");
 
 const parseTitle = (raw: string | undefined): string | undefined => {
   if (!raw) {
@@ -42,7 +49,7 @@ const parseTitle = (raw: string | undefined): string | undefined => {
   // The first bare token is the title (```ts blume.config.ts), skipping Shiki
   // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`
   // and `twoslash` keywords.
-  return raw
+  return withoutQuotedAttrs(raw)
     .trim()
     .split(/\s+/u)
     .find(
@@ -56,7 +63,7 @@ const parseTitle = (raw: string | undefined): string | undefined => {
 };
 
 const hasLineNumbers = (raw: string | undefined): boolean =>
-  Boolean(raw && LINE_NUMBERS.test(raw));
+  Boolean(raw && LINE_NUMBERS.test(withoutQuotedAttrs(raw)));
 
 /** Build the transformer. Runs after Shiki's built-in `data-language` hook. */
 export const codeTitleTransformer = (): CodeTitleTransformer => ({

package/src/markdown/index.ts

@@ -46,15 +46,16 @@ type HastPlugin = NonNullable<
 
 /**
  * Hast plugins enabled by config. Inline `` `code`{:lang} `` highlighting is
- * opt-in; self-linking heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to
- * their own id) are on unless `markdown.headingAnchors` is `false`. Inline code
- * runs first so the anchor wrap re-refs already-highlighted code.
+ * always on: it only fires on an explicit trailing `{:lang}` marker, so plain
+ * inline code is untouched and there's nothing to opt out of. Self-linking
+ * heading anchors (`<h2>`–`<h6>` wrapped in an `<a>` to their own id) are on
+ * unless `markdown.headingAnchors` is `false`. Inline code runs first so the
+ * anchor wrap re-refs already-highlighted code.
  */
 const blumeHastPlugins = (options: BlumeMarkdownOptions): HastPlugin[] => {
-  const plugins: HastPlugin[] = [];
-  if (options.inline) {
-    plugins.push(inlineCodeHighlightPlugin() as unknown as HastPlugin);
-  }
+  const plugins: HastPlugin[] = [
+    inlineCodeHighlightPlugin() as unknown as HastPlugin,
+  ];
   if (options.headingAnchors !== false) {
     plugins.push(headingAnchorPlugin() as unknown as HastPlugin);
   }
@@ -204,8 +205,6 @@ export interface BlumeMarkdownOptions {
    * On unless explicitly `false`.
    */
   headingAnchors?: boolean;
-  /** Highlight inline `` `code`{:lang} `` snippets (`markdown.code.inline`). */
-  inline?: boolean;
 }
 
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */
@@ -215,38 +214,37 @@ export const blumeMarkdownProcessor = (options: BlumeMarkdownOptions = {}) =>
     hastPlugins: blumeHastPlugins(options),
   });
 
-export interface BlumeMdxOptions extends BlumeMarkdownOptions {
-  /** Enable KaTeX math parsing and rendering. */
-  math?: boolean;
-}
+export type BlumeMdxOptions = BlumeMarkdownOptions;
 
 /**
  * Sätteri MDX processor: Blume's feature set plus the MDAST plugins that target
  * components — `package-install` → package-manager tabs, `:::note` →
- * `<Callout>`, and ` ```mermaid ` → a `<blume-mermaid>` element. Used as the
- * `processor` for `@astrojs/mdx` so these apply to
- * `.mdx` only (plain `.md` uses {@link blumeMarkdownProcessor}). Math is opt-in
- * via config since `$` is common in prose and code.
+ * `<Callout>`, ` ```mermaid ` → a `<blume-mermaid>` element, and block math
+ * (`$$…$$`) → the `<Math>` component. Used as the `processor` for
+ * `@astrojs/mdx` so these apply to `.mdx` only (plain `.md` uses
+ * {@link blumeMarkdownProcessor}).
+ *
+ * Math is always on but block-only: `singleDollarTextMath: false` keeps a bare
+ * `$` (currency, shell, code) as literal text and only parses `$$…$$`. The
+ * generated runtime imports the `<Math>` component (and KaTeX's stylesheet) only
+ * when content actually uses `$$`, so a math-free site ships no KaTeX CSS.
  *
  * The plugins are modeled with minimal structural types; bridge them to
  * Satteri's full `MdastPlugin` type at this single boundary.
  */
-export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) => {
-  const plugins: unknown[] = [
-    packageInstallPlugin(),
-    directiveToCalloutPlugin(),
-    mermaidPlugin(),
-  ];
-  if (options.math) {
-    plugins.push(mathPlugin());
-  }
-  return satteri({
+export const blumeMdxProcessor = (options: BlumeMdxOptions = {}) =>
+  satteri({
     features: {
       ...FEATURES,
       directive: true,
-      ...(options.math ? { math: true } : {}),
+      // Block-only: `$$…$$` parses, a bare `$` stays literal text.
+      math: { singleDollarTextMath: false },
     },
     hastPlugins: blumeHastPlugins(options),
-    mdastPlugins: plugins as unknown as MdastPlugin[],
+    mdastPlugins: [
+      packageInstallPlugin(),
+      directiveToCalloutPlugin(),
+      mermaidPlugin(),
+      mathPlugin(),
+    ] as unknown as MdastPlugin[],
   });
-};

package/src/markdown/math.ts

@@ -8,8 +8,9 @@ interface MathNode extends MdastNode {
 /**
  * Satteri MDAST plugin that turns math nodes into Blume's `<Math>` component,
  * which renders them with KaTeX at build time. Block math (`$$…$$`) becomes a
- * block element; inline math (`$…$`) stays inline. Only active when math is
- * enabled in config, so `$` is otherwise left as literal text.
+ * block element. Blume runs the parser block-only (`singleDollarTextMath:
+ * false`), so a bare `$` stays literal and no `inlineMath` nodes are produced;
+ * the `inlineMath` visitor remains as a harmless safety net.
  */
 export const mathPlugin = () => ({
   inlineMath(node: MathNode, ctx: MdastVisitorContext) {

package/src/markdown/package-commands.ts

@@ -98,6 +98,19 @@ const parseIntent = (input: string): Intent => {
   if (!verb) {
     return { args: [], operation: "install" };
   }
+  // Yarn Classic spells global installs `yarn global <add|remove> …`; map it
+  // onto the flag-style intent so every manager renders its own global form
+  // instead of falling into the run-as-script branch.
+  if (first === "yarn" && verb === "global") {
+    const [globalVerb, ...globalArgs] = verbArgs;
+    const globalOp = globalVerb ? normalizeVerb(globalVerb) : null;
+    if (globalOp === "add" || globalOp === "remove") {
+      return {
+        args: [...normalizeFlags(globalArgs), "-g"],
+        operation: globalOp,
+      };
+    }
+  }
   const operation = normalizeVerb(verb);
   if (operation === null) {
     // Unknown subcommand (e.g. `npm test`); run it as a script.

package/src/og/card.ts

@@ -145,7 +145,9 @@ export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const accent = resolveAccent(options.accent ?? "blue");
   const brand = options.brand?.trim();
   const logo = options.logo?.trim();
-  const initial = brand ? brand.charAt(0).toUpperCase() : "";
+  // Slice by code point, not code unit — `charAt(0)` would split a leading
+  // surrogate pair (an emoji brand initial) into a lone half that renders blank.
+  const initial = brand ? ([...brand][0]?.toUpperCase() ?? "") : "";
   const description = options.description?.trim();
   const repo = options.repo?.trim();
   const site = options.site?.trim();

package/src/openapi/model.ts

@@ -144,7 +144,8 @@ export const extractOperations = (
         method,
         operationId: operation.operationId,
         path,
-        route: `${baseRoute}/${tagSlug}/${key}`,
+        // A root-mounted reference (`route: "/"`) must not emit `//tag/key`.
+        route: `${baseRoute === "/" ? "" : baseRoute}/${tagSlug}/${key}`,
         summary: operation.summary ?? "",
         tag,
         tagSlug,

package/src/openapi/parse.ts

@@ -26,6 +26,9 @@ const URL_SPEC = /^https?:\/\//u;
 const FETCH_TIMEOUT_MS = 15_000;
 const MAX_ATTEMPTS = 3;
 const BASE_BACKOFF_MS = 500;
+// Honor Retry-After only up to a sane ceiling: a server answering with
+// `Retry-After: 3600` must not stall a build for an hour per attempt.
+const MAX_RETRY_WAIT_MS = 10_000;
 const SECOND_MS = 1000;
 // Worth another try: request timeout, too-early, rate-limited, and the 5xx range.
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
@@ -138,7 +141,12 @@ const fetchSpecText = async (spec: string): Promise<string> => {
       throw last.error;
     }
     // oxlint-disable-next-line no-await-in-loop -- back off before retrying
-    await sleep(last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt);
+    await sleep(
+      Math.min(
+        last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt,
+        MAX_RETRY_WAIT_MS
+      )
+    );
   }
   throw last.error;
 };

package/src/openapi/references.ts

@@ -145,6 +145,7 @@ export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
 /** Blume-rendered OpenAPI references, deduped by route (first wins). */
 export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
   const seen = new Set<string>();
+  const usedSlugs = new Set<string>();
   const result: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
     if (ref.kind !== "openapi" || ref.renderer !== "blume") {
@@ -154,7 +155,16 @@ export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
       continue;
     }
     seen.add(ref.route);
-    result.push(ref);
+    // Distinct routes can slugify identically (`/api/v1` and `/api-v1` both
+    // yield `api-v1`). The slug keys the `blume:openapi` data module, so a
+    // collision would let one spec silently overwrite the other while the
+    // loser's pages still point at the shared key — disambiguate.
+    let { slug } = ref;
+    for (let n = 2; usedSlugs.has(slug); n += 1) {
+      slug = `${ref.slug}-${n}`;
+    }
+    usedSlugs.add(slug);
+    result.push(slug === ref.slug ? ref : { ...ref, slug });
   }
   return result;
 };