blume 2.1.0 → 2.1.2

package/src/astro/generate.ts

@@ -34,7 +34,11 @@ import {
   navVariants,
 } from "../components/layout/nav-utils.ts";
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
-import { validateUsedComponents } from "../core/component-diagnostics.ts";
+import { withChangelogIndexText } from "../core/changelog-index.ts";
+import {
+  missingExampleDiagnostics,
+  validateUsedComponents,
+} from "../core/component-diagnostics.ts";
 import {
   analyzeComponentOverrides,
   emptyComponentOverrides,
@@ -93,13 +97,13 @@ import {
   builtinProxyReferences,
   hasScalarReferences,
   needsPlaygroundProxy,
-  referenceRoutes,
 } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { resolveSearchPopular } from "../search/popular.ts";
+import { sourcePages } from "../search/source-pages.ts";
 import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
@@ -125,6 +129,7 @@ import {
   customOgRoutes,
   discoverPages,
   hasGeneratedChangelog,
+  navTargetRoutes,
   routeIsTaken,
 } from "./pages.ts";
 import { candidateHolding } from "./render-deps.ts";
@@ -180,28 +185,35 @@ export type { PrerenderDepsPlugin } from "./render-deps.ts";
 const BLUME_SRC = join(packageRoot(), "src");
 
 /**
- * Absolute path to `babel-plugin-react-compiler`, resolved from Blume's own
- * package root (Blume ships it). Returns null when React or the compiler is off.
+ * Whether the generated `react()` call turns the React Compiler on: React and
+ * `react.compiler` are both on, and `oxc-transform-react` (Blume ships it)
+ * resolves. False when React or the compiler is off.
  *
- * The path must be absolute: @vitejs/plugin-react resolves babel plugins from
- * the *project* root, not `.blume/`, so a bare specifier fails in a user project
- * that never installed the plugin directly. Resolving from `packageRoot()` binds
- * to Blume's shipped copy regardless of the user's package manager or hoisting.
+ * The compiler is loaded by `@vitejs/plugin-react` with a bare
+ * `import("oxc-transform-react")` from its own directory, which fails the
+ * build when it throws, so the check walks the same chain — Blume →
+ * `@astrojs/react` → `@vitejs/plugin-react` — rather than resolving from
+ * Blume's root, which a strict package manager may not link the plugin to.
  */
 export const resolveReactCompiler = (
   config: ResolvedConfig,
   needsReact: boolean,
   pkgDir: string = packageRoot()
-): string | null => {
+): boolean => {
   if (!(needsReact && config.react.compiler)) {
-    return null;
+    return false;
   }
   try {
-    return createRequire(pathToFileURL(join(pkgDir, "_.js")).href).resolve(
-      "babel-plugin-react-compiler"
+    const astroReact = createRequire(
+      pathToFileURL(join(pkgDir, "_.js")).href
+    ).resolve("@astrojs/react");
+    const pluginReact = createRequire(astroReact).resolve(
+      "@vitejs/plugin-react"
     );
+    createRequire(pluginReact).resolve("oxc-transform-react");
+    return true;
   } catch {
-    return null;
+    return false;
   }
 };
 
@@ -213,11 +225,11 @@ export const resolveReactCompiler = (
 export const reactCompilerWarnings = (
   config: ResolvedConfig,
   needsReact: boolean,
-  compilerPath: string | null
+  compiler: boolean
 ): string[] =>
-  needsReact && config.react.compiler && !compilerPath
+  needsReact && config.react.compiler && !compiler
     ? [
-        "React Compiler is enabled but `babel-plugin-react-compiler` could not be resolved; falling back to an uncompiled build. Reinstall Blume, or set `react: { compiler: false }` to silence this.",
+        "React Compiler is enabled but `oxc-transform-react` could not be resolved; falling back to an uncompiled build. Reinstall Blume, or set `react: { compiler: false }` to silence this.",
       ]
     : [];
 
@@ -1142,23 +1154,32 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   // Resolved UI dictionaries: one per locale under i18n, English baseline
   // otherwise. Threaded into chrome so the catch-all can pick the active locale.
+  // The `changelog` config's title and description replace the dictionaries'.
   const uiByLocale = i18n
     ? Object.fromEntries(
         i18n.locales.map(({ code }) => [
           code,
-          resolveUIStrings(code, {
-            defaultLocale: i18n.defaultLocale,
-            overrides: i18n.ui,
-          }),
+          withChangelogIndexText(
+            config,
+            resolveUIStrings(code, {
+              defaultLocale: i18n.defaultLocale,
+              overrides: i18n.ui,
+            }),
+            code
+          ),
         ])
       )
     : {};
-  const defaultUi = i18n
-    ? resolveUIStrings(i18n.defaultLocale, {
-        defaultLocale: i18n.defaultLocale,
-        overrides: i18n.ui,
-      })
-    : EN_UI;
+  const defaultUi = withChangelogIndexText(
+    config,
+    i18n
+      ? resolveUIStrings(i18n.defaultLocale, {
+          defaultLocale: i18n.defaultLocale,
+          overrides: i18n.ui,
+        })
+      : EN_UI,
+    i18n?.defaultLocale
+  );
 
   const navigationByLocale = i18n
     ? Object.fromEntries(
@@ -1255,6 +1276,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       openInChat: config.ai.openInChat,
       repoUrl,
       search: {
+        analytics: config.search.analytics,
         enabled: config.search.provider.mode !== "none",
         popular: resolveSearchPopular(config.search.popular, config.basePath),
         provider: config.search.provider.kind,
@@ -1796,21 +1818,26 @@ export const diagnosticWarning = (diagnostic: Diagnostic): string =>
 
 /**
  * Missing-dependency preflight: the search provider's SDK, content source
- * SDKs, the assistant backend's provider SDK, the deployment adapter's package,
- * and — since React ships with Blume while Vue/Svelte don't — any island
- * framework's Astro integration. A build fails here, before anything is
- * written, with the install command for the project's package manager —
- * otherwise Vite dies later on an opaque unresolved import from the hidden
- * runtime. Dev warns and keeps serving: only the pages and routes that import
- * the package break, and installing it is picked up on the next restart.
+ * SDKs, the assistant backend's and narration provider's SDKs, the deployment
+ * adapter's package, and — since React ships with Blume while Vue/Svelte
+ * don't — any island framework's Astro integration. A build fails here,
+ * before anything is written, with the install command for the project's
+ * package manager — otherwise Vite dies later on an opaque unresolved import
+ * from the hidden runtime. Dev warns and keeps serving: only the pages and
+ * routes that import the package break, and installing it is picked up on
+ * the next restart. Dev leaves narration's SDK out, since only a build
+ * generates the clips.
  */
 const dependencyPreflight = async (
   project: BlumeProject,
   frameworks: Set<string>
 ): Promise<string[]> => {
   const build = project.mode === "build";
+  const { config } = project;
   const diagnostic = await missingDependencyDiagnostic(
-    project.config,
+    build
+      ? config
+      : { ...config, narration: { ...config.narration, provider: null } },
     project.context.root,
     build ? "error" : "warning",
     frameworks
@@ -2064,11 +2091,12 @@ export const generateRuntime = async (
   const needsVue = frameworks.has("vue");
   const needsSvelte = frameworks.has("svelte");
 
-  // Absolute path to the React Compiler babel plugin (null when off). Resolved
-  // here, Node-side, so the generated config points babel straight at Blume's
-  // shipped copy — see resolveReactCompiler. Any unresolved-but-requested
-  // warning is folded into `warnings` below (declared later).
-  const reactCompilerPath = resolveReactCompiler(config, needsReact);
+  // Whether react() turns the React Compiler on (false when off). Checked here,
+  // Node-side, so an unresolvable compiler degrades to an uncompiled build
+  // instead of failing it — see resolveReactCompiler. Any
+  // unresolved-but-requested warning is folded into `warnings` below (declared
+  // later).
+  const reactCompiler = resolveReactCompiler(config, needsReact);
 
   // Custom pages that should get a generated OG card (the home most of all).
   // Computed before the MCP `.well-known` routes are appended below — those are
@@ -2146,7 +2174,7 @@ export const generateRuntime = async (
           needsSvelte,
           needsVue,
           pages,
-          reactCompilerPath,
+          reactCompiler,
           searchClientPath,
           themePath,
         })
@@ -2209,7 +2237,7 @@ export const generateRuntime = async (
           languageIcons,
           sources: [
             `${BLUME_SRC}/**/*.{astro,ts,tsx}`,
-            `${context.root}/**/*.{astro,mdx,ts,tsx}`,
+            `${context.root}/**/*.{astro,jsx,mdx,ts,tsx}`,
           ],
           twoslashCss: twoslashCss(),
           userTheme,
@@ -2247,7 +2275,10 @@ export const generateRuntime = async (
     writeMcpFiles(mcp, write, agentData),
     writeApiFiles(project, api, write, agentData, mcp),
     playgroundProxy.enabled
-      ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
+      ? write(
+          playgroundProxy.entrypoint,
+          playgroundProxyTemplate(proxyOrigins, config.rateLimit)
+        )
       : Promise.resolve(false),
   ]);
 
@@ -2317,7 +2348,11 @@ export const generateRuntime = async (
   if (searchAdapter.kind === "mixedbread") {
     await write(
       join(srcDir, "pages", "api", "search.ts"),
-      mixedbreadSearchEndpointTemplate(searchAdapter.options)
+      mixedbreadSearchEndpointTemplate(
+        searchAdapter.options,
+        sourcePages(project),
+        config.rateLimit
+      )
     );
   }
 
@@ -2372,7 +2407,7 @@ export const generateRuntime = async (
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...proxyAllowlistWarnings(config, openApiData),
     ...apiPageProxyWarnings(project),
-    ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
+    ...reactCompilerWarnings(config, needsReact, reactCompiler),
     ...mcp.warnings,
     ...islandDiscovery.warnings,
     ...exampleDiscovery.warnings,
@@ -2380,24 +2415,18 @@ export const generateRuntime = async (
     ...overrideWarnings,
   ];
 
-  // Missing-navigation-target check, now that every servable route is known:
-  // content routes, custom `.astro` pages, the generated changelog, and any
-  // OpenAPI reference routes (so a tab an author points at one still validates).
-  const navTargetRoutes = new Set<string>([
-    ...project.graph.routes.keys(),
-    ...pages.map((page) => page.pattern),
-    ...referenceRoutes(config),
-  ]);
-  if (changelogIndex) {
-    navTargetRoutes.add("/changelog");
-  }
+  // Missing-navigation-target check, now that every servable route is known
+  // (see `navTargetRoutes`).
   // Curated `search.popular` icons live outside the navigation model, so they
   // miss `validateNavIcons` in the graph build — they're checked here too,
   // where the search config is known. A typo otherwise just renders the
   // default glyph.
   warnings.push(
     ...[
-      ...validateNavTargets(project.graph.navigation, navTargetRoutes),
+      ...validateNavTargets(
+        project.graph.navigation,
+        navTargetRoutes(project, pages)
+      ),
       ...validateSearchPopularIcons(config.search.popular),
     ].map(diagnosticWarning)
   );
@@ -2414,6 +2443,12 @@ export const generateRuntime = async (
       knownComponentTags,
       new Set(registry.map((item) => item.name))
     ).map(diagnosticWarning),
+    ...missingExampleDiagnostics(
+      project.graph.pages,
+      exampleDiscovery,
+      context.root,
+      knownComponentTags
+    ).map(diagnosticWarning),
     ...dependencyWarnings
   );
   if (hasScalarReferences(config)) {

package/src/astro/integration.ts

@@ -7,6 +7,7 @@ import { join, relative, resolve } from "pathe";
 import { loadEnvFiles } from "../cli/env.ts";
 import type { CustomPageRoute } from "../core/custom-pages.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
+import { POWERED_BY_HEADERS } from "../core/powered-by.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import {
@@ -146,23 +147,33 @@ export const publishBuildProject = (project: BlumeProject | null): void => {
  * the Astro root recorded on `astro:config:done`. Scan diagnostics surface as
  * warnings — there is no `--strict` to honor here, and the build itself has
  * already succeeded. `null` when nothing asked for a scan.
+ *
+ * The app's runtime settings were baked in at eject, `poweredBy` among them
+ * (the integration option that registers the runtime middleware), so the
+ * artifacts follow that option rather than the config file: one switch puts
+ * `X-Powered-By` on the server-rendered responses and in `_headers` alike.
  */
 const scanForArtifacts = async (
   astroRoot: URL | null,
-  artifactsRoot: string | undefined,
+  options: Pick<BlumeIntegrationOptions, "buildArtifactsRoot" | "poweredBy">,
   logger: ArtifactLogger
 ): Promise<BlumeProject | null> => {
-  if (!(astroRoot && artifactsRoot)) {
+  if (!(astroRoot && options.buildArtifactsRoot)) {
     return null;
   }
-  const root = resolve(fileURLToPath(astroRoot), artifactsRoot);
+  const root = resolve(fileURLToPath(astroRoot), options.buildArtifactsRoot);
   // Remote sources read their tokens from the environment during the scan.
   loadEnvFiles(root);
   const project = await scanProject(root, { mode: "build" });
   for (const diagnostic of project.diagnostics) {
     logger.warn(`[${diagnostic.code}] ${diagnostic.message}`);
   }
-  return project;
+  return options.poweredBy === undefined
+    ? project
+    : {
+        ...project,
+        config: { ...project.config, poweredBy: options.poweredBy },
+      };
 };
 
 /**
@@ -317,6 +328,12 @@ export type BlumePageRoute = CustomPageRoute;
 
 export interface BlumeIntegrationOptions {
   pages: BlumePageRoute[];
+  /**
+   * Whether responses name Blume in `X-Powered-By` (see
+   * `core/powered-by.ts`): the dev server's, and the server-rendered ones of
+   * a build, through the runtime middleware. Defaults to `true`.
+   */
+  poweredBy?: boolean;
   /**
    * Page routes that have a raw-Markdown variant (the content manifest). The
    * hidden runtime leaves this out: the CLI publishes the live set through
@@ -342,10 +359,11 @@ export interface BlumeIntegrationOptions {
    */
   buildArtifactsRoot?: string;
   /**
-   * The pattern redirects (`/beta/:slug*`), compiled against base-less
-   * request paths (see `core/redirect-patterns.ts`). Astro's own `redirects`
-   * carry only the exact ones, since it can't prerender a pattern's pages, so
-   * the dev server answers these itself.
+   * Every configured redirect, compiled against base-less request paths
+   * (see `compileEveryRedirect`), for the dev server to answer itself.
+   * Astro's own `redirects` carry only the exact ones, since it can't
+   * prerender a pattern's pages, and its dev handler answers one whose
+   * destination `[...slug]` serves with a `301` whatever its status.
    */
   redirects?: CompiledRedirect[];
 }
@@ -398,10 +416,12 @@ const negotiateMarkdown =
       if (homeLinkHeader && isHomeUrl(req.url)) {
         res.setHeader("Link", homeLinkHeader);
       }
-      if (prefersMarkdown(req.headers.accept)) {
-        const variant = markdownVariantUrl(req.url, contentRoutes);
-        if (variant) {
-          res.setHeader("Vary", "Accept");
+      const variant = markdownVariantUrl(req.url, contentRoutes);
+      if (variant) {
+        // Both answers at a negotiated URL depend on `Accept`, the HTML one
+        // too, so a cache never hands one client's variant to the other.
+        res.setHeader("Vary", "Accept");
+        if (prefersMarkdown(req.headers.accept)) {
           req.url = variant;
         }
       }
@@ -410,11 +430,11 @@ const negotiateMarkdown =
   };
 
 /**
- * Answer a pattern redirect in dev with its configured status, the way the
- * server wrappers do in a build. Request URLs arrive base-less (see
- * {@link negotiateMarkdown}), and the patterns were based to match.
+ * Answer a configured redirect in dev with its status, the way the server
+ * wrappers do in a build. Request URLs arrive base-less (see
+ * {@link negotiateMarkdown}), and the redirects were based to match.
  */
-const answerPatternRedirects =
+const answerRedirects =
   (redirects: readonly CompiledRedirect[]) =>
   (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
     const answer = matchCompiledRedirect(redirects, requestPath(req.url ?? ""));
@@ -426,6 +446,24 @@ const answerPatternRedirects =
     res.end();
   };
 
+/**
+ * Name Blume in `X-Powered-By` on every dev response, as the deployed site
+ * does. It goes on the Node response before anything answers, so the
+ * redirects, the `public/` files Vite serves, and the rendered pages all
+ * carry it, and a page or project middleware that sets its own value
+ * replaces it.
+ */
+const identifyBlume = (
+  _req: IncomingMessage,
+  res: ServerResponse,
+  next: () => void
+): void => {
+  for (const [name, value] of Object.entries(POWERED_BY_HEADERS)) {
+    res.setHeader(name, value);
+  }
+  next();
+};
+
 /** The `.d.ts` the integration injects for the `blume:*` virtual modules. */
 const MODULE_TYPES_FILE = "modules.d.ts";
 
@@ -459,11 +497,7 @@ export const blumeIntegration = (
       "astro:build:done": async ({ dir, logger }) => {
         const project =
           registry().buildProject ??
-          (await scanForArtifacts(
-            astroRoot,
-            options.buildArtifactsRoot,
-            logger
-          ));
+          (await scanForArtifacts(astroRoot, options, logger));
         if (!project) {
           return;
         }
@@ -502,6 +536,15 @@ export const blumeIntegration = (
           entrypoint: "blume/components/icon-sprite-middleware.ts",
           order: "post",
         });
+        // Names Blume on the responses Astro renders (see
+        // components/powered-by-middleware.ts). Innermost too, so a header
+        // the project's own middleware sets wins.
+        if (options.poweredBy !== false) {
+          addMiddleware({
+            entrypoint: "blume/components/powered-by-middleware.ts",
+            order: "post",
+          });
+        }
         for (const page of options.pages) {
           injectRoute({
             entrypoint: page.entrypoint,
@@ -533,7 +576,14 @@ export const blumeIntegration = (
         });
         if (options.redirects) {
           server.middlewares.stack.unshift({
-            handle: answerPatternRedirects(options.redirects),
+            handle: answerRedirects(options.redirects),
+            route: "",
+          });
+        }
+        // Ahead of the redirects, so their answers carry it too.
+        if (options.poweredBy !== false) {
+          server.middlewares.stack.unshift({
+            handle: identifyBlume,
             route: "",
           });
         }

package/src/astro/markdown-negotiation.ts

@@ -8,6 +8,9 @@
  * helpers (`deploy/cloudflare-negotiation.ts` — its deploy bundle is uploaded
  * unbundled, so it cannot import this module); when editing here, mirror the
  * change there. Parity is enforced by `test/cloudflare-negotiation.test.ts`.
+ * Vercel's routing conditions (`deploy/vercel-negotiation.ts`) spell the same
+ * rule as regexes, checked against {@link prefersMarkdown} by
+ * `test/vercel-negotiation.test.ts`.
  */
 
 interface AcceptEntry {

package/src/astro/module-types.ts

@@ -82,7 +82,9 @@ declare module "blume:consent-client" {
 }
 
 declare module "blume:search-client" {
-  export const createSearch: () =>
+  export const createSearch: (
+    options?: import("blume/components/layout/search/types.ts").SearchClientOptions
+  ) =>
     | import("blume/components/layout/search/types.ts").SearchFn
     | Promise<import("blume/components/layout/search/types.ts").SearchFn>;
 }

package/src/astro/pages.ts

@@ -4,6 +4,7 @@ import {
 } from "../core/changelog-index.ts";
 import { staticSegments } from "../core/custom-pages.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import { referenceRoutes } from "../openapi/references.ts";
 import type { BlumePageRoute } from "./integration.ts";
 
 export {
@@ -48,6 +49,28 @@ export const hasGeneratedChangelog = (
   hasChangelogIndex(project.graph.pages, project.config) &&
   !routeIsTaken(userPages, project.graph.pages, CHANGELOG_INDEX_ROUTE);
 
+/**
+ * Every route a navigation entry (a tab, selector item, featured link, header
+ * action, or CTA) may point at: content routes, custom `.astro` pages, the
+ * generated changelog, and reference routes (so a tab an author points at one
+ * still validates). `generateRuntime` and `blume doctor` both check
+ * `validateNavTargets` against it, so they flag the same entries.
+ */
+export const navTargetRoutes = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): Set<string> => {
+  const routes = new Set<string>([
+    ...project.graph.routes.keys(),
+    ...userPages.map((page) => page.pattern),
+    ...referenceRoutes(project.config),
+  ]);
+  if (hasGeneratedChangelog(project, userPages)) {
+    routes.add(CHANGELOG_INDEX_ROUTE);
+  }
+  return routes;
+};
+
 const humanizeSegment = (segment: string): string =>
   segment
     .split(/[-_]/u)

package/src/astro/render-deps.ts

@@ -369,11 +369,16 @@ export const prerenderDepsPlugin = (
       if (!dir || !serverSide) {
         return;
       }
-      await linkRenderDeps(
-        dir,
-        imported.get(environment ?? "") ?? new Map<string, string>(),
-        pkgDir
-      );
+      const packages = imported.get(environment ?? "");
+      // A bundle that leaves no package import external loads nothing from
+      // `node_modules` at runtime, so it gets none. The Cloudflare adapter
+      // bundles the Worker whole, and a copy of its output that follows the
+      // links (a CI artifact) would otherwise upload every one of Blume's
+      // dependencies as a Worker module.
+      if (environment !== undefined && !packages?.size) {
+        return;
+      }
+      await linkRenderDeps(dir, packages ?? new Map<string, string>(), pkgDir);
     },
   };
 };

package/src/astro/runtime-deps.ts

@@ -103,6 +103,25 @@ export const assistantProviderDependencies = (
       )
     : [];
 
+/**
+ * The narration provider's SDK, when missing: `openai()` speaks through
+ * `@ai-sdk/openai`, which the build loads to generate the clips, while
+ * `gateway()` needs nothing beyond the core `ai` package Blume ships.
+ */
+export const narrationProviderDependencies = (
+  narration: ResolvedConfig["narration"],
+  root: string,
+  pkgDir: string = packageRoot()
+): MissingDependency[] =>
+  narration.enabled && narration.provider
+    ? unresolved(
+        `Narration provider "${narration.provider.kind}"`,
+        narration.provider.runtimeDeps,
+        root,
+        pkgDir
+      )
+    : [];
+
 /**
  * The deployment adapter's package, when missing. Node and Vercel ship with
  * Blume, so theirs always resolve; Netlify and Cloudflare are optional peers.
@@ -152,8 +171,9 @@ export const islandFrameworkDependencies = (
 /**
  * Every package the resolved config's adapters (and the given island
  * frameworks) import that isn't installed: the search SDK, content source
- * SDKs, the assistant provider SDK, the deployment adapter, and island
- * integrations. The adapters' `runtimeDeps` are the one place that knows.
+ * SDKs, the assistant and narration provider SDKs, the deployment adapter,
+ * and island integrations. The adapters' `runtimeDeps` are the one place that
+ * knows.
  */
 export const missingRuntimeDependencies = (
   config: ResolvedConfig,
@@ -164,6 +184,7 @@ export const missingRuntimeDependencies = (
   ...searchProviderDependencies(config.search.provider, root, pkgDir),
   ...sourceAdapterDependencies(config.content.sources, root, pkgDir),
   ...assistantProviderDependencies(config.ai.assistant, root, pkgDir),
+  ...narrationProviderDependencies(config.narration, root, pkgDir),
   ...deploymentAdapterDependencies(config.deployment, root, pkgDir),
   ...islandFrameworkDependencies(frameworks, root),
 ];