blume 1.1.0 → 1.1.2

package/src/components/content/diff.ts

@@ -8,13 +8,15 @@
  * a unified patch (string or `.patch`/`.diff` file), a pair of file paths, or a
  * pair of inline strings.
  */
+import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 
+import { registerCustomTheme } from "@pierre/diffs";
 import { preloadDiffHTML, preloadPatchDiff } from "@pierre/diffs/ssr";
 import { isAbsolute, join } from "pathe";
 
 import { DEFAULT_CODE_THEMES } from "../../markdown/themes.ts";
-import type { CodeThemes } from "../../markdown/themes.ts";
+import type { CodeTheme, CodeThemes } from "../../markdown/themes.ts";
 
 export interface DiffOptions {
   /** Path to the "after" file, resolved relative to {@link DiffOptions.root}. */
@@ -46,6 +48,53 @@ const resolvePath = (path: string, root: string): string =>
 const readText = (path: string, root: string): Promise<string> =>
   readFile(resolvePath(path, root), "utf-8");
 
+const registeredDiffThemes = new WeakMap<object, Map<string, string>>();
+const registeredDiffThemeNames = new Set<string>();
+
+/**
+ * Pierre accepts custom Shiki themes through its registry, while Shiki itself
+ * accepts the object directly. Register each configured object under a name
+ * derived from its content and resolved type, so registration survives
+ * dev-server reloads: the same theme resolves to the same name (already
+ * registered, so it's skipped — Pierre logs a console error on a same-name
+ * re-register), while an edited theme gets a fresh name instead of a stale
+ * entry. The memo is keyed per resolved type as well — a typeless object
+ * shared between both modes must not hand light mode the dark-typed
+ * registration.
+ */
+const diffThemeName = (theme: CodeTheme, mode: "dark" | "light"): string => {
+  if (typeof theme === "string") {
+    return theme;
+  }
+  const type = theme.type ?? mode;
+  let byType = registeredDiffThemes.get(theme);
+  if (!byType) {
+    byType = new Map();
+    registeredDiffThemes.set(theme, byType);
+  }
+  const cached = byType.get(type);
+  if (cached) {
+    return cached;
+  }
+  const hash = createHash("sha256")
+    .update(JSON.stringify(theme))
+    .digest("hex")
+    .slice(0, 12);
+  const name = `blume-custom-${hash}-${type}`;
+  if (!registeredDiffThemeNames.has(name)) {
+    const registered = { ...theme, name, type };
+    registerCustomTheme(name, () => Promise.resolve(registered));
+    registeredDiffThemeNames.add(name);
+  }
+  byType.set(type, name);
+  return name;
+};
+
+const diffThemes = (themes: CodeThemes): { dark: string; light: string } => ({
+  dark: diffThemeName(themes.dark, "dark"),
+  light: diffThemeName(themes.light, "light"),
+});
+
 /**
  * Resolve `<Diff>` inputs to a prerendered HTML string. Throws when no input
  * group is supplied or a pair is half-specified, so the component can degrade
@@ -67,7 +116,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
   if (patch !== undefined || src !== undefined) {
     const text = patch ?? (await readText(src as string, root));
     const result = await preloadPatchDiff({
-      options: { theme },
+      options: { theme: diffThemes(theme) },
       patch: text,
     });
     return result.prerenderedHTML;
@@ -80,7 +129,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     return await preloadDiffHTML({
       newFile: { contents: await readText(after, root), name: after },
       oldFile: { contents: await readText(before, root), name: before },
-      options: { theme },
+      options: { theme: diffThemes(theme) },
     });
   }
 
@@ -91,7 +140,7 @@ export const renderDiff = async (options: DiffOptions): Promise<string> => {
     return await preloadDiffHTML({
       newFile: { contents: newText, lang, name: "snippet" },
       oldFile: { contents: old, lang, name: "snippet" },
-      options: { disableFileHeader: true, theme },
+      options: { disableFileHeader: true, theme: diffThemes(theme) },
     });
   }
 

package/src/components/layout/RootLayout.astro

@@ -306,7 +306,15 @@ const mcpUrl =
 // Scope the sidebar (and the breadcrumbs/pagination derived from it) to the
 // 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);
+// `navigation.root` keeps the root-tab check in the tabs' localized/based
+// path space (`/en`, `/docs`), so a locale or base prefix doesn't misread the
+// root tab as a section tab.
+const sidebar = sidebarForRoute(
+  navigation.sidebar,
+  navigation.tabs,
+  page.route,
+  navigation.root
+);
 const activeTab = activeTabForRoute(navigation.tabs, page.route);
 const crumbs = findBreadcrumbs(sidebar, page.route);
 const { prev, next } = getPagination(flattenPages(sidebar), page.route);

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

@@ -135,12 +135,16 @@ const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean => {
  * so a root/un-tabbed route lists only the pages outside every tab's section
  * instead of duplicating each tab as a sidebar group. A container left empty by
  * this pruning is dropped too, so no bare heading is stranded. The root tab
- * (`/`) spans everything, so it never removes anything.
+ * spans everything, so it never removes anything.
  */
-const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
+const withoutTabSections = (
+  nodes: NavNode[],
+  tabs: NavTab[],
+  root: string
+): NavNode[] => {
   const tabPaths = new Set<string>();
   for (const tab of tabs) {
-    if (tab.path !== "/") {
+    if (tab.path !== root) {
       tabPaths.add(tab.path);
     }
   }
@@ -174,9 +178,15 @@ const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
  * under one tab shows only that tab's group — so a multi-section site (e.g.
  * Adapters / API / AI tabs) drills each tab into its own pages instead of one
  * global tree, the way Fumadocs' root folders do. On a route under no tab (or
- * the root `/` tab), the tab-owned groups are hidden so the root sidebar shows
+ * the root tab), the tab-owned groups are hidden so the root sidebar shows
  * only pages that don't belong to a tab.
  *
