blume 1.6.0 → 1.6.1

package/src/core/version-cut.ts

@@ -177,12 +177,14 @@ export const insertArchivedVersion = async (
   const indent = text.slice(lineStart).match(/^\s*/u)?.[0] ?? "";
   const rest = text.slice(insertAt);
   // Match the array's authored shape: empty stays bare, an inline array gets
-  // an inline entry, a multiline array gets its own indented line.
+  // an inline entry, a multiline array gets its own indented line — on the
+  // file's own line ending, so a CRLF config doesn't gain a lone LF.
+  const eol = /^\r?\n/u.exec(rest)?.[0];
   let entry: string;
   if (rest.trimStart().startsWith("]")) {
     entry = `{ id: "${id}" }`;
-  } else if (rest.startsWith("\n")) {
-    entry = `\n${indent}  { id: "${id}" },`;
+  } else if (eol) {
+    entry = `${eol}${indent}  { id: "${id}" },`;
   } else {
     entry = `{ id: "${id}" }, `;
   }

package/src/deploy/vercel-negotiation.ts

@@ -9,6 +9,9 @@
  * into it so a content-page request that prefers `text/markdown` is rewritten
  * (not redirected) to the page's prerendered `.md` mirror — the deployed
  * counterpart of the dev-server rewrite in `astro/markdown-negotiation.ts`.
+ * The same routing config also answers a *missing* page: a request that
+ * prefers Markdown (or asks for a `.md` URL no page backs) gets the
+ * prerendered Markdown 404 body with the 404 status, instead of the HTML shell.
  */
 
 /**
@@ -49,6 +52,32 @@ const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
 
 const VARY_ACCEPT = { vary: "Accept" };
 
+/** Where the prerendered Markdown 404 (`pages/404.md.ts`) lands. */
+const NOT_FOUND_MARKDOWN_DEST = "/404.md";
+
+/** The adapter's own not-found fallback — the anchor the Markdown 404 precedes. */
+const NOT_FOUND_HTML_DEST = "/404.html";
+
+/**
+ * Miss-phase routes that answer a missing page with the Markdown 404 body: any
+ * path when the client prefers Markdown, and any `.md`/`.mdx` URL (a request
+ * for a raw-Markdown mirror that has no page wants Markdown back, not the HTML
+ * shell). Both keep the 404 status. Spliced immediately before the adapter's
+ * `/404.html` fallback, so they run after every server route (the MCP
+ * endpoint, server islands, images) has had its turn and never hijack a
+ * request one of those would have answered.
+ */
+const NOT_FOUND_MARKDOWN_ROUTES: readonly VercelRoute[] = [
+  {
+    dest: NOT_FOUND_MARKDOWN_DEST,
+    has: ACCEPT_MARKDOWN_CONDITION,
+    headers: VARY_ACCEPT,
+    src: "^/.*$",
+    status: 404,
+  },
+  { dest: NOT_FOUND_MARKDOWN_DEST, src: "^/.*\\.mdx?$", status: 404 },
+];
+
 /**
  * Vercel rejects route `src` patterns longer than 4096 characters, so route
  * alternations are split across as many route entries as needed. The budget
@@ -186,12 +215,14 @@ export const TRAILING_SLASH_REDIRECT: VercelRoute = {
  * user-authored route of that identical shape would be semantically equal to
  * the one re-added); the homepage `Link` route by its three-field
  * continue-with-link shape (the Build Output config is adapter-generated, so
- * no user-authored route competes in this file).
+ * no user-authored route competes in this file); the Markdown 404 routes by
+ * their `/404.md` destination.
  */
 const isNegotiationRoute = (route: VercelRoute): boolean =>
   route.has?.some(
     (condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE
   ) === true ||
+  (route.dest === NOT_FOUND_MARKDOWN_DEST && route.status === 404) ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
     isString(route.src) &&
@@ -213,17 +244,21 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
  * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
  * signature directory). The trailing-slash 308 redirect is always spliced in
  * alongside, so slashed duplicates of every page collapse onto the canonical
- * slashless URL. Returns the updated JSON text (tab-indented, like the
- * adapter's own output), or `null` when there is nowhere safe to splice: an
- * unparsable config, no `routes` array, or no `handle: "filesystem"` marker
- * to anchor the splice.
+ * slashless URL. With `notFoundMarkdown` (the build emitted `404.md`), the
+ * Markdown 404 routes go into the miss phase right before the adapter's
+ * `/404.html` fallback — and nowhere when that fallback is absent, since a
+ * `dest` with no file behind it would serve nothing. Returns the updated JSON
+ * text (tab-indented, like the adapter's own output), or `null` when there is
+ * nowhere safe to splice: an unparsable config, no `routes` array, or no
+ * `handle: "filesystem"` marker to anchor the splice.
  */
 export const injectNegotiationRoutes = (
   configText: string,
   routePaths: readonly string[],
   homeLinkHeader?: string | null,
   contentTypeOverrides?: Record<string, string>,
-  homeTokens?: number
+  homeTokens?: number,
+  notFoundMarkdown = false
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -272,6 +307,14 @@ export const injectNegotiationRoutes = (
     ...rewriteRoutes,
     TRAILING_SLASH_REDIRECT
   );
+  if (notFoundMarkdown) {
+    const fallbackIndex = routes.findIndex(
+      (route) => route.status === 404 && route.dest === NOT_FOUND_HTML_DEST
+    );
+    if (fallbackIndex !== -1) {
+      routes.splice(fallbackIndex, 0, ...NOT_FOUND_MARKDOWN_ROUTES);
+    }
+  }
   config.routes = routes;
   return `${JSON.stringify(config, null, "\t")}\n`;
 };

package/src/og/card.ts

@@ -81,7 +81,7 @@ export interface OgCardOptions {
   accent?: string;
   /** Brand/site name shown in the top-left lockup. */
   brand?: string;
-  /** Muted subtitle under the headline (usually the site description). */
+  /** Muted subtitle under the headline (the page description, else the site's). */
   description?: string;
   /**
    * Inlined SVG markup of the configured logo, painted into the brand

package/src/openapi/references.ts

@@ -54,6 +54,11 @@ export interface ReferenceSource {
   includeInSearch: boolean;
   /** Whether generated pages emit noindex metadata and stay out of the sitemap. */
   noindex: boolean;
+  /**
+   * Whether operation meta descriptions end with the generated English
+   * "Reference for …" sentence, or carry the spec's own prose alone.
+   */
+  seoDescriptionSuffix: boolean;
   /** Local path or `http(s)` URL, verbatim from config. */
   spec: string;
   /**
@@ -132,6 +137,7 @@ interface Block {
     label?: string;
     noindex: boolean;
     route?: string;
+    seoDescriptionSuffix: boolean;
     spec: string;
   }[];
   spec?: string;
@@ -146,6 +152,7 @@ const sourcesOf = (block: Block): Block["sources"] => {
       includeInLlms: true,
       includeInSearch: true,
       noindex: false,
+      seoDescriptionSuffix: true,
       spec: block.spec,
     });
   }
@@ -192,6 +199,7 @@ const referencesFor = (
       renderer,
       route,
       scalar: block.scalar,
+      seoDescriptionSuffix: source.seoDescriptionSuffix,
       slug: routeSlug(route),
       spec: source.spec,
       theme: block.theme,

package/src/openapi/render-mdx.ts

@@ -174,12 +174,23 @@ const GRAPHQL_MEMBER_PHRASES = {
 /**
  * The spec's own prose for the operation, followed by the endpoint it documents
  * — so every operation page carries a distinct, self-describing meta
- * description even when the spec's summaries are terse.
+ * description even when the spec's summaries are terse. With the suffix
+ * switched off (`seoDescriptionSuffix: false`, for sites whose prose isn't
+ * English) the description is the prose alone, or the page `title` — a
+ * language-neutral `GET /pets`, channel, or field name — when the operation
+ * has no prose at all, so no page ships an empty description.
  */
 const operationDescription = (
   spec: ApiSpecData,
-  operation: ApiOperationRef
+  operation: ApiOperationRef,
+  options: { suffix: boolean; title: string }
 ): string => {
+  if (!options.suffix) {
+    return clip(
+      plainProse(operation.description || operation.summary) || options.title,
+      META_DESCRIPTION_MAX
+    );
+  }
   // AsyncAPI operations act on a channel, not an HTTP endpoint; GraphQL pages
   // document a root field or a named type.
   let suffix: string;
@@ -210,7 +221,7 @@ export const operationMdx = (
   operation: ApiOperationRef,
   reference?: Pick<
     ReferenceSource,
-    "includeInLlms" | "includeInSearch" | "noindex"
+    "includeInLlms" | "includeInSearch" | "noindex" | "seoDescriptionSuffix"
   >
 ): RenderedPage => {
   const method = operation.method.toUpperCase();
@@ -242,7 +253,10 @@ export const operationMdx = (
     searchFlags.exclude = true;
   }
   const seo: RenderedPageData["seo"] = {
-    description: operationDescription(spec, operation),
+    description: operationDescription(spec, operation, {
+      suffix: reference?.seoDescriptionSuffix !== false,
+      title,
+    }),
   };
   if (reference?.noindex) {
     seo.noindex = true;

package/src/openapi/scalar.ts

@@ -144,9 +144,6 @@ export const buildReferenceFiles = async (options: {
       warnings.push(spec.warning);
     }
     const pagePath = referencePagePath(ref.route);
-    // Relative path from the page back to src/generated/data.json: a page one
-    // directory deep (api/events.astro) needs an extra "../".
-    const depth = pagePath.split("/").length - 1;
     files.push({
       content: scalarReferenceTemplate({
         configuration: {
@@ -157,7 +154,6 @@ export const buildReferenceFiles = async (options: {
           // hideTestRequestButton, orderSchemaPropertiesBy, and the rest).
           ...ref.scalar,
         },
-        dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
         noindex: ref.noindex,
         route: ref.route,
         title: ref.label,

package/src/registry/eject.ts

@@ -9,7 +9,12 @@ import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
-import { discoverExamples, exampleMarkdownLookup } from "../astro/examples.ts";
+import {
+  EXAMPLE_SCAN_GLOB,
+  discoverExamples,
+  exampleMarkdownLookup,
+  exampleScanRoots,
+} from "../astro/examples.ts";
 import {
   buildRuntimeData,
   collectStaged,
@@ -61,6 +66,7 @@ import {
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
 import { buildThemeCss } from "../theme/palette.ts";
+import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 
 const toPosix = (path: string): string => path.split("\\").join("/");
@@ -203,7 +209,7 @@ const mcpFiles = async (
       path: join(genDir, "mcp-data.json"),
     },
     {
-      content: mcpEndpointTemplate(route),
+      content: mcpEndpointTemplate(),
       path: join(srcDir, "pages", mcpPageFile(route)),
     },
     {
@@ -251,13 +257,21 @@ const changelogFiles = (
 };
 
 /** Contents of the configured `examples.css`, or `""` when unset/absent. */
-const readExamplesCss = (
-  root: string,
-  css: string | undefined
-): Promise<string> =>
-  css && existsSync(join(root, css))
-    ? readFile(join(root, css), "utf-8")
-    : Promise.resolve("");
+/**
+ * Read a user stylesheet that eject inlines into a generated entry under
+ * `genDir`, re-rooting its relative `@source` paths from the user's file.
+ * Resolves to an empty string when the file is unset or absent.
+ */
+const readUserCss = async (
+  file: string | null,
+  genDir: string
+): Promise<string> => {
+  if (!(file && existsSync(file))) {
+    return "";
+  }
+  const css = await readFile(file, "utf-8");
+  return rebaseSourceDirectives(css, { from: file, to: genDir });
+};
 
 /**
  * The per-example preview route `<Component />` iframes embed, nested under
@@ -331,10 +345,11 @@ export const eject = async (
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
     detectUsesMath(root),
-    context.themeFile
-      ? readFile(context.themeFile, "utf-8")
-      : Promise.resolve(""),
-    readExamplesCss(root, config.examples.css),
+    readUserCss(context.themeFile, genDir),
+    readUserCss(
+      config.examples.css ? join(root, config.examples.css) : null,
+      genDir
+    ),
     buildRawMarkdown(project),
     discoverIslands(root),
   ]);
@@ -387,9 +402,11 @@ export const eject = async (
         contentRoot: relContext.contentRoot,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
-        dataPath: "./src/generated/data.json",
         examplesPath: "./src/generated/examples.ts",
         examplesThemePath: "./src/generated/examples.css",
+        // No CLI publishes the runtime data modules in memory after eject, so
+        // the config aliases each to the JSON snapshot written below.
+        generatedModulesDir: "./src/generated",
         integrationBridge: ejectIntegrationBridge(
           config,
           root,
@@ -398,7 +415,6 @@ export const eject = async (
         needsReact,
         needsSvelte,
         needsVue,
-        openapiPath: "./src/generated/openapi.json",
         pages: relPages,
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css",
@@ -452,7 +468,9 @@ export const eject = async (
       // Relative sources keep the ejected app portable.
       content: examplesEntryTemplate({
         configTokens: buildThemeCss(config.theme),
-        sources: ["../../**/*.{astro,jsx,svelte,ts,tsx,vue}"],
+        sources: exampleScanRoots(root, examples.dir).map(
+          (dir) => `${relative(genDir, dir)}/${EXAMPLE_SCAN_GLOB}`
+        ),
         userCss: userExamplesCss,
       }),
       path: join(genDir, "examples.css"),
@@ -513,7 +531,8 @@ export const eject = async (
   if (config.seo.og.enabled) {
     files.push({
       content: ogEndpointTemplate(
-        customOgRoutes(pages, config.title, config.seo.og.titles)
+        customOgRoutes(pages, config.title, config.seo.og.titles),
+        { pageDescriptions: config.seo.og.description !== false }
       ),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });

package/src/theme/entry.ts

@@ -835,7 +835,7 @@ ${options.userTheme}
 interface ExamplesEntryOptions {
   /** Config-derived token overrides (`:root { --blume-accent: ... }`). */
   configTokens: string;
-  /** Globs to scan for utility classes (example files and their imports). */
+  /** Globs to scan for utility classes (the project and examples directory). */
   sources: string[];
   /** Raw contents of the configured `examples.css`, if any. */
   userCss: string;
@@ -855,7 +855,7 @@ export const examplesEntryTemplate = (options: ExamplesEntryOptions): string =>
   `/* Generated by Blume. Do not edit. */
 @import "tailwindcss";
 
-/* Scan the example files and the project sources they import. */
+/* Scan the project (and an out-of-root examples directory) for utility classes. */
 ${options.sources.map((source) => `@source "${source}";`).join("\n")}
 
 ${DARK_VARIANT}

package/src/theme/sources.ts

@@ -0,0 +1,49 @@
+import { dirname, isAbsolute, relative, resolve } from "pathe";
+
+/**
+ * A Tailwind `@source "…"` / `@source not "…"` directive with a quoted path.
+ * `@source inline("…")` never matches: the quote must directly follow the
+ * keyword (or `not`), and `inline(` sits in between.
+ */
+const SOURCE_DIRECTIVE =
+  /@source(?<not>\s+not)?\s+(?<quote>["'])(?<path>[^"']+)\k<quote>/gu;
+
+/**
+ * Rewrite the relative `@source` paths in a user stylesheet so they still
+ * point where the author meant once the sheet is inlined into a generated
+ * Tailwind entry. Tailwind resolves `@source` relative to the stylesheet that
+ * declares it, and Blume splices `theme.css` / `examples.css` verbatim into
+ * `.blume/src/generated/*.css` (or `src/generated/*.css` after eject), which
+ * would silently re-root them there. Resolving each path against the user's
+ * file and re-expressing it relative to the generated directory keeps the
+ * standard contract — write `@source "../../packages/ui"` next to the file
+ * that says it — and lets a monorepo scan sibling workspace packages for
+ * utility classes without any knowledge of Blume's internal layout. Absolute
+ * paths pass through untouched.
+ */
+export const rebaseSourceDirectives = (
+  css: string,
+  options: {
+    /** The user's stylesheet the CSS was read from. */
+    from: string;
+    /** The directory of the generated entry the CSS is inlined into. */
+    to: string;
+  }
+): string => {
+  const base = dirname(options.from);
+  return css.replace(
+    SOURCE_DIRECTIVE,
+    (
+      directive: string,
+      not: string | undefined,
+      quote: string,
+      path: string
+    ): string => {
+      if (isAbsolute(path)) {
+        return directive;
+      }
+      const rebased = relative(options.to, resolve(base, path));
+      return `@source${not ?? ""} ${quote}${rebased}${quote}`;
+    }
+  );
+};