blume 1.5.3 → 1.6.1

package/src/astro/generate.ts

@@ -14,7 +14,15 @@ import { pathToFileURL } from "node:url";
 
 import { imageSize } from "image-size";
 import pMap from "p-map";
-import { basename, dirname, join, normalize, relative, resolve } from "pathe";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+} from "pathe";
 import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
@@ -25,7 +33,10 @@ import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import { analyzeComponentOverrides } from "../core/component-overrides.ts";
-import { collectContentAssets } from "../core/content-assets.ts";
+import {
+  collectContentAssets,
+  rewriteRelativeImages,
+} from "../core/content-assets.ts";
 import type {
   BlumeBanner,
   BlumeData,
@@ -34,8 +45,14 @@ import type {
 } from "../core/data.ts";
 import { BlumeError } from "../core/diagnostics.ts";
 import { writeTextAtomic } from "../core/fs-atomic.ts";
+import {
+  apiUrl as githubApiUrl,
+  editBaseUrl as githubEditBaseUrl,
+  repoUrl as githubRepoUrl,
+} from "../core/github.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
+import { buildIncludeGraph } from "../core/includes.ts";
 import {
   validateNavTargets,
   validateSearchPopularIcons,
@@ -44,14 +61,20 @@ import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveDocsCollection } from "../core/sources/resolve.ts";
+import { trimChar } from "../core/trim.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
-import type { Diagnostic, Navigation, ProjectContext } from "../core/types.ts";
+import type { Diagnostic, Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
-import type { OpenApiData } from "../openapi/model.ts";
-import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
+import type { ApiSpecData, OpenApiData } from "../openapi/model.ts";
+import {
+  builtinProxyKinds,
+  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";
@@ -62,12 +85,22 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
-import { buildFontsCss, configuredFonts } from "../theme/fonts.ts";
+import {
+  buildFontsCss,
+  configuredFonts,
+  fontLocaleCodes,
+} from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
+import { rebaseSourceDirectives } from "../theme/sources.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
-import { discoverExamples, exampleMarkdownLookup } from "./examples.ts";
+import {
+  EXAMPLE_SCAN_GLOB,
+  discoverExamples,
+  exampleMarkdownLookup,
+  exampleScanRoots,
+} from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
 import {
   customOgRoutes,
@@ -75,6 +108,8 @@ import {
   hasGeneratedChangelog,
   routeIsTaken,
 } from "./pages.ts";
+import { publishRuntimeModules } from "./runtime-modules.ts";
+import type { RuntimeModuleId } from "./runtime-modules.ts";
 import {
   askComponentTemplate,
   askEndpointTemplate,
@@ -93,12 +128,12 @@ import {
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
   playgroundProxyTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
-  runtimeDirWithin,
   staticJsonEndpointTemplate,
   runtimeDependencies,
   runtimePackageTemplate,
@@ -512,47 +547,6 @@ 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 interface ServerAppResolvePlugin {
-  enforce: "pre";
-  name: string;
-  resolveId: (
-    this: ServerAppResolveContext,
-    id: string
-  ) => Promise<string | null>;
-}
-
-export const serverAppResolvePlugin = (): ServerAppResolvePlugin => ({
-  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 = new Map([
   ["svelte", "@astrojs/svelte"],
@@ -729,6 +723,21 @@ const readOptional = async (path: string | null): Promise<string> => {
   }
 };
 
+/**
+ * Read a user stylesheet (`theme.css`, `examples.css`) that gets inlined into
+ * a generated Tailwind entry under `outputDir`, re-rooting its relative
+ * `@source` paths so they still resolve from where the author wrote them.
+ */
+const readUserCss = async (
+  file: string | null,
+  outputDir: string
+): Promise<string> => {
+  const css = await readOptional(file);
+  return file
+    ? rebaseSourceDirectives(css, { from: file, to: outputDir })
+    : css;
+};
+
 /** Heuristically detect whether the project uses React islands. */
 export const detectNeedsReact = async (root: string): Promise<boolean> => {
   const matches = await glob(["**/*.{tsx,jsx}"], {
@@ -843,7 +852,19 @@ export const collectStaged = (project: BlumeProject): Map<string, string> => {
   const staged = new Map<string, string>();
   for (const page of project.graph.pages) {
     if (page.collection === "staged" && page.entryId && page.body) {
-      staged.set(page.entryId, page.body.text);
+      // A colocated `./image.png` reference resolves against `.blume/content`
+      // once the body is materialized there, where the file does not exist.
+      // Point it at the served original instead — the same rewrite the
+      // agent-facing Markdown gets.
+      const text = page.sourcePath
+        ? rewriteRelativeImages({
+            deployBase: project.config.deployment.base,
+            projectRoot: project.context.root,
+            source: page.body.text,
+            sourcePath: page.sourcePath,
+          })
+        : page.body.text;
+      staged.set(page.entryId, text);
     }
   }
   return staged;
@@ -916,6 +937,22 @@ const readLogoSvg = (
 const isStringShorthand = <T>(value: T | string): value is string =>
   typeof value === "string";
 
+/**
+ * The URL behind the header's repo mark. A string is used as-is: `github`
+ * drives the per-page edit link, the header mark and the manifest's
+ * `repository` together, so a project whose docs repo is private has to unset
+ * all three, and would otherwise have no way to point the mark at anything.
+ */
+const headerRepoUrl = (
+  repo: boolean | string,
+  derived: string | null
+): string | null => {
+  if (isStringShorthand(repo)) {
+    return repo;
+  }
+  return repo ? derived : null;
+};
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -1156,7 +1193,11 @@ const resolveOgSite = (config: ResolvedConfig): string | undefined => {
     : undefined;
 };
 
-/** The OG card's subtitle: `seo.og.description` (`false` omits it) over the site description. */
+/**
+ * The OG card's site-wide subtitle: `seo.og.description` (`false` omits it)
+ * over the site description. The generated endpoint prefers a page's own
+ * description and falls back to this.
+ */
 const resolveOgDescription = (config: ResolvedConfig): string | undefined => {
   const configured = config.seo.og.description;
   if (configured === false) {
@@ -1165,14 +1206,29 @@ const resolveOgDescription = (config: ResolvedConfig): string | undefined => {
   return configured ?? config.description;
 };
 
+/**
+ * Repo coordinates for content components. `host` and the derived `api` ride
+ * along so a card on an Enterprise site links and queries that instance rather
+ * than the public one.
+ */
+const resolveGithubData = (
+  github: ResolvedConfig["github"]
+): BlumeData["config"]["github"] =>
+  github
+    ? {
+        api: githubApiUrl(github),
+        host: github.host,
+        owner: github.owner,
+        repo: github.repo,
+      }
+    : null;
+
 /** Serialize the content graph into the data module the runtime consumes. */
 export const buildRuntimeData = (project: BlumeProject): string => {
   const { config, context, graph, manifest } = project;
   const { github } = config;
-  const repoUrl = github
-    ? `https://github.com/${github.owner}/${github.repo}`
-    : null;
-  const editBase = github ? `${repoUrl}/edit/${github.branch}` : null;
+  const repoUrl = github ? githubRepoUrl(github) : null;
+  const editBase = github ? githubEditBaseUrl(github) : null;
   const logo = resolveLogo(project);
   const ogLogo = resolveOgMark(project, logo?.svg);
 
@@ -1181,7 +1237,18 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       return null;
     }
     const rel = relative(context.root, sourcePath).split("\\").join("/");
-    const editPath = github?.dir ? `${github.dir}/${rel}` : rel;
+    // The edit path is repo-relative: `github.dir` places the project inside
+    // the repo, so a source above the project dir (a monorepo vault beside the
+    // docs app) still resolves to an in-repo file. A path that escapes the
+    // repo itself has nothing to edit — fabricating one yields a 404 link.
+    // `dir` is a bare string in the schema, so a leading slash (`/apps/docs`)
+    // is trimmed rather than read as an absolute path — which would drop the
+    // link from every page of a site that has always written it that way.
+    const editDir = trimChar(github?.dir ?? "", "/");
+    const editPath = normalize(editDir ? join(editDir, rel) : rel);
+    if (editPath.startsWith("..") || isAbsolute(editPath)) {
+      return null;
+    }
     return `${editBase}/${editPath}`;
   };
 
@@ -1190,9 +1257,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
   // Resolve the header repo link per locale. API references no longer add a tab
   // automatically — authors point a `navigation.tabs` entry at the reference
   // route to surface it (see `referenceRoutes`).
+  const markUrl = headerRepoUrl(config.navigation.repo, repoUrl);
   const withRepoUrl = (nav: Navigation): Navigation => ({
     ...nav,
-    repoUrl: config.navigation.repo && repoUrl ? repoUrl : null,
+    repoUrl: markUrl,
   });
 
   // Resolved UI dictionaries: one per locale under i18n, English baseline
@@ -1221,6 +1289,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           code,
           withRepoUrl(
             graph.navigationByLocale[code] ?? {
+              actions: [],
+              cta: null,
               featured: [],
               selectors: [],
               sidebar: [],
@@ -1250,9 +1320,12 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       discovery: {
         agentReadability: config.seo.agentReadability,
         llmsTxt: config.ai.llmsTxt.enabled,
+        // Mirrors `buildSitemapFiles`: no site, no sitemap.
+        sitemap: config.seo.sitemap && Boolean(config.deployment.site),
       },
       favicon: resolveFavicon(project),
       feedback: config.feedback,
+      github: resolveGithubData(github),
       i18n: i18n
         ? {
             defaultLocale: i18n.defaultLocale,
@@ -1267,6 +1340,15 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             })),
           }
         : null,
+      // `undefined` members drop out of the JSON snapshot; the null keeps the
+      // "nothing configured" case explicit for the layouts.
+      identity:
+        config.seo.organization || config.seo.software
+          ? {
+              organization: config.seo.organization,
+              software: config.seo.software,
+            }
+          : null,
       imageZoom: config.markdown.imageZoom,
       logo,
       mcp: config.ai.mcp.enabled
@@ -1311,8 +1393,12 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       title: feed.title,
     })),
     // CSS variables for Astro's <Font> component; matches the astro.config
-    // `fonts:` entries derived from the same theme.fonts config.
-    fontCssVars: configuredFonts(config.theme.fonts),
+    // `fonts:` entries derived from the same theme.fonts config (and the
+    // same locale-derived subsets, so preloads cover the scripts pages use).
+    fontCssVars: configuredFonts(
+      config.theme.fonts,
+      fontLocaleCodes(config.i18n)
+    ),
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
@@ -1332,6 +1418,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     routes: manifest.routes.map((route) => ({
       alternates: route.alternates,
       collection: route.collection,
+      description: route.description ?? null,
       draft: route.draft,
       editUrl: route.editUrl ?? editUrlFor(route.sourcePath),
       entryId: route.entryId,
@@ -1414,16 +1501,24 @@ const planMcp = (
   };
 };
 
-/** Write the MCP data snapshot, server endpoint, and discovery documents. */
+/** A pass's runtime data modules, published together once every writer ran. */
+type RuntimeModules = Map<RuntimeModuleId, string>;
+
+/**
+ * Publish the MCP data snapshot (`blume:mcp-data`) and write the server
+ * endpoint and discovery documents.
+ */
 const writeMcpFiles = async (
   project: BlumeProject,
   plan: McpPlan,
-  write: (path: string, content: string) => Promise<boolean>
+  write: (path: string, content: string) => Promise<boolean>,
+  modules: RuntimeModules
 ): Promise<void> => {
   if (!plan.enabled) {
     return;
   }
   const data = await buildMcpData(project);
+  modules.set("blume:mcp-data", JSON.stringify(data));
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -1432,13 +1527,9 @@ const writeMcpFiles = async (
     version: data.version,
   };
   await Promise.all([
-    write(
-      join(plan.srcDir, "generated", "mcp-data.json"),
-      `${JSON.stringify(data)}\n`
-    ),
     write(
       join(plan.srcDir, "pages", mcpPageFile(plan.route)),
-      mcpEndpointTemplate(plan.route)
+      mcpEndpointTemplate()
     ),
     write(
       join(plan.dir, "discovery.ts"),
@@ -1460,11 +1551,7 @@ const writeMcpFiles = async (
  * `prerender = false` export wins over the injection default.
  */
 const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
-  enabled:
-    config.openapi.enabled &&
-    config.openapi.renderer === "blume" &&
-    config.openapi.playground.enabled &&
-    config.openapi.playground.proxy === true,
+  enabled: needsPlaygroundProxy(config),
   entrypoint: join(srcDir, "blume-openapi", "api-proxy.ts"),
   pattern: "/_api-proxy",
 });
@@ -1480,46 +1567,68 @@ const planPlaygroundProxy = (config: ResolvedConfig, srcDir: string) => ({
  * origin to allow and are skipped; AsyncAPI documents declare `servers` as a
  * map and contribute nothing (the proxy is OpenAPI-only).
  */
-const specOrigins = (data: OpenApiData): string[] => {
+const specOriginsOf = (spec: ApiSpecData): string[] => {
   const origins = new Set<string>();
-  for (const spec of Object.values(data)) {
-    // SAFETY: `document` is arbitrary parsed JSON; the assertion only names
-    // the optional `servers` shape, and every access below re-checks it —
-    // `Array.isArray(servers)` guards the list and `server.url ?? ""` the url.
-    const { servers } = spec.document as { servers?: { url?: string }[] };
-    for (const server of Array.isArray(servers) ? servers : []) {
-      const url = server.url ?? "";
-      // `new URL("https://{region}.api.example.com")` parses — the braces land
-      // in the hostname — so templated URLs need an explicit check or their
-      // junk literal becomes an allowlist entry no real request can match.
-      if (url.includes("{")) {
-        continue;
-      }
-      try {
-        origins.add(new URL(url).origin);
-      } catch {
-        // Not an absolute URL: nothing to allow.
-      }
+  // A GraphQL schema names no servers; its configured live endpoint is the
+  // one origin the playground targets.
+  if (spec.endpoint !== undefined) {
+    try {
+      origins.add(new URL(spec.endpoint).origin);
+    } catch {
+      // Not an absolute URL: nothing to allow.
     }
   }
-  return [...origins].toSorted();
+  // SAFETY: `document` is arbitrary parsed JSON; the assertion only names
+  // the optional `servers` shape, and every access below re-checks it —
+  // `Array.isArray(servers)` guards the list and `server.url ?? ""` the url.
+  const { servers } = spec.document as { servers?: { url?: string }[] };
+  for (const server of Array.isArray(servers) ? servers : []) {
+    const url = server.url ?? "";
+    // `new URL("https://{region}.api.example.com")` parses — the braces land
+    // in the hostname — so templated URLs need an explicit check or their
+    // junk literal becomes an allowlist entry no real request can match.
+    if (url.includes("{")) {
+      continue;
+    }
+    try {
+      origins.add(new URL(url).origin);
+    } catch {
+      // Not an absolute URL: nothing to allow.
+    }
+  }
+  return [...origins];
 };
 
+const specOrigins = (data: OpenApiData): string[] =>
+  [...new Set(Object.values(data).flatMap(specOriginsOf))].toSorted();
+
 /**
- * The build-time diagnostic for a proxy whose allowlist came out empty. The
- * allowlist comes solely from absolute `servers[].url` entries — relative and
- * templated ones carry no origin — and with none at all the endpoint would
- * 403 every playground send with nothing pointing the author at the spec.
+ * Build-time diagnostics for playground sends the built-in proxy would refuse.
+ * The baked-in allowlist pools every documented origin, but each spec's
+ * playground only ever targets that spec's own servers/endpoint — so a
+ * non-empty pool can still leave one spec's Send 403ing on every request.
+ * Hence the check is per spec: any spec routed through the built-in proxy
+ * whose own origins came out empty (no absolute `servers[].url`, no absolute
+ * GraphQL `endpoint`) gets a warning naming it.
  */
 const proxyAllowlistWarnings = (
-  enabled: boolean,
-  origins: string[]
-): string[] =>
-  enabled && origins.length === 0
-    ? [
-        "openapi.playground.proxy is enabled, but no spec declares an absolute servers[].url (relative and templated URLs carry no origin), so the proxy's allowlist is empty and it will refuse every request. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.",
-      ]
-    : [];
+  config: ResolvedConfig,
+  data: OpenApiData
+): string[] => {
+  const kinds = builtinProxyKinds(config);
+  const warnings: string[] = [];
+  for (const spec of Object.values(data)) {
+    if (!kinds.includes(spec.kind) || specOriginsOf(spec).length > 0) {
+      continue;
+    }
+    warnings.push(
+      spec.kind === "graphql"
+        ? `The "${spec.label}" GraphQL reference (${spec.route}) has playground.proxy: true, but no absolute endpoint is configured for it, so the built-in proxy has no origin to allow and will refuse every request its playground sends. Set the graphql block's (or the source's) \`endpoint\` to the live GraphQL URL, or point playground.proxy at an external proxy URL.`
+        : `The "${spec.label}" reference (${spec.route}) has playground.proxy: true, but its spec declares no absolute servers[].url (relative and templated URLs carry no origin), so the built-in proxy has no origin to allow and will refuse every request its playground sends. Add an absolute server URL to the spec, or point playground.proxy at an external proxy URL.`
+    );
+  }
+  return warnings;
+};
 
 /**
  * Write the Ask AI endpoint and, unless the backend runs its own retrieval
@@ -1529,7 +1638,8 @@ const proxyAllowlistWarnings = (
 const writeAskFiles = async (
   project: BlumeProject,
   srcDir: string,
-  write: (path: string, content: string) => Promise<boolean>
+  write: (path: string, content: string) => Promise<boolean>,
+  modules: RuntimeModules
 ): Promise<void> => {
   const { ask } = project.config.ai;
   if (!(ask?.enabled && !ask.endpoint)) {
@@ -1537,10 +1647,7 @@ const writeAskFiles = async (
   }
   const grounded = ask.provider !== "inkeep";
   if (grounded) {
-    await write(
-      join(srcDir, "generated", "ask-data.json"),
-      `${JSON.stringify(await buildAskData(project))}\n`
-    );
+    modules.set("blume:ask-data", JSON.stringify(await buildAskData(project)));
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
@@ -1553,10 +1660,11 @@ const writeAskFiles = async (
 
 /**
  * Write the default 404 page at Astro's reserved `src/pages/404.astro` path so
- * static builds emit `dist/404.html`. Skipped when the project already owns
- * `/404` (a custom `pages/404.astro` or a `404.md` content page), letting it be
- * fully overridden without a route collision; `pruneOrphans` then removes any
- * previously-generated copy.
+ * static builds emit `dist/404.html`, plus its Markdown twin at `404.md.ts`
+ * (`dist/404.md`) for agents that ask a missing URL for Markdown. Both are
+ * skipped when the project already owns `/404` (a custom `pages/404.astro` or
+ * a `404.md` content page), letting it be fully overridden without a route
+ * collision; `pruneOrphans` then removes any previously-generated copies.
  */
 const writeNotFoundPage = async (
   write: (path: string, content: string) => Promise<boolean>,
@@ -1567,7 +1675,10 @@ const writeNotFoundPage = async (
   if (routeIsTaken(pages, contentPages, "/404")) {
     return;
   }
-  await write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate());
+  await Promise.all([
+    write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate()),
+    write(join(srcDir, "pages", "404.md.ts"), notFoundMarkdownTemplate()),
+  ]);
 };
 
 /**
@@ -1615,20 +1726,6 @@ const buildComponentSlots = async (
   };
 };
 
-/**
- * Whether the docs glob-loader's watcher observes the runtime dir: a
- * filesystem collection whose base contains it (a migrated, `content.root:
- * "."` project) — the one layout where the dev watcher must be kept out of
- * Astro's cache dir. See `devWatchOption` in templates.ts.
- */
-const contentWatchesRuntimeDir = (
-  hasFilesystemSource: boolean,
-  collectionBase: string,
-  context: ProjectContext
-): boolean =>
-  hasFilesystemSource &&
-  runtimeDirWithin(collectionBase, context.outDir) !== null;
-
 /** The OG endpoint fonts for a scanned project (see {@link resolveOgFonts}). */
 const projectOgFonts = (project: BlumeProject): DerivedOgFonts =>
   resolveOgFonts(
@@ -1671,13 +1768,12 @@ export const generateRuntime = async (
   assertFontFilesExist(project);
   const out = context.outDir;
   const srcDir = join(out, "src");
+  const generatedDir = join(srcDir, "generated");
   const askPath = join(srcDir, "generated", "Ask.astro");
-  const dataPath = join(srcDir, "generated", "data.json");
   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)
   // can be pruned afterwards. `write` wraps the atomic writer and tracks paths.
@@ -1686,6 +1782,11 @@ export const generateRuntime = async (
     written.add(normalize(path));
     return writeIfChanged(path, content);
   };
+  // The data snapshots the generated pages import (`blume:data`, the search
+  // index, …) are collected here and published in memory at the end of the
+  // pass — see `runtime-modules.ts`. An id a feature leaves unset is
+  // unpublished, the in-memory counterpart of `pruneOrphans`.
+  const modules: RuntimeModules = new Map();
 
   const depsLinkWarning = await ensureDepsLink(out);
 
@@ -1714,8 +1815,8 @@ export const generateRuntime = async (
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
     detectUsesMath(context.root, staged.values()),
-    readOptional(context.themeFile),
-    readOptional(examplesCssFile(context.root, config)),
+    readUserCss(context.themeFile, generatedDir),
+    readUserCss(examplesCssFile(context.root, config), generatedDir),
     loadIntegrationBridge(config, context),
     discoverIslands(context.root),
     discoverExamples(context.root, config.examples.source),
@@ -1780,8 +1881,9 @@ export const generateRuntime = async (
       pattern: playgroundProxy.pattern,
     });
   }
-  // Computed once: the endpoint template bakes it in below, and an empty list
-  // is worth a diagnostic — the proxy would refuse every request it gets.
+  // Computed once: the endpoint template bakes it in below. A spec that
+  // contributes no origin of its own gets a per-spec diagnostic
+  // (`proxyAllowlistWarnings`) — the proxy would refuse its every send.
   const proxyOrigins = specOrigins(openApiData);
 
   const hasStaged = staged.size > 0;
@@ -1804,21 +1906,15 @@ export const generateRuntime = async (
           aliases: resolveTsconfigAliases(context.root),
           askPath,
           config,
+          contentRoot: docsCollection.base,
           contentRoutes: markdownRoutePaths(project),
-          contentWatchesRuntimeDir: contentWatchesRuntimeDir(
-            hasFilesystemSource,
-            docsCollection.base,
-            context
-          ),
           context,
-          dataPath,
           examplesPath,
           examplesThemePath,
           integrationBridge,
           needsReact,
           needsSvelte,
           needsVue,
-          openapiPath,
           pages,
           reactCompilerPath,
           searchClientPath,
@@ -1866,13 +1962,16 @@ export const generateRuntime = async (
         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.
+      // the project (and an out-of-root examples directory) is scanned, so the
+      // docs theme never reaches a preview. Anything further afield — a sibling
+      // package the examples import — is the user's `@source` in examples.css.
       write(
         examplesThemePath,
         examplesEntryTemplate({
           configTokens: buildThemeCss(config.theme),
-          sources: [`${context.root}/**/*.{astro,jsx,svelte,ts,tsx,vue}`],
+          sources: exampleScanRoots(context.root, exampleDiscovery.dir).map(
+            (dir) => `${dir}/${EXAMPLE_SCAN_GLOB}`
+          ),
           userCss: userExamplesCss,
         })
       ),
@@ -1927,8 +2026,8 @@ export const generateRuntime = async (
         )
       )
     ),
-    writeAskFiles(project, srcDir, write),
-    writeMcpFiles(project, mcp, write),
+    writeAskFiles(project, srcDir, write, modules),
+    writeMcpFiles(project, mcp, write, modules),
     playgroundProxy.enabled
       ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
       : Promise.resolve(false),
@@ -1937,7 +2036,14 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate(ogRoutes, projectOgFonts(project), changelogIndex)
+      ogEndpointTemplate(
+        ogRoutes,
+        {
+          ...projectOgFonts(project),
+          pageDescriptions: config.seo.og.description !== false,
+        },
+        changelogIndex
+      )
     );
   }
 
@@ -1975,10 +2081,7 @@ export const generateRuntime = async (
   // Client-loaded providers (orama, flexsearch) ship a static index + endpoint.
   if (servesStaticIndex(config.search.provider)) {
     const documents = await buildSearchDocuments(project);
-    await write(
-      join(srcDir, "generated", "search.json"),
-      `${JSON.stringify(documents)}\n`
-    );
+    modules.set("blume:search-index", JSON.stringify(documents));
     await write(
       join(srcDir, "pages", "blume-search.json.ts"),
       searchEndpointTemplate()
@@ -1993,16 +2096,22 @@ export const generateRuntime = async (
     );
   }
 
+  // The include graph (partial → including pages) behind `includeHmrPlugin`:
+  // editing a partial invalidates every page that splices it. Written even
+  // when empty so the plugin's configured path always resolves.
+  await write(
+    join(srcDir, "generated", "includes.json"),
+    `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`
+  );
+
   const rawMarkdown = await buildRawMarkdown(project);
+  modules.set("blume:raw-markdown", JSON.stringify(rawMarkdown));
   // The originals behind the rewritten `/blume-assets/content/…` references in
   // the agent-facing Markdown, plus the endpoint that serves them (and the
   // remote-source assets materialized under `.blume/public/blume-assets`).
   const contentAssets = await collectContentAssets(project);
+  modules.set("blume:content-assets", JSON.stringify(contentAssets));
   await Promise.all([
-    write(
-      join(srcDir, "generated", "raw-markdown.json"),
-      `${JSON.stringify(rawMarkdown)}\n`
-    ),
     write(
       join(srcDir, "pages", "[...slug].md.ts"),
       rawMarkdownEndpointTemplate("md")
@@ -2011,10 +2120,6 @@ export const generateRuntime = async (
       join(srcDir, "pages", "[...slug].mdx.ts"),
       rawMarkdownEndpointTemplate("mdx")
     ),
-    write(
-      join(srcDir, "generated", "content-assets.json"),
-      `${JSON.stringify(contentAssets)}\n`
-    ),
     write(
       join(srcDir, "pages", "blume-assets", "[...asset].ts"),
       contentAssetsEndpointTemplate(
@@ -2030,16 +2135,11 @@ export const generateRuntime = async (
     const feedXml = Object.fromEntries(
       feeds.map((feed) => [feed.type, renderRssFeed(feed)])
     );
-    await Promise.all([
-      write(
-        join(srcDir, "generated", "rss.json"),
-        `${JSON.stringify(feedXml)}\n`
-      ),
-      write(
-        join(srcDir, "pages", "[section]", "rss.xml.ts"),
-        rssEndpointTemplate()
-      ),
-    ]);
+    modules.set("blume:rss", JSON.stringify(feedXml));
+    await write(
+      join(srcDir, "pages", "[section]", "rss.xml.ts"),
+      rssEndpointTemplate()
+    );
   }
 
   // Scalar-rendered API/AsyncAPI reference pages (`renderer: "scalar"`). One
@@ -2047,7 +2147,7 @@ export const generateRuntime = async (
   // regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
-    ...proxyAllowlistWarnings(playgroundProxy.enabled, proxyOrigins),
+    ...proxyAllowlistWarnings(config, openApiData),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
     ...mcp.warnings,
     ...islandDiscovery.warnings,
@@ -2114,16 +2214,16 @@ export const generateRuntime = async (
     );
   }
 
-  // `openapi.json` (the `blume:openapi` alias) is always written — even as `{}`
-  // — so the alias resolves whether or not a reference is enabled; the specs
-  // were parsed during the scan, so this is just serialization.
+  // `blume:openapi` is always published — even as `{}` — so the import resolves
+  // whether or not a reference is enabled; the specs were parsed during the
+  // scan, so this is just serialization. `blume:data` is the page data every
+  // layout reads. Neither is "structural" for Astro; publishing hot-reloads.
+  modules.set("blume:data", buildRuntimeData(project));
+  modules.set("blume:openapi", JSON.stringify(openApiData));
   // 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.
+  // `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(openApiData)}\n`),
     write(
       join(out, "blume.manifest.json"),
       `${JSON.stringify(project.manifest, null, 2)}\n`
@@ -2135,5 +2235,10 @@ export const generateRuntime = async (
   // endpoint left behind after the feature was switched off.
   await pruneOrphans(srcDir, written);
 
+  // Publish last, once every page that imports a module is on disk: a live
+  // dev server invalidates the changed modules and reloads the browser against
+  // the finished tree, never a half-written one.
+  publishRuntimeModules(modules);
+
   return { structuralChange: structural.some(Boolean), warnings };
 };