blume 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # blume
 
+## 1.1.3
+
+### Patch Changes
+
+- 42522fc: Downlevel `<Component>` to its example's source in agent-facing Markdown. The `/<route>.md` mirror, `llms-full.txt`, and the MCP `get_page` tool now render `<Component path="…" />` as a fenced code block of the example's source (the same code the on-page "Code" tab shows) instead of leaving the raw JSX tag, so agents reading a page get the component's code rather than an opaque element. An unknown path (or a missing `path`) is left verbatim, and a same-name `ai.markdownComponents` serializer still overrides the built-in.
+- a71f70e: Add a `dateFormat` config option for the "last updated" stamp and the changelog timeline. Both surfaces previously hardcoded `dateStyle: "long"`; they now share a configurable pass-through to `Intl.DateTimeFormat` options, defaulting to `{ dateStyle: "long" }` so existing sites are unchanged. Set a preset (`dateFormat: { dateStyle: "medium" }`) or a numeric house style (`dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" }`); dates still render in the site's locale and in UTC unless a `timeZone` is given.
+- 68fc939: Harden the agent-facing code-fence helper against a polynomial-time regex (ReDoS). Trailing newlines are now stripped with an unambiguous pattern, so example source with many interior blank lines can't force quadratic backtracking.
+- ee77cfd: Stop long OpenAPI routes from overflowing the native API reference layout. An operation's heading now wraps a long `METHOD /path` title instead of clipping it off the content column, and the overview list rows stack the summary over the route (each getting the full row width) and wrap a long route inside the card — dropping the duplicate path that overlapped the label when a spec sets no summary.
+- 93a94a2: Fix two responsive/mobile layout issues. Twoslash code blocks now wrap their lines on narrow screens instead of pushing the page sideways (hover popups still escape as before), and a long site title in the header now truncates on one line instead of wrapping into the fixed-height bar.
+- a27c543: Add a `scalar` passthrough object to the `openapi` and `asyncapi` config blocks (Scalar renderer). Any [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md) set there is forwarded verbatim to the embedded `<ScalarComponent>` — `localization` (to translate Scalar's own UI), `agent`, `hideTestRequestButton`, `orderSchemaPropertiesBy`, and the rest. Options in the `scalar` object win over Blume's derived spec/theme config, making it a full escape hatch to Scalar's API; the dedicated `theme` field remains the ergonomic shorthand.
+- fa07dc4: Create the `.blume/node_modules` dependency junction when an isolated linker (Bun's `isolated` mode, pnpm) dedupes the workspace's own `astro` dependency to Blume's copy. The walk from `.blume/` found the "correct" astro through the workspace's direct-dep symlink — in a directory holding none of Blume's integrations — so the junction was skipped and the build died on `Cannot find module '@astrojs/mdx'`.
+
+## 1.1.2
+
+### Patch Changes
+
+- 6cf2995: Allow custom Shiki theme objects in `markdown.codeBlocks.theme.light` and `markdown.codeBlocks.theme.dark`. Custom themes now flow through fenced code, inline highlighted code, `<CodeBlock>`, and `<Diff>` alongside bundled Shiki theme names.
+- cb30a40: Recognize the localized/based root tab when scoping the sidebar. With i18n enabled and header tabs configured, a non-default locale's tabs arrive localized (`/` becomes `/en`), but render-time scoping compared the active tab against a bare `/` — so on any `/en/...` route the root tab was misread as a section tab, and a root-level `(group)` folder (whose path is exactly the locale prefix) collapsed the sidebar to that one group. The same bare comparison blanked the sidebar entirely under a `basePath` with a root tab. The navigation now carries its root in the tabs' own path space (`/`, `/en`, `/docs`) and the sidebar scoping compares against it, so non-default locales show the full tree minus tab-owned sections, matching the default locale.
+- aa3f588: Size `<Component>` preview panes to the rendered example instead of the source line count. The generated frame page now observes the example with a ResizeObserver and reports its height to the docs page, which applies it to both the Preview and Code tabs — so short sources that render tall UIs no longer clip, and long sources that render small components no longer float in dead space. The line-count estimate remains the SSR/no-JS initial height (288px floor, 400px ceiling; the measured height is unceilinged up to the viewport), with a height transition so the settle on lazy load doesn't snap. Examples that resize after load keep the pane in sync, and viewport-tracking examples (`h-screen`) can't feed the measurement back into unbounded growth.
+- 103733d: Re-point a cache-restored `.blume/node_modules` junction that resolves a superseded Blume install. A restored build cache (e.g. Vercel's) could resurrect the junction pointing into the previous release's store directory; because releases rarely bump Astro, every astro-based health check passed straight through the stale link, and the freshly generated Astro config then imported the old package — crashing on any export added since (`blumeTwoslashTransformer is not a function`). The junction is now dropped and relinked whenever the directory behind it holds a `blume` other than the one running.
+
 ## 1.1.1
 
 ### Patch Changes

package/dist/cli/index.js

@@ -3106,6 +3106,7 @@ var referencesFor = (kind, block, defaultLabel, renderer, display, basePath) =>
       label,
       renderer,
       route,
+      scalar: block.scalar,
       slug: routeSlug(route),
       spec: source.spec,
       theme: block.theme
@@ -4327,6 +4328,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}
@@ -4365,6 +4367,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";
 
@@ -4392,8 +4395,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;
@@ -4401,10 +4405,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) =>
@@ -4770,7 +4771,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>
 `;
@@ -7927,9 +7963,23 @@ var githubConfigSchema = z2.strictObject({
   owner: z2.string(),
   repo: z2.string()
 });
+var codeThemeSchema = z2.custom((value) => {
+  if (typeof value === "string") {
+    return true;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const theme = value;
+  const settingsValid = theme.settings === undefined || Array.isArray(theme.settings);
+  const tokenColorsValid = theme.tokenColors === undefined || Array.isArray(theme.tokenColors);
+  const colorsValid = theme.colors === undefined || typeof theme.colors === "object" && theme.colors !== null && !Array.isArray(theme.colors);
+  const hasContent = theme.settings !== undefined || theme.tokenColors !== undefined || theme.colors !== undefined;
+  return settingsValid && tokenColorsValid && colorsValid && hasContent;
+}, "Expected a Shiki theme name or custom theme object");
 var codeBlockThemeSchema = z2.strictObject({
-  dark: z2.string().default("github-dark"),
-  light: z2.string().default("github-light")
+  dark: codeThemeSchema.default("github-dark"),
+  light: codeThemeSchema.default("github-light")
 });
 var codeBlocksConfigSchema = z2.strictObject({
   theme: codeBlockThemeSchema.default({})
@@ -7945,6 +7995,19 @@ var lastModifiedConfigSchema = z2.union([
   z2.boolean(),
   z2.strictObject({ type: z2.enum(["git", "frontmatter"]).default("git") })
 ]);
+var dateFormatConfigSchema = z2.strictObject({
+  calendar: z2.string().optional(),
+  dateStyle: z2.enum(["full", "long", "medium", "short"]).optional(),
+  day: z2.enum(["numeric", "2-digit"]).optional(),
+  era: z2.enum(["long", "short", "narrow"]).optional(),
+  month: z2.enum(["numeric", "2-digit", "long", "short", "narrow"]).optional(),
+  numberingSystem: z2.string().optional(),
+  timeZone: z2.string().optional(),
+  weekday: z2.enum(["long", "short", "narrow"]).optional(),
+  year: z2.enum(["numeric", "2-digit"]).optional()
+}).refine((value) => value.dateStyle === undefined || value.weekday === undefined && value.era === undefined && value.year === undefined && value.month === undefined && value.day === undefined, {
+  message: "dateFormat.dateStyle can't be combined with weekday/era/year/month/day; use one or the other."
+});
 var codeConfigSchema = z2.strictObject({
   icons: z2.boolean().default(true),
   wrap: z2.boolean().default(false)
@@ -7963,12 +8026,14 @@ var openapiSourceSchema = z2.strictObject({
   route: z2.string().optional(),
   spec: z2.string()
 });
+var scalarConfigSchema = z2.record(z2.string(), z2.unknown()).optional();
 var openapiConfigSchema = z2.strictObject({
   codeSamples: z2.array(z2.string()).default(["curl", "js", "python"]),
   enabled: z2.boolean().default(false),
   expandSchemas: z2.boolean().default(false),
   renderer: z2.enum(["blume", "scalar"]).default("blume"),
   route: z2.string().default("/reference"),
+  scalar: scalarConfigSchema,
   sources: z2.array(openapiSourceSchema).default([]),
   spec: z2.string().optional(),
   theme: z2.string().optional()
@@ -7976,6 +8041,7 @@ var openapiConfigSchema = z2.strictObject({
 var asyncapiConfigSchema = z2.strictObject({
   enabled: z2.boolean().default(false),
   route: z2.string().default("/events"),
+  scalar: scalarConfigSchema,
   sources: z2.array(openapiSourceSchema).default([]),
   spec: z2.string().optional(),
   theme: z2.string().optional()
@@ -8020,6 +8086,7 @@ var blumeConfigSchema = z2.strictObject({
   banner: bannerConfigSchema.optional(),
   basePath: z2.string().optional().transform((value) => normalizeBasePath(value)),
   content: contentConfigSchema.default({}),
+  dateFormat: dateFormatConfigSchema.default({ dateStyle: "long" }),
   deployment: deploymentConfigSchema.default({}),
   description: z2.string().optional(),
   examples: examplesConfigSchema.default("examples"),
@@ -8738,19 +8805,21 @@ var buildNavigation = (pages, options) => {
       }
     }
   }
+  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
   if (options.sidebar) {
     const sidebar2 = buildConfigSidebar(options.sidebar, byRoute, display, basePath);
     return {
       featured,
+      root: rootTabPath,
       selectors,
       sidebar: sidebar2,
       tabs: withTabHrefs(tabs, sidebar2)
     };
   }
-  const rootTabPath = withBasePath(basePath, options.localizedRoot ?? "/");
   const sidebar = buildFileSystemSidebar(pages, options.folderMeta, sharedFolderMeta, metaPrefix, display, new Set(tabs.flatMap((tab) => tab.path === rootTabPath ? [] : [tab.path])), options.diagnostics);
   return {
     featured,
+    root: rootTabPath,
     selectors,
     sidebar,
     tabs: withTabHrefs(tabs, sidebar)
@@ -11683,6 +11752,22 @@ var youtube = ({ props }) => {
   const title = typeof props.title === "string" && props.title !== "" ? props.title : "Watch on YouTube";
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
+var fencedBlock = (lang, code) => {
+  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}
+${trimmed}
+${fence}`;
+};
+var exampleComponentSerializers = (examples) => ({
+  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;
+  }
+});
 var SERIALIZERS = {
   Callout: callout,
   Steps: steps,
@@ -11878,10 +11963,14 @@ var buildIndex = (project) => {
 var buildFull = async (project) => {
   const { config } = project;
   const pages = eligiblePages(project).toSorted((a, b) => a.route.localeCompare(b.route));
+  const components = {
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...config.ai.markdownComponents
+  };
   const sections = await Promise.all(pages.map(async (page) => {
     const raw = await readEntryText(project, page);
     const parsed = frontmatter_default(raw);
-    const body = downlevelComponents(applyAgentVisibility(parsed.content), config.ai.markdownComponents, parsed.data).trim();
+    const body = downlevelComponents(applyAgentVisibility(parsed.content), components, parsed.data).trim();
     const url = pageUrl(page.route, config.deployment.site, normalizeBasePath(config.deployment.base));
     return [`# ${page.title}`, `Source: ${url}`, "", body].join(`
 `);
@@ -12488,6 +12577,7 @@ import {
   lstat,
   mkdir as mkdir6,
   readFile as readFile14,
+  realpath,
   rename,
   rm as rm2,
   symlink,
@@ -12522,6 +12612,10 @@ import { readFile as readFile10 } from "node:fs/promises";
 var agentMarkdown = (entry) => entry.md ?? entry.mdx;
 var buildRawMarkdown = async (project) => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
+  const components = {
+    ...exampleComponentSerializers(project.examples ?? {}),
+    ...project.config.ai.markdownComponents
+  };
   const readRoute = async (route) => {
     const page = pageById.get(route.id);
     if (page) {
@@ -12531,7 +12625,7 @@ var buildRawMarkdown = async (project) => {
   };
   const entries = await Promise.all(project.manifest.routes.map(async (route) => {
     const source = applyAgentVisibility(await readRoute(route));
-    const md = downlevelComponents(source, project.config.ai.markdownComponents, frontmatter_default(source).data);
+    const md = downlevelComponents(source, components, frontmatter_default(source).data);
     const entry = md === source ? { mdx: source } : { md, mdx: source };
     return [route.path, entry];
   }));
@@ -13299,7 +13393,8 @@ var buildReferenceFiles = async (options) => {
       content: scalarReferenceTemplate({
         configuration: {
           ...spec.config,
-          ...themeConfiguration(config, ref.theme)
+          ...themeConfiguration(config, ref.theme),
+          ...ref.scalar
         },
         dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
         route: ref.route,
@@ -13530,6 +13625,13 @@ ${THEME_MAPPING}
   letter-spacing: 0;
 }
 
+/* A heading can carry one long unbreakable token — an OpenAPI operation's title
+   is \`METHOD /very/long/{path}\` when the spec sets no summary — which would run
+   off the content column. Break it across lines instead of overflowing. */
+.prose :where(h1, h2, h3, h4, h5, h6) {
+  overflow-wrap: break-word;
+}
+
 .prose :where(h1) {
   font-size: 3rem;
   line-height: 1.1;
@@ -14080,6 +14182,16 @@ var OVERRIDES = `
   padding-right: 1.25rem;
 }
 
+/* Twoslash blocks keep \`overflow: visible\` so popups can escape, which means
+   long lines can't scroll — they'd push past the viewport on narrow screens.
+   Wrap them on mobile instead; hover popups still position against the token. */
+@media (max-width: 640px) {
+  .prose pre.twoslash code {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+}
+
 /* The rich renderer renders each popup's type signature as a nested Shiki
    pre. Strip the code-block chrome (border, radius, padding, background) so it
    sits flush inside the popup, which owns the frame. */
@@ -14358,6 +14470,10 @@ var discoverExamples = async (root, pattern = "examples") => {
   }
   return { examples, warnings };
 };
+var exampleMarkdownLookup = (examples) => Object.fromEntries(examples.map((example) => [
+  example.path,
+  { lang: example.lang, source: example.source }
+]));
 
 // src/astro/generate.ts
 var BLUME_SRC = join26(packageRoot(), "src");
@@ -14389,12 +14505,13 @@ var resolveAstroPackageJson = (modulesDir) => {
     return null;
   }
 };
-var resolvedAstroPath = (fromDir) => {
+var resolvedAstroHit = (fromDir) => {
   let dir = normalize3(fromDir);
   while (true) {
-    const resolved = resolveAstroPackageJson(join26(dir, "node_modules"));
-    if (resolved) {
-      return resolved;
+    const modulesDir = join26(dir, "node_modules");
+    const pkg = resolveAstroPackageJson(modulesDir);
+    if (pkg) {
+      return { modulesDir, pkg };
     }
     const parent = dirname9(dir);
     if (parent === dir) {
@@ -14403,6 +14520,13 @@ var resolvedAstroPath = (fromDir) => {
     dir = parent;
   }
 };
+var sameRealDir = (a, b) => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+};
 var depsCandidates = (pkgDir) => [
   join26(pkgDir, "node_modules"),
   dirname9(pkgDir)
@@ -14441,6 +14565,28 @@ var astroConflictWarning = (blumeAstroPkg, shadowAstroPkg) => {
   const pin = blume ?? "<Blume's astro version>";
   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.`;
 };
+var dropStaleDepsLink = async (link, pkgDir) => {
+  let existing;
+  try {
+    existing = await lstat(link);
+  } catch {
+    return;
+  }
+  if (!existing.isSymbolicLink()) {
+    return;
+  }
+  let linkedBlume;
+  let runningBlume;
+  try {
+    linkedBlume = await realpath(join26(link, "blume"));
+    runningBlume = await realpath(pkgDir);
+  } catch {
+    return;
+  }
+  if (linkedBlume !== runningBlume) {
+    await rm2(link, { force: true });
+  }
+};
 var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
   const astroDir = candidateHolding(pkgDir, "astro");
   if (!astroDir) {
@@ -14448,16 +14594,18 @@ var ensureDepsLink = async (outDir, pkgDir = packageRoot()) => {
   }
   const mdxDir = candidateHolding(pkgDir, "@astrojs", "mdx");
   const blumeAstro = resolveAstroPackageJson(astroDir);
-  const outDirAstro = resolvedAstroPath(outDir);
-  const astroCorrect = blumeAstro !== null && outDirAstro === blumeAstro;
-  if (astroCorrect && mdxDir === astroDir) {
+  await dropStaleDepsLink(join26(outDir, "node_modules"), pkgDir);
+  const outDirHit = resolvedAstroHit(outDir);
+  const astroCorrect = blumeAstro !== null && outDirHit?.pkg === blumeAstro;
+  const walkLandsInDeps = astroCorrect && outDirHit !== null && sameRealDir(outDirHit.modulesDir, astroDir);
+  if (walkLandsInDeps && mdxDir === astroDir) {
     return null;
   }
   if (mdxDir && (mdxDir === astroDir || astroCorrect)) {
     await linkDepsJunction(join26(outDir, "node_modules"), mdxDir);
     return null;
   }
-  return astroConflictWarning(blumeAstro, outDirAstro);
+  return astroConflictWarning(blumeAstro, outDirHit?.pkg ?? null);
 };
 var ISLAND_FRAMEWORK_DEPS = {
   svelte: "@astrojs/svelte",
@@ -14943,6 +15091,7 @@ var generateRuntime = async (project) => {
     tags: overrideTags,
     warnings: overrideWarnings
   } = componentSlots;
+  project.examples = exampleMarkdownLookup(exampleDiscovery.examples);
   const frameworks = new Set([
     ...islandDiscovery.islands.map((island) => island.framework),
     ...exampleDiscovery.examples.map((example) => example.framework),
@@ -16037,6 +16186,8 @@ var eject = async (root) => {
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  const examples = await discoverExamples(root, config.examples.source);
+  project.examples = exampleMarkdownLookup(examples.examples);
   const [
     pages,
     needsReactRaw,
@@ -16044,8 +16195,7 @@ var eject = async (root) => {
     userTheme,
     userExamplesCss,
     rawMarkdown,
-    islands,
-    examples
+    islands
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
@@ -16053,8 +16203,7 @@ var eject = async (root) => {
     context.themeFile ? readFile15(context.themeFile, "utf-8") : Promise.resolve(""),
     readExamplesCss(root, config.examples.css),
     buildRawMarkdown(project),
-    discoverIslands(root),
-    discoverExamples(root, config.examples.source)
+    discoverIslands(root)
   ]);
   const frameworks = new Set([
     ...islands.islands.map((island) => island.framework),
@@ -17224,5 +17373,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main);
 
-//# debugId=F92BD712EE9633C264756E2164756E21
+//# debugId=74F150F28E9B859A64756E2164756E21
 //# sourceMappingURL=index.js.map