blume 1.6.0 → 1.6.1

package/src/astro/generate.ts

@@ -91,10 +91,16 @@ import {
   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,
@@ -102,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,
@@ -120,6 +128,7 @@ import {
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
   playgroundProxyTemplate,
@@ -714,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}"], {
@@ -1169,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) {
@@ -1390,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,
@@ -1472,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,
@@ -1490,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"),
@@ -1605,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)) {
@@ -1613,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"),
@@ -1629,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>,
@@ -1643,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()),
+  ]);
 };
 
 /**
@@ -1733,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.
@@ -1748,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);
 
@@ -1776,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),
@@ -1870,14 +1909,12 @@ export const generateRuntime = async (
           contentRoot: docsCollection.base,
           contentRoutes: markdownRoutePaths(project),
           context,
-          dataPath,
           examplesPath,
           examplesThemePath,
           integrationBridge,
           needsReact,
           needsSvelte,
           needsVue,
-          openapiPath,
           pages,
           reactCompilerPath,
           searchClientPath,
@@ -1925,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,
         })
       ),
@@ -1986,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),
@@ -1996,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
+      )
     );
   }
 
@@ -2034,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()
@@ -2061,15 +2105,13 @@ export const generateRuntime = async (
   );
 
   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")
@@ -2078,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(
@@ -2097,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
@@ -2181,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`
@@ -2202,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 };
 };

package/src/astro/index.ts

@@ -5,3 +5,10 @@ export { withIncludeRefresh } from "./include-refresh.ts";
 export type { GenerateResult } from "./generate.ts";
 export { blumeIntegration } from "./integration.ts";
 export type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";
+export {
+  publishRuntimeModules,
+  readRuntimeModule,
+  RUNTIME_MODULE_FILES,
+  runtimeModulesPlugin,
+} from "./runtime-modules.ts";
+export type { RuntimeModuleId } from "./runtime-modules.ts";

package/src/astro/markdown-negotiation.ts

@@ -29,7 +29,7 @@ const parseAccept = (accept: string): AcceptEntry[] =>
 
 /**
  * Whether the client explicitly prefers Markdown over HTML. Browsers never send
- * `text/markdown`, so an ordinary page request (`text/html`, `*​/*`) is false.
+ * `text/markdown`, so an ordinary page request (`text/html` or the catch-all wildcard) is false.
  */
 export const prefersMarkdown = (accept: string | null | undefined): boolean => {
   if (!accept) {

package/src/astro/runtime-modules.ts

@@ -0,0 +1,196 @@
+/**
+ * In-memory runtime data modules.
+ *
+ * The generated runtime's data snapshots — the page data behind `blume:data`,
+ * the parsed API specs, the static search index, the raw-Markdown and
+ * content-asset maps, the MCP and Ask corpora, and the rendered RSS feeds —
+ * used to be written under `.blume/src/generated/*.json` and imported by the
+ * generated pages through aliases or relative paths. `generateRuntime` now
+ * publishes them here and `runtimeModulesPlugin` serves them to Vite as
+ * virtual modules, so a regeneration never round-trips the disk or waits on a
+ * file watcher: publishing invalidates the changed modules in every live dev
+ * server (Vite walks the importers, so the pages that render them re-evaluate
+ * on the next request) and asks the browser to reload — the same effect a JSON
+ * file change used to reach through the watcher, minus the write and the
+ * watch debounce.
+ *
+ * The registry hangs off `globalThis`, not module state. On a published
+ * install the CLI bundle (`dist/cli`) carries its own copy of this module,
+ * separate from the one Vite loads from `blume/astro` for the generated
+ * config, and both must see the same map. `blume dev`, `blume build`, and
+ * `blume check` all run Astro in-process, so the map the CLI fills is the map
+ * the plugin reads.
+ *
+ * `blume eject` keeps the file form: the ejected project has no CLI to
+ * publish, so its `astro.config.mjs` aliases each id to the JSON file eject
+ * writes under `src/generated/` — the names in {@link RUNTIME_MODULE_FILES}.
+ */
+
+export type RuntimeModuleId =
+  | "blume:ask-data"
+  | "blume:content-assets"
+  | "blume:data"
+  | "blume:mcp-data"
+  | "blume:openapi"
+  | "blume:raw-markdown"
+  | "blume:rss"
+  | "blume:search-index";
+
+/** Virtual module id → the `src/generated` JSON file eject writes for it. */
+export const RUNTIME_MODULE_FILES: ReadonlyMap<RuntimeModuleId, string> =
+  new Map([
+    ["blume:ask-data", "ask-data.json"],
+    ["blume:content-assets", "content-assets.json"],
+    ["blume:data", "data.json"],
+    ["blume:mcp-data", "mcp-data.json"],
+    ["blume:openapi", "openapi.json"],
+    ["blume:raw-markdown", "raw-markdown.json"],
+    ["blume:rss", "rss.json"],
+    ["blume:search-index", "search.json"],
+  ]);
+
+const RUNTIME_MODULE_IDS: ReadonlySet<string> = new Set(
+  RUNTIME_MODULE_FILES.keys()
+);
+
+/** Rollup's virtual-module convention: `\0` keeps other plugins off the id. */
+const RESOLVED_PREFIX = "\0";
+
+/** A node in Vite's module graph; only its identity matters here. */
+interface RuntimeModuleNode {
+  id: string | null;
+}
+
+/**
+ * The Vite dev-server slice the registry touches (structurally typed, like
+ * every Blume-authored Vite plugin — see `includeHmrPlugin`).
+ */
+export interface RuntimeModuleServer {
+  httpServer?: {
+    once: (event: "close", listener: () => void) => void;
+  } | null;
+  moduleGraph: {
+    getModuleById: (id: string) => RuntimeModuleNode | undefined;
+    invalidateModule: (mod: RuntimeModuleNode) => void;
+  };
+  ws: { send: (payload: { type: "full-reload" }) => void };
+}
+
+interface RuntimeModuleRegistry {
+  /** Published JSON text by module id. */
+  modules: Map<string, string>;
+  /** Live dev servers to invalidate on publish. */
+  servers: Set<RuntimeModuleServer>;
+}
+
+const REGISTRY_KEY = Symbol.for("blume.runtime-modules");
+
+type RegistryHost = typeof globalThis & {
+  [REGISTRY_KEY]?: RuntimeModuleRegistry;
+};
+
+const registry = (): RuntimeModuleRegistry => {
+  // SAFETY: the registry is stashed on globalThis under a well-known symbol so
+  // every copy of this module in the process shares it; the intersection only
+  // names that slot.
+  const host = globalThis as RegistryHost;
+  host[REGISTRY_KEY] ??= { modules: new Map(), servers: new Set() };
+  return host[REGISTRY_KEY];
+};
+
+/** The published JSON text for a module, if any (tests and diagnostics). */
+export const readRuntimeModule = (id: RuntimeModuleId): string | undefined =>
+  registry().modules.get(id);
+
+/**
+ * Replace the published snapshot set with `modules` (an id absent from the map
+ * is unpublished — its feature was switched off). Returns the ids whose text
+ * changed; each is invalidated in every live dev server, followed by one
+ * full-reload per server. Nothing is sent when nothing changed, so a
+ * regeneration triggered by an unrelated edit stays quiet — the same contract
+ * `writeIfChanged` gave the file form.
+ */
+export const publishRuntimeModules = (
+  modules: ReadonlyMap<RuntimeModuleId, string>
+): RuntimeModuleId[] => {
+  const { modules: current, servers } = registry();
+  const changed: RuntimeModuleId[] = [];
+  for (const id of RUNTIME_MODULE_FILES.keys()) {
+    const next = modules.get(id);
+    if (current.get(id) === next) {
+      continue;
+    }
+    if (next === undefined) {
+      current.delete(id);
+    } else {
+      current.set(id, next);
+    }
+    changed.push(id);
+  }
+  if (changed.length === 0) {
+    return changed;
+  }
+  for (const server of servers) {
+    for (const id of changed) {
+      const mod = server.moduleGraph.getModuleById(`${RESOLVED_PREFIX}${id}`);
+      if (mod) {
+        server.moduleGraph.invalidateModule(mod);
+      }
+    }
+    server.ws.send({ type: "full-reload" });
+  }
+  return changed;
+};
+
+export interface RuntimeModulesPlugin {
+  configureServer: (server: RuntimeModuleServer) => void;
+  enforce: "pre";
+  load: (id: string) => string | undefined;
+  name: string;
+  resolveId: (id: string) => string | undefined;
+}
+
+/**
+ * Serve the published runtime modules to Vite. `enforce: "pre"` claims the
+ * `blume:*` ids before Vite's resolver would try (and fail) to find them as
+ * packages. Loading an unpublished id is a hard error rather than an empty
+ * module: the generated pages only import a module when its data exists, so a
+ * miss means the config was run outside the CLI that publishes.
+ */
+export const runtimeModulesPlugin = (): RuntimeModulesPlugin => ({
+  configureServer(server) {
+    const { servers } = registry();
+    servers.add(server);
+    // Astro restarts the dev container in place on a config change (and the
+    // CLI restarts it on a route-set change): the old Vite server closes and
+    // a new one registers, so drop the stale handle rather than invalidating
+    // into a dead graph.
+    server.httpServer?.once("close", () => {
+      servers.delete(server);
+    });
+  },
+  enforce: "pre",
+  load(id) {
+    if (!id.startsWith(RESOLVED_PREFIX)) {
+      return;
+    }
+    const moduleId = id.slice(RESOLVED_PREFIX.length);
+    if (!RUNTIME_MODULE_IDS.has(moduleId)) {
+      return;
+    }
+    const text = registry().modules.get(moduleId);
+    if (text === undefined) {
+      throw new Error(
+        `Blume runtime module "${moduleId}" was requested before it was published. Run the generated project through the Blume CLI (blume dev / blume build), which publishes the runtime data before starting Astro.`
+      );
+    }
+    // A JSON.parse over a string literal evaluates faster than an equivalent
+    // object literal for large snapshots (V8's guidance; Vite's own JSON
+    // plugin does the same past a size threshold).
+    return `export default JSON.parse(${JSON.stringify(text)});\n`;
+  },
+  name: "blume:runtime-modules",
+  resolveId(id) {
+    return RUNTIME_MODULE_IDS.has(id) ? `${RESOLVED_PREFIX}${id}` : undefined;
+  },
+});