blume 1.6.0 → 1.6.2

package/src/astro/templates.ts

@@ -22,6 +22,7 @@ import type { ExampleSpec } from "./examples.ts";
 import type { BlumePageRoute } from "./integration.ts";
 import type { IslandSpec } from "./islands.ts";
 import type { OgCustomRoute } from "./pages.ts";
+import { RUNTIME_MODULE_FILES } from "./runtime-modules.ts";
 
 const WORKSPACE_MARKERS = [
   ".git",
@@ -290,9 +291,38 @@ const adapterRoot = (context: ProjectContext): string =>
  * re-optimization. A blanket `/node_modules/` exclude would instead switch the
  * React Compiler off for Blume's own components in published installs (they
  * resolve under `node_modules/blume/src`, and exclude beats include in the
- * plugin's filter), so only the pre-bundle cache is excluded.
+ * plugin's filter), so only the pre-bundle cache is excluded. The hidden runtime
+ * relocates that cache to `<runtime>/.cache/vite` (see `cacheOptions`), so both
+ * the default and the relocated path are excluded.
  */
-const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//]`;
+const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//, /\/\.cache\/vite\//]`;
+
+/**
+ * The `cacheDir` entries for the generated config's top level and its `vite`
+ * block. The hidden runtime's `node_modules` is a junction into Blume's own
+ * package directory, and Astro (`node_modules/.astro`: the content data store,
+ * the fonts cache) and Vite (`node_modules/.vite`: pre-bundled deps) both
+ * default their caches under the project's `node_modules`. Two Blume projects
+ * that resolve the same package (a monorepo building docs and a sandbox in
+ * parallel) would therefore share one data store, and each build would serve
+ * the other's content — or 404 on entries the other cleared. Keep every cache
+ * inside the runtime dir instead. An ejected project (`generatedModulesDir`
+ * set) has real `node_modules`, so it keeps the defaults.
+ */
+const runtimeCacheOptions = (
+  context: ProjectContext,
+  generatedModulesDir: string | undefined
+) => {
+  if (generatedModulesDir !== undefined) {
+    return { astro: "", vite: "" };
+  }
+  return {
+    astro: `
+  cacheDir: ${JSON.stringify(`${context.outDir}/.cache/astro`)},`,
+    vite: `
+    cacheDir: ${JSON.stringify(`${context.outDir}/.cache/vite`)},`,
+  };
+};
 
 /**
  * The `react()` integration call. When `compilerPath` is set (the resolved
@@ -394,6 +424,40 @@ const resolveOptimizeDeps = (options: {
   return { optimizeDepsEntries, optimizeDepsInclude };
 };
 
+/**
+ * How the generated config reaches the runtime data modules (`blume:data`,
+ * the search index, …): served from memory by `runtimeModulesPlugin` in the
+ * hidden runtime, or aliased to JSON files under `generatedModulesDir` for an
+ * ejected project, which has no CLI to publish them (see `runtime-modules.ts`).
+ */
+interface RuntimeModuleWiring {
+  /** `resolve.alias` entries (one per module), empty in the in-memory form. */
+  aliasLines: string;
+  /** Extra `blume/astro` imports the wiring needs. */
+  imports: string[];
+  /** Leading `vite.plugins` entry, empty in the file-alias form. */
+  pluginEntry: string;
+}
+
+const renderRuntimeModuleWiring = (
+  generatedModulesDir: string | undefined
+): RuntimeModuleWiring => {
+  if (generatedModulesDir === undefined) {
+    return {
+      aliasLines: "",
+      imports: ["runtimeModulesPlugin"],
+      pluginEntry: "runtimeModulesPlugin(), ",
+    };
+  }
+  const aliasLines = [...RUNTIME_MODULE_FILES]
+    .map(
+      ([id, file]) =>
+        `\n        ${JSON.stringify(id)}: ${JSON.stringify(`${generatedModulesDir}/${file}`)},`
+    )
+    .join("");
+  return { aliasLines, imports: [], pluginEntry: "" };
+};
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -404,13 +468,18 @@ export const astroConfigTemplate = (options: {
   contentRoutes: string[];
   /** The generated Ask trigger (`blume:ask`); renders nothing when Ask is off. */
   askPath: string;
-  dataPath: string;
   examplesPath: string;
   /** The example-preview Tailwind entry (`blume:examples-theme`). */
   examplesThemePath: string;
   themePath: string;
   searchClientPath: string;
-  openapiPath: string;
+  /**
+   * Where the runtime data modules (`blume:data`, the search index, …) live as
+   * JSON files, for a project with no CLI to publish them in memory (eject):
+   * each id is aliased to its file under this directory. Absent, the modules
+   * are served from memory by `runtimeModulesPlugin` — the hidden runtime.
+   */
+  generatedModulesDir?: string;
   /**
    * Absolute path to `babel-plugin-react-compiler` when the React Compiler is
    * enabled (resolved from Blume's package root by the caller); null/absent
@@ -427,17 +496,27 @@ export const astroConfigTemplate = (options: {
   /** Bridge used to load configured integrations without serializing them. */
   integrationBridge?: IntegrationBridgeOptions;
 }): string => {
-  const { context, config, needsReact, pages, dataPath, themePath } = options;
+  const { context, config, needsReact, pages, themePath } = options;
+
+  const { astro: cacheOptions, vite: viteCacheOption } = runtimeCacheOptions(
+    context,
+    options.generatedModulesDir
+  );
   const {
     askPath,
     contentRoutes,
     examplesPath,
     examplesThemePath,
+    generatedModulesDir,
     needsSvelte,
     needsVue,
-    openapiPath,
     searchClientPath,
   } = options;
+  const {
+    aliasLines: runtimeModuleAliasLines,
+    imports: runtimeModuleImports,
+    pluginEntry: runtimeModulesPluginEntry,
+  } = renderRuntimeModuleWiring(generatedModulesDir);
   const { deployment } = config;
   const userAliasLines = renderUserAliases(options.aliases);
   const server = deployment.output === "server";
@@ -588,6 +667,7 @@ export const astroConfigTemplate = (options: {
     "blumeIntegration",
     "includeHmrPlugin",
     "prerenderDepsPlugin",
+    ...runtimeModuleImports,
     ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
   ];
   const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
@@ -655,7 +735,7 @@ ${userConfigSetup}export default defineConfig({
   root: ${JSON.stringify(context.outDir)},
   srcDir: ${JSON.stringify(`${context.outDir}/src`)},
   outDir: ${JSON.stringify(astroOutDir(context))},
-  publicDir: ${JSON.stringify(`${context.root}/public`)},
+  publicDir: ${JSON.stringify(`${context.root}/public`)},${cacheOptions}
   output: ${JSON.stringify(deployment.output)},${adapterOption}${sessionOption}${siteOption}${baseOption}${imageOption}${redirectsOption}${i18nOption}${fontsOption}
   integrations: [${integrations.join(", ")}${userIntegrationSpread}],
   markdown: {
@@ -683,8 +763,8 @@ ${userConfigSetup}export default defineConfig({
   // request latency behind the user's intent, so most navigations swap
   // instantly.
   prefetch: { prefetchAll: true },
-  vite: {
-    plugins: [tailwindcss(), includeHmrPlugin(${JSON.stringify(
+  vite: {${viteCacheOption}
+    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${JSON.stringify(
       `${context.outDir}/src/generated/includes.json`
     )}), prerenderDepsPlugin()],
     // Everything hydration can reach must be part of the dev dep optimizer's
@@ -733,12 +813,10 @@ ${userConfigSetup}export default defineConfig({
     resolve: {
       alias: {
         "blume:ask": ${JSON.stringify(askPath)},
-        "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
         "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
-        "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
-        "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
+        "blume:theme": ${JSON.stringify(themePath)},${runtimeModuleAliasLines}${userAliasLines}
       },
     },
     server: {
@@ -932,7 +1010,7 @@ export const askEndpointTemplate = (
   if (grounded) {
     imports.push(
       'import { createAskContext } from "blume/ai/ask-context.ts";',
-      'import askData from "../../generated/ask-data.json";'
+      'import askData from "blume:ask-data";'
     );
     const groundFields: string[] = [];
     if (instructions) {
@@ -1080,7 +1158,7 @@ const { strings } = Astro.props;
 /** Generate the static search index endpoint (`/blume-search.json`). */
 export const searchEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
-import documents from "../generated/search.json";
+import documents from "blume:search-index";
 
 export const prerender = true;
 
@@ -1258,7 +1336,7 @@ export const POST: APIRoute = async ({ request }) => {
  */
 export const rawMarkdownEndpointTemplate = (kind: "md" | "mdx"): string =>
   `// Generated by Blume. Do not edit.
-import raw from "../generated/raw-markdown.json";
+import raw from "blume:raw-markdown";
 
 export const prerender = true;
 
@@ -1308,7 +1386,7 @@ import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import type { APIRoute } from "astro";
-import assets from "../../generated/content-assets.json";
+import assets from "blume:content-assets";
 
 export const prerender = true;
 
@@ -1400,22 +1478,18 @@ export const mcpPageFile = (route: string): string =>
  * generated data snapshot. Runs server-side (no prerender) so agents can query
  * the docs over Streamable HTTP.
  */
-export const mcpEndpointTemplate = (route: string): string => {
-  const clean = trimChar(route, "/");
-  const up = "../".repeat(clean.split("/").length);
-  return `// Generated by Blume. Do not edit.
+export const mcpEndpointTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";
 import { createMcpFetchHandler } from "blume/ai/mcp/server.ts";
-import type { McpData } from "blume/ai/mcp/data.ts";
-import data from "${up}generated/mcp-data.json";
+import data from "blume:mcp-data";
 
 export const prerender = false;
 
-const handler = createMcpFetchHandler(data as McpData);
+const handler = createMcpFetchHandler(data);
 
 export const ALL: APIRoute = ({ request }) => handler(request);
 `;
-};
 
 /**
  * Generate the playground's CORS proxy endpoint
@@ -1464,7 +1538,7 @@ export function GET() {
  */
 export const rssEndpointTemplate = (): string =>
   `// Generated by Blume. Do not edit.
-import feeds from "../../generated/rss.json";
+import feeds from "blume:rss";
 
 export const prerender = true;
 
@@ -1486,7 +1560,16 @@ export function GET({ props }: { props: { section: string } }) {
 /** Generate the OG image endpoint (`.blume/src/pages/og/[...slug].png.ts`). */
 export const ogEndpointTemplate = (
   customRoutes: OgCustomRoute[] = [],
-  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {},
+  og: {
+    families?: OgFontFamilies;
+    fonts?: OgFont[];
+    /**
+     * Whether a page's own description may replace the site-wide subtitle.
+     * `false` when `seo.og.description` is `false`, which hides the subtitle
+     * on every card, page text included. Defaults to `true`.
+     */
+    pageDescriptions?: boolean;
+  } = {},
   includeChangelog = false
 ): string =>
   `// Generated by Blume. Do not edit.
@@ -1510,28 +1593,52 @@ const families: OgFontFamilies | undefined = ${
     og.families ? JSON.stringify(og.families) : "undefined"
   };
 
+// A page's own description (its \`seo.description\`, else \`description\`) is
+// the card subtitle, so the image says what the page's og:description says.
+// Pages without one fall back to the site-wide subtitle at render time.
+// \`seo.og.description: false\` hides the subtitle on every card, page text
+// included, which is what switches this off.
+const pageDescriptions = ${og.pageDescriptions !== false};
+
+interface CardProps {
+  title: string;
+  description: string | null;
+}
+
 export function getStaticPaths() {
   const seen = new Set<string>();
-  const paths: { params: { slug: string }; props: { title: string } }[] = [];
-  const add = (slug: string, title: string) => {
+  const paths: { params: { slug: string }; props: CardProps }[] = [];
+  const add = (slug: string, title: string, description: string | null) => {
     if (seen.has(slug)) {
       return;
     }
     seen.add(slug);
-    paths.push({ params: { slug }, props: { title } });
+    paths.push({
+      params: { slug },
+      props: { title, description: pageDescriptions ? description : null },
+    });
   };
   // A custom page wins over a content route sharing its path, so add it first.
+  // Its description is unknown at generate time, so it takes the site subtitle.
   for (const route of customRoutes) {
-    add(route.slug, route.title);
+    add(route.slug, route.title, null);
   }
   for (const route of data.routes) {
-    add(route.path === "/" ? "index" : route.path.slice(1), route.title);
+    add(
+      route.path === "/" ? "index" : route.path.slice(1),
+      route.title,
+      route.description
+    );
   }${
     includeChangelog
       ? `
   // The generated changelog index is not a content route, so it needs its own
   // card. Added last: a custom page or content route owning /changelog wins.
-  add("changelog", data.ui.changelog?.title ?? "Changelog");`
+  add(
+    "changelog",
+    data.ui.changelog?.title ?? "Changelog",
+    data.ui.changelog?.description ?? null
+  );`
       : ""
   }
   return paths;
@@ -1544,11 +1651,11 @@ const repoSlug = data.config.github
   ? \`\${data.config.github.owner}/\${data.config.github.repo}\`
   : undefined;
 
-export async function GET({ props }: { props: { title: string } }) {
+export async function GET({ props }: { props: CardProps }) {
   const png = await renderOgImage({
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
-    description: data.config.og.description,
+    description: props.description ?? data.config.og.description,
     families,
     fonts,
     logo: data.config.og.logo,
@@ -1572,13 +1679,11 @@ export async function GET({ props }: { props: { title: string } }) {
  * but mounted inside Blume's {@link ReferenceLayout} so the page keeps Blume's
  * navbar on top. `renderMode: "client"` mounts the reference into a container
  * element (rather than emitting a full HTML document), which is what lets it
- * live inside our shell. `dataImport` is the route-depth-aware relative path to
- * the generated data module the layout reads.
+ * live inside our shell.
  */
 export const scalarReferenceTemplate = <Configuration extends object>(options: {
   /** Scalar options forwarded verbatim (spec/theme config plus the author's `scalar` escape hatch). */
   configuration: Configuration;
-  dataImport: string;
   noindex?: boolean;
   route: string;
   title: string;
@@ -1587,7 +1692,7 @@ export const scalarReferenceTemplate = <Configuration extends object>(options: {
 // Generated by Blume. Do not edit.
 import { ScalarComponent } from "@scalar/astro";
 import ReferenceLayout from "blume/components/layout/ReferenceLayout.astro";
-import data from ${JSON.stringify(options.dataImport)};
+import data from "blume:data";
 
 export const prerender = true;
 
@@ -2411,6 +2516,231 @@ const suggestions = [
 </PageLayout>
 `;
 
+/**
+ * Generate `.blume/src/pages/404.md.ts`: the Markdown twin of the default 404
+ * page, prerendered to `dist/404.md`. An agent that asked for a missing page
+ * with `Accept: text/markdown` — or fetched a `.md` URL no page backs — gets
+ * this body with the 404 status instead of the HTML shell; Vercel server
+ * builds wire that into the routing config (`deploy/vercel-negotiation.ts`).
+ * Same recovery links as the HTML page, absolute when the site URL is known:
+ * the body is read out of context, so a relative link would leave the reader
+ * guessing the host. Written alongside `404.astro` and skipped under the same
+ * rule, so a project that owns `/404` owns both variants.
+ */
+export const notFoundMarkdownTemplate =
+  (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import { withBase } from "blume/components/islands/base-path.ts";
+import { absoluteUrl } from "blume/core/site-url.ts";
+import data from "blume:data";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+
+// Absolute for internal routes when the site is known; an external tab href
+// passes through untouched.
+const href = (path: string): string => {
+  const based = withBase(path);
+  return data.config.site && based.startsWith("/") && !based.startsWith("//")
+    ? absoluteUrl(data.config.site, based)
+    : based;
+};
+
+// The recovery set of 404.astro: home, every top-level section (a tab links to
+// its resolved target), then the machine-readable indexes that exist.
+const links = [
+  { href: href("/"), label: nf.home },
+  ...data.navigation.tabs.map((tab) => ({
+    href: href(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: href("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: href("/llms.txt"), label: nf.llms }]
+    : []),
+  ...(data.config.discovery.api
+    ? [{ href: href("/openapi.json"), label: nf.api }]
+    : []),
+];
+
+const body = [
+  "# " + nf.title,
+  "",
+  nf.description,
+  "",
+  "## " + nf.suggestions,
+  "",
+  ...links.map((link) => "- [" + link.label + "](" + link.href + ")"),
+  "",
+].join("\\n");
+
+export function GET() {
+  return new Response(body, {
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      // ~4 characters per token; keep in sync with markdownTokenCount.
+      "x-markdown-tokens": String(Math.ceil(body.length / 4)),
+    },
+  });
+}
+`;
+
+/**
+ * Generate `.blume/src/pages/404.json.ts`: the JSON twin of the default 404
+ * page, prerendered to `dist/404.json` as RFC 9457 problem details. An agent
+ * that asked for a missing page with `Accept: application/json` gets this body
+ * with the 404 status instead of the HTML shell (Vercel server builds wire
+ * that into the routing config, like the Markdown twin). Same recovery links
+ * as the other variants, carried as `links` and spelled out in `resolution`.
+ * Written alongside `404.astro` and skipped under the same rule.
+ */
+export const notFoundJsonTemplate =
+  (): string => `// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import { problem } from "blume/ai/api/problem.ts";
+import { withBase } from "blume/components/islands/base-path.ts";
+import { absoluteUrl } from "blume/core/site-url.ts";
+import data from "blume:data";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+
+// Absolute for internal routes when the site is known; an external tab href
+// passes through untouched.
+const href = (path: string): string => {
+  const based = withBase(path);
+  return data.config.site && based.startsWith("/") && !based.startsWith("//")
+    ? absoluteUrl(data.config.site, based)
+    : based;
+};
+
+// The recovery set of 404.astro: home, every top-level section (a tab links to
+// its resolved target), then the machine-readable indexes that exist.
+const links = [
+  { href: href("/"), label: nf.home },
+  ...data.navigation.tabs.map((tab) => ({
+    href: href(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: href("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: href("/llms.txt"), label: nf.llms }]
+    : []),
+  ...(data.config.discovery.api
+    ? [{ href: href("/openapi.json"), label: nf.api }]
+    : []),
+];
+
+const body = problem({
+  code: "PAGE_NOT_FOUND",
+  detail: nf.description,
+  links,
+  resolution: nf.suggestions + ": " + links.map((link) => link.href).join(", "),
+  status: 404,
+  title: nf.title,
+});
+
+export function GET() {
+  return new Response(JSON.stringify(body, null, 2) + "\\n", {
+    headers: { "Content-Type": "application/problem+json; charset=utf-8" },
+  });
+}
+`;
+
+/**
+ * Generate the prerendered JSON docs API endpoints under
+ * `.blume/src/pages/api/docs/`: the page index (`pages.json`), one JSON
+ * document per page (`pages/[...route].json`), and the navigation tree
+ * (`navigation.json`). Each is a thin wrapper over `blume/ai/api/handlers.ts`
+ * reading the same snapshot the MCP server serves (`blume:mcp-data`), so the
+ * REST and MCP answers can never diverge.
+ */
+export const apiPagesIndexTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import { pagesIndexResponse } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = true;
+
+export function GET() {
+  return pagesIndexResponse(data);
+}
+`;
+
+export const apiPageTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import { pageParams, pageResponse } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = true;
+
+export function getStaticPaths() {
+  return pageParams(data);
+}
+
+export function GET({ props }: { props: { route: string } }) {
+  return pageResponse(data, props.route);
+}
+`;
+
+export const apiNavigationTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import { navigationResponse } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = true;
+
+export function GET() {
+  return navigationResponse(data);
+}
+`;
+
+/**
+ * Generate the live search endpoint (`.blume/src/pages/api/docs/search.ts`),
+ * server output only: the REST twin of the MCP `search_docs` tool, over the
+ * same snapshot and index.
+ */
+export const apiSearchTemplate = (): string =>
+  `// Generated by Blume. Do not edit.
+import type { APIRoute } from "astro";
+import { createSearchHandler } from "blume/ai/api/handlers.ts";
+import data from "blume:mcp-data";
+
+export const prerender = false;
+
+const handler = createSearchHandler(data);
+
+export const GET: APIRoute = ({ request }) => handler(request);
+`;
+
+/**
+ * Generate the API namespace's catch-all (`.blume/src/pages/api/[...path].ts`),
+ * server output only: any `/api/…` request no endpoint answers gets an RFC
+ * 9457 problem document with the 404 status instead of the HTML not-found
+ * page. Static segments always beat the rest parameter, so `/api/ask`, the
+ * search proxy, and every prerendered docs endpoint keep winning. The site
+ * context is baked in so the resolution links are absolute when the site is
+ * known.
+ */
+export const apiNotFoundTemplate = (context: {
+  base: string;
+  site: string | null;
+}): string =>
+  `// Generated by Blume. Do not edit.
+import type { APIRoute } from "astro";
+import { apiNotFoundResponse } from "blume/ai/api/handlers.ts";
+
+export const prerender = false;
+
+const context = ${JSON.stringify(context)};
+
+export const ALL: APIRoute = ({ request }) => apiNotFoundResponse(request, context);
+`;
+
 /** The literal Astro hydration directive for an island's client mode. */
 const islandDirective = (spec: IslandSpec): string =>
   spec.client === "only"
@@ -2692,6 +3022,36 @@ declare module "blume:data" {
   export default data;
 }
 
+declare module "blume:ask-data" {
+  const askData: import("blume/ai/ask-context.ts").AskData;
+  export default askData;
+}
+
+declare module "blume:content-assets" {
+  const assets: Record<string, string>;
+  export default assets;
+}
+
+declare module "blume:mcp-data" {
+  const data: import("blume/ai/mcp/data.ts").McpData;
+  export default data;
+}
+
+declare module "blume:raw-markdown" {
+  const raw: Record<string, import("blume/ai/markdown.ts").RawMarkdownEntry>;
+  export default raw;
+}
+
+declare module "blume:rss" {
+  const feeds: Record<string, string>;
+  export default feeds;
+}
+
+declare module "blume:search-index" {
+  const documents: import("blume/search/documents.ts").SearchDocument[];
+  export default documents;
+}
+
 declare module "blume:examples" {
   type Examples = typeof import("./generated/examples.ts").examples;
   export const examples: Record<string, Examples[keyof Examples]>;

package/src/cli/commands/build.ts

@@ -334,12 +334,20 @@ const emitVercelNegotiation = async (
   // endpoint stamps it on dev/server-rendered responses itself.
   const rawMarkdown = await buildRawMarkdown(project);
   const home = rawMarkdown["/"];
+  // The Markdown and JSON 404 routes point at the prerendered twins; only
+  // wire each when the build actually emitted it (a project that owns `/404`
+  // gets none).
+  const staticDir = join(root, ".vercel", "output", "static");
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
     buildHomeLinkHeader(config, routePaths),
     overrides,
-    home ? markdownTokenCount(agentMarkdown(home)) : undefined
+    home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+    {
+      json: existsSync(join(staticDir, "404.json")),
+      markdown: existsSync(join(staticDir, "404.md")),
+    }
   );
   if (injected === null) {
     logger.warn(

package/src/cli/commands/dev.ts

@@ -19,8 +19,9 @@ import { prepareProject } from "../prepare.ts";
 
 /**
  * Resolve a `--host` flag value into what Astro/Vite's `server.host` expects.
- * citty (0.1) has no mixed string/boolean arg type, so `host` is declared as a
- * string and a bare `--host` parses as `""` — Node would bind all interfaces
+ * citty has no mixed string/boolean arg type, so `host` is declared as a
+ * string and a bare `--host` parses as `""` (the CLI entry rewrites it to
+ * `--host=` first; see `host-args.ts`) — Node would bind all interfaces
  * for `""`, but Vite's `resolveHostname` treats it as a literal hostname and
  * prints malformed URLs like `http://:4321/`. Match Astro's own `--host`
  * semantics instead: bare flag → `true` (bind all interfaces), `--host
@@ -219,7 +220,9 @@ export const devCommand = defineCommand({
     }).on("all", regenerate);
     const disposers = [
       ...project.sources.map((source) => source.watch?.(regenerate)),
-      () => void projectWatcher.close(),
+      () => {
+        void projectWatcher.close();
+      },
     ].filter((dispose) => dispose !== undefined);
 
     const shutdown = async () => {