blume 1.1.1 → 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;
@@ -213,6 +227,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/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

@@ -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",
       },
     },
@@ -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/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.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

@@ -3,6 +3,7 @@ import {
   lstat,
   mkdir,
   readFile,
+  realpath,
   rename,
   rm,
   symlink,
@@ -57,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,
@@ -159,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
@@ -169,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) {
@@ -185,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,
@@ -301,6 +320,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:
@@ -316,7 +376,11 @@ const astroConflictWarning = (
  *     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`,
@@ -341,12 +405,26 @@ export const ensureDepsLink = async (
   }
   const mdxDir = candidateHolding(pkgDir, "@astrojs", "mdx");
   const blumeAstro = resolveAstroPackageJson(astroDir);
-  const outDirAstro = resolvedAstroPath(outDir);
+  // 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 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
@@ -360,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);
 };
 
 /**
@@ -1289,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) =>
@@ -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>
 `;