blume 1.6.1 → 1.6.2

package/src/astro/generate.ts

@@ -25,10 +25,13 @@ import {
 } from "pathe";
 import { glob } from "tinyglobby";
 
+import { OPENAPI_PATH } from "../ai/api/paths.ts";
+import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
 import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
+import type { McpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
@@ -125,9 +128,15 @@ import {
   exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
+  apiNavigationTemplate,
+  apiNotFoundTemplate,
+  apiPageTemplate,
+  apiPagesIndexTemplate,
+  apiSearchTemplate,
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundJsonTemplate,
   notFoundMarkdownTemplate,
   notFoundPageTemplate,
   ogEndpointTemplate,
@@ -1319,6 +1328,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       description: config.description,
       discovery: {
         agentReadability: config.seo.agentReadability,
+        api: config.ai.api,
         llmsTxt: config.ai.llmsTxt.enabled,
         // Mirrors `buildSitemapFiles`: no site, no sitemap.
         sitemap: config.seo.sitemap && Boolean(config.deployment.site),
@@ -1505,20 +1515,32 @@ const planMcp = (
 type RuntimeModules = Map<RuntimeModuleId, string>;
 
 /**
- * Publish the MCP data snapshot (`blume:mcp-data`) and write the server
- * endpoint and discovery documents.
+ * The agent data snapshot (`blume:mcp-data`) behind the MCP server and the
+ * JSON docs API: built once per pass when either is on, published to the
+ * runtime modules, and handed to both writers. Null when neither needs it.
  */
-const writeMcpFiles = async (
+const publishAgentData = async (
   project: BlumeProject,
+  plans: { api: ApiPlan; mcp: McpPlan },
+  modules: RuntimeModules
+): Promise<McpData | null> => {
+  if (!(plans.mcp.enabled || plans.api.enabled)) {
+    return null;
+  }
+  const data = await buildMcpData(project);
+  modules.set("blume:mcp-data", JSON.stringify(data));
+  return data;
+};
+
+/** Write the MCP server endpoint and discovery documents. */
+const writeMcpFiles = async (
   plan: McpPlan,
   write: (path: string, content: string) => Promise<boolean>,
-  modules: RuntimeModules
+  data: McpData | null
 ): Promise<void> => {
-  if (!plan.enabled) {
+  if (!(plan.enabled && data)) {
     return;
   }
-  const data = await buildMcpData(project);
-  modules.set("blume:mcp-data", JSON.stringify(data));
   const discoveryInput = {
     base: data.base,
     name: data.name,
@@ -1542,6 +1564,129 @@ const writeMcpFiles = async (
   ]);
 };
 
+/** The resolved plan for the JSON docs API within a single generate pass. */
+interface ApiPlan {
+  /**
+   * Whether the `/api/` catch-all (JSON 404s) is written: server output, no
+   * user page owning a rest route under `/api/`, and no content page served
+   * from the `/api` namespace (the catch-all would outrank those pages).
+   */
+  catchAll: boolean;
+  enabled: boolean;
+  /** Whether the live endpoints (search) are written — server output only. */
+  server: boolean;
+  /**
+   * Whether `/openapi.json` is generated: skipped when a `public/openapi.json`
+   * or a user page owns the route, so a site can publish its own description.
+   */
+  spec: boolean;
+  srcDir: string;
+}
+
+/** Whether a user page pattern is a rest route under `/api/` (`/api/[...x]`). */
+const ownsApiRest = (page: { pattern: string }): boolean =>
+  page.pattern.startsWith("/api/[");
+
+/**
+ * Whether a content route lives in the `/api` namespace — a docs section
+ * about an API commonly does (`content/api/overview.md` → `/api/overview`).
+ * Astro ranks `/api/[...path]` above the content catch-all (`/[...slug]`),
+ * so the JSON 404 route would shadow those pages wherever routing decides
+ * (the dev server, adapters that don't serve prerendered files first).
+ */
+const contentUnderApi = (page: { route: string }): boolean =>
+  page.route === "/api" || page.route.startsWith("/api/");
+
+/**
+ * Decide what the JSON docs API generates. The prerendered endpoints always
+ * ride along when the feature is on (they live under Blume's own `/api/docs/`
+ * namespace); the live ones need server output; the OpenAPI description yields
+ * to one the project ships itself.
+ */
+const planApi = (
+  project: BlumeProject,
+  srcDir: string,
+  userPages: { pattern: string }[]
+): ApiPlan => {
+  const { config, context } = project;
+  const server = config.deployment.output === "server";
+  return {
+    catchAll:
+      server &&
+      !userPages.some(ownsApiRest) &&
+      !project.graph.pages.some(contentUnderApi),
+    enabled: config.ai.api,
+    server,
+    spec:
+      !routeIsTaken(userPages, project.graph.pages, OPENAPI_PATH) &&
+      !existsSync(join(context.root, "public", "openapi.json")),
+    srcDir,
+  };
+};
+
+/**
+ * Write the JSON docs API: the prerendered page index, per-page documents, and
+ * navigation; on server output the search endpoint and the `/api/` catch-all;
+ * and the OpenAPI description of the whole agent-facing surface. The MCP
+ * route reaches the description only when the server was actually planned (a
+ * collision can disable it), so it never advertises an endpoint that isn't
+ * there.
+ */
+const writeApiFiles = async (
+  project: BlumeProject,
+  plan: ApiPlan,
+  write: (path: string, content: string) => Promise<boolean>,
+  data: McpData | null,
+  mcp: McpPlan
+): Promise<void> => {
+  if (!(plan.enabled && data)) {
+    return;
+  }
+  const { config } = project;
+  const mcpRoute = mcp.enabled ? mcp.route : null;
+  const apiDir = join(plan.srcDir, "pages", "api");
+  const writes = [
+    write(join(apiDir, "docs", "pages.json.ts"), apiPagesIndexTemplate()),
+    write(
+      join(apiDir, "docs", "pages", "[...route].json.ts"),
+      apiPageTemplate()
+    ),
+    write(join(apiDir, "docs", "navigation.json.ts"), apiNavigationTemplate()),
+  ];
+  if (plan.server) {
+    writes.push(write(join(apiDir, "docs", "search.ts"), apiSearchTemplate()));
+  }
+  if (plan.catchAll) {
+    writes.push(
+      write(
+        join(apiDir, "[...path].ts"),
+        apiNotFoundTemplate({ base: data.base, site: data.site })
+      )
+    );
+  }
+  if (plan.spec) {
+    writes.push(
+      write(
+        join(plan.srcDir, "pages", "openapi.json.ts"),
+        staticJsonEndpointTemplate(
+          buildApiSpec({
+            agentReadability: config.seo.agentReadability,
+            base: data.base,
+            description: config.description,
+            llmsTxt: config.ai.llmsTxt.enabled,
+            mcpRoute,
+            name: config.title,
+            search: plan.server,
+            site: data.site,
+            version: data.version,
+          })
+        )
+      )
+    );
+  }
+  await Promise.all(writes);
+};
+
 /**
  * Decide whether to generate the playground's built-in CORS proxy endpoint.
  * Only the Blume renderer's playground with `proxy: true` needs it — a proxy
@@ -1661,10 +1806,12 @@ const writeAskFiles = async (
 /**
  * Write the default 404 page at Astro's reserved `src/pages/404.astro` path so
  * 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.
+ * (`dist/404.md`) for agents that ask a missing URL for Markdown and its JSON
+ * twin at `404.json.ts` (`dist/404.json`, RFC 9457 problem details) for those
+ * that ask for JSON. All three 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>,
@@ -1678,6 +1825,7 @@ const writeNotFoundPage = async (
   await Promise.all([
     write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate()),
     write(join(srcDir, "pages", "404.md.ts"), notFoundMarkdownTemplate()),
+    write(join(srcDir, "pages", "404.json.ts"), notFoundJsonTemplate()),
   ]);
 };
 
@@ -1866,6 +2014,11 @@ export const generateRuntime = async (
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
+  // The JSON docs API shares the MCP server's snapshot; build it once when
+  // either is on.
+  const api = planApi(project, srcDir, pages);
+  const agentData = await publishAgentData(project, { api, mcp }, modules);
+
   // The parsed OpenAPI specs behind the `blume:openapi` alias, also the source
   // of the proxy's origin allowlist below. The source parsed them during the
   // scan, so reading them here is free.
@@ -2027,7 +2180,8 @@ export const generateRuntime = async (
       )
     ),
     writeAskFiles(project, srcDir, write, modules),
-    writeMcpFiles(project, mcp, write, modules),
+    writeMcpFiles(mcp, write, agentData),
+    writeApiFiles(project, api, write, agentData, mcp),
     playgroundProxy.enabled
       ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
       : Promise.resolve(false),

package/src/astro/templates.ts

@@ -2560,6 +2560,9 @@ const links = [
   ...(data.config.discovery.llmsTxt
     ? [{ href: href("/llms.txt"), label: nf.llms }]
     : []),
+  ...(data.config.discovery.api
+    ? [{ href: href("/openapi.json"), label: nf.api }]
+    : []),
 ];
 
 const body = [
@@ -2584,6 +2587,160 @@ export function GET() {
 }
 `;
 
+/**
+ * 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"

package/src/cli/commands/build.ts

@@ -334,18 +334,20 @@ const emitVercelNegotiation = async (
   // endpoint stamps it on dev/server-rendered responses itself.
   const rawMarkdown = await buildRawMarkdown(project);
   const home = rawMarkdown["/"];
-  // The Markdown 404 routes point at the prerendered `404.md`; only wire them
-  // when the build actually emitted it (a project that owns `/404` gets none).
-  const notFoundMarkdown = existsSync(
-    join(root, ".vercel", "output", "static", "404.md")
-  );
+  // 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,
-    notFoundMarkdown
+    {
+      json: existsSync(join(staticDir, "404.json")),
+      markdown: existsSync(join(staticDir, "404.md")),
+    }
   );
   if (injected === null) {
     logger.warn(

package/src/core/config-input.ts

@@ -788,6 +788,15 @@ export interface McpConfig {
  * hosted MCP server.
  */
 export interface AiConfig {
+  /**
+   * The JSON docs API — the REST twin of the MCP tools. Serves the page index
+   * (`/api/docs/pages.json`), each page as JSON (`/api/docs/pages/{route}.json`),
+   * and the navigation tree (`/api/docs/navigation.json`) as prerendered
+   * files, plus full-text search (`/api/docs/search?q=`) on server output,
+   * all described by an OpenAPI document at `/openapi.json`. Errors are RFC
+   * 9457 problem details. Defaults to `true`; set `false` to publish none of it.
+   */
+  api?: boolean;
   /** The Ask AI chat assistant. */
   ask?: AskConfig;
   /**

package/src/core/data.ts

@@ -138,7 +138,13 @@ export interface BlumeDataConfig {
    * `deployment.site`, the condition under which one is emitted) feeds the
    * 404 page's recovery links rather than the head.
    */
-  discovery: { agentReadability: boolean; llmsTxt: boolean; sitemap: boolean };
+  discovery: {
+    agentReadability: boolean;
+    /** Whether the JSON docs API and its `/openapi.json` are published. */
+    api: boolean;
+    llmsTxt: boolean;
+    sitemap: boolean;
+  };
   favicon: BlumeFavicon;
   feedback: boolean;
   /**

package/src/core/i18n-ui.ts

@@ -109,6 +109,8 @@ const uiStringsObject = z.object({
     .prefault({}),
   notFound: z
     .object({
+      /** Label of the OpenAPI description link on the Markdown/JSON 404. */
+      api: z.string().default("JSON API description (openapi.json)"),
       description: z
         .string()
         .default("We couldn't find the page you're looking for."),

package/src/core/schema.ts

@@ -838,6 +838,13 @@ const llmsTxtObjectSchema = z.strictObject({
 type LlmsTxtResolved = z.output<typeof llmsTxtObjectSchema>;
 
 const aiConfigSchema = z.strictObject({
+  /**
+   * The JSON docs API: the page index, per-page JSON, and navigation under
+   * `/api/docs/` (prerendered, so a static site serves them from files), the
+   * live search endpoint on server output, and the OpenAPI description of
+   * the whole machine-readable surface at `/openapi.json`. On by default.
+   */
+  api: z.boolean().default(true),
   ask: z
     .strictObject({
       // Name of the env var holding the provider's API key; each provider has

package/src/deploy/vercel-negotiation.ts

@@ -11,7 +11,9 @@
  * counterpart of the dev-server rewrite in `astro/markdown-negotiation.ts`.
  * The same routing config also answers a *missing* page: a request that
  * prefers Markdown (or asks for a `.md` URL no page backs) gets the
- * prerendered Markdown 404 body with the 404 status, instead of the HTML shell.
+ * prerendered Markdown 404 body with the 404 status, instead of the HTML
+ * shell, and one that prefers JSON (or asks for a `.json` URL) gets the
+ * prerendered problem-details 404.
  */
 
 /**
@@ -27,6 +29,15 @@
 export const ACCEPT_MARKDOWN_HEADER_VALUE =
   "(.*,)?\\s*text/(x-)?markdown(\\s*[;,].*)?$";
 
+/**
+ * The JSON counterpart, for the problem-details 404: `application/json` or
+ * `application/problem+json`. Browsers never send either on a navigation
+ * (the catch-all wildcard does not match), so ordinary page requests are
+ * unaffected.
+ */
+export const ACCEPT_JSON_HEADER_VALUE =
+  "(.*,)?\\s*application/(problem\\+)?json(\\s*[;,].*)?$";
+
 /**
  * A Build Output API route — the subset these helpers read and write. Parsed
  * routes keep whatever other fields they carry at runtime; only these are
@@ -50,11 +61,18 @@ const ACCEPT_MARKDOWN_CONDITION: VercelRoute["has"] = [
   { key: "accept", type: "header", value: ACCEPT_MARKDOWN_HEADER_VALUE },
 ];
 
+const ACCEPT_JSON_CONDITION: VercelRoute["has"] = [
+  { key: "accept", type: "header", value: ACCEPT_JSON_HEADER_VALUE },
+];
+
 const VARY_ACCEPT = { vary: "Accept" };
 
 /** Where the prerendered Markdown 404 (`pages/404.md.ts`) lands. */
 const NOT_FOUND_MARKDOWN_DEST = "/404.md";
 
+/** Where the prerendered JSON 404 (`pages/404.json.ts`) lands. */
+const NOT_FOUND_JSON_DEST = "/404.json";
+
 /** The adapter's own not-found fallback — the anchor the Markdown 404 precedes. */
 const NOT_FOUND_HTML_DEST = "/404.html";
 
@@ -78,6 +96,30 @@ const NOT_FOUND_MARKDOWN_ROUTES: readonly VercelRoute[] = [
   { dest: NOT_FOUND_MARKDOWN_DEST, src: "^/.*\\.mdx?$", status: 404 },
 ];
 
+/**
+ * The JSON 404's miss-phase routes, the problem-details twin of the Markdown
+ * ones: any path when the client prefers JSON, and any `.json` URL no file
+ * backs. Spliced at the same anchor, after every server route — so the
+ * `/api/` catch-all (which answers its own namespace with a problem document)
+ * has already had its turn.
+ */
+const NOT_FOUND_JSON_ROUTES: readonly VercelRoute[] = [
+  {
+    dest: NOT_FOUND_JSON_DEST,
+    has: ACCEPT_JSON_CONDITION,
+    headers: VARY_ACCEPT,
+    src: "^/.*$",
+    status: 404,
+  },
+  { dest: NOT_FOUND_JSON_DEST, src: "^/.*\\.json$", status: 404 },
+];
+
+/** Which prerendered 404 twins the build emitted, so their routes get wired. */
+export interface NotFoundVariants {
+  json?: boolean;
+  markdown?: boolean;
+}
+
 /**
  * Vercel rejects route `src` patterns longer than 4096 characters, so route
  * alternations are split across as many route entries as needed. The budget
@@ -223,6 +265,7 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
     (condition) => condition.value === ACCEPT_MARKDOWN_HEADER_VALUE
   ) === true ||
   (route.dest === NOT_FOUND_MARKDOWN_DEST && route.status === 404) ||
+  (route.dest === NOT_FOUND_JSON_DEST && route.status === 404) ||
   (route.continue === true &&
     route.headers?.vary === "Accept" &&
     isString(route.src) &&
@@ -244,10 +287,11 @@ const isNegotiationRoute = (route: VercelRoute): boolean =>
  * platform's mechanism for extensionless static files (e.g. the Web Bot Auth
  * signature directory). The trailing-slash 308 redirect is always spliced in
  * alongside, so slashed duplicates of every page collapse onto the canonical
- * slashless URL. With `notFoundMarkdown` (the build emitted `404.md`), the
- * Markdown 404 routes go into the miss phase right before the adapter's
- * `/404.html` fallback — and nowhere when that fallback is absent, since a
- * `dest` with no file behind it would serve nothing. Returns the updated JSON
+ * slashless URL. For each 404 twin the build emitted (`notFound.markdown` for
+ * `404.md`, `notFound.json` for `404.json`), its routes go into the miss
+ * phase right before the adapter's `/404.html` fallback — and nowhere when
+ * that fallback is absent, since a `dest` with no file behind it would serve
+ * nothing. Returns the updated JSON
  * text (tab-indented, like the adapter's own output), or `null` when there is
  * nowhere safe to splice: an unparsable config, no `routes` array, or no
  * `handle: "filesystem"` marker to anchor the splice.
@@ -258,7 +302,7 @@ export const injectNegotiationRoutes = (
   homeLinkHeader?: string | null,
   contentTypeOverrides?: Record<string, string>,
   homeTokens?: number,
-  notFoundMarkdown = false
+  notFound: NotFoundVariants = {}
 ): string | null => {
   const overrideEntries = Object.entries(contentTypeOverrides ?? {});
   let config: {
@@ -307,12 +351,16 @@ export const injectNegotiationRoutes = (
     ...rewriteRoutes,
     TRAILING_SLASH_REDIRECT
   );
-  if (notFoundMarkdown) {
+  const notFoundRoutes = [
+    ...(notFound.markdown ? NOT_FOUND_MARKDOWN_ROUTES : []),
+    ...(notFound.json ? NOT_FOUND_JSON_ROUTES : []),
+  ];
+  if (notFoundRoutes.length > 0) {
     const fallbackIndex = routes.findIndex(
       (route) => route.status === 404 && route.dest === NOT_FOUND_HTML_DEST
     );
     if (fallbackIndex !== -1) {
-      routes.splice(fallbackIndex, 0, ...NOT_FOUND_MARKDOWN_ROUTES);
+      routes.splice(fallbackIndex, 0, ...notFoundRoutes);
     }
   }
   config.routes = routes;