blume 0.7.0 → 1.0.0

package/src/core/ui-packs/vi.ts

@@ -23,6 +23,11 @@ export const vi: UIStringsOverride = {
     send: "Gửi",
     title: "Hỏi AI",
   },
+  banner: { dismiss: "Đóng thông báo" },
+  changelog: {
+    description: "Cập nhật sản phẩm và ghi chú phát hành.",
+    title: "Nhật ký thay đổi",
+  },
   feedback: {
     no: "Không",
     question: "Trang này có hữu ích không?",
@@ -30,13 +35,16 @@ export const vi: UIStringsOverride = {
     yes: "Có",
   },
   languageSwitcher: { label: "Ngôn ngữ", untranslated: "Chưa dịch" },
+  nav: { breadcrumb: "Đường dẫn điều hướng" },
   page: {
     lastUpdated: "Cập nhật lần cuối",
     next: "Tiếp theo",
+    pagination: "Phân trang",
     previous: "Trước",
     skipToContent: "Chuyển đến nội dung",
   },
   search: {
+    all: "Tất cả",
     button: "Tìm kiếm",
     devOnly: "Tìm kiếm có sẵn trong bản dựng production.",
     label: "Tìm kiếm tài liệu",

package/src/core/ui-packs/zh-tw.ts

@@ -23,6 +23,11 @@ export const zhTW: UIStringsOverride = {
     send: "傳送",
     title: "向 AI 提問",
   },
+  banner: { dismiss: "關閉公告" },
+  changelog: {
+    description: "產品更新與版本說明。",
+    title: "更新日誌",
+  },
   feedback: {
     no: "沒有幫助",
     question: "這個頁面有幫助嗎？",
@@ -30,13 +35,16 @@ export const zhTW: UIStringsOverride = {
     yes: "有幫助",
   },
   languageSwitcher: { label: "語言", untranslated: "未翻譯" },
+  nav: { breadcrumb: "麵包屑導覽" },
   page: {
     lastUpdated: "最後更新於",
     next: "下一頁",
+    pagination: "分頁",
     previous: "上一頁",
     skipToContent: "跳至內容",
   },
   search: {
+    all: "全部",
     button: "搜尋",
     devOnly: "搜尋在正式版組建中可用。",
     label: "搜尋文件",

package/src/core/ui-packs/zh.ts

@@ -23,6 +23,11 @@ export const zh: UIStringsOverride = {
     send: "发送",
     title: "向 AI 提问",
   },
+  banner: { dismiss: "关闭公告" },
+  changelog: {
+    description: "产品更新与版本说明。",
+    title: "更新日志",
+  },
   feedback: {
     no: "没有帮助",
     question: "这个页面有帮助吗？",
@@ -30,13 +35,16 @@ export const zh: UIStringsOverride = {
     yes: "有帮助",
   },
   languageSwitcher: { label: "语言", untranslated: "未翻译" },
+  nav: { breadcrumb: "面包屑导航" },
   page: {
     lastUpdated: "最后更新于",
     next: "下一页",
+    pagination: "分页",
     previous: "上一页",
     skipToContent: "跳到内容",
   },
   search: {
+    all: "全部",
     button: "搜索",
     devOnly: "搜索在生产构建中可用。",
     label: "搜索文档",

package/src/deploy/adapter-output.ts

@@ -17,12 +17,15 @@ type Adapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
  *
  * `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.
+ * project root survives the relocation. `netlify` writes a Frameworks API tree
+ * at `.netlify/v1` (its `.netlify/build` sibling is only the intermediate SSR
+ * bundle, already traced into `v1/functions`); only `v1` is moved, so the
+ * `.netlify/state.json` written by `netlify link` survives too. `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",
+  netlify: ".netlify/v1",
   vercel: ".vercel/output",
 };
 
@@ -30,7 +33,10 @@ export const ADAPTER_OUTPUT_PATHS: Partial<Record<Adapter, string>> = {
  * 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/`.
+ * `.vercel/output/static`; for a Node server build it is Astro's
+ * `build.client` dir (`dist/client/`), the only directory the standalone
+ * server's static handler reads from. Netlify publishes `dist/` itself and
+ * Cloudflare serves the `outDir` root, so every other build serves `dist/`.
  */
 export const deployStaticDir = (
   config: ResolvedConfig,
@@ -40,7 +46,11 @@ export const deployStaticDir = (
   if (output === "server" && adapter === "vercel") {
     return join(context.root, ".vercel", "output", "static");
   }
-  return context.distDir ?? join(context.root, "dist");
+  const dist = context.distDir ?? join(context.root, "dist");
+  if (output === "server" && adapter === "node") {
+    return join(dist, "client");
+  }
+  return dist;
 };
 
 /** Outcome of {@link surfaceAdapterOutput}, for logging and `.gitignore`. */
@@ -76,7 +86,7 @@ export const surfaceAdapterOutput = async (
   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.
+  // never the moved sub-path — the platform's own state (`.vercel/project.json`,
+  // `.netlify/state.json`) lives there too and must also be ignored.
   return { from, ignore: `${rel.split("/")[0]}/`, moved: true, to };
 };

package/src/deploy/redirects.ts

@@ -34,14 +34,19 @@ export const buildNetlifyRedirects = (redirects: Redirect[]): string =>
     .map((redirect) => `${redirect.from} ${redirect.to} ${redirect.status}`)
     .join("\n")}\n`;
 
-/** `vercel.json` contents with a `redirects` array (permanent = 301/308). */
+/**
+ * `vercel.json` contents with a `redirects` array. Uses `statusCode` (Vercel's
+ * alternative to the boolean `permanent`) so the configured code ships exactly:
+ * `permanent` would silently coerce a 301 to 308 and a 302 to 307, diverging
+ * from the `_redirects` file, which preserves exact codes.
+ */
 export const buildVercelConfig = (redirects: Redirect[]): string =>
   `${JSON.stringify(
     {
       redirects: redirects.map((redirect) => ({
         destination: redirect.to,
-        permanent: redirect.status === 301 || redirect.status === 308,
         source: redirect.from,
+        statusCode: redirect.status,
       })),
     },
     null,

package/src/deploy/sitemap.ts

@@ -1,7 +1,21 @@
+import {
+  customStaticRoutes,
+  discoverPagesSync,
+  hasGeneratedChangelog,
+} from "../astro/pages.ts";
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { escapeXml } from "./xml.ts";
 
+/**
+ * Astro's reserved error routes. A user-authored override (`pages/404.astro`,
+ * `pages/500.astro`, or a `404.md` content page — see `writeNotFoundPage` in
+ * `astro/generate.ts`) is neither dynamic nor private, so it would otherwise
+ * be emitted — but error pages aren't crawlable destinations and must stay out
+ * of the sitemap.
+ */
+const ERROR_ROUTES = new Set(["/404", "/500"]);
+
 /** A `<lastmod>` element (W3C date) when the page has a valid modified date. */
 const lastmodTag = (value: string | undefined): string => {
   if (!value) {
@@ -14,9 +28,11 @@ const lastmodTag = (value: string | undefined): string => {
 };
 
 /**
- * Build a sitemap.xml from the route manifest. Returns null when the sitemap is
- * disabled or no `site` is configured (absolute URLs are required for a valid
- * sitemap). Drafts, hidden, and `noindex` pages are excluded.
+ * Build a sitemap.xml from the route manifest plus the routes the manifest
+ * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
+ * the generated `/changelog` index. Returns null when the sitemap is disabled
+ * or no `site` is configured (absolute URLs are required for a valid sitemap).
+ * Drafts, hidden, and `noindex` pages are excluded.
  */
 export const buildSitemap = (project: BlumeProject): string | null => {
   const { site } = project.config.deployment;
@@ -27,19 +43,45 @@ export const buildSitemap = (project: BlumeProject): string | null => {
   const base = site.replace(/\/$/u, "");
   // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top.
   const deployBase = normalizeBasePath(project.config.deployment.base);
+  const seen = new Set<string>();
   const urls: string[] = [];
-  for (const page of project.graph.pages) {
-    if (page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex) {
-      continue;
-    }
+  const pushUrl = (route: string, lastModified?: string): void => {
     // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
     // then escape XML metacharacters (notably `&`) so a route like
     // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
     // rejected.
-    const loc = escapeXml(
-      encodeURI(`${base}${withBasePath(deployBase, page.route)}`)
-    );
-    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(page.lastModified)}</url>`);
+    const loc = escapeXml(encodeURI(`${base}${route}`));
+    if (seen.has(loc)) {
+      return;
+    }
+    seen.add(loc);
+    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
+  };
+  for (const page of project.graph.pages) {
+    if (
+      page.meta.draft ||
+      page.meta.sidebar.hidden ||
+      page.meta.seo.noindex ||
+      ERROR_ROUTES.has(page.route)
+    ) {
+      continue;
+    }
+    pushUrl(withBasePath(deployBase, page.route), page.lastModified);
+  }
+  // Custom `.astro` pages and the generated changelog index mount outside
+  // `basePath` (they're injected at their pattern — see `blumeIntegration`), so
+  // only the deployment base layers onto their URLs.
+  const userPages = project.context.pagesRoot
+    ? discoverPagesSync(project.context.pagesRoot)
+    : [];
+  const extraRoutes = customStaticRoutes(userPages).filter(
+    (route) => !ERROR_ROUTES.has(route)
+  );
+  if (hasGeneratedChangelog(project, userPages)) {
+    extraRoutes.push("/changelog");
+  }
+  for (const route of extraRoutes) {
+    pushUrl(withBasePath(deployBase, route));
   }
   urls.sort();
 

package/src/index.ts

@@ -1,3 +1,8 @@
+export type {
+  ComponentMarkdown,
+  ComponentMarkdownChild,
+  ComponentMarkdownContext,
+} from "./ai/component-markdown.ts";
 export { defineConfig } from "./core/config.ts";
 export type {
   BlumeBanner,

package/src/markdown/base-links.ts

@@ -1,4 +1,4 @@
-import { isInternalPath, withBasePath } from "../core/base-path.ts";
+import { isInternalPath, withComposedBasePath } from "../core/base-path.ts";
 import type { MdastNode } from "./mdast.ts";
 
 interface UrlNode extends MdastNode {
@@ -27,13 +27,15 @@ const ASSET_PATH = /\.[a-z0-9]+$/iu;
 const pathOf = (url: string): string => url.replace(/[#?].*$/u, "");
 
 /**
- * Satteri MDAST plugin that prepends the site-wide `basePath` to root-relative
- * internal page links (`[x](/guide)` -> `/docs/guide`), so authors write links
- * as if mounted at root. Idempotent (via `withBasePath`) and inert for external
- * URLs, fragments, relative paths, images, and asset links. Only constructed
- * when a base is set (see `markdown/index.ts`).
+ * Satteri MDAST plugin that prepends the served-URL base — `deployment.base`
+ * layered over the site-wide `basePath` — to root-relative internal page links
+ * (`[x](/guide)` -> `/base/docs/guide`), so authors write links as if mounted
+ * at root. Idempotent per layer (via `withComposedBasePath`, so a hand-written
+ * `/docs/x` isn't double-prefixed) and inert for external URLs, fragments,
+ * relative paths, images, and asset links. Only constructed when a base is set
+ * (see `markdown/index.ts`).
  */
-export const baseLinksPlugin = (basePath: string) => {
+export const baseLinksPlugin = (deployBase: string, basePath: string) => {
   const rebase = (node: UrlNode, ctx: MdastUrlContext): void => {
     const { url } = node;
     if (
@@ -41,7 +43,7 @@ export const baseLinksPlugin = (basePath: string) => {
       isInternalPath(url) &&
       !ASSET_PATH.test(pathOf(url))
     ) {
-      const next = withBasePath(basePath, url);
+      const next = withComposedBasePath(deployBase, basePath, url);
       if (next !== url) {
         ctx.setProperty(node, "url", next);
       }

package/src/markdown/index.ts

@@ -217,17 +217,29 @@ export interface BlumeMarkdownOptions {
    * links as if mounted at root.
    */
   basePath?: string;
+  /**
+   * Astro's `deployment.base` subdirectory (`""` or `/seg`), layered on top of
+   * `basePath` when links are rewritten. Kept separate so a hand-written
+   * `basePath` link isn't double-prefixed (see `withComposedBasePath`).
+   */
+  deployBase?: string;
 }
 
 /**
  * MDAST plugins that apply to both `.md` and `.mdx`. Currently just the
- * base-path link rewrite, added only when a `basePath` is configured.
+ * base-path link rewrite, added only when a `basePath` or `deployBase` is
+ * configured.
  */
 const blumeSharedMdastPlugins = (
   options: BlumeMarkdownOptions
 ): MdastPlugin[] =>
-  options.basePath
-    ? [baseLinksPlugin(options.basePath) as unknown as MdastPlugin]
+  options.basePath || options.deployBase
+    ? [
+        baseLinksPlugin(
+          options.deployBase ?? "",
+          options.basePath ?? ""
+        ) as unknown as MdastPlugin,
+      ]
     : [];
 
 /** Sätteri processor for plain `.md`, with Blume's curated feature set. */

package/src/markdown/inline-code.ts

@@ -104,8 +104,13 @@ export const inlineCodeHighlightPlugin = (
           type: "element",
         };
       } catch {
-        // Unknown language or load failure: leave the code unhighlighted
-        // (falling through returns undefined, so the node is left as-is).
+        // Unknown language or load failure: still strip the marker — the
+        // literal `{:lang}` must not ship in the page — and fall back to
+        // plain, unhighlighted inline code.
+        return {
+          ...node,
+          children: [{ type: "text", value: parsed.code }],
+        };
       }
     },
   },

package/src/markdown/package-commands.ts

@@ -149,10 +149,16 @@ const buildCommand = (manager: PackageManager, intent: Intent): string => {
       return `${manager} dlx ${args}`;
     }
     case "ci": {
-      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere.
-      return manager === "npm"
-        ? "npm ci"
-        : `${manager} install --frozen-lockfile`;
+      // `npm ci` maps to a frozen, lockfile-faithful install elsewhere. Yarn
+      // Berry's flag is `--immutable` (`--frozen-lockfile` was removed in
+      // Yarn 4), matching the Berry-only `yarn dlx` the `exec` case emits.
+      if (manager === "npm") {
+        return "npm ci";
+      }
+      if (manager === "yarn") {
+        return "yarn install --immutable";
+      }
+      return `${manager} install --frozen-lockfile`;
     }
     case "remove": {
       if (manager === "npm") {

package/src/og/card.ts

@@ -2,6 +2,8 @@ import { Renderer } from "@takumi-rs/core";
 import { container, image, text } from "@takumi-rs/helpers";
 import type { Node } from "@takumi-rs/helpers";
 
+import { OG_IMAGE_HEIGHT, OG_IMAGE_WIDTH } from "./dimensions.ts";
+
 // Reuse one renderer (and its loaded default fonts) across all images.
 let renderer: Renderer | null = null;
 const getRenderer = (): Renderer => {
@@ -53,8 +55,8 @@ export interface OgCardOptions {
   site?: string;
 }
 
-const WIDTH = 1200;
-const HEIGHT = 630;
+const WIDTH = OG_IMAGE_WIDTH;
+const HEIGHT = OG_IMAGE_HEIGHT;
 
 // Light neutral scale mirrored from the docs homepage theme tokens:
 // FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,

package/src/og/dimensions.ts

@@ -0,0 +1,12 @@
+/**
+ * Dimensions of a generated OG card, shared by the renderer (`card.ts`) and the
+ * layouts that declare them as `og:image:width`/`og:image:height` so a crawler
+ * can lay out the card without fetching the PNG first.
+ *
+ * This lives apart from `card.ts` because that module imports the Takumi native
+ * binding at load; a layout importing it would drag the renderer into every
+ * page render (and into the prerender/SSR bundles that externalize it).
+ */
+export const OG_IMAGE_WIDTH = 1200;
+export const OG_IMAGE_HEIGHT = 630;
+export const OG_IMAGE_TYPE = "image/png";

package/src/openapi/model.ts

@@ -104,12 +104,13 @@ const isOperation = (value: unknown): value is OperationObject =>
 /**
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
- * a repeated `operationId` still yields distinct routes.
+ * a repeated `operationId` still yields distinct routes. `warnings` reports
+ * anything skipped (a `$ref` path item), so missing operations aren't silent.
  */
 export const extractOperations = (
   document: ApiDocument,
   baseRoute: string
-): { operations: ApiOperationRef[]; tags: ApiTagRef[] } => {
+): { operations: ApiOperationRef[]; tags: ApiTagRef[]; warnings: string[] } => {
   const operations: ApiOperationRef[] = [];
   const tagOrder: string[] = [];
   const tagsSeen = new Set<string>();
@@ -117,10 +118,17 @@ export const extractOperations = (
     (document.tags ?? []).map((tag) => [tag.name, tag.description ?? ""])
   );
   const seen = new Set<string>();
+  const warnings: string[] = [];
 
   for (const [path, rawItem] of Object.entries(document.paths ?? {})) {
     const item = rawItem as PathItemObject | undefined;
-    if (!item || "$ref" in item) {
+    if (!item) {
+      continue;
+    }
+    if ("$ref" in item) {
+      warnings.push(
+        `Path "${path}" is a $ref to a shared path item; referenced path items are not resolved, so its operations are missing from the reference. Inline the path item under "paths" to render it.`
+      );
       continue;
     }
     for (const method of HTTP_METHODS) {
@@ -161,7 +169,7 @@ export const extractOperations = (
     slug: slugify(name) || "operations",
   }));
 
-  return { operations, tags };
+  return { operations, tags, warnings };
 };
 
 /** Resolve the operation object for a ref out of its document. */

package/src/openapi/parse.ts

@@ -47,6 +47,19 @@ export interface ParsedSpec {
   warnings: string[];
 }
 
+/**
+ * The spec was read successfully but its contents aren't an OpenAPI document
+ * (an empty file, or YAML that parses to a scalar or list — say, a README
+ * pointed at by mistake). Kept distinct from read/fetch failures so callers
+ * can suggest fixing the file instead of checking reachability.
+ */
+export class InvalidSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidSpecError";
+  }
+}
+
 /** Where and whether to cache a remote spec's text between runs. */
 export interface SpecFetchOptions {
   /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
@@ -235,5 +248,13 @@ export const parseSpec = async (
   const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize(text);
   const { specification } = upgrade(normalized);
+  // `normalize` yields undefined for anything that isn't a YAML/JSON mapping
+  // (empty file, scalar, list) and `upgrade(undefined)` yields a null
+  // specification — reject it here so the renderer never sees a non-document.
+  if (specification === null || typeof specification !== "object") {
+    throw new InvalidSpecError(
+      `${spec} is not a valid OpenAPI document (expected a YAML or JSON object).`
+    );
+  }
   return { document: specification as ApiDocument, warnings };
 };

package/src/openapi/references.ts

@@ -31,6 +31,12 @@ export interface ReferenceSource {
   slug: string;
   /** Normalized route the reference mounts at, e.g. `/reference`. */
   route: string;
+  /**
+   * Site-wide `basePath` the rendered pages are mounted under (`""` when
+   * none). Kept separate from `route` — the content pipeline applies it to
+   * staged entries itself — so consumers prefix only the URLs they emit.
+   */
+  basePath: string;
   label: string;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
@@ -38,6 +44,11 @@ export interface ReferenceSource {
   theme?: string;
   /** Display options carried through to the Blume renderer. */
   display: ReferenceDisplay;
+  /**
+   * Warnings recorded while deduping — another source's route collided with
+   * this one and was dropped. Surfaced as diagnostics when the source loads.
+   */
+  collisions?: string[];
 }
 
 const NON_SLUG = /[^a-z0-9]+/gu;
@@ -78,7 +89,8 @@ const referencesFor = (
   block: Block,
   defaultLabel: string,
   renderer: ReferenceRenderer,
-  display: ReferenceDisplay
+  display: ReferenceDisplay,
+  basePath: string
 ): ReferenceSource[] => {
   if (!block.enabled) {
     return [];
@@ -102,6 +114,7 @@ const referencesFor = (
     }
 
     return {
+      basePath,
       display,
       kind,
       label,
@@ -131,9 +144,17 @@ export const resolveReferences = (
     {
       codeSamples: config.openapi.codeSamples,
       expandSchemas: config.openapi.expandSchemas,
-    }
+    },
+    config.basePath
+  ),
+  ...referencesFor(
+    "asyncapi",
+    config.asyncapi,
+    "Events",
+    "scalar",
+    NO_DISPLAY,
+    config.basePath
   ),
-  ...referencesFor("asyncapi", config.asyncapi, "Events", "scalar", NO_DISPLAY),
 ];
 
 /** Nav tabs (header links) for every reference, regardless of renderer. */
@@ -152,19 +173,24 @@ export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
 /**
  * Accept one resolved reference into the deduped Blume-rendered set, or return
  * null to skip it. Mutates `seen`/`usedSlugs` so repeated routes/slugs collapse.
+ * A dropped route collision is recorded on the kept reference (mirroring the
+ * Scalar path's warning) — losing a whole spec's pages must not be silent.
  */
 const blumeReferenceOf = (
   ref: ReferenceSource,
-  seen: Set<string>,
+  seen: Map<string, ReferenceSource>,
   usedSlugs: Set<string>
 ): ReferenceSource | null => {
   if (ref.kind !== "openapi" || ref.renderer !== "blume") {
     return null;
   }
-  if (seen.has(ref.route)) {
+  const kept = seen.get(ref.route);
+  if (kept) {
+    (kept.collisions ??= []).push(
+      `Two API reference sources resolve to ${ref.route}; keeping the first.`
+    );
     return null;
   }
-  seen.add(ref.route);
   // 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
@@ -176,12 +202,16 @@ const blumeReferenceOf = (
     n += 1;
   }
   usedSlugs.add(slug);
-  return slug === ref.slug ? ref : { ...ref, slug };
+  const accepted = slug === ref.slug ? ref : { ...ref, slug };
+  // Keep the accepted object (not the original) so a later collision's warning
+  // lands on the reference the caller actually receives.
+  seen.set(ref.route, accepted);
+  return accepted;
 };
 
 /** Blume-rendered OpenAPI references, deduped by route (first wins). */
 export const blumeReferences = (config: ResolvedConfig): ReferenceSource[] => {
-  const seen = new Set<string>();
+  const seen = new Map<string, ReferenceSource>();
   const usedSlugs = new Set<string>();
   const result: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {