blume 1.1.1 → 1.1.2

package/dist/types/core/config-input.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type { OpenApiSource, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
@@ -722,12 +723,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/dist/types/core/schema.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 declare const hydrationMode: z.ZodEnum<["load", "idle", "visible", "media", "only"]>;
@@ -1916,24 +1917,24 @@ export declare const blumeConfigSchema: z.ZodObject<{
         }>>;
         codeBlocks: z.ZodDefault<z.ZodObject<{
             theme: z.ZodDefault<z.ZodObject<{
-                dark: z.ZodDefault<z.ZodString>;
-                light: z.ZodDefault<z.ZodString>;
+                dark: z.ZodDefault<z.ZodType<CodeTheme, z.ZodTypeDef, CodeTheme>>;
+                light: z.ZodDefault<z.ZodType<CodeTheme, z.ZodTypeDef, CodeTheme>>;
             }, "strict", z.ZodTypeAny, {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             }, {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             }>>;
         }, "strict", z.ZodTypeAny, {
             theme: {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             };
         }, {
             theme?: {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             } | undefined;
         }>>;
         /**
@@ -1954,8 +1955,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         codeBlocks: {
             theme: {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             };
         };
         headingAnchors: boolean;
@@ -1967,8 +1968,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         codeBlocks?: {
             theme?: {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             } | undefined;
         } | undefined;
         headingAnchors?: boolean | undefined;
@@ -2982,8 +2983,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         };
         codeBlocks: {
             theme: {
-                dark: string;
-                light: string;
+                dark: CodeTheme;
+                light: CodeTheme;
             };
         };
         headingAnchors: boolean;
@@ -3375,8 +3376,8 @@ export declare const blumeConfigSchema: z.ZodObject<{
         } | undefined;
         codeBlocks?: {
             theme?: {
-                dark?: string | undefined;
-                light?: string | undefined;
+                dark?: CodeTheme | undefined;
+                light?: CodeTheme | undefined;
             } | undefined;
         } | undefined;
         headingAnchors?: boolean | undefined;

package/dist/types/core/types.d.ts

@@ -213,6 +213,13 @@ export interface Navigation {
     tabs: NavTab[];
     selectors: NavSelector[];
     sidebar: NavNode[];
+    /**
+     * The tree root in final path space — localized and based (`/`, `/en`,
+     * `/docs`). Tab paths arrive in the same space, so the tab sitting at this
+     * path spans the whole tree and must be scoped as the root tab, not as a
+     * section tab. Absent on older serialized graphs; treat as `/`.
+     */
+    root?: string;
     /** Pinned links shown above the sidebar sections, unscoped by tab. */
     featured: FeaturedLink[];
     /** Repo URL for the header link, or null when hidden (`navigation.repo`). */

package/dist/types/markdown/themes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The light/dark Shiki themes Blume highlights code with. Every Shiki surface —
+ * fenced code (the generated Astro `shikiConfig.themes`), inline `` `code`{:lang} ``,
+ * out-of-pipeline `highlightCode`, and `<Diff>` — resolves to the same pair so a
+ * project's `markdown.codeBlocks.theme` shifts them all in lockstep. This is the
+ * single home for the github fallback used when nothing is configured.
+ */
+import type { ThemeRegistrationAny } from "shiki";
+/** A bundled Shiki theme name or an inline custom Shiki theme definition. */
+export type CodeTheme = string | ThemeRegistrationAny;
+/**
+ * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
+ * `interface`) so it keeps the implicit index signature Shiki's `themes`
+ * parameter (`Partial<Record<string, …>>`) expects.
+ */
+export type CodeThemes = {
+    dark: CodeTheme;
+    light: CodeTheme;
+};
+/** The default pair, used when `markdown.codeBlocks.theme` is unset. */
+export declare const DEFAULT_CODE_THEMES: CodeThemes;

package/docs/configuration/index.mdx

@@ -55,7 +55,7 @@ export default defineConfig({
     },
     codeBlocks: {
       theme: {
-        light: "github-light", // any bundled Shiki theme
+        light: "github-light", // bundled name or custom Shiki theme object
         dark: "github-dark",
       },
     },

package/docs/content/components.mdx

@@ -560,7 +560,7 @@ A card linking to a GitHub repository with its live star and fork counts. Counts
 
 `Component` renders an example file from your project's `examples/` directory as a live preview alongside its highlighted source, in tabs. Point it at a file with `path` — its location under `examples/`, without the extension (so `examples/counter.tsx` is `path="counter"`). React, Vue, Svelte, and Astro examples are all supported; framework examples hydrate, Astro ones render statically. It keeps the preview and the code in sync from a single file.
 
-The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live.
+The preview renders in an isolated frame that the docs styles never reach — no prose margins, typography, or theme chrome bleed into your component. The frame gets Tailwind (preflight + utilities scanned from your example files and anything they import), Blume's design tokens so classes like `bg-background` follow the site palette by default, and it follows the site's light/dark toggle live. The pane sizes itself to the rendered example — and keeps tracking it if the example grows or shrinks after load — with the Preview and Code tabs sharing one height so toggling them never shifts the page.
 
 To style previews with your own design system — say, shadcn variables — point `examples.css` at a stylesheet. It's injected into every preview frame after Blume's defaults, so your tokens win. Don't `@import "tailwindcss"` in it; the frame already provides Tailwind. Both `.dark` and `[data-theme="dark"]` work for dark-mode overrides:
 

package/docs/content/syntax.mdx

@@ -154,6 +154,20 @@ export default defineConfig({
 });
 ```
 
+You can also provide a custom [Shiki theme definition](https://shiki.style/guide/load-theme) directly. Import a VS Code-compatible theme JSON file (using an import attribute when your runtime requires one) and assign it to either color mode; bundled names and custom definitions can be mixed:
+
+```ts blume.config.ts
+import darkTheme from "./themes/acme-dark.json" with { type: "json" };
+
+export default defineConfig({
+  markdown: {
+    codeBlocks: {
+      theme: { light: "github-light", dark: darkTheme },
+    },
+  },
+});
+```
+
 ### Line numbers
 
 Append `lineNumbers` to render a line-number gutter — on its own or alongside a title:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/generate.ts

@@ -3,6 +3,7 @@ import {
   lstat,
   mkdir,
   readFile,
+  realpath,
   rename,
   rm,
   symlink,
@@ -301,6 +302,47 @@ const astroConflictWarning = (
   return `Astro version conflict: another dependency hoisted ${versions} to the project root, so @astrojs/mdx binds to the wrong copy and the build fails on a missing export (e.g. "chunkToString"). A single symlink can't reconcile a split install — pin Blume's Astro by adding a package.json "overrides" (npm/bun/pnpm) or "resolutions" (yarn) entry { "astro": "${pin}" }, then reinstall. Run \`npm ls astro\` to find the dependency pulling the older copy.`;
 };
 
+/**
+ * Drop a `.blume/node_modules` junction that resolves a *different* Blume than
+ * the one running. A restored build cache (e.g. Vercel's) can resurrect the
+ * junction pointing into a superseded store directory — blume@1.1.0's isolated
+ * deps dir after 1.1.1 was installed. Releases rarely bump Astro, so the stale
+ * target still resolves the very same astro and every astro-based probe in
+ * {@link ensureDepsLink} passes through the link — while the `blume/*` imports
+ * in the freshly generated config load the previous release, crashing on any
+ * export added since. Staleness is judged by realpath: the link is stale
+ * exactly when the directory behind it holds a `blume` that isn't `pkgDir`.
+ * A target with no `blume` entry (the workspace layout links
+ * `packages/blume/node_modules`, which holds only the deps) resolves Blume
+ * through the normal ancestor walk and stays. Real directories stay too,
+ * mirroring {@link linkDepsJunction} — we only ever remove a link we own.
+ */
+const dropStaleDepsLink = async (
+  link: string,
+  pkgDir: string
+): Promise<void> => {
+  let existing: Awaited<ReturnType<typeof lstat>>;
+  try {
+    existing = await lstat(link);
+  } catch {
+    return;
+  }
+  if (!existing.isSymbolicLink()) {
+    return;
+  }
+  let linkedBlume: string;
+  let runningBlume: string;
+  try {
+    linkedBlume = await realpath(join(link, "blume"));
+    runningBlume = await realpath(pkgDir);
+  } catch {
+    return;
+  }
+  if (linkedBlume !== runningBlume) {
+    await rm(link, { force: true });
+  }
+};
+
 /**
  * Make the generated runtime resolve Astro and its integrations against Blume's
  * own dependency set. Three failure modes this repairs:
@@ -341,6 +383,10 @@ export const ensureDepsLink = async (
   }
   const mdxDir = candidateHolding(pkgDir, "@astrojs", "mdx");
   const blumeAstro = resolveAstroPackageJson(astroDir);
+  // Before probing what `.blume/` resolves, drop a cache-restored junction
+  // that binds it to a superseded Blume — the probes below would otherwise
+  // pass right through it (same astro, older blume) and leave it in place.
+  await dropStaleDepsLink(join(outDir, "node_modules"), pkgDir);
   const outDirAstro = resolvedAstroPath(outDir);
   // `.blume/` resolves the very same astro Blume's deps provide.
   const astroCorrect = blumeAstro !== null && outDirAstro === blumeAstro;

package/src/astro/templates.ts

@@ -1966,6 +1966,12 @@ ${entries}
  * live toggles — and sets both `data-theme` and a `dark` class so either
  * dark-mode convention works in user CSS. When the page is opened directly
  * (no parent), it falls back to the stored preference, then the OS setting.
+ *
+ * A second script reports the example's rendered height to the parent
+ * (`blume:example-height` via postMessage) so the docs page can size the
+ * preview pane to the content instead of guessing from the source line count.
+ * A ResizeObserver keeps the report live, so examples that grow or shrink
+ * after load (chat threads, accordions) stay in sync.
  */
 export const examplesPageTemplate = (): string =>
   `---
@@ -2020,7 +2026,42 @@ const Example = entry.Component;
   <!-- Flex + margin:auto centers the example and, unlike place-items, keeps
        the top edge reachable when the example outgrows the frame. -->
   <body style="display:flex;min-height:100svh;padding:1.5rem">
-    <div style="margin:auto"><Example /></div>
+    <div data-blume-example style="margin:auto"><Example /></div>
+    <script is:inline>
+      (() => {
+        // Report the example's rendered height so the embedding docs page can
+        // size the preview pane to the content. The wrapper is observed rather
+        // than the body: the body stretches to the frame's own height, so it
+        // would only echo the pane back. Direct opens have no distinct parent
+        // and skip out; the frame is same-origin with the docs page (see the
+        // theme sync above), so the origin is pinned on both ends.
+        if (window.parent === window) {
+          return;
+        }
+        const wrapper = document.querySelector("[data-blume-example]");
+        if (!wrapper) {
+          return;
+        }
+        // The body's padding frames the example; fold it into the report so
+        // the parent can apply the number as-is. Read from the live value —
+        // the user's examples.css is injected after Blume's defaults precisely
+        // so their tokens win, so a root font-size override must be honored
+        // rather than assuming 1.5rem is 48px.
+        const bodyStyle = getComputedStyle(document.body);
+        const paddingPx =
+          parseFloat(bodyStyle.paddingTop) + parseFloat(bodyStyle.paddingBottom);
+        new ResizeObserver(() => {
+          window.parent.postMessage(
+            {
+              height:
+                Math.ceil(wrapper.getBoundingClientRect().height) + paddingPx,
+              type: "blume:example-height",
+            },
+            window.location.origin
+          );
+        }).observe(wrapper);
+      })();
+    </script>
   </body>
 </html>
 `;

package/src/components/content/Component.astro

@@ -47,14 +47,31 @@ const codeHtml = entry
     })
   : undefined;
 
-// Both tabs share one height so toggling them never shifts the layout. Size it
-// to the source (≈21px/line + padding), clamped to a comfortable 18rem floor and
-// a 400px ceiling — taller sources scroll inside the pane.
+// Both tabs share one height so toggling them never shifts the layout. The
+// line-count estimate (≈21px/line + padding, 18rem floor, 25rem ceiling) is
+// only the initial SSR/no-JS height: once the frame loads it reports its
+// rendered height (see the script below) and both panes follow it, so
+// previews fit the example — including ones that grow or shrink after load.
+// The measured height is never ceilinged — the code tab scrolls inside
+// whatever height it's given (`pre.blume-source`) — but the estimate is:
+// a long source would otherwise render a thousands-of-pixels placeholder
+// whose collapse to the measured height no transition could hide. No-JS
+// readers aren't hurt by the cap, since the source scrolls at any height.
 const LINE_PX = 21;
 const PADDING_PX = 36;
+const ESTIMATE_MAX_PX = 400;
+// The floor also clamps the measured height client-side; it rides along on the
+// iframe as `data-blume-min-pane` so the script and this estimate can't drift.
+const MIN_PANE_PX = 288;
 const lineCount = entry ? entry.code.replace(/\n+$/u, "").split("\n").length : 0;
-const paneHeight = Math.min(400, Math.max(288, lineCount * LINE_PX + PADDING_PX));
+const paneHeight = Math.min(
+  ESTIMATE_MAX_PX,
+  Math.max(MIN_PANE_PX, lineCount * LINE_PX + PADDING_PX)
+);
 const paneStyle = `height:${paneHeight}px`;