+ * `root` is the tree root in the tabs' own path space (`Navigation.root`) —
+ * tab paths arrive localized and based, so under i18n or a `basePath` the root
+ * tab is `/en` or `/docs`, not `/`. Comparing against `/` would misread it as
+ * a section tab: a root-level `(group)` folder's path is exactly that prefix,
+ * so the sidebar collapsed to that one group (or blanked entirely).
+ *
  * When a matched tab owns no sidebar group — a standalone page like the
  * generated changelog timeline (`/changelog`), or a tab whose source produced
  * no pages — the sidebar is empty. It must not fall back to the full tree: that
@@ -187,13 +197,14 @@ const withoutTabSections = (nodes: NavNode[], tabs: NavTab[]): NavNode[] => {
 export const sidebarForRoute = (
   sidebar: NavNode[],
   tabs: NavTab[],
-  route: string
+  route: string,
+  root = "/"
 ): NavNode[] => {
   const tab = activeTabForRoute(tabs, route);
-  if (tab && tab.path !== "/") {
+  if (tab && tab.path !== root) {
     return sectionChildren(sidebar, tab.path) ?? [];
   }
-  const scoped = withoutTabSections(sidebar, tabs);
+  const scoped = withoutTabSections(sidebar, tabs, root);
   return scoped.length > 0 ? scoped : sidebar;
 };
 

package/src/core/config-input.ts

@@ -1,6 +1,7 @@
 import type { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type {
   blumeConfigSchema,
@@ -568,9 +569,11 @@ export interface AiConfig {
   /**
    * Markdown serializers for custom components in agent-facing output (the
    * `.md` mirror, `llms-full.txt`, MCP `get_page`), keyed by JSX name. Each
-   * receives the component's statically-evaluated `props` and downleveled
-   * `children` and returns replacement Markdown — or `null` to leave the JSX
-   * verbatim. A same-name entry replaces a built-in serializer.
+   * receives the component's statically-evaluated `props` (with the page's
+   * `frontmatter` in scope, so `prop={frontmatter.status}` resolves), its
+   * downleveled `children`, and the page's `frontmatter` data, and returns
+   * replacement Markdown — or `null` to leave the JSX verbatim. A same-name
+   * entry replaces a built-in serializer.
    *
    * These live in `blume.config.ts` (which is executed at build time), not in
    * `components.tsx` (which is only statically analyzed, never run).
@@ -768,6 +771,13 @@ export interface OgConfig {
   logo?: string;
   /** Optional generated-card colors. */
   palette?: OgPaletteConfig;
+  /**
+   * Card headlines for custom `.astro` pages, keyed by route (`"/"`, `"/cli"`).
+   * A custom page has no frontmatter to read, so its card is otherwise titled
+   * by humanizing its last URL segment (`/cli` → "Cli"); an entry here wins.
+   * Content pages always take their card headline from the page title.
+   */
+  titles?: Record<string, string>;
 }
 
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
@@ -839,12 +849,12 @@ export interface MarkdownConfig {
    * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>`.
    */
   codeBlocks?: {
-    /** Shiki theme names per color mode. */
+    /** Bundled Shiki theme names or inline custom Shiki themes per color mode. */
     theme?: {
-      /** Dark-mode theme. Defaults to `github-dark`. */
-      dark?: string;
-      /** Light-mode theme. Defaults to `github-light`. */
-      light?: string;
+      /** Dark-mode theme name or custom theme. Defaults to `github-dark`. */
+      dark?: CodeTheme;
+      /** Light-mode theme name or custom theme. Defaults to `github-light`. */
+      light?: CodeTheme;
     };
   };
   /**

package/src/core/diagnostics.ts

@@ -38,12 +38,14 @@ const DOCS_PATHS: Record<string, string> = {
   BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
   BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
   BLUME_DUPLICATE_ROUTE: DOCS_CONTENT_NAVIGATION,
+  BLUME_DUPLICATE_SIDEBAR_ORDER: DOCS_CONTENT_NAVIGATION,
   BLUME_FRONTMATTER_INVALID: "/docs/reference/frontmatter",
   BLUME_META_INVALID: "/docs/content/meta",
   BLUME_META_LOAD_FAILED: "/docs/content/meta",
   BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
   BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
   BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
+  BLUME_NAV_INDEX_TITLE_MISMATCH: DOCS_CONTENT_NAVIGATION,
   BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
   BLUME_NODE_VERSION: "/docs/quickstart",
   BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,

package/src/core/graph.ts

@@ -70,6 +70,7 @@ const localePagesFor = (
     if (!present.has(key)) {
       filled.push({
         ...source,
+        fallback: true,
         locale: code,
         route: withBasePath(basePath, localizeRoute(key, code, i18n)),
       });
@@ -85,7 +86,8 @@ const buildLocaleNavigation = (
   fallback: FallbackLocale,
   fallbackByKey: Map<string, PageRecord>,
   options: BuildContentGraphOptions,
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  diagnostics: Diagnostic[]
 ): Navigation => {
   // Localize internal tab paths — the tab's own and its dropdown items' — so a
   // header tab points to its in-locale route (e.g. `/docs` -> `/fr/docs`);
@@ -112,6 +114,7 @@ const buildLocaleNavigation = (
   );
   return buildNavigation(localePages, {
     basePath: options.basePath ?? "",
+    diagnostics,
     display: options.navigation.sidebar.display,
     featured: options.navigation.featured,
     folderMeta: options.folderMeta,
@@ -137,7 +140,8 @@ const buildLocaleNavigation = (
 const buildI18nNavigation = (
   pages: PageRecord[],
   options: BuildContentGraphOptions,
-  i18n: ResolvedI18nConfig
+  i18n: ResolvedI18nConfig,
+  diagnostics: Diagnostic[]
 ): {
   navigation: Navigation;
   navigationByLocale: Record<string, Navigation>;
@@ -155,16 +159,30 @@ const buildI18nNavigation = (
   }
 
   // Each locale gets an independent tree, so navigation may diverge per language.
+  // Untranslated pages are padded into every locale from the fallback, so a tie
+  // in shared content would otherwise be re-reported once per locale — dedupe on
+  // code + file + message, which are all locale-stable for padded pages. A
+  // locale-specific tie names its own translated files/labels and survives.
   const navigationByLocale: Record<string, Navigation> = {};
+  const seen = new Set<string>();
   for (const { code } of i18n.locales) {
+    const localeDiagnostics: Diagnostic[] = [];
     navigationByLocale[code] = buildLocaleNavigation(
       code,
       pages,
       fallback,
       fallbackByKey,
       options,
-      i18n
+      i18n,
+      localeDiagnostics
     );
+    for (const diagnostic of localeDiagnostics) {
+      const key = `${diagnostic.code}\n${diagnostic.file ?? ""}\n${diagnostic.message}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        diagnostics.push(diagnostic);
+      }
+    }
   }
   const navigation = navigationByLocale[i18n.defaultLocale] ?? {
     featured: [],
@@ -184,10 +202,11 @@ export const buildContentGraph = (
   const { i18n } = options;
 
   const { navigation, navigationByLocale } = i18n
-    ? buildI18nNavigation(pages, options, i18n)
+    ? buildI18nNavigation(pages, options, i18n, diagnostics)
     : {
         navigation: buildNavigation(pages, {
           basePath: options.basePath ?? "",
+          diagnostics,
           display: options.navigation.sidebar.display,
           featured: options.navigation.featured,
           folderMeta: options.folderMeta,

package/src/core/navigation.ts

@@ -7,6 +7,7 @@ import type {
   SidebarItemConfig,
 } from "./schema.ts";
 import type {
+  Diagnostic,
   FeaturedLink,
   NavNode,
   Navigation,
@@ -56,7 +57,17 @@ interface MutablePage {
   badge?: string;
   deprecated?: boolean;
   pageId: string;
+  /** Absolute source path (filesystem adapter only), to anchor diagnostics. */
+  file?: string;
   order: number;
+  /**
+   * Whether `order` reflects a deliberate authoring choice (explicit
+   * `sidebar.order`, a numeric filename prefix, or a folder-meta `pages` rank)
+   * rather than a derived value like a changelog entry's publish date — two
+   * changelog entries published on the same day aren't an authoring mistake,
+   * so they're excluded from the duplicate-order diagnostic.
+   */
+  orderIsAuthored: boolean;
 }
 
 interface MutableGroup {
@@ -110,24 +121,35 @@ const ensureGroup = (
   return group;
 };
 
-const pageOrder = (page: PageRecord, filename: string): number => {
+const pageOrder = (
+  page: PageRecord,
+  filename: string
+): { order: number; orderIsAuthored: boolean } => {
   if (page.meta.sidebar.order !== undefined) {
-    return page.meta.sidebar.order;
+    return { order: page.meta.sidebar.order, orderIsAuthored: true };
   }
   if (isIndexStem(filename.replace(extname(filename), ""))) {
-    return Number.NEGATIVE_INFINITY;
+    return { order: Number.NEGATIVE_INFINITY, orderIsAuthored: false };
   }
   // Changelog entries read newest-first, matching the generated timeline. Sort
   // on the negated publish timestamp so a later date yields a smaller order
   // under the ascending comparator; undated entries fall back to filename order.
+  // The date is derived, not an authoring choice, so same-day entries aren't a
+  // duplicate-order mistake.
   if (page.contentType === "changelog") {
     const iso = page.meta.date ?? page.meta.changelog?.date;
     const time = iso ? Date.parse(iso) : Number.NaN;
     if (!Number.isNaN(time)) {
-      return -time;
+      return { order: -time, orderIsAuthored: false };
     }
   }
-  return numericOrder(filename);
+  // An undated changelog entry's numeric filename prefix is usually a date
+  // (`2024-01-05-release.md`) rather than a rank, so it is derived too.
+  const order = numericOrder(filename);
+  return {
+    order,
+    orderIsAuthored: page.contentType !== "changelog" && Number.isFinite(order),
+  };
 };
 
 /**
@@ -166,6 +188,9 @@ const applyFolderMeta = (
         const position = rank.get(child.key);
         if (position !== undefined) {
           child.order = position;
+          if (child.kind === "page") {
+            child.orderIsAuthored = true;
+          }
         }
       }
     }
@@ -178,7 +203,108 @@ const applyFolderMeta = (
   }
 };
 
-const sortNodes = (nodes: MutableNode[]): void => {
+/**
+ * Warn when an index page's own frontmatter title diverges from its folder's
+ * explicit `meta.title`. The sidebar label and the page's own `<title>`/heading
+ * are resolved from two independent sources — under i18n, a translator can
+ * update the folder's `meta.ts` and forget the index page's own frontmatter
+ * (or vice versa), and a correct-looking sidebar hides the mismatch.
+ *
+ * Only fires when the page has an explicit frontmatter `title` of its own:
+ * when it's absent, `page.title` is derived from the first heading or the
+ * filename, so it almost never coincidentally matches a custom folder title —
+ * flagging that would be noise on exactly the plain-landing-page case this is
+ * least worth warning about. The root group's `meta.title` (an empty
+ * `folderPath`) is also skipped: nothing ever renders it as a sidebar label,
+ * so a mismatch there wouldn't correspond to anything visible.
+ *
+ * Fallback-filled pages are exempt: their title belongs to the fallback
+ * locale, so comparing it against this locale's `meta.title` would flag every
+ * not-yet-translated index page (once per locale) and point the suggestion at
+ * the fallback locale's source file, where "fixing" it would break that
+ * locale. The default locale's own build still checks the real page.
+ */
+const indexTitleMismatchDiagnostic = (
+  page: PageRecord,
+  folderPath: string,
+  folderMeta: Map<string, FolderMeta>,
+  sharedMeta: Map<string, FolderMeta>,
+  metaPrefix: string
+): Diagnostic | undefined => {
+  if (!page.meta.title || page.fallback || folderPath === "") {
+    return undefined;
+  }
+  const meta =
+    folderMeta.get(metaKey(folderPath, metaPrefix)) ??
+    sharedMeta.get(folderPath);
+  if (!meta?.title || meta.title === page.title) {
+    return undefined;
+  }
+  return {
+    code: "BLUME_NAV_INDEX_TITLE_MISMATCH",
+    file: page.sourcePath ?? page.id,
+    message: `Index page "${page.navPath}" has title "${page.title}", but its folder's meta.title is "${meta.title}" — the sidebar shows the folder title while the page's own <title>/heading still say "${page.title}".`,
+    severity: "warning",
+    suggestion: `Update the page's frontmatter title to match ("${meta.title}"), or leave it if the divergence is intentional.`,
+  };
+};
+
+/** Whether a node's `order` reflects a deliberate authoring choice. */
+const isAuthoredOrder = (node: MutableNode): boolean =>
+  node.kind === "group" || node.orderIsAuthored;
+
+/**
+ * Warn when two sibling nodes share an explicit/numeric order (frontmatter
+ * `sidebar.order`, a numeric filename prefix, or folder-meta `order`) — they'd
+ * otherwise fall back to a silent, arbitrary alphabetical tiebreak. Nodes at
+ * the default fallback order (no numeric prefix, no explicit order) are
+ * excluded: that's the common, intentional case of "just sort alphabetically."
+ * So is a derived, non-authored order (e.g. two changelog entries published
+ * on the same day) — not an authoring mistake.
+ */
+const duplicateOrderDiagnostics = (nodes: MutableNode[]): Diagnostic[] => {
+  const byOrder = new Map<number, MutableNode[]>();
+  for (const node of nodes) {
+    if (!Number.isFinite(node.order) || !isAuthoredOrder(node)) {
+      continue;
+    }
+    const tied = byOrder.get(node.order);
+    if (tied) {
+      tied.push(node);
+    } else {
+      byOrder.set(node.order, [node]);
+    }
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const [order, tied] of byOrder) {
+    if (tied.length > 1) {
+      const names = tied.map((node) => `"${node.label}"`);
+      const list =
+        names.length > 2
+          ? `${names.slice(0, -1).join(", ")}, and ${names.at(-1)}`
+          : names.join(" and ");
+      const verb = tied.length > 2 ? "all have" : "both have";
+      // Anchor the diagnostic to one tied source file so tooling can point
+      // somewhere concrete; the message names the rest. Folder-only ties
+      // (folder-meta `order`) have no single file, so `file` stays unset.
+      const file = tied.find(
+        (node): node is MutablePage => node.kind === "page"
+      )?.file;
+      diagnostics.push({
+        code: "BLUME_DUPLICATE_SIDEBAR_ORDER",
+        file,
+        message: `${list} ${verb} sidebar order ${order}; falling back to alphabetical order.`,
+        severity: "warning",
+        suggestion:
+          "Give each item a distinct sidebar.order (or folder meta order).",
+      });
+    }
+  }
+  return diagnostics;
+};
+
+const sortNodes = (nodes: MutableNode[], diagnostics: Diagnostic[]): void => {
+  diagnostics.push(...duplicateOrderDiagnostics(nodes));
   nodes.sort((a, b) => {
     if (a.order !== b.order) {
       return a.order - b.order;
@@ -187,7 +313,7 @@ const sortNodes = (nodes: MutableNode[]): void => {
   });
   for (const node of nodes) {
     if (node.kind === "group") {
-      sortNodes(node.children);
+      sortNodes(node.children, diagnostics);
     }
   }
 };
@@ -263,20 +389,37 @@ const buildFileSystemSidebar = (
   sharedMeta: Map<string, FolderMeta>,
   metaPrefix: string,
   display: SidebarDisplay,
-  tabPaths: Set<string>
+  tabPaths: Set<string>,
+  diagnostics: Diagnostic[] = []
 ): NavNode[] => {
   const root = createGroup("", "", "", 0);
 
   for (const page of pages) {
-    if (page.meta.sidebar.hidden) {
-      continue;
-    }
     // Group by the locale-stripped path so the locale dir is not a nav group.
     const parts = page.navPath.split("/");
     const filename = parts.at(-1) ?? page.navPath;
     const stem = filename.replace(extname(filename), "");
     const dirs = parts.slice(0, -1);
 
+    // Checked before the hidden filter: a sidebar-hidden index page still
+    // renders with its own <title>, so title drift matters there just the same.
+    if (isIndexStem(stem)) {
+      const diagnostic = indexTitleMismatchDiagnostic(
+        page,
+        dirs.join("/"),
+        folderMeta,
+        sharedMeta,
+        metaPrefix
+      );
+      if (diagnostic) {
+        diagnostics.push(diagnostic);
+      }
+    }
+
+    if (page.meta.sidebar.hidden) {
+      continue;
+    }
+
     // Each group's URL path is the matching prefix of the page's route. navPath
     // is locale-stripped while the route may carry a locale/base prefix, so
     // align the folder segments from the right (the extra leading segments are
@@ -301,22 +444,25 @@ const buildFileSystemSidebar = (
       parent.routePath ??= `/${folderParts.slice(0, consumed).join("/")}`;
     }
 
+    const { order, orderIsAuthored } = pageOrder(page, filename);
     parent.children.push({
       badge: page.meta.sidebar.badge,
       deprecated: page.meta.deprecated || undefined,
       description: page.description,
+      file: page.sourcePath,
       icon: page.meta.sidebar.icon,
       key: segmentKey(stem),
       kind: "page",
       label: page.meta.sidebar.label ?? page.title,
-      order: pageOrder(page, filename),
+      order,
+      orderIsAuthored,
       pageId: page.id,
       route: page.route,
     });
   }
 
   applyFolderMeta(root, folderMeta, sharedMeta, metaPrefix);
-  sortNodes(root.children);
+  sortNodes(root.children, diagnostics);
   hoistPages(root.children, display === "flat");
   hoistTabSections(root.children, tabPaths, display === "flat");
   return root.children.map((child) => toNavNode(child, display));
@@ -500,6 +646,12 @@ export const buildNavigation = (
      * scoping.
      */
     localizedRoot?: string;
+    /**
+     * Sink for diagnostics produced while building the tree (duplicate sidebar
+     * `order` values, index-page title/folder-meta-title mismatches). Pushed
+     * into in place; omit to discard.
+     */
+    diagnostics?: Diagnostic[];
   }
 ): Navigation => {
   const basePath = options.basePath ?? "";
@@ -555,6 +707,15 @@ export const buildNavigation = (
     }
   }
 
+  // A tab pointing at the tree root spans the whole sidebar rather than one
+  // section, so it must not feed tab-section hoisting. `tabs` carries final
+  // paths (localized, then based), so the root is compared in the same space —
+  // a root-level `(group)` folder's routePath is exactly the based/localized
+  // prefix (`/docs`, `/fr`) and a bare `"/"` check would miss the match (or,
+  // under a base, falsely scope a group named like the prefix). Carried on the
+  // returned navigation so render-time scoping compares in the same space too.
+  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
+
   if (options.sidebar) {
     const sidebar = buildConfigSidebar(
       options.sidebar,
@@ -564,29 +725,27 @@ export const buildNavigation = (
     );
     return {
       featured,
+      root: rootTabPath,
       selectors,
       sidebar,
       tabs: withTabHrefs(tabs, sidebar),
     };
   }
 
-  // A tab pointing at the tree root spans the whole sidebar rather than one
-  // section, so it must not feed tab-section hoisting. `tabs` carries final
-  // paths (localized, then based), so the root is compared in the same space —
-  // a root-level `(group)` folder's routePath is exactly the based/localized
-  // 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])))
+    new Set(
+      tabs.flatMap((tab) => (tab.path === rootTabPath ? [] : [tab.path]))
+    ),
+    options.diagnostics
   );
   return {
     featured,
+    root: rootTabPath,
     selectors,
     sidebar,
     tabs: withTabHrefs(tabs, sidebar),