blume 0.6.7 → 0.8.0

package/src/astro/generate.ts

@@ -43,7 +43,10 @@ import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
-import { tailwindEntryTemplate } from "../theme/entry.ts";
+import {
+  examplesEntryTemplate,
+  tailwindEntryTemplate,
+} from "../theme/entry.ts";
 import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
@@ -51,7 +54,12 @@ import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
 import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
-import { customOgRoutes, discoverPages, routeIsTaken } from "./pages.ts";
+import {
+  customOgRoutes,
+  discoverPages,
+  hasGeneratedChangelog,
+  routeIsTaken,
+} from "./pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -61,6 +69,7 @@ import {
   envTemplate,
   exampleMapTemplate,
   exampleWrapperTemplate,
+  examplesPageTemplate,
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
@@ -93,6 +102,47 @@ const canResolveFrom = (fromDir: string, spec: string): boolean => {
   }
 };
 
+/**
+ * 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.
+ *
+ * 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.
+ */
+const resolveReactCompiler = (
+  config: ResolvedConfig,
+  needsReact: boolean
+): string | null => {
+  if (!(needsReact && config.react.compiler)) {
+    return null;
+  }
+  try {
+    return createRequire(
+      pathToFileURL(join(packageRoot(), "_.js")).href
+    ).resolve("babel-plugin-react-compiler");
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Warning (as a spreadable list) for the case where the React Compiler was
+ * requested but its plugin couldn't be resolved — so the build silently drops
+ * to uncompiled output rather than failing.
+ */
+const reactCompilerWarnings = (
+  config: ResolvedConfig,
+  needsReact: boolean,
+  compilerPath: string | null
+): string[] =>
+  needsReact && config.react.compiler && !compilerPath
+    ? [
+        "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.",
+      ]
+    : [];
+
 /**
  * Realpath of the `astro` package node resolves from a directory, or null when
  * none resolves. Comparing this for `.blume/` against Blume's own deps tells
@@ -145,7 +195,12 @@ const linkDepsJunction = async (
   link: string,
   depsDir: string
 ): Promise<void> => {
-  const existing = await lstat(link).catch(() => null);
+  let existing: Awaited<ReturnType<typeof lstat>> | null;
+  try {
+    existing = await lstat(link);
+  } catch {
+    existing = null;
+  }
   if (existing) {
     if (!existing.isSymbolicLink()) {
       return;
@@ -282,12 +337,61 @@ export const prerenderDepsPlugin = (
   },
 });
 
+/** The subset of Rollup's plugin context `blume:server-app-resolve` needs. */
+interface ServerAppResolveContext {
+  resolve: (source: string) => Promise<{ id: string } | null>;
+}
+
+/**
+ * Work around an Astro + Vite dev bug that breaks content renames.
+ *
+ * Astro's dev SSR entry is the virtual module `astro:server-app`, but its
+ * resolver only matches the exact id (`/^astro:server-app$/`). Whenever the
+ * route set changes — a content add, remove, or rename — Astro triggers a full
+ * page reload, during which Vite re-requests the entry as `astro:server-app.js`.
+ * The trailing `.js` misses Astro's filter, so the load fails ("Failed to load
+ * url astro:server-app.js") and Vite's SSR module runner is left corrupted: the
+ * in-memory content store never reconnects, so `getEntry` returns undefined and
+ * the renamed page 404s until the dev server is manually restarted.
+ *
+ * Stripping the spurious `.js` and delegating back to Astro's resolver lets the
+ * reload complete cleanly, so the renamed route resolves without a restart.
+ */
+export const serverAppResolvePlugin = (): {
+  enforce: "pre";
+  name: string;
+  resolveId: (
+    this: ServerAppResolveContext,
+    id: string
+  ) => Promise<string | null>;
+} => ({
+  enforce: "pre",
+  name: "blume:server-app-resolve",
+  async resolveId(id) {
+    if (id === "astro:server-app.js") {
+      const resolved = await this.resolve("astro:server-app");
+      return resolved?.id ?? null;
+    }
+    return null;
+  },
+});
+
 /** Astro integration package each non-React island framework needs installed. */
 const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
   svelte: "@astrojs/svelte",
   vue: "@astrojs/vue",
 };
 
+/**
+ * Adapter package the project must install itself for each deployment
+ * platform whose adapter Blume doesn't ship. Node and Vercel ship with Blume,
+ * so they never need this.
+ */
+const DEPLOYMENT_ADAPTER_DEPS: Record<string, string> = {
+  cloudflare: "@astrojs/cloudflare",
+  netlify: "@astrojs/netlify",
+};
+
 /**
  * Warn when a Vue/Svelte island is present but its Astro integration isn't
  * installed — Vite would otherwise fail opaquely on the generated config import.
@@ -309,6 +413,75 @@ const islandFrameworkWarnings = (
   return warnings;
 };
 
+/**
+ * Warn when the resolved server-output adapter is one the project must install
+ * itself (Netlify/Cloudflare; Node and Vercel ship with Blume). The generated
+ * astro.config.mjs imports the adapter package directly — and on those
+ * platforms the adapter is even auto-selected from env vars — so warn early
+ * rather than let the build die with an opaque ERR_MODULE_NOT_FOUND from the
+ * hidden generated config. Availability mirrors the search-provider check: a
+ * dep resolves from the project root or from the Blume package itself.
+ */
+const deploymentAdapterWarnings = (
+  deployment: ResolvedConfig["deployment"],
+  root: string
+): string[] => {
+  const dep =
+    deployment.output === "server" && deployment.adapter
+      ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter]
+      : undefined;
+  if (
+    dep &&
+    !(canResolveFrom(root, dep) || canResolveFrom(packageRoot(), dep))
+  ) {
+    return [
+      `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
+    ];
+  }
+  return [];
+};
+
+/** Absolute path to the configured `examples.css`, or null when unset. */
+const examplesCssFile = (root: string, config: ResolvedConfig): string | null =>
+  config.examples.css ? join(root, config.examples.css) : null;
+
+/**
+ * Write the per-example preview route (`{basePath}/blume-examples/<path>`)
+ * that `<Component />` iframes embed — the iframe boundary is what isolates
+ * previews from the docs CSS. Nested under `basePath` in the filesystem so
+ * the routes stay reachable behind a proxy that only forwards the base;
+ * pruneOrphans clears a stale copy when `basePath` changes or the last
+ * example is removed. Returns (as a spreadable list) a warning when the
+ * configured `examples.css` doesn't exist.
+ */
+const writeExamplesPreview = async (options: {
+  config: ResolvedConfig;
+  hasExamples: boolean;
+  root: string;
+  srcDir: string;
+  write: (path: string, content: string) => Promise<boolean>;
+}): Promise<string[]> => {
+  const { config, hasExamples, root, srcDir, write } = options;
+  if (hasExamples) {
+    await write(
+      join(
+        srcDir,
+        "pages",
+        ...config.basePath.split("/").filter(Boolean),
+        "blume-examples",
+        "[...path].astro"
+      ),
+      examplesPageTemplate()
+    );
+  }
+  const cssFile = examplesCssFile(root, config);
+  return cssFile && !existsSync(cssFile)
+    ? [
+        `examples.css points at "${config.examples.css}", which doesn't exist; previews render without it.`,
+      ]
+    : [];
+};
+
 /** Read a file's contents, or return an empty string if it is absent. */
 const readOptional = async (path: string | null): Promise<string> => {
   if (!path) {
@@ -331,16 +504,24 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
   return matches.length > 0;
 };
 
+/** Block math (`$$…$$`) or an explicitly authored `<Math …>` component. */
+const containsMath = (content: string): boolean =>
+  content.includes("$$") || content.includes("<Math");
+
 /**
- * Detect whether the project authors block math (`$$…$$`) in any `.mdx`. Drives
- * whether the generated runtime imports the `<Math>` component and KaTeX's
- * stylesheet, so a math-free site ships no KaTeX CSS. Math parsing itself is
- * always on but block-only, so a literal `$$` in source is a necessary
- * condition — no false negatives. A stray `$$` (e.g. inside a code fence) merely
- * over-includes the idempotent import, which is harmless.
+ * Detect whether the project can render math: block math (`$$…$$`) or an
+ * explicit `<Math>` tag in any local `.md`/`.mdx`, or in staged (non-filesystem)
+ * source bodies. Drives whether the generated runtime imports the `<Math>`
+ * component and KaTeX's stylesheet, so a math-free site ships no KaTeX CSS.
+ * Math parsing itself is always on but block-only, so one of those literals is
+ * a necessary condition — no false negatives. A stray `$$` (e.g. inside a code
+ * fence) merely over-includes the idempotent import, which is harmless.
  */
-export const detectUsesMath = async (root: string): Promise<boolean> => {
-  const files = await glob(["**/*.mdx"], {
+export const detectUsesMath = async (
+  root: string,
+  staged: Iterable<string> = []
+): Promise<boolean> => {
+  const files = await glob(["**/*.{md,mdx}"], {
     cwd: root,
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true,
@@ -348,7 +529,7 @@ export const detectUsesMath = async (root: string): Promise<boolean> => {
   const contents = await Promise.all(
     files.map((file) => readOptional(join(root, file)))
   );
-  return contents.some((content) => content.includes("$$"));
+  return [...contents, ...staged].some(containsMath);
 };
 
 const writeIfChanged = async (
@@ -397,12 +578,14 @@ export const pruneOrphans = async (
     cwd: srcDir,
     onlyFiles: true,
   });
-  await Promise.all(
-    existing
-      .map((path) => normalize(path))
-      .filter((path) => !written.has(path))
-      .map((path) => rm(path, { force: true }))
-  );
+  const removals: Promise<void>[] = [];
+  for (const path of existing) {
+    const normalized = normalize(path);
+    if (!written.has(normalized)) {
+      removals.push(rm(normalized, { force: true }));
+    }
+  }
+  await Promise.all(removals);
 };
 
 /**
@@ -601,7 +784,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       return null;
     }
     const rel = relative(context.root, sourcePath).split("\\").join("/");
-    return `${editBase}/${github?.dir ? `${github.dir}/${rel}` : rel}`;
+    const editPath = github?.dir ? `${github.dir}/${rel}` : rel;
+    return `${editBase}/${editPath}`;
   };
 
   const { i18n } = config;
@@ -659,6 +843,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         ? { suggestions: config.ai.ask.suggestions }
         : null,
       banner: resolveBanner(config),
+      basePath: config.basePath,
+      codeThemes: config.markdown.codeBlocks.theme,
       codeWrap: config.markdown.code.wrap,
       description: config.description,
       favicon: resolveFavicon(project),
@@ -800,6 +986,7 @@ const writeMcpFiles = async (
   }
   const data = await buildMcpData(project);
   const discoveryInput = {
+    base: data.base,
     name: data.name,
     route: plan.route,
     site: data.site,
@@ -878,32 +1065,6 @@ export interface GenerateResult {
   warnings: string[];
 }
 
-/**
- * Whether to generate the default `/changelog` index. Written when there are
- * `type: changelog` entries — or when a release-backed changelog source is
- * configured, so its route (and any nav tab pointing at it) still resolves to an
- * empty timeline on a build where the source could not be fetched (e.g. CI
- * without a token). Skipped when a user content page or a custom `.astro` page
- * already owns `/changelog`.
- */
-const shouldGenerateChangelog = (
-  project: BlumeProject,
-  userPages: { pattern: string }[]
-): boolean => {
-  const hasChangelog = project.graph.pages.some(
-    (page) =>
-      page.contentType === "changelog" &&
-      !(page.meta.draft || page.meta.sidebar.hidden)
-  );
-  const hasChangelogSource = (project.config.content.sources ?? []).some(
-    (source) => source.type === "github-releases"
-  );
-  return (
-    (hasChangelog || hasChangelogSource) &&
-    !routeIsTaken(userPages, project.graph.pages, "/changelog")
-  );
-};
-
 /**
  * Statically analyze the user's `components.ts` (never executing it) and plan the
  * generated `components.ts` module plus any hydration wrappers. Returns the plan
@@ -947,6 +1108,7 @@ export const generateRuntime = async (
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
+  const examplesThemePath = join(srcDir, "generated", "examples.css");
   const openapiPath = join(srcDir, "generated", "openapi.json");
 
   // Record every file this pass writes so orphans (from a now-disabled feature)
@@ -962,29 +1124,38 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
+  // entryId so i18n duplicates of one entry write a single file. Collected here
+  // so math detection also sees staged bodies (they never live under root).
+  const staged = collectStaged(project);
+  // Statically analyze `components.ts` overrides (never executed): drives the
+  // `islands` group, hydration on layout/mdx overrides, string-path resolution,
+  // and the "framework component with no client mode" diagnostic. Independent of
+  // the discovery reads, so it joins the same parallel batch.
   const [
     pages,
     detectedReact,
     usesMath,
     userTheme,
+    userExamplesCss,
     islandDiscovery,
     exampleDiscovery,
+    componentSlots,
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
-    detectUsesMath(context.root),
+    detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
+    readOptional(examplesCssFile(context.root, config)),
     discoverIslands(context.root),
-    discoverExamples(context.root, config.examples),
+    discoverExamples(context.root, config.examples.source),
+    buildComponentSlots(context.componentsFile),
   ]);
-  // Statically analyze `components.ts` overrides (never executed): drives the
-  // `islands` group, hydration on layout/mdx overrides, string-path resolution,
-  // and the "framework component with no client mode" diagnostic.
   const {
     plan: slotPlan,
     tags: overrideTags,
     warnings: overrideWarnings,
-  } = await buildComponentSlots(context.componentsFile);
+  } = componentSlots;
 
   // Each island/example framework enables its Astro renderer. React also
   // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
@@ -999,6 +1170,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);
+
   // 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
   // private and filtered out anyway, but the intent is the user's pages.
@@ -1010,9 +1187,6 @@ export const generateRuntime = async (
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
-  // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
-  // entryId so i18n duplicates of one entry write a single file.
-  const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
   // Only emit a project-scanning `docs` collection when a filesystem source
   // actually feeds it. An all-staged project (openapi/notion/…) has only staged
@@ -1020,120 +1194,135 @@ export const generateRuntime = async (
   // project root for nothing — see contentConfigTemplate.
   const hasFilesystemSource = project.sources.some((source) => !source.staged);
 
-  const structural = await Promise.all([
-    write(
-      join(out, "astro.config.mjs"),
-      astroConfigTemplate({
-        aliases: resolveTsconfigAliases(context.root),
-        config,
-        contentRoutes: project.manifest.routes.map((route) => route.path),
-        context,
-        dataPath,
-        examplesPath,
-        needsReact,
-        needsSvelte,
-        needsVue,
-        openapiPath,
-        pages,
-        searchClientPath,
+  // All of these write to distinct generated paths and never read one another's
+  // output, so the structural files, the per-convention hydration wrappers, and
+  // the Ask/MCP writers all run in one parallel batch. Only the structural
+  // writes' change flags feed `structuralChange`, so they stay a nested group.
+  const [structural] = await Promise.all([
+    Promise.all([
+      write(
+        join(out, "astro.config.mjs"),
+        astroConfigTemplate({
+          aliases: resolveTsconfigAliases(context.root),
+          config,
+          contentRoutes: project.manifest.routes.map((route) => route.path),
+          context,
+          dataPath,
+          examplesPath,
+          examplesThemePath,
+          needsReact,
+          needsSvelte,
+          needsVue,
+          openapiPath,
+          pages,
+          reactCompilerPath,
+          searchClientPath,
+          themePath,
+        })
+      ),
+      write(
+        join(out, "package.json"),
+        runtimePackageTemplate(
+          runtimeDependencies({ config, needsReact, needsSvelte, needsVue })
+        )
+      ),
+      write(join(out, "tsconfig.json"), runtimeTsconfigTemplate()),
+      write(join(srcDir, "env.d.ts"), envTemplate()),
+      write(
+        join(srcDir, "content.config.ts"),
+        contentConfigTemplate({
+          collection: resolveDocsCollection(config, context),
+          config,
+          context,
+          filesystem: hasFilesystemSource,
+          staged: hasStaged,
+        })
+      ),
+      write(
+        join(srcDir, "pages", "[...slug].astro"),
+        catchAllPageTemplate({
+          askEnabled,
+          exportEpub,
+          exportPdf,
+          mathEnabled: usesMath,
+          needsReact,
+        })
+      ),
+      write(join(srcDir, "generated", "components.ts"), slotPlan.module),
+      write(
+        join(srcDir, "generated", "islands.ts"),
+        islandMapTemplate(islandDiscovery.islands)
+      ),
+      write(
+        join(srcDir, "generated", "examples.ts"),
+        exampleMapTemplate(exampleDiscovery.examples, config.basePath)
+      ),
+      // The isolated Tailwind entry for `<Component />` preview frames: only
+      // example files (and the project sources they import) are scanned, so
+      // the docs theme never reaches a preview.
+      write(
+        examplesThemePath,
+        examplesEntryTemplate({
+          configTokens: buildThemeCss(config.theme),
+          sources: [`${context.root}/**/*.{astro,jsx,svelte,ts,tsx,vue}`],
+          userCss: userExamplesCss,
+        })
+      ),
+      write(
         themePath,
-      })
-    ),
-    write(
-      join(out, "package.json"),
-      runtimePackageTemplate(
-        runtimeDependencies({ config, needsReact, needsSvelte, needsVue })
+        tailwindEntryTemplate({
+          configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
+          sources: [
+            `${BLUME_SRC}/**/*.{astro,ts,tsx}`,
+            `${context.root}/**/*.{astro,mdx,ts,tsx}`,
+          ],
+          twoslashCss: twoslashCss(),
+          userTheme,
+        })
+      ),
+    ]),
+    // Per-island hydration wrappers for the `islands/` convention. The map
+    // module (written above, always) imports these; orphans from removed
+    // islands are pruned at the end of the pass.
+    Promise.all(
+      islandDiscovery.islands.map((island) =>
+        write(
+          join(srcDir, "generated", "islands", `${island.name}.astro`),
+          islandWrapperTemplate(island)
+        )
       )
     ),
-    write(join(out, "tsconfig.json"), runtimeTsconfigTemplate()),
-    write(join(srcDir, "env.d.ts"), envTemplate()),
-    write(
-      join(srcDir, "content.config.ts"),
-      contentConfigTemplate({
-        collection: resolveDocsCollection(config, context),
-        config,
-        context,
-        filesystem: hasFilesystemSource,
-        staged: hasStaged,
-      })
-    ),
-    write(
-      join(srcDir, "pages", "[...slug].astro"),
-      catchAllPageTemplate({
-        askEnabled,
-        exportEpub,
-        exportPdf,
-        mathEnabled: usesMath,
-        needsReact,
-      })
-    ),
-    write(join(srcDir, "generated", "components.ts"), slotPlan.module),
-    write(
-      join(srcDir, "generated", "islands.ts"),
-      islandMapTemplate(islandDiscovery.islands)
-    ),
-    write(
-      join(srcDir, "generated", "examples.ts"),
-      exampleMapTemplate(exampleDiscovery.examples)
+    // Per-override hydration wrappers for `defineComponents` islands and
+    // `client:*` layout/mdx overrides. The generated `components.ts` (written
+    // above) imports these; orphans from removed overrides are pruned at the
+    // end of the pass.
+    Promise.all(
+      slotPlan.wrappers.map((wrapper) =>
+        write(
+          join(srcDir, "generated", "component-slots", `${wrapper.name}.astro`),
+          wrapper.content
+        )
+      )
     ),
-    write(
-      themePath,
-      tailwindEntryTemplate({
-        configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
-        sources: [
-          `${BLUME_SRC}/**/*.{astro,ts,tsx}`,
-          `${context.root}/**/*.{astro,mdx,ts,tsx}`,
-        ],
-        twoslashCss: twoslashCss(),
-        userTheme,
-      })
+    // Per-example live wrappers for the `examples/` convention, resolved by
+    // `<Component path>` through the `examples.ts` map (written above, always).
+    Promise.all(
+      exampleDiscovery.examples.map((example) =>
+        write(
+          join(
+            srcDir,
+            "generated",
+            "examples",
+            `${exampleSlug(example.path)}.astro`
+          ),
+          exampleWrapperTemplate(example)
+        )
+      )
     ),
+    writeAskFiles(project, srcDir, write),
+    writeMcpFiles(project, mcp, write),
   ]);
 
-  // Per-island hydration wrappers for the `islands/` convention. The map module
-  // (written above, always) imports these; orphans from removed islands are
-  // pruned at the end of the pass.
-  await Promise.all(
-    islandDiscovery.islands.map((island) =>
-      write(
-        join(srcDir, "generated", "islands", `${island.name}.astro`),
-        islandWrapperTemplate(island)
-      )
-    )
-  );
-
-  // Per-override hydration wrappers for `defineComponents` islands and `client:*`
-  // layout/mdx overrides. The generated `components.ts` (written above) imports
-  // these; orphans from removed overrides are pruned at the end of the pass.
-  await Promise.all(
-    slotPlan.wrappers.map((wrapper) =>
-      write(
-        join(srcDir, "generated", "component-slots", `${wrapper.name}.astro`),
-        wrapper.content
-      )
-    )
-  );
-
-  // Per-example live wrappers for the `examples/` convention, resolved by
-  // `<Component path>` through the `examples.ts` map (written above, always).
-  await Promise.all(
-    exampleDiscovery.examples.map((example) =>
-      write(
-        join(
-          srcDir,
-          "generated",
-          "examples",
-          `${exampleSlug(example.path)}.astro`
-        ),
-        exampleWrapperTemplate(example)
-      )
-    )
-  );
-
-  await writeAskFiles(project, srcDir, write);
-
-  await writeMcpFiles(project, mcp, write);
-
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
@@ -1142,7 +1331,7 @@ export const generateRuntime = async (
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1155,12 +1344,23 @@ export const generateRuntime = async (
     );
   }
 
-  // The default 404 page (`/404`), unless the project already owns the route.
-  await writeNotFoundPage(write, srcDir, pages, project.graph.pages);
-
-  // The provider-specific client loader behind the `blume:search-client` alias
-  // is always (re)generated so the alias resolves even when search is disabled.
-  await write(searchClientPath, searchClientTemplate(config));
+  // Three independent writes: the per-example preview routes that
+  // `<Component />` iframes embed (returning a warning when the configured
+  // examples.css is missing), the default 404 page (`/404`, unless the project
+  // already owns the route), and the provider-specific client loader behind
+  // the `blume:search-client` alias — always (re)generated so the alias
+  // resolves even when search is disabled.
+  const [examplesWarnings] = await Promise.all([
+    writeExamplesPreview({
+      config,
+      hasExamples: exampleDiscovery.examples.length > 0,
+      root: context.root,
+      srcDir,
+      write,
+    }),
+    writeNotFoundPage(write, srcDir, pages, project.graph.pages),
+    write(searchClientPath, searchClientTemplate(config)),
+  ]);
 
   // Client-loaded providers (orama, flexsearch) ship a static index + endpoint.
   if (servesStaticIndex(config.search.provider)) {
@@ -1191,11 +1391,11 @@ export const generateRuntime = async (
     ),
     write(
       join(srcDir, "pages", "[...slug].md.ts"),
-      rawMarkdownEndpointTemplate()
+      rawMarkdownEndpointTemplate("md")
     ),
     write(
       join(srcDir, "pages", "[...slug].mdx.ts"),
-      rawMarkdownEndpointTemplate()
+      rawMarkdownEndpointTemplate("mdx")
     ),
   ]);
 
@@ -1222,9 +1422,11 @@ export const generateRuntime = async (
   // mounted on its configured route and regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
+    ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
     ...mcp.warnings,
     ...islandDiscovery.warnings,
     ...exampleDiscovery.warnings,
+    ...examplesWarnings,
     ...overrideWarnings,
   ];
 
@@ -1236,7 +1438,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceTabs(config).map((tab) => tab.path),
   ]);
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
   warnings.push(
@@ -1287,7 +1489,10 @@ export const generateRuntime = async (
 
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
+  warnings.push(
+    ...deploymentAdapterWarnings(config.deployment, context.root),
+    ...islandFrameworkWarnings(frameworks, context.root)
+  );
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
@@ -1302,27 +1507,26 @@ export const generateRuntime = async (
     );
   }
 
-  // Data and manifest are not "structural" for Astro; they hot-reload.
-  await write(
-    join(srcDir, "generated", "data.json"),
-    buildRuntimeData(project)
-  );
   // The parsed OpenAPI specs behind the `blume:openapi` alias. Always written
   // (even as `{}`) so the alias resolves whether or not a reference is enabled;
   // the source parsed the specs during the scan, so this is just serialization.
   const openApiSource = project.sources.find(isOpenApiSource);
-  await write(
-    openapiPath,
-    `${JSON.stringify(openApiSource ? openApiSource.openApiData() : {})}\n`
-  );
-  await write(
-    join(out, "blume.manifest.json"),
-    `${JSON.stringify(project.manifest, null, 2)}\n`
-  );
-
-  // Write staged source bodies and prune orphans under `.blume/content` (its own
-  // tree, outside `.blume/src`), so a removed remote entry doesn't linger.
-  await writeStagedContent(out, staged);
+  // These write to distinct trees and never read one another, so they batch.
+  // `data.json`/`openapi.json` and the manifest are not "structural" for Astro;
+  // they hot-reload. `writeStagedContent` owns the `.blume/content` tree (its
+  // own pruning), outside `.blume/src`, so a removed remote entry doesn't linger.
+  await Promise.all([
+    write(join(srcDir, "generated", "data.json"), buildRuntimeData(project)),
+    write(
+      openapiPath,
+      `${JSON.stringify(openApiSource ? openApiSource.openApiData() : {})}\n`
+    ),
+    write(
+      join(out, "blume.manifest.json"),
+      `${JSON.stringify(project.manifest, null, 2)}\n`
+    ),
+    writeStagedContent(out, staged),
+  ]);
 
   // Remove anything under `.blume/src` this pass didn't write — e.g. an Ask AI
   // endpoint left behind after the feature was switched off.