+// Animate the settle from the estimate to the measured height so the lazy
+// frame's load doesn't snap the layout.
+const paneClass = "motion-safe:transition-[height] motion-safe:duration-200";
 ---
 
 {
@@ -62,15 +79,21 @@ const paneStyle = `height:${paneHeight}px`;
     // `sync={false}`: each preview's Preview/Code tabs are independent — unlike
     // CodeGroup, switching one Component must not switch the others.
     <Tabs hash={false} sync={false}>
-      <Tab class="overflow-hidden p-0!" style={paneStyle} title="Preview">
+      <Tab
+        class={`overflow-hidden p-0! ${paneClass}`}
+        style={paneStyle}
+        title="Preview"
+      >
         <iframe
           class="h-full w-full"
+          data-blume-example-frame
+          data-blume-min-pane={MIN_PANE_PX}
           loading="lazy"
           src={previewSrc}
           title={`Preview of ${path}`}
         />
       </Tab>
-      <Tab class="overflow-hidden" style={paneStyle} title="Code">
+      <Tab class={`overflow-hidden ${paneClass}`} style={paneStyle} title="Code">
         <Fragment set:html={codeHtml} />
       </Tab>
     </Tabs>
@@ -81,3 +104,73 @@ const paneStyle = `height:${paneHeight}px`;
     </div>
   )
 }
