blume 1.1.1 → 1.1.3

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/Logo.astro

@@ -29,7 +29,7 @@ const brandText = logo?.text ?? site.title;
 ---
 
 <a
-  class="inline-flex items-center gap-2 font-semibold text-base text-foreground"
+  class="inline-flex min-w-0 items-center gap-2 font-semibold text-base text-foreground"
   href={withBase(brandHref)}
 >
   {
@@ -71,5 +71,5 @@ const brandText = logo?.text ?? site.title;
         </>
       ))
   }
-  {brandText && <span>{brandText}</span>}
+  {brandText && <span class="truncate">{brandText}</span>}
 </a>

package/src/components/layout/RootLayout.astro

@@ -1,6 +1,8 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { resolveDateFormatOptions } from "../../core/date-format.ts";
+import type { ResolvedDateFormat } from "../../core/schema.ts";
 import type { BlumeClientData } from "../../core/data.ts";
 import type {
   Heading,
@@ -151,6 +153,11 @@ interface Props {
   clientData?: BlumeClientData | null;
   /** Table-of-contents settings (`toc` config): visibility + heading range. */
   toc?: { enabled: boolean; maxLevel: number; minLevel: number };
+  /**
+   * Date-formatting options (`dateFormat` config) for the "last updated" stamp,
+   * shared with the changelog timeline. Defaults to the long form when omitted.
+   */
+  dateFormat?: ResolvedDateFormat;
   /**
    * Content-column preset. `"bare"` (the generated changelog index) drops both
    * the sidebar and the table of contents and centers a single wide column;
@@ -202,6 +209,7 @@ const {
   layout = {},
   clientData,
   toc = { enabled: true, maxLevel: 3, minLevel: 2 },
+  dateFormat,
   contentLayout = "default",
 } = Astro.props;
 
@@ -288,14 +296,15 @@ const twitterCard = ogImage ? "summary_large_image" : "summary";
 const xSite = normalizeXHandle(x?.handle);
 const xCreator = normalizeXHandle(x?.creator);
 
-// "Last updated on <date>" — formatted in UTC to match the changelog timeline.
+// "Last updated on <date>" — the configured `dateFormat`, in UTC (unless the
+// config names a zone) so it matches the changelog timeline.
 const lastModifiedDate = lastModified ? new Date(lastModified) : null;
 const formattedLastModified =
   lastModifiedDate && !Number.isNaN(lastModifiedDate.getTime())
-    ? new Intl.DateTimeFormat(locale || "en", {
-        dateStyle: "long",
-        timeZone: "UTC",
-      }).format(lastModifiedDate)
+    ? new Intl.DateTimeFormat(
+        locale || "en",
+        resolveDateFormatOptions(dateFormat)
+      ).format(lastModifiedDate)
     : null;
 
 // The hosted MCP server's absolute URL, used by the page-actions install menu.
@@ -306,7 +315,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/components/openapi/ApiTagOperations.astro

@@ -25,16 +25,25 @@ const operations = Object.values(specs[source]?.operations ?? {}).filter(
       {operations.map((operation) => (
         <li>
           <a
-            class="flex items-center gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
+            class="flex items-start gap-3 rounded-blume border border-border p-3 text-inherit no-underline! transition-colors hover:border-accent hover:bg-muted hover:no-underline!"
             href={withBase(operation.route)}
           >
-            <MethodBadge method={operation.method} />
-            <span class="font-medium text-foreground text-sm">
-              {operation.summary || operation.path}
-            </span>
-            <code class="ml-auto hidden text-muted-foreground text-xs sm:inline">
-              {operation.path}
-            </code>
+            <MethodBadge class="mt-0.5 shrink-0" method={operation.method} />
+            {/* Title over path, stacked, so a long summary and a long route each
+                get the full row width instead of being squeezed side by side. */}
+            <div class="flex flex-col gap-0.5">
+              <span class="break-words font-medium text-foreground text-sm">
+                {operation.summary || operation.path}
+              </span>
+              {/* The path doubles as the label when the spec sets no summary, so
+                  only repeat it as the reference line when it adds information;
+                  break-all keeps a long route wrapping inside the card. */}
+              {operation.summary && (
+                <code class="break-all text-muted-foreground text-xs">
+                  {operation.path}
+                </code>
+              )}
+            </div>
           </a>
         </li>
       ))}

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;
     };
   };
   /**
@@ -896,6 +897,13 @@ export interface OpenApiConfig {
   renderer?: "blume" | "scalar";
   /** Where the reference mounts. Defaults to `/reference`. */
   route?: string;
+  /**
+   * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`
+   * (Scalar renderer only) — e.g. `localization`, `agent`,
+   * `hideTestRequestButton`, `orderSchemaPropertiesBy`. These win over Blume's
+   * derived spec/theme config, so it's a full escape hatch to Scalar's API.
+   */
+  scalar?: Record<string, unknown>;
   /** One or more specs; each renders on its own route by default. */
   sources?: OpenApiSource[];
   /** Shorthand for a single source: `sources: [{ spec }]`. */
@@ -914,6 +922,12 @@ export interface AsyncApiConfig {
   enabled?: boolean;
   /** Where the reference mounts. Defaults to `/events`. */
   route?: string;
+  /**
+   * Extra Scalar options forwarded verbatim to the embedded `<ScalarComponent>`.
+   * These win over Blume's derived spec/theme config — a full escape hatch to
+   * Scalar's API.
+   */
+  scalar?: Record<string, unknown>;
   /** One or more specs. */
   sources?: OpenApiSource[];
   /** Shorthand for a single source. */
@@ -1002,6 +1016,33 @@ export type LastModifiedConfig =
       type?: "git" | "frontmatter";
     };
 
+/**
+ * Date presentation for the "last updated" stamp and the changelog timeline —
+ * a curated pass-through to `Intl.DateTimeFormat`, shared by both surfaces.
+ * Defaults to `{ dateStyle: "long" }`. Dates render in UTC unless `timeZone` is
+ * set. `dateStyle` is a preset and can't be combined with the component fields.
+ */
+export interface DateFormatConfig {
+  /** Preset date length; mutually exclusive with the component fields below. */
+  dateStyle?: "full" | "long" | "medium" | "short";
+  /** Weekday representation. */
+  weekday?: "long" | "short" | "narrow";
+  /** Era representation (e.g. the Japanese imperial era). */
+  era?: "long" | "short" | "narrow";
+  /** Year representation. */
+  year?: "numeric" | "2-digit";
+  /** Month representation. */
+  month?: "numeric" | "2-digit" | "long" | "short" | "narrow";
+  /** Day representation. */
+  day?: "numeric" | "2-digit";
+  /** IANA time zone (e.g. `Asia/Tokyo`). Defaults to `UTC`. */
+  timeZone?: string;
+  /** Calendar system (e.g. `japanese`, `buddhist`). */
+  calendar?: string;
+  /** Numbering system (e.g. `latn`, `arab`). */
+  numberingSystem?: string;
+}
+
 /**
  * On-page table of contents. `true`/`false` toggles it; the object form narrows
  * the heading range. Defaults to on, H2–H3.
@@ -1045,6 +1086,11 @@ export interface BlumeConfig {
   basePath?: string;
   /** Where content lives and how it's discovered. */
   content?: ContentConfig;
+  /**
+   * Date presentation for the "last updated" stamp and the changelog timeline.
+   * Pass-through `Intl.DateTimeFormat` options; defaults to `{ dateStyle: "long" }`.
+   */
+  dateFormat?: DateFormatConfig;
   /** Where and how the site deploys (site URL, adapter, output mode). */
   deployment?: DeploymentConfig;
   /** Default meta description, used where a page sets none. */

package/src/core/date-format.ts

@@ -0,0 +1,17 @@
+import type { ResolvedDateFormat } from "./schema.ts";
+
+/**
+ * The default date presentation — the long form (`July 21, 2026`,
+ * `2026年7月21日`) both stamps used before `dateFormat` was configurable.
+ */
+export const DEFAULT_DATE_FORMAT: ResolvedDateFormat = { dateStyle: "long" };
+
+/**
+ * Resolve a configured `dateFormat` into `Intl.DateTimeFormat` options for the
+ * per-page "last updated" stamp and the changelog timeline. Both surfaces call
+ * this so they format alike. Dates render in UTC unless the config names a
+ * `timeZone`, so a stamp reads the same regardless of the build machine's zone.
+ */
+export const resolveDateFormatOptions = (
+  format: ResolvedDateFormat = DEFAULT_DATE_FORMAT
+): Intl.DateTimeFormatOptions => ({ timeZone: "UTC", ...format });

package/src/core/navigation.ts

@@ -707,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,
@@ -716,19 +725,13 @@ 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,
@@ -742,6 +745,7 @@ export const buildNavigation = (
   );
   return {
     featured,
+    root: rootTabPath,
     selectors,
     sidebar,
     tabs: withTabHrefs(tabs, sidebar),

package/src/core/project-graph.ts

@@ -20,6 +20,7 @@ import type {
   BlumeManifest,
   ContentGraph,
   Diagnostic,
+  ExampleLookup,
   PageRecord,
   ProjectContext,
 } from "./types.ts";
@@ -74,6 +75,14 @@ export interface BlumeProject {
   droppedPages: number;
   /** The instantiated content sources, for lazy entry reads (search/AI/raw). */
   sources: ContentSource[];
+  /**
+   * Discovered `examples/` sources keyed by `<Component path>`, attached by the
+   * runtime/eject layer after {@link scanProject} (example discovery is an Astro
+   * concern, so core doesn't run it). Undefined until then; the agent-facing
+   * Markdown downleveler reads it to turn `<Component path="…" />` into the
+   * example's source. Empty when the project has no examples.
+   */
+  examples?: ExampleLookup;
 }
 
 /**