blume 0.6.7 → 0.7.0

package/src/core/config-input.ts

@@ -315,11 +315,16 @@ export interface NavSelectorItem {
  * A header dropdown for switching context — versions, languages, products, or a
  * generic dropdown. `kind` drives the icon and a11y labeling.
  */
+/** Context-partition selector kinds (a versioned/localized/multi-product site). */
+type NavSelectorContextKind = "product" | "version";
+/** What a header selector switches between. */
+type NavSelectorKind = "dropdown" | "language" | NavSelectorContextKind;
+
 export interface NavSelector {
   /** The options shown in the dropdown. */
   items?: NavSelectorItem[];
   /** What the selector switches between. */
-  kind: "dropdown" | "language" | "product" | "version";
+  kind: NavSelectorKind;
   /** Selector label / current value. */
   label: string;
 }
@@ -385,6 +390,11 @@ export interface FontsConfig {
 }
 
 /** Colors, fonts, radius, and color-mode behavior. */
+/** Corner radius scale (`none`/`sm` tighter, `md`/`lg` rounder). */
+type RadiusScaleTight = "none" | "sm";
+type RadiusScaleRound = "md" | "lg";
+type RadiusScale = RadiusScaleTight | RadiusScaleRound;
+
 export interface ThemeConfig {
   /**
    * Accent color. A palette name (`blue`, `violet`, `green`, …) or any CSS
@@ -405,7 +415,7 @@ export interface ThemeConfig {
   /** Initial color mode. Defaults to `system`. */
   mode?: "system" | "light" | "dark";
   /** Corner radius scale. Defaults to `md`. */
-  radius?: "none" | "sm" | "md" | "lg";
+  radius?: RadiusScale;
 }
 
 // ---------------------------------------------------------------------------
@@ -477,6 +487,10 @@ export interface AskSuggestion {
 }
 
 /** The Ask AI chat assistant. */
+/** Backends that can route an Ask AI request. */
+type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
+type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+
 export interface AskConfig {
   /**
    * Name of the env var holding the provider API key. Each provider has a
@@ -493,12 +507,7 @@ export interface AskConfig {
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
-  provider?:
-    | "gateway"
-    | "openrouter"
-    | "llmgateway"
-    | "inkeep"
-    | "openai-compatible";
+  provider?: AskProvider;
   /** Starter prompts shown before the first question. */
   suggestions?: AskSuggestion[];
 }
@@ -603,9 +612,13 @@ export interface I18nConfig {
  * Where and how the site deploys. `site` (and `adapter`) are auto-detected from
  * the platform env on Vercel, Netlify, and Cloudflare.
  */
+/** Astro server-output adapters, by hosting platform. */
+type CloudDeploymentAdapter = "netlify" | "cloudflare";
+type DeploymentAdapter = "vercel" | "node" | CloudDeploymentAdapter;
+
 export interface DeploymentConfig {
   /** Astro adapter for server output. `null` (default) keeps a static build. */
-  adapter?: "vercel" | "node" | "netlify" | "cloudflare" | null;
+  adapter?: DeploymentAdapter | null;
   /** Base path when the site is served from a subdirectory. */
   base?: string;
   /** Build output mode. Defaults to `static`. */
@@ -617,12 +630,17 @@ export interface DeploymentConfig {
   site?: string;
 }
 
+/** HTTP redirect status codes: permanent (301/308) and temporary (302/307). */
+type RedirectStatusPermanent = 301 | 308;
+type RedirectStatusTemporary = 302 | 307;
+type RedirectStatus = RedirectStatusPermanent | RedirectStatusTemporary;
+
 /** A URL redirect rule. */
 export interface RedirectConfig {
   /** Path to redirect from. */
   from: string;
   /** HTTP status. Defaults to `301`. */
-  status?: 301 | 302 | 307 | 308;
+  status?: RedirectStatus;
   /** Path or URL to redirect to. */
   to: string;
 }
@@ -717,7 +735,10 @@ export interface CodeConfig {
 export interface MarkdownConfig {
   /** Code-block rendering: language icons, line wrap. */
   code?: CodeConfig;
-  /** Syntax-highlighting themes for fenced code blocks. */
+  /**
+   * Syntax-highlighting themes for every code surface — fenced blocks, inline
+   * `` `code`{:lang} ``, `<CodeBlock>`, and `<Diff>`.
+   */
   codeBlocks?: {
     /** Shiki theme names per color mode. */
     theme?: {
@@ -736,6 +757,16 @@ export interface MarkdownConfig {
   imageZoom?: boolean;
 }
 
+/** React island behavior. */
+export interface ReactConfig {
+  /**
+   * Auto-memoize React components/hooks with the React Compiler
+   * (`babel-plugin-react-compiler`). On by default whenever React is enabled;
+   * set to `false` to skip the compiler's babel pass. Defaults to `true`.
+   */
+  compiler?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // OpenAPI / AsyncAPI
 // ---------------------------------------------------------------------------
@@ -787,6 +818,25 @@ export interface AsyncApiConfig {
 // Misc top-level unions
 // ---------------------------------------------------------------------------
 
+/** `<Component />` example previews (the object form of `examples`). */
+export interface ExamplesConfig {
+  /**
+   * A stylesheet, relative to the project root, injected into every preview
+   * frame after Blume's default tokens. Previews render inside an isolated
+   * iframe the docs styles never reach, so design tokens for the previewed
+   * components — shadcn variables, `@theme` mappings, custom fonts — live
+   * here. Tailwind is already provided in the frame; the file should hold
+   * tokens and styles, not another `@import "tailwindcss"`.
+   */
+  css?: string;
+  /**
+   * Where example files live, relative to the project root. Defaults to
+   * `examples`; may be a glob to target a registry that colocates component
+   * sources with their examples (e.g. `registry/<pkg>/**\/examples/*`).
+   */
+  source?: string;
+}
+
 /**
  * Reader-facing "Export" page actions. A boolean toggles both formats; the
  * object form enables each individually. Defaults to `false`.
@@ -843,6 +893,16 @@ export interface BlumeConfig {
   asyncapi?: AsyncApiConfig;
   /** Site-wide announcement banner shown above the header. */
   banner?: BannerConfig;
+  /**
+   * Site-wide mount point prepended to every generated route (e.g. `/docs`) —
+   * pages, links, redirects, sitemap, OG images, `llms.txt`, and the search
+   * index — while staying invisible to the sidebar/nav tree (no wrapper group).
+   * Distinct from a per-source `prefix` (which namespaces one source *and*
+   * creates a group) and from `deployment.base` (Astro's host-subdirectory
+   * base, for serving the whole site — root included — from a subpath). The two
+   * compose: with both set, a page lands at `{deployment.base}/{basePath}/page`.
+   */
+  basePath?: string;
   /** Where content lives and how it's discovered. */
   content?: ContentConfig;
   /** Where and how the site deploys (site URL, adapter, output mode). */
@@ -850,11 +910,15 @@ export interface BlumeConfig {
   /** Default meta description, used where a page sets none. */
   description?: string;
   /**
-   * Where `<Component path>` resolves live previews and their source from,
-   * relative to the project root. Defaults to `examples`. May be a glob to
-   * target a registry that colocates component sources with their examples.
+   * `<Component path>` example previews. A string is shorthand for
+   * `{ source }`: where examples live, relative to the project root (defaults
+   * to `examples`; may be a glob to target a registry that colocates
+   * component sources with their examples). The object form adds `css` — a
+   * stylesheet injected into every preview frame (previews render in an
+   * iframe the docs theme never reaches), for the previewed components'
+   * design tokens, e.g. shadcn variables.
    */
-  examples?: string;
+  examples?: string | ExamplesConfig;
   /** Reader-facing PDF/EPUB export actions. Defaults to `false`. */
   export?: ExportConfig;
   /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
@@ -875,6 +939,8 @@ export interface BlumeConfig {
   navigation?: NavigationConfig;
   /** Native OpenAPI reference. */
   openapi?: OpenApiConfig;
+  /** React island behavior (compiler auto-memoization). */
+  react?: ReactConfig;
   /** URL redirect rules. */
   redirects?: RedirectConfig[];
   /** Search backend and credentials. */

package/src/core/config.ts

@@ -91,8 +91,9 @@ import type { Diagnostic } from "./types.ts";
  * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
  *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
  *
- * - `examples` — where `<Component path>` previews resolve their source from
- *   (defaults to `examples/`; supports a glob for colocated registries).
+ * - `examples` — `<Component path>` previews: `source` (default `examples/`;
+ *   supports a glob for colocated registries) and `css`, a stylesheet injected
+ *   into the isolated preview frames (e.g. shadcn variables).
  *
  * @example Zero-config — just render the Markdown under `docs/`.
  * ```ts
@@ -197,11 +198,12 @@ export const loadConfig = async (
     };
     // Surface every issue in one failing run — reporting only the first turns
     // a three-mistake config into three fix-rerun-fail loops.
+    const moreIssues = rest.map((d) => `  - ${d.message}`).join("\n");
     throw new BlumeError(
       rest.length > 0
         ? {
             ...primary,
-            message: `${primary.message}\n${rest.length} more config issue(s):\n${rest.map((d) => `  - ${d.message}`).join("\n")}`,
+            message: `${primary.message}\n${rest.length} more config issue(s):\n${moreIssues}`,
           }
         : primary
     );

package/src/core/content.ts

@@ -22,6 +22,7 @@ export const discoverContent = async (options: {
   include: string[];
   exclude: string[];
   defaultType: string;
+  basePath?: string;
   i18n?: ResolvedI18nConfig;
 }): Promise<{ pages: PageRecord[]; diagnostics: Diagnostic[] }> => {
   const source = filesystemSource({
@@ -38,6 +39,7 @@ export const discoverContent = async (options: {
 
   for (const entry of entries) {
     const normalized = normalizeEntry(entry, {
+      basePath: options.basePath ?? "",
       defaultType: options.defaultType,
       i18n: options.i18n,
       source: { name: source.name, prefix: source.prefix, staged: false },

package/src/core/data.ts

@@ -93,6 +93,8 @@ export interface BlumeDataConfig {
     suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;
+  /** `markdown.codeBlocks.theme`: light/dark Shiki themes for code surfaces. */
+  codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
   codeWrap: boolean;
   description: string | undefined;

package/src/core/diagnostics.ts

@@ -20,35 +20,40 @@ export const createDiagnostic = (diagnostic: Diagnostic): Diagnostic =>
 /** Docs site base; diagnostic help links resolve against it. */
 const DOCS_BASE = "https://useblume.dev";
 
+const DOCS_DEPLOYMENT = "/docs/deployment";
+const DOCS_REFERENCE_CLI = "/docs/reference/cli";
+const DOCS_CONTENT_SOURCES = "/docs/content/sources";
+const DOCS_CONTENT_NAVIGATION = "/docs/content/navigation";
+
 /** Diagnostic code → the docs page that explains it. */
 const DOCS_PATHS: Record<string, string> = {
-  BLUME_ADAPTER_REQUIRED: "/docs/deployment",
-  BLUME_ASSETS_UNCHECKED: "/docs/reference/cli",
-  BLUME_ASSET_FETCH_FAILED: "/docs/content/sources",
-  BLUME_BROKEN_ANCHOR: "/docs/reference/cli",
-  BLUME_BROKEN_ASSET: "/docs/reference/cli",
-  BLUME_BROKEN_LINK: "/docs/reference/cli",
+  BLUME_ADAPTER_REQUIRED: DOCS_DEPLOYMENT,
+  BLUME_ASSETS_UNCHECKED: DOCS_REFERENCE_CLI,
+  BLUME_ASSET_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+  BLUME_BROKEN_ANCHOR: DOCS_REFERENCE_CLI,
+  BLUME_BROKEN_ASSET: DOCS_REFERENCE_CLI,
+  BLUME_BROKEN_LINK: DOCS_REFERENCE_CLI,
   BLUME_CONFIG_INVALID: "/docs/configuration",
   BLUME_CONFIG_LOAD_FAILED: "/docs/configuration",
-  BLUME_CONTENT_ROOT_MISSING: "/docs/content/sources",
-  BLUME_DEAD_LINK: "/docs/reference/cli",
-  BLUME_DUPLICATE_ROUTE: "/docs/content/navigation",
+  BLUME_CONTENT_ROOT_MISSING: DOCS_CONTENT_SOURCES,
+  BLUME_DEAD_LINK: DOCS_REFERENCE_CLI,
+  BLUME_DUPLICATE_ROUTE: 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_MISSING_PAGE: "/docs/content/navigation",
+  BLUME_MISSING_SECRET: DOCS_DEPLOYMENT,
+  BLUME_NAV_DUPLICATE_LABEL: DOCS_CONTENT_NAVIGATION,
+  BLUME_NAV_HIDDEN_IN_SIDEBAR: DOCS_CONTENT_NAVIGATION,
+  BLUME_NAV_MISSING_PAGE: DOCS_CONTENT_NAVIGATION,
   BLUME_NODE_VERSION: "/docs/quickstart",
-  BLUME_SERVER_FEATURE_REQUIRED: "/docs/deployment",
-  BLUME_SOURCE_FETCH_FAILED: "/docs/content/sources",
-  BLUME_SOURCE_MISCONFIGURED: "/docs/content/sources",
-  BLUME_SOURCE_OFFLINE: "/docs/content/sources",
-  BLUME_SOURCE_SDK_MISSING: "/docs/content/sources",
-  BLUME_SOURCE_UNAVAILABLE: "/docs/content/sources",
+  BLUME_SERVER_FEATURE_REQUIRED: DOCS_DEPLOYMENT,
+  BLUME_SOURCE_FETCH_FAILED: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_MISCONFIGURED: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_OFFLINE: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_SDK_MISSING: DOCS_CONTENT_SOURCES,
+  BLUME_SOURCE_UNAVAILABLE: DOCS_CONTENT_SOURCES,
   BLUME_UNKNOWN_COMPONENT: "/docs/configuration/customization",
-  BLUME_UNKNOWN_ICON: "/docs/content/navigation",
+  BLUME_UNKNOWN_ICON: DOCS_CONTENT_NAVIGATION,
 };
 
 /** The docs URL that explains a diagnostic code, if one is mapped. */
@@ -74,6 +79,29 @@ const escapeRegExp = (value: string): string =>
  * lands under its parent. Array indices are skipped. Returns 1-based line/column,
  * or undefined when nothing matches.
  */
+const stepSegment = (
+  source: string,
+  segment: string | number,
+  cursor: number
+): { index: number; next: number; stop: boolean } => {
+  // A non-string path segment (array index) is skipped without moving on.
+  if (typeof segment !== "string") {
+    return { index: -1, next: cursor, stop: false };
+  }
+  // The negative lookbehind keeps a segment like `title` from matching the
+  // tail of an unrelated key such as `subtitle:`.
+  const matcher = new RegExp(
+    `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
+    "gu"
+  );
+  matcher.lastIndex = cursor;
+  const match = matcher.exec(source);
+  if (!match) {
+    return { index: -1, next: cursor, stop: true };
+  }
+  return { index: match.index, next: matcher.lastIndex, stop: false };
+};
+
 const locatePath = (
   source: string,
   path: readonly (string | number)[]
@@ -81,22 +109,14 @@ const locatePath = (
   let cursor = 0;
   let found = -1;
   for (const segment of path) {
-    if (typeof segment !== "string") {
-      continue;
-    }
-    // The negative lookbehind keeps a segment like `title` from matching the
-    // tail of an unrelated key such as `subtitle:`.
-    const matcher = new RegExp(
-      `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
-      "gu"
-    );
-    matcher.lastIndex = cursor;
-    const match = matcher.exec(source);
-    if (!match) {
+    const step = stepSegment(source, segment, cursor);
+    if (step.stop) {
       break;
     }
-    found = match.index;
-    cursor = matcher.lastIndex;
+    cursor = step.next;
+    if (step.index >= 0) {
+      found = step.index;
+    }
   }
   if (found < 0) {
     return;

package/src/core/gitignore.ts

@@ -18,7 +18,10 @@ export const ensureGitignore = async (
   const path = join(root, ".gitignore");
   const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
   const present = new Set(
-    existing.split("\n").map(gitignoreKey).filter(Boolean)
+    existing.split("\n").flatMap((line) => {
+      const key = gitignoreKey(line);
+      return key ? [key] : [];
+    })
   );
   const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
   if (added.length === 0) {

package/src/core/graph.ts

@@ -1,3 +1,4 @@
+import { withBasePath } from "./base-path.ts";
 import { localizeRoute, resolveFallbackLocale } from "./i18n.ts";
 import { validateNavIcons, validateNavStructure } from "./nav-diagnostics.ts";
 import { buildNavigation } from "./navigation.ts";
@@ -13,19 +14,23 @@ import type {
   PageRecord,
 } from "./types.ts";
 
-/** Assemble the content graph: routes map, nav, and duplicate diagnostics. */
-export const buildContentGraph = (
-  pages: PageRecord[],
-  options: {
-    folderMeta: Map<string, FolderMeta>;
-    sharedFolderMeta?: Map<string, FolderMeta>;
-    navigation: ResolvedConfig["navigation"];
-    i18n?: ResolvedI18nConfig;
-  }
-): ContentGraph => {
+interface BuildContentGraphOptions {
+  /** Site-wide route mount point (`""` or `/seg`); invisible to the nav tree. */
+  basePath?: string;
+  folderMeta: Map<string, FolderMeta>;
+  sharedFolderMeta?: Map<string, FolderMeta>;
+  navigation: ResolvedConfig["navigation"];
+  i18n?: ResolvedI18nConfig;
+}
+
+type FallbackLocale = ReturnType<typeof resolveFallbackLocale>;
+
+/** Build the route → page-id map, flagging any duplicate-route collisions. */
+const collectRoutes = (
+  pages: PageRecord[]
+): { diagnostics: Diagnostic[]; routes: Map<string, string> } => {
   const routes = new Map<string, string>();
   const diagnostics: Diagnostic[] = [];
-
   for (const page of pages) {
     const existing = routes.get(page.route);
     if (existing) {
@@ -40,94 +45,157 @@ export const buildContentGraph = (
     }
     routes.set(page.route, page.id);
   }
+  return { diagnostics, routes };
+};
 
-  const { i18n } = options;
-  const navigationByLocale: Record<string, Navigation> = {};
-  let navigation: Navigation;
-
-  if (i18n) {
-    // Pages of the fallback locale, by translation key — used to fill in a
-    // locale's sidebar for pages it hasn't translated yet, so navigation mirrors
-    // the default structure instead of showing an empty (or partial) tree.
-    const fallback = resolveFallbackLocale(i18n);
-    const fallbackByKey = new Map<string, PageRecord>();
-    if (fallback) {
-      for (const page of pages) {
-        if (page.locale === fallback) {
-          fallbackByKey.set(page.translationKey, page);
-        }
-      }
+/**
+ * A locale's pages, padded with fallback-locale entries for any translation it
+ * hasn't authored yet, so navigation mirrors the default structure instead of
+ * showing an empty (or partial) tree.
+ */
+const localePagesFor = (
+  code: string,
+  real: PageRecord[],
+  fallback: FallbackLocale,
+  fallbackByKey: Map<string, PageRecord>,
+  i18n: ResolvedI18nConfig,
+  basePath: string
+): PageRecord[] => {
+  if (!(fallback && code !== fallback)) {
+    return real;
+  }
+  const present = new Set(real.map((page) => page.translationKey));
+  const filled: PageRecord[] = [];
+  for (const [key, source] of fallbackByKey) {
+    if (!present.has(key)) {
+      filled.push({
+        ...source,
+        locale: code,
+        route: withBasePath(basePath, localizeRoute(key, code, i18n)),
+      });
     }
+  }
+  return [...real, ...filled];
+};
 
-    // Each locale gets an independent tree from its own pages and folder meta,
-    // so navigation may diverge per language.
-    for (const { code } of i18n.locales) {
-      // Localize internal tab paths so a header tab points to its in-locale
-      // route (e.g. `/docs` -> `/fr/docs`); external paths pass through.
-      const tabs = options.navigation.tabs?.map((tab) => ({
-        ...tab,
-        path: tab.path.startsWith("/")
-          ? localizeRoute(tab.path, code, i18n)
-          : tab.path,
-      }));
+/** Build one locale's navigation tree from its own pages and folder meta. */
+const buildLocaleNavigation = (
+  code: string,
+  pages: PageRecord[],
+  fallback: FallbackLocale,
+  fallbackByKey: Map<string, PageRecord>,
+  options: BuildContentGraphOptions,
+  i18n: ResolvedI18nConfig
+): Navigation => {
+  // Localize internal tab paths so a header tab points to its in-locale route
+  // (e.g. `/docs` -> `/fr/docs`); external paths pass through.
+  const tabs = options.navigation.tabs?.map((tab) => ({
+    ...tab,
+    path: tab.path.startsWith("/")
+      ? localizeRoute(tab.path, code, i18n)
+      : tab.path,
+  }));
+  const real = pages.filter((page) => page.locale === code);
+  const localePages = localePagesFor(
+    code,
+    real,
+    fallback,
+    fallbackByKey,
+    i18n,
+    options.basePath ?? ""
+  );
+  return buildNavigation(localePages, {
+    basePath: options.basePath ?? "",
+    display: options.navigation.sidebar.display,
+    featured: options.navigation.featured,
+    folderMeta: options.folderMeta,
+    // Meta files live in locale directories only under the `dir` parser
+    // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations sit
+    // next to the originals and `guides/meta.ts` applies to every locale —
+    // prefixing would look up keys that can never exist.
+    metaPrefix:
+      i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
+    refByLogical: true,
+    selectors: options.navigation.selectors,
+    sharedFolderMeta: options.sharedFolderMeta,
+    sidebar: options.navigation.sidebar.items,
+    tabs,
+  });
+};
 
-      const real = pages.filter((page) => page.locale === code);
-      let localePages = real;
-      if (fallback && code !== fallback) {
-        const present = new Set(real.map((page) => page.translationKey));
-        const filled: PageRecord[] = [];
-        for (const [key, source] of fallbackByKey) {
-          if (!present.has(key)) {
-            filled.push({
-              ...source,
-              locale: code,
-              route: localizeRoute(key, code, i18n),
-            });
-          }
-        }
-        localePages = [...real, ...filled];
+/** Per-locale navigation trees plus the default-locale tree for i18n sites. */
+const buildI18nNavigation = (
+  pages: PageRecord[],
+  options: BuildContentGraphOptions,
+  i18n: ResolvedI18nConfig
+): {
+  navigation: Navigation;
+  navigationByLocale: Record<string, Navigation>;
+} => {
+  // Pages of the fallback locale, by translation key — used to fill in a
+  // locale's sidebar for pages it hasn't translated yet.
+  const fallback = resolveFallbackLocale(i18n);
+  const fallbackByKey = new Map<string, PageRecord>();
+  if (fallback) {
+    for (const page of pages) {
+      if (page.locale === fallback) {
+        fallbackByKey.set(page.translationKey, page);
       }
-
-      navigationByLocale[code] = buildNavigation(localePages, {
-        display: options.navigation.sidebar.display,
-        featured: options.navigation.featured,
-        folderMeta: options.folderMeta,
-        // Meta files live in locale directories only under the `dir` parser
-        // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations
-        // sit next to the originals and `guides/meta.ts` applies to every
-        // locale — prefixing would look up keys that can never exist.
-        metaPrefix:
-          i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
-        refByLogical: true,
-        selectors: options.navigation.selectors,
-        sharedFolderMeta: options.sharedFolderMeta,
-        sidebar: options.navigation.sidebar.items,
-        tabs,
-      });
     }
-    navigation = navigationByLocale[i18n.defaultLocale] ?? {
-      featured: [],
-      selectors: [],
-      sidebar: [],
-      tabs: [],
-    };
-  } else {
-    navigation = buildNavigation(pages, {
-      display: options.navigation.sidebar.display,
-      featured: options.navigation.featured,
-      folderMeta: options.folderMeta,
-      selectors: options.navigation.selectors,
-      sharedFolderMeta: options.sharedFolderMeta,
-      sidebar: options.navigation.sidebar.items,
-      tabs: options.navigation.tabs,
-    });
   }
 
+  // Each locale gets an independent tree, so navigation may diverge per language.
+  const navigationByLocale: Record<string, Navigation> = {};
+  for (const { code } of i18n.locales) {
+    navigationByLocale[code] = buildLocaleNavigation(
+      code,
+      pages,
+      fallback,
+      fallbackByKey,
+      options,
+      i18n
+    );
+  }
+  const navigation = navigationByLocale[i18n.defaultLocale] ?? {
+    featured: [],
+    selectors: [],
+    sidebar: [],
+    tabs: [],
+  };
+  return { navigation, navigationByLocale };
+};
+
+/** Assemble the content graph: routes map, nav, and duplicate diagnostics. */
+export const buildContentGraph = (
+  pages: PageRecord[],
+  options: BuildContentGraphOptions
+): ContentGraph => {
+  const { diagnostics, routes } = collectRoutes(pages);
+  const { i18n } = options;
+
+  const { navigation, navigationByLocale } = i18n
+    ? buildI18nNavigation(pages, options, i18n)
+    : {
+        navigation: buildNavigation(pages, {
+          basePath: options.basePath ?? "",
+          display: options.navigation.sidebar.display,
+          featured: options.navigation.featured,
+          folderMeta: options.folderMeta,
+          selectors: options.navigation.selectors,
+          sharedFolderMeta: options.sharedFolderMeta,
+          sidebar: options.navigation.sidebar.items,
+          tabs: options.navigation.tabs,
+        }),
+        navigationByLocale: {} as Record<string, Navigation>,
+      };
+
   // Icon typos, duplicate labels, and hidden-page-in-sidebar are validated on
   // the built navigation. Missing-target detection needs the full route set
   // (incl. custom + generated pages), so it runs later in generateRuntime.
-  diagnostics.push(...validateNavIcons(navigation));
-  diagnostics.push(...validateNavStructure(navigation, pages));
+  diagnostics.push(
+    ...validateNavIcons(navigation),
+    ...validateNavStructure(navigation, pages)
+  );
 
   return {
     diagnostics,