+
+<script>
+  // Preview frames measure their rendered example and report the height (see
+  // `examplesPageTemplate`). One listener serves every <Component> on the
+  // page; the sender is matched to its iframe through `event.source`. The
+  // measured height replaces the server's line-count estimate on both tab
+  // panels together, preserving the shared-height invariant that keeps
+  // Preview/Code toggles from shifting the layout. The floor comes from the
+  // iframe's `data-blume-min-pane` (written next to the server estimate) so
+  // there is one source of truth for it.
+
+  // Refuse growth beyond the viewport. An example that sizes itself to the
+  // frame's viewport (h-screen/100svh) tracks whatever height this listener
+  // sets, so each report would come back as the pane height plus the frame
+  // padding — unbounded growth. Clamping to the viewport parks that cycle:
+  // once the pane reaches it, the frame's content stops changing size and
+  // the observer goes quiet. Genuinely tall examples scroll inside the
+  // frame past this point, which a taller-than-screen pane wouldn't have
+  // spared them anyway.
+  const applyMeasuredHeight = (frame: HTMLIFrameElement) => {
+    const tabs = frame.closest("blume-tabs");
+    const reported = Number(frame.dataset.blumeReportedHeight);
+    if (!tabs || !Number.isFinite(reported)) {
+      return;
+    }
+    const height = `${Math.max(
+      Number(frame.dataset.blumeMinPane) || 0,
+      Math.min(reported, window.innerHeight)
+    )}px`;
+    for (const panel of tabs.querySelectorAll<HTMLElement>(
+      "[data-blume-tab-panel]"
+    )) {
+      panel.style.height = height;
+    }
+  };
+
+  window.addEventListener("message", (event) => {
+    if (
+      event.origin !== window.location.origin ||
+      event.data?.type !== "blume:example-height" ||
+      !Number.isFinite(event.data.height)
+    ) {
+      return;
+    }
+    const frames = document.querySelectorAll<HTMLIFrameElement>(
+      "iframe[data-blume-example-frame]"
+    );
+    const frame = Array.from(frames).find(
+      (candidate) => candidate.contentWindow === event.source
+    );
+    if (!frame) {
+      return;
+    }
+    // Keep the raw report around so the viewport clamp can be recomputed
+    // when the window resizes, not only when the frame next reports.
+    frame.dataset.blumeReportedHeight = String(event.data.height);
+    applyMeasuredHeight(frame);
+  });
+
+  // A pane capped by a small viewport would otherwise stay small after the
+  // window grows: the frame's content stopped changing size, so its observer
+  // has nothing new to report.
+  window.addEventListener("resize", () => {
+    for (const frame of document.querySelectorAll<HTMLIFrameElement>(
+      "iframe[data-blume-example-frame][data-blume-reported-height]"
+    )) {
+      applyMeasuredHeight(frame);
+    }
+  });
+</script>

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,
@@ -848,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;
     };
   };
   /**