blume 1.1.2 → 1.1.3

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

@@ -23,6 +23,20 @@ export interface Diagnostic {
     suggestion?: string;
     docsUrl?: string;
 }
+/** One discovered `examples/` file reduced to what Markdown downleveling needs. */
+export interface ExampleMarkdownEntry {
+    /** Shiki language for the fenced block — the file's extension. */
+    lang: string;
+    /** Raw example source, shown verbatim in the agent-facing code fence. */
+    source: string;
+}
+/**
+ * Discovered examples keyed by their `<Component path>` (the file's location
+ * under `examples/`, sans extension). Lets the agent-facing Markdown downlevel
+ * `<Component path="…" />` to the example's source, since the live preview
+ * can't survive the trip to plain Markdown.
+ */
+export type ExampleLookup = Record<string, ExampleMarkdownEntry>;
 /** A heading extracted from page content, used for the TOC and search. */
 export interface Heading {
     depth: number;

package/dist/types/openapi/references.d.ts

@@ -35,6 +35,11 @@ export interface ReferenceSource {
     spec: string;
     /** Per-block Scalar theme name override, if any (Scalar renderer only). */
     theme?: string;
+    /**
+     * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
+     * only). Takes precedence over Blume's derived spec/theme config.
+     */
+    scalar?: Record<string, unknown>;
     /** Display options carried through to the Blume renderer. */
     display: ReferenceDisplay;
     /**

package/docs/advanced/api-reference.mdx

@@ -104,6 +104,26 @@ openapi: {
 
 A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`. Its "Try it" playground calls your **target API directly from the browser** (Blume doesn't proxy), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` and the playground apply to the Scalar renderer only.
 
+### Passing Scalar options
+
+`theme` is a shorthand for the one option most people reach for, but Scalar supports many more. A `scalar` object forwards any [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) straight to the embedded reference — Blume doesn't gate the keys, so anything Scalar accepts flows through:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  renderer: "scalar",
+  spec: "./openapi.yaml",
+  scalar: {
+    localization: { locale: "es" },   // translate Scalar's own UI
+    agent: { disabled: true },         // disable the Scalar Agent
+    hideTestRequestButton: true,
+    orderSchemaPropertiesBy: "preserve",
+  },
+}
+```
+
+Blume's own [`i18n`](/docs/content/i18n) translates the docs chrome, but Scalar has a separate localization system — set `scalar.localization.locale` to translate the embedded reference too. Options in the `scalar` object win over Blume's derived config, so anything set here (including `theme`, `customCss`, or the spec `content`/`url`) overrides Blume's defaults. The same `scalar` block works on the `asyncapi` reference.
+
 ## AsyncAPI
 
 Event-driven APIs use a sibling `asyncapi` block with the same shape. AsyncAPI is rendered by Scalar (the native renderer is OpenAPI-only for now); only the default route differs (`/events`):

package/docs/configuration/index.mdx

@@ -252,6 +252,33 @@ lastModified: 2026-06-20
 
 When enabled, the date is also emitted as schema.org `dateModified` in the page's structured data.
 
+## Date format
+
+Both the "Last updated" stamp and the [changelog](/docs/advanced/changelog) timeline render their dates through the same `dateFormat`, so they read alike. Dates always render in the site's locale; `dateFormat` controls the _shape_. It defaults to the long form (`July 21, 2026`, `2026年7月21日`):
+
+```ts blume.config.ts
+dateFormat: { dateStyle: "long" },
+```
+
+`dateFormat` is a pass-through to [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) options. Use a `dateStyle` preset for a length:
+
+```ts blume.config.ts
+dateFormat: { dateStyle: "medium" },
+```
+
+Or the individual component fields for a numeric house style like `2026/07/21`:
+
+```ts blume.config.ts
+dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },
+```
+
+| Option | Description |
+| --- | --- |
+| `dateStyle` | Preset length: `"full"`, `"long"`, `"medium"`, or `"short"`. Can't be combined with the component fields. |
+| `weekday`, `era`, `year`, `month`, `day` | Individual components, e.g. `year: "numeric"`, `month: "2-digit"`. |
+| `timeZone` | IANA time zone. Defaults to `UTC`, so a date reads the same regardless of where the site builds. |
+| `calendar`, `numberingSystem` | Calendar system (e.g. `"japanese"`) and numbering system (e.g. `"arab"`). |
+
 ## SEO
 
 Open Graph images, RSS feeds, and JSON-LD structured data, grouped under `seo`. See the [SEO guide](/docs/configuration/seo) for metadata, frontmatter overrides, and the full reference.

package/package.json

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

package/src/ai/component-markdown.ts

@@ -1,6 +1,7 @@
 import { mdxToMdast } from "satteri";
 
 import { parseYouTubeId } from "../components/content/youtube.ts";
+import type { ExampleLookup } from "../core/types.ts";
 
 /**
  * Downlevel Blume's MDX components to plain Markdown for agent-facing output
@@ -336,6 +337,33 @@ const youtube: ComponentMarkdown = ({ props }) => {
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
 
+/** Fence `code` so its opening/closing run outlengths any backticks inside. */
+const fencedBlock = (lang: string, code: string): string => {
+  const trimmed = code.replace(/(?<!\n)\n+$/u, "");
+  const runs = trimmed.match(/`+/gu);
+  const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+  const fence = "`".repeat(Math.max(3, longest + 1));
+  return `${fence}${lang}\n${trimmed}\n${fence}`;
+};
+
+/**
+ * Build the `<Component>` serializer for a project's discovered examples. The
+ * live preview can't survive the trip to Markdown, so the agent-facing output
+ * carries the example's source — the same code the "Code" tab shows — as a
+ * fenced block. An unknown `path` (or a missing `path` prop) declines, leaving
+ * the JSX verbatim, mirroring the "no example found" note the component renders
+ * on the page.
+ */
+export const exampleComponentSerializers = (
+  examples: ExampleLookup
+): Record<string, ComponentMarkdown> => ({
+  Component: ({ props }) => {
+    const path = typeof props.path === "string" ? props.path : undefined;
+    const example = path === undefined ? undefined : examples[path];
+    return example ? fencedBlock(example.lang, example.source) : null;
+  },
+});
+
 /**
  * The built-in serializer registry, keyed by JSX name. `Step` and `Tab` are
  * intentionally absent: they only carry meaning inside their containers,

package/src/ai/llms.ts

@@ -4,7 +4,10 @@ import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
-import { downlevelComponents } from "./component-markdown.ts";
+import {
+  downlevelComponents,
+  exampleComponentSerializers,
+} from "./component-markdown.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 // Routes carry `basePath`; a `deployment.base` subdirectory is layered on top —
@@ -163,6 +166,12 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
   const pages = eligiblePages(project).toSorted((a, b) =>
     a.route.localeCompare(b.route)
   );
+  // Downlevel `<Component>` to its example's source; a same-name user
+  // `markdownComponents` entry is spread last and still wins.
+  const components = {
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...config.ai.markdownComponents,
+  };
 
   const sections = await Promise.all(
     pages.map(async (page) => {
@@ -173,7 +182,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       const parsed = matter(raw);
       const body = downlevelComponents(
         applyAgentVisibility(parsed.content),
-        config.ai.markdownComponents,
+        components,
         parsed.data
       ).trim();
       const url = pageUrl(

package/src/ai/markdown.ts

@@ -4,7 +4,10 @@ import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
-import { downlevelComponents } from "./component-markdown.ts";
+import {
+  downlevelComponents,
+  exampleComponentSerializers,
+} from "./component-markdown.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
 /** One route's raw-Markdown variants. */
@@ -37,6 +40,13 @@ export const buildRawMarkdown = async (
 ): Promise<Record<string, RawMarkdownEntry>> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
+  // Downlevel `<Component>` to its example's source. A user `markdownComponents`
+  // entry of the same name is spread last, so it still wins.
+  const components = {
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...project.config.ai.markdownComponents,
+  };
+
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
     const page = pageById.get(route.id);
     if (page) {
@@ -50,11 +60,7 @@ export const buildRawMarkdown = async (
       const source = applyAgentVisibility(await readRoute(route));
       // The `.md` variant keeps the front-matter block in the output, but its
       // data must also be in scope for `prop={frontmatter.*}` expressions.
-      const md = downlevelComponents(
-        source,
-        project.config.ai.markdownComponents,
-        matter(source).data
-      );
+      const md = downlevelComponents(source, components, matter(source).data);
       const entry: RawMarkdownEntry =
         md === source ? { mdx: source } : { md, mdx: source };
       return [route.path, entry] as const;

package/src/astro/examples.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
+import type { ExampleLookup } from "../core/types.ts";
 import type { IslandClientMode } from "./islands.ts";
 import { readClientMode } from "./islands.ts";
 
@@ -146,3 +147,15 @@ export const discoverExamples = async (
 
   return { examples, warnings };
 };
+
+/**
+ * Reduce discovered examples to the `<Component path>` → source lookup the
+ * agent-facing Markdown downleveler needs (see {@link BlumeProject.examples}).
+ */
+export const exampleMarkdownLookup = (examples: ExampleSpec[]): ExampleLookup =>
+  Object.fromEntries(
+    examples.map((example) => [
+      example.path,
+      { lang: example.lang, source: example.source },
+    ])
+  );

package/src/astro/generate.ts

@@ -58,7 +58,7 @@ import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
-import { discoverExamples } from "./examples.ts";
+import { discoverExamples, exampleMarkdownLookup } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
 import {
   customOgRoutes,
@@ -160,8 +160,9 @@ const resolveAstroPackageJson = (modulesDir: string): string | null => {
 };
 
 /**
- * Realpath of the `astro` package reachable through the normal node_modules
- * ancestor walk from a generated runtime, or null when none resolves.
+ * The `astro` package reachable through the normal node_modules ancestor walk
+ * from a generated runtime — its realpath'd `package.json` plus the
+ * `node_modules` directory the walk found it in — or null when none resolves.
  *
  * This deliberately does not use `createRequire().resolve()`. pnpm's generated
  * bin shim adds Blume's virtual-store dependencies to `NODE_PATH`, which
@@ -170,13 +171,21 @@ const resolveAstroPackageJson = (modulesDir: string): string | null => {
  * reachable skips the dependency link and makes `import "astro/config"` fail.
  * Walking the physical node_modules ancestors mirrors the lookup that config
  * actually gets.
+ *
+ * The containing directory matters as much as the package: under an isolated
+ * linker the walk can find a store-deduped astro in a directory that holds
+ * nothing else of Blume's, so "the right astro resolves" does not imply "the
+ * integrations resolve" — callers must check where the hit came from.
  */
-const resolvedAstroPath = (fromDir: string): string | null => {
+const resolvedAstroHit = (
+  fromDir: string
+): { modulesDir: string; pkg: string } | null => {
   let dir = normalize(fromDir);
   while (true) {
-    const resolved = resolveAstroPackageJson(join(dir, "node_modules"));
-    if (resolved) {
-      return resolved;
+    const modulesDir = join(dir, "node_modules");
+    const pkg = resolveAstroPackageJson(modulesDir);
+    if (pkg) {
+      return { modulesDir, pkg };
     }
     const parent = dirname(dir);
     if (parent === dir) {
@@ -186,6 +195,15 @@ const resolvedAstroPath = (fromDir: string): string | null => {
   }
 };
 
+/** Whether two paths name the same physical directory (realpath equality). */
+const sameRealDir = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * The two places an installer can put Blume's dependencies:
  *   - `<blume>/node_modules` — deps nested under the package (workspace source,
@@ -358,7 +376,11 @@ const dropStaleDepsLink = async (
  *     install. An `overrides` pin plus an incremental `npm install` hoists
  *     astro to the project root (deleting Blume's nested copy) but leaves
  *     `@astrojs/mdx` and friends nested under `blume/node_modules`, where the
- *     upward walk from `.blume/` can't see them.
+ *     upward walk from `.blume/` can't see them. The same shape arises under
+ *     an isolated linker when the workspace itself declares astro at a version
+ *     matching Blume's: the store dedupes both to one copy, so the walk finds
+ *     the "correct" astro through the workspace's own direct-dep symlink — in
+ *     a node_modules holding none of Blume's other deps.
  *
  * The repair is the same symlink: Blume's dependency directory linked in as
  * `.blume/node_modules` so the generated config's bare specifiers (`astro`,
@@ -387,12 +409,22 @@ export const ensureDepsLink = async (
   // 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);
+  const outDirHit = resolvedAstroHit(outDir);
   // `.blume/` resolves the very same astro Blume's deps provide.
-  const astroCorrect = blumeAstro !== null && outDirAstro === blumeAstro;
-  // Clean hoisted install: astro is correct and the integrations sit beside
-  // it, so they resolve through the same walk — nothing to do.
-  if (astroCorrect && mdxDir === astroDir) {
+  const astroCorrect = blumeAstro !== null && outDirHit?.pkg === blumeAstro;
+  // Clean hoisted install: astro is correct, found in Blume's own dependency
+  // directory, and the integrations sit beside it — the same walk resolves
+  // them too, so there is nothing to do. Requiring the walk to land in
+  // `astroDir` itself (not merely resolve an identical astro) matters under
+  // isolated linkers: a workspace that declares astro at a version matching
+  // Blume's gets a store-deduped symlink in its own node_modules, so the walk
+  // finds the "correct" astro in a directory holding only the workspace's
+  // direct deps — none of Blume's integrations (issue #103).
+  const walkLandsInDeps =
+    astroCorrect &&
+    outDirHit !== null &&
+    sameRealDir(outDirHit.modulesDir, astroDir);
+  if (walkLandsInDeps && mdxDir === astroDir) {
     return null;
   }
   // Linking the integrations' directory yields a consistent set when it also
@@ -406,7 +438,7 @@ export const ensureDepsLink = async (
   // Split layout: Blume's astro is nested (a conflicting astro took the root
   // spot) but @astrojs/mdx hoisted away from it, binding to the shadow. Only a
   // root pin fixes this — surface it.
-  return astroConflictWarning(blumeAstro, outDirAstro);
+  return astroConflictWarning(blumeAstro, outDirHit?.pkg ?? null);
 };
 
 /**
@@ -1335,6 +1367,9 @@ export const generateRuntime = async (
     tags: overrideTags,
     warnings: overrideWarnings,
   } = componentSlots;
+  // Expose the discovered examples for agent-facing Markdown downleveling
+  // (`<Component>` → source) before any consumer (raw `.md`, MCP, llms) runs.
+  project.examples = exampleMarkdownLookup(exampleDiscovery.examples);
 
   // Each island/example framework enables its Astro renderer. React also
   // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are

package/src/astro/templates.ts

@@ -1445,6 +1445,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   page={{ title: seo.title ?? title, description: seo.description ?? frontmatter.description, route }}
   headings={headings}
   toc={data.config.toc}
+  dateFormat={data.config.dateFormat}
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
@@ -1502,6 +1503,7 @@ import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
+import { resolveDateFormatOptions } from "blume/core/date-format.ts";
 import { layoutOverrides } from "../generated/components.ts";
 import data from "blume:data";
 
@@ -1529,8 +1531,9 @@ const localeMeta = i18n
 const dir = localeMeta?.dir ?? "ltr";
 const htmlLang = i18n ? i18n.defaultLocale : "en";
 
-// Formatted in the same locale as the chrome, and in UTC, to match the
-// per-page "last updated" stamp.
+// Formatted in the same locale as the chrome, and with the configured
+// \`dateFormat\` (UTC by default), to match the per-page "last updated" stamp.
+const dateFormatOptions = resolveDateFormatOptions(data.config.dateFormat);
 const formatDate = (value: string | null | undefined) => {
   if (!value) {
     return;
@@ -1538,10 +1541,7 @@ const formatDate = (value: string | null | undefined) => {
   const date = new Date(value);
   return Number.isNaN(date.getTime())
     ? undefined
-    : new Intl.DateTimeFormat(htmlLang, {
-        dateStyle: "long",
-        timeZone: "UTC",
-      }).format(date);
+    : new Intl.DateTimeFormat(htmlLang, dateFormatOptions).format(date);
 };
 
 const slugify = (text: string) =>

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.

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

@@ -897,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 }]`. */
@@ -915,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. */
@@ -1003,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.
@@ -1046,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/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;
 }
 
 /**