blume 2.0.2 → 2.1.0

package/src/astro/templates.ts

@@ -6,22 +6,34 @@ import { dirname, isAbsolute, join, relative } from "pathe";
 import type { AskRetrievalOptions } from "../ai/ask-context.ts";
 import type { AskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
+import type { CaptchaAdapter } from "../captcha/schema.ts";
+import { CONSENT_CLIENT_MODULES } from "../consent/clients.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { TOC_HIDDEN_KEY } from "../core/heading-markers.ts";
+import { compileRedirects, isPatternPath } from "../core/redirect-patterns.ts";
+import type { CompiledRedirect } from "../core/redirect-patterns.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveDocsCollection } from "../core/sources/collection.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
+import { hasVariables } from "../core/variables.ts";
 import { deployPassthrough } from "../deploy/adapters/types.ts";
 import { SVG_ASSET_HEADERS } from "../deploy/headers.ts";
 import { deployPlatform } from "../deploy/platforms/index.ts";
 import { adapterRoot, distDir } from "../deploy/platforms/paths.ts";
 import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
+import { API_RAIL_KEY } from "../markdown/api-rail.ts";
+import { VIEWS_KEY } from "../markdown/views.ts";
 import type { OgCache } from "../og/cache.ts";
-import type { OgFont, OgFontFamilies } from "../og/card.ts";
+import type { OgFont, OgFontFamilies, OgGoogleFont } from "../og/card.ts";
+import { RATE_LIMIT_BINDING } from "../ratelimit/cloudflare.ts";
+import type { RateLimitAdapter } from "../ratelimit/schema.ts";
 import type { MixedbreadOptions } from "../search/adapters/mixedbread.ts";
-import type { ResolvedSearchAdapter } from "../search/adapters/registry.ts";
+import type {
+  ResolvedSearchAdapter,
+  SearchAdapterKind,
+} from "../search/adapters/registry.ts";
 import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
 import { importSpecifier, wrapperPropsType } from "./component-slots.ts";
 import type { ExampleSpec } from "./examples.ts";
@@ -185,7 +197,8 @@ export const runtimeDependencies = (options: {
   deps.push(
     ...new Set(config.reference.flatMap((adapter) => adapter.runtimeDeps)),
     ...config.search.provider.runtimeDeps,
-    ...config.analytics.flatMap((adapter) => adapter.runtimeDeps)
+    ...config.analytics.flatMap((adapter) => adapter.runtimeDeps),
+    ...(config.consent?.runtimeDeps ?? [])
   );
   // Each content source adapter declares the SDK its fetch imports (Notion,
   // Sanity); the descriptor is the one place that knows.
@@ -398,14 +411,32 @@ export interface ClientFeatures {
 /** Every feature on: what a checkout that predates the detection shipped. */
 const ALL_CLIENT_FEATURES: ClientFeatures = { epub: true, mermaid: true };
 
+/**
+ * The npm module each browser-queried search adapter's client imports (see
+ * `components/layout/search/`). The `<Search>` dialog lazy-imports that client
+ * on first open, after the dev dep optimizer's startup run, so the first
+ * search of a fresh `blume dev` session discovered the library, re-ran the
+ * optimizer, and reloaded the page. Pagefind loads its script from the build
+ * output and Mixedbread queries through the server, so neither has one.
+ */
+const SEARCH_CLIENT_DEPS: Partial<Record<SearchAdapterKind, string>> = {
+  algolia: "algoliasearch/lite",
+  flexsearch: "flexsearch",
+  orama: "@orama/orama",
+  "orama-cloud": "@oramacloud/client",
+  typesense: "typesense",
+};
+
 const resolveOptimizeDeps = (options: {
   aliases: Record<string, string> | undefined;
   context: ProjectContext;
   features: ClientFeatures;
   needsReact: boolean;
   reactCompilerPath: string | null | undefined;
+  searchKind: SearchAdapterKind;
 }): OptimizeDepsConfig => {
   const { context, features } = options;
+  const searchDep = SEARCH_CLIENT_DEPS[options.searchKind];
   const optimizeDepsEntries = [
     ...(context.pagesRoot ? [`${context.pagesRoot}/**/*.astro`] : []),
     `${context.root}/islands/**/*.{jsx,svelte,tsx,vue}`,
@@ -418,6 +449,8 @@ const resolveOptimizeDeps = (options: {
     // Mermaid costs the dev server seconds at startup for nothing otherwise.
     ...(features.mermaid ? ["blume > mermaid"] : []),
     ...(features.epub ? ["blume > epub-gen-memory/bundle"] : []),
+    // Only the configured search adapter's client library.
+    ...(searchDep ? [`blume > ${searchDep}`] : []),
     // Astro's own client-router/prefetch virtual modules are deliberately NOT
     // forced in here: they read Vite `define`-injected constants
     // (__PREFETCH_PREFETCH_ALL__ and friends) that a pre-bundled copy loses,
@@ -532,17 +565,23 @@ const blumeIntegrationOptions = (options: {
   contentRoutes: string[];
   ejected: boolean;
   pages: BlumePageRoute[];
-}): BlumeIntegrationOptions =>
-  options.ejected
+  redirects: CompiledRedirect[];
+}): BlumeIntegrationOptions => {
+  const shared: BlumeIntegrationOptions = { pages: options.pages };
+  if (options.redirects.length > 0) {
+    shared.redirects = options.redirects;
+  }
+  return options.ejected
     ? {
+        ...shared,
         buildArtifactsRoot: ".",
         contentRoutes: options.contentRoutes,
         homeLinkHeader:
-          buildHomeLinkHeader(options.config, options.contentRoutes) ??
+          buildHomeLinkHeader(options.config, options.contentRoutes, "dev") ??
           undefined,
-        pages: options.pages,
       }
-    : { pages: options.pages };
+    : shared;
+};
 
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
@@ -558,6 +597,8 @@ export const astroConfigTemplate = (options: {
   /** The example-preview Tailwind entry (`blume:examples-theme`). */
   examplesThemePath: string;
   themePath: string;
+  /** The configured consent adapter's browser module (`blume:consent-client`). */
+  consentClientPath: string;
   searchClientPath: string;
   /** The generated client-feature loaders (`blume:features`). */
   featuresPath: string;
@@ -594,6 +635,7 @@ export const astroConfigTemplate = (options: {
   );
   const {
     askPath,
+    consentClientPath,
     contentRoutes,
     examplesPath,
     examplesThemePath,
@@ -623,6 +665,7 @@ export const astroConfigTemplate = (options: {
     features,
     needsReact,
     reactCompilerPath: options.reactCompilerPath,
+    searchKind: config.search.provider.kind,
   });
 
   const {
@@ -660,13 +703,20 @@ export const astroConfigTemplate = (options: {
   const basedRedirects = applyBaseToAstroRedirects(
     config.redirects,
     config.basePath,
-    deployment.options.base ?? ""
+    deployment.options.base ?? "",
+    new Set(contentRoutes)
+  );
+  // Only exact redirects: Astro can't prerender a pattern's redirect pages
+  // (it would need every path the pattern covers), so a pattern reaches the
+  // dev server through the integration and each host through its own rules.
+  const exactRedirects = basedRedirects.filter(
+    (redirect) => !isPatternPath(redirect.from)
   );
   const redirectsOption =
-    basedRedirects.length > 0
+    exactRedirects.length > 0
       ? `\n  redirects: ${JSON.stringify(
           Object.fromEntries(
-            basedRedirects.map((redirect) => [
+            exactRedirects.map((redirect) => [
               redirect.from,
               { destination: redirect.to, status: redirect.status },
             ])
@@ -734,12 +784,19 @@ export const astroConfigTemplate = (options: {
   const svelteImport = needsSvelte
     ? `import svelte from "@astrojs/svelte";\n`
     : "";
+  // Content variables in `.mdx` are replaced before the MDX compiler parses
+  // the source, which reads `{{name}}` as a JavaScript expression.
+  const substitutesVariables = hasVariables(config.variables);
+  const variablesPluginEntry = substitutesVariables
+    ? `variablesVitePlugin(${JSON.stringify(config.variables)}), `
+    : "";
   const blumeImports = [
     "blumeIntegration",
     "includeHmrPlugin",
     "prerenderDepsPlugin",
     ...runtimeModuleImports,
     ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
+    ...(substitutesVariables ? ["variablesVitePlugin"] : []),
   ];
   const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
 
@@ -769,6 +826,7 @@ export const astroConfigTemplate = (options: {
     deployBase,
     externalLinks: config.markdown.externalLinks,
     headingAnchors: config.markdown.headingAnchors,
+    variables: config.variables,
   });
   const processorOptions =
     options.generatedModulesDir === undefined
@@ -797,6 +855,7 @@ export const astroConfigTemplate = (options: {
         contentRoutes,
         ejected,
         pages,
+        redirects: compileRedirects(basedRedirects),
       })
     )})`
   );
@@ -860,7 +919,7 @@ ${userConfigSetup}export default defineConfig({
   // the overlap only adds memory.
   build: { concurrency: Math.min(8, availableParallelism()) },
   vite: {${viteCacheOption}
-    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${configPath(
+    plugins: [${runtimeModulesPluginEntry}${variablesPluginEntry}tailwindcss(), includeHmrPlugin(${configPath(
       `${context.outDir}/src/generated/includes.json`,
       ejected
     )}), prerenderDepsPlugin()],
@@ -892,6 +951,10 @@ ${userConfigSetup}export default defineConfig({
     // \`/bundle\` subpath that is actually imported: optimizing the package
     // root leaves that entry out. Production (Rollup) already handles the
     // interop, so all of this only affects dev.
+    //
+    // The search adapter's client library rides the list for the same reason
+    // as the compiler runtime: the search dialog lazy-imports it on first
+    // open, and discovering it then re-optimizes and reloads the page.
     optimizeDeps: {
       entries: ${JSON.stringify(optimizeDepsEntries)},
       include: ${JSON.stringify(optimizeDepsInclude)},
@@ -915,6 +978,7 @@ ${userConfigSetup}export default defineConfig({
     resolve: {
       alias: {
         "blume:ask": ${configPath(askPath, ejected)},
+        "blume:consent-client": ${configPath(consentClientPath, ejected)},
         "blume:examples": ${configPath(examplesPath, ejected)},
         "blume:examples-theme": ${configPath(examplesThemePath, ejected)},
         "blume:features": ${configPath(featuresPath, ejected)},
@@ -1066,12 +1130,21 @@ const ASK_FALLBACK_PROMPT =
 
 /** The `ai.assistant` values the generated endpoint has to carry with it. */
 export interface AskEndpointOptions {
+  /** `ai.assistant.captcha` — the bot check the route verifies first. */
+  captcha?: CaptchaAdapter;
   /** `ai.assistant.cors` — origins allowed to call the route from another site. */
   cors?: string[];
+  /** `rateLimit` — the limiter the route checks before any work. */
+  rateLimit?: RateLimitAdapter | null;
   /** `ai.assistant.instructions` — extra system-prompt text. */
   instructions?: string;
   /** `ai.assistant.retrieval` — how much documentation each question carries. */
   retrieval?: AskRetrievalOptions;
+  /**
+   * `ai.assistant.tools`, resolved against the adapter's default: give the
+   * model the docs search and read-page tools.
+   */
+  tools?: boolean;
 }
 
 /** The pieces `askEndpointTemplate` splices in for `ai.assistant.cors`. */
@@ -1103,7 +1176,7 @@ const askCorsTemplate = (cors: readonly string[] = []): AskCorsTemplate =>
         imports: [
           'import { preflightResponse, withCors } from "blume/ai/cors.ts";',
         ],
-        open: "withCors(ALLOWED_ORIGINS, async ({ request }) => {",
+        open: "withCors(ALLOWED_ORIGINS, async (context) => {",
         setup: `
 const ALLOWED_ORIGINS = ${JSON.stringify(cors)};
 
@@ -1111,7 +1184,89 @@ export const OPTIONS: APIRoute = ({ request }) =>
   preflightResponse(request, ALLOWED_ORIGINS);
 `,
       }
-    : { close: "};", imports: [], open: "async ({ request }) => {", setup: "" };
+    : { close: "};", imports: [], open: "async (context) => {", setup: "" };
+
+/** The pieces a server route splices in to check `rateLimit` first. */
+interface RateLimitTemplate {
+  /** The check at the top of the handler; reads `context`. */
+  check: string;
+  /** The runtime import, plus what the adapter's store needs. */
+  imports: string[];
+  /** The route's limiter, built once at module scope. */
+  setup: string;
+}
+
+/**
+ * `rateLimit` for one server route: a limiter built at module scope from the
+ * configured adapter, checked against every request, keyed by the reader's
+ * address and `scope` so each route keeps its own budget (see
+ * `ratelimit/runtime.ts`). Upstash reads its secrets through `getSecret`;
+ * Cloudflare's binding comes from the Worker's env. Nothing at all when
+ * rate limiting is off.
+ */
+export const rateLimitTemplate = (
+  adapter: RateLimitAdapter | null | undefined,
+  scope: string
+): RateLimitTemplate => {
+  if (!adapter) {
+    return { check: "", imports: [], setup: "" };
+  }
+  const imports = [
+    'import { createLimiter, rateLimited } from "blume/ratelimit/runtime.ts";',
+  ];
+  let runtime = "";
+  if (adapter.kind === "upstash") {
+    imports.push('import { getSecret } from "astro:env/server";');
+    runtime = ", { secret: getSecret }";
+  } else if (adapter.kind === "cloudflare") {
+    imports.push(
+      "// @ts-ignore `cloudflare:workers` is typed once `wrangler types` has run.",
+      'import { env } from "cloudflare:workers";'
+    );
+    runtime = `, { binding: Reflect.get(env, ${JSON.stringify(RATE_LIMIT_BINDING)}) }`;
+  }
+  return {
+    check: `  const limited = await rateLimited(limiter, context, ${JSON.stringify(scope)});
+  if (limited) {
+    return limited;
+  }
+`,
+    imports,
+    setup: `\nconst limiter = createLimiter(${JSON.stringify(adapter)}${runtime});\n`,
+  };
+};
+
+/**
+ * `ai.assistant.captcha` for the ask route: verify the question's token with
+ * the provider before the model runs (see `captcha/verify.ts`). A missing
+ * secret answers with the same "not configured" notice as a missing
+ * provider key, which the panel shows as is; a failed check answers `403`.
+ */
+const askCaptchaTemplate = (adapter?: CaptchaAdapter): RateLimitTemplate => {
+  if (!adapter) {
+    return { check: "", imports: [], setup: "" };
+  }
+  const [secret = ""] = adapter.requiredSecrets;
+  return {
+    check: `  const captchaSecret = getSecret(${JSON.stringify(secret)});
+  if (!captchaSecret) {
+    return new Response(
+      ${JSON.stringify(`The assistant is not configured: set ${secret}.`)},
+      { status: 503 }
+    );
+  }
+  const captchaToken =
+    typeof body.captcha === "string" ? body.captcha : undefined;
+  if (!(await verifyCaptcha(CAPTCHA, captchaToken, context, { secret: captchaSecret }))) {
+    return new Response("Verification failed: the bot check didn't pass.", {
+      status: 403,
+    });
+  }
+`,
+    imports: ['import { verifyCaptcha } from "blume/captcha/verify.ts";'],
+    setup: `\nconst CAPTCHA = ${JSON.stringify(adapter)};\n`,
+  };
+};
 
 /**
  * Largest request body the assistant route reads: 64 KB, well above the
@@ -1145,6 +1300,8 @@ export const askEndpointTemplate = (
 ): string => {
   const { instructions, retrieval } = options ?? {};
   const { grounded } = backend;
+  // The tools read the grounding snapshot, so an ungrounded backend has none.
+  const tools = grounded && Boolean(options?.tools);
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
@@ -1172,12 +1329,32 @@ export const askEndpointTemplate = (
     if (retrieval) {
       groundFields.push(`retrieval: ${JSON.stringify(retrieval)}`);
     }
+    if (tools) {
+      groundFields.push("tools: true");
+    }
     const groundOptions =
       groundFields.length > 0 ? `, { ${groundFields.join(", ")} }` : "";
     setup += `\nconst ground = createAskContext(askData${groundOptions});\n`;
+    if (tools) {
+      imports.push(
+        'import { stepCountIs } from "ai";',
+        'import { ASK_MAX_STEPS, createAskTools } from "blume/ai/ask-tools.ts";'
+      );
+      setup += "const askTools = createAskTools(askData);\n";
+    }
   }
   const cors = askCorsTemplate(options?.cors);
   imports.push(...cors.imports);
+  const limit = rateLimitTemplate(options?.rateLimit, "ask");
+  for (const line of limit.imports) {
+    if (!imports.includes(line)) {
+      imports.push(line);
+    }
+  }
+  setup += limit.setup;
+  const captcha = askCaptchaTemplate(options?.captcha);
+  imports.push(...captcha.imports);
+  setup += captcha.setup;
   // Validate the client-supplied body and cap its size. The endpoint is
   // unauthenticated, so bounding message count/length limits how much a caller
   // can spend against the model per request, and restricting roles to
@@ -1186,7 +1363,8 @@ export const askEndpointTemplate = (
   // limiter (or your provider's limits) for stronger protection. The body is
   // read under a 64 KB cap before any parsing, since a self-hosted Node server
   // would otherwise buffer an arbitrarily large POST in memory first.
-  const validate = `  const text = await readCappedText(request, ${ASK_BODY_LIMIT_BYTES});
+  const validate = `  const { request } = context;
+${limit.check}  const text = await readCappedText(request, ${ASK_BODY_LIMIT_BYTES});
   if (text === undefined) {
     return new Response("Request too large: the body must be at most 64 KB.", {
       status: 413,
@@ -1244,11 +1422,22 @@ export const askEndpointTemplate = (
       ? "instructions"
       : `instructions:\n        ${JSON.stringify(fallbackPrompt)}`,
     "messages",
+    // The model may search and read pages, then answer, within one request:
+    // tool calls run here on the server and only the text reaches the reader.
+    ...(tools
+      ? ["tools: askTools(body.page)", "stopWhen: stepCountIs(ASK_MAX_STEPS)"]
+      : []),
     ...backend.template.fields,
   ];
+  // The request's signal aborts when the reader closes the panel mid-answer
+  // (the client drops the connection): passing it on stops the model call,
+  // which otherwise kept generating, and billing, to completion into a closed
+  // connection. `streamText` ends an aborted call through its abort path, not
+  // `onError`, so the reader leaving is never logged as a provider error.
   const call = `    const result = streamText({
       ${streamFields.join(",\n      ")},
 ${onError}
+      abortSignal: request.signal,
     });`;
   const stream = grounded
     ? `    const instructions =
@@ -1259,7 +1448,7 @@ ${call}`
   const handler = `export const POST: APIRoute = ${cors.open}
 ${validate}
 ${keyCheck}
-  try {
+${captcha.check}  try {
 ${stream}
     return createTextStreamResponse({
       stream: toTextStream({ stream: result.stream }),
@@ -1304,9 +1493,11 @@ const { strings } = Astro.props;
 ---
 
 <Assistant
+  captcha={data.config.assistant?.captcha ?? undefined}
   endpoint={data.config.assistant?.endpoint ?? undefined}
   strings={strings ?? data.ui.assistant}
   suggestions={data.config.assistant?.suggestions ?? []}
+  support={data.config.assistant?.support ?? undefined}
 />
 `
     : `---
@@ -1406,6 +1597,36 @@ ${
 }
 `;
 
+/**
+ * Generate `.blume/src/generated/consent-client.ts`, behind the
+ * `blume:consent-client` alias: the configured consent adapter's browser
+ * module (see `consent/clients.ts`), started by `ConsentHead.astro` with the
+ * adapter's options baked in. Only that adapter's module is referenced, so a
+ * site bundles no other adapter's code. An adapter without one (a hosted
+ * manager), or no `consent` at all, gets a no-op so the alias always resolves.
+ */
+export const consentClientTemplate = (
+  consent: ResolvedConfig["consent"]
+): string => {
+  const module = consent ? CONSENT_CLIENT_MODULES.get(consent.kind) : undefined;
+  if (!(consent && module)) {
+    return `// Generated by Blume. Do not edit.
+// The consent adapter has no browser module, or consent is off.
+export const startConsentClient = (): void => {};
+`;
+  }
+  return `// Generated by Blume. Do not edit.
+// The \`${consent.kind}\` consent adapter's browser module, with its options.
+import { start } from ${JSON.stringify(module)};
+
+export const startConsentClient = (
+  consent: Parameters<typeof start>[0]
+): void => {
+  start(consent, ${JSON.stringify(consent.options)});
+};
+`;
+};
+
 /**
  * Generate `.blume/src/generated/search-client.ts` — the provider-specific
  * loader the `<Search>` component lazy-imports via the `blume:search-client`
@@ -1458,13 +1679,19 @@ export const createSearch = () => create({ url });
  * content was synced (see the Mixedbread sync step / \`mxbai vs sync\`).
  */
 export const mixedbreadSearchEndpointTemplate = (
-  options: MixedbreadOptions
-): string =>
-  `// Generated by Blume. Do not edit.
-import type { APIRoute } from "astro";
-import { getSecret } from "astro:env/server";
-import Mixedbread from "@mixedbread/sdk";
-import { readCappedText } from "blume/core/request-body.ts";
+  options: MixedbreadOptions,
+  rateLimit?: RateLimitAdapter | null
+): string => {
+  const limit = rateLimitTemplate(rateLimit, "search");
+  const imports = [
+    'import type { APIRoute } from "astro";',
+    'import { getSecret } from "astro:env/server";',
+    'import Mixedbread from "@mixedbread/sdk";',
+    'import { readCappedText } from "blume/core/request-body.ts";',
+    ...limit.imports.filter((line) => !line.includes('"astro:env/server"')),
+  ];
+  return `// Generated by Blume. Do not edit.
+${imports.join("\n")}
 
 export const prerender = false;
 
@@ -1472,9 +1699,10 @@ const client = new Mixedbread({ apiKey: getSecret("MIXEDBREAD_API_KEY") ?? "" })
 const OPTIONS = ${JSON.stringify(options)};
 // Every option besides the store reaches the search call verbatim.
 const { storeId: STORE_ID, ...SEARCH_OPTIONS } = OPTIONS;
-
-export const POST: APIRoute = async ({ request }) => {
-  // A search body is one short query: read it under a 16 KB cap, so a
+${limit.setup}
+export const POST: APIRoute = async (context) => {
+  const { request } = context;
+${limit.check}  // A search body is one short query: read it under a 16 KB cap, so a
   // self-hosted server never buffers an arbitrarily large POST first.
   const text = await readCappedText(request, 16_384);
   if (text === undefined) {
@@ -1519,6 +1747,7 @@ export const POST: APIRoute = async ({ request }) => {
   });
 };
 `;
+};
 
 /**
  * Generate the raw-Markdown endpoints (`[...slug].md.ts` and `[...slug].mdx.ts`).
@@ -1721,17 +1950,26 @@ export const ALL: APIRoute = ({ request }) => handler(request);
  * client-side data: that is the whole trust boundary keeping the endpoint from
  * being an open proxy onto the deployment's own network.
  */
-export const playgroundProxyTemplate = (origins: string[]): string =>
-  `// Generated by Blume. Do not edit.
-import type { APIRoute } from "astro";
-import { createPlaygroundProxyHandler } from "blume/openapi/proxy.ts";
+export const playgroundProxyTemplate = (
+  origins: string[],
+  rateLimit?: RateLimitAdapter | null
+): string => {
+  const limit = rateLimitTemplate(rateLimit, "api-proxy");
+  const route = limit.check
+    ? `export const ALL: APIRoute = async (context) => {
+${limit.check}  return handler(context.request);
+};`
+    : "export const ALL: APIRoute = ({ request }) => handler(request);";
+  return `// Generated by Blume. Do not edit.
+${['import type { APIRoute } from "astro";', 'import { createPlaygroundProxyHandler } from "blume/openapi/proxy.ts";', ...limit.imports].join("\n")}
 
 export const prerender = false;
 
 const handler = createPlaygroundProxyHandler(${JSON.stringify(origins)});
-
-export const ALL: APIRoute = ({ request }) => handler(request);
+${limit.setup}
+${route}
 `;
+};
 
 /** Generate a prerendered endpoint that serves a fixed JSON payload. */
 export const staticJsonEndpointTemplate = <Payload extends object>(
@@ -1792,7 +2030,7 @@ export const navFragmentTemplate = (): string =>
   `---
 // Generated by Blume. Do not edit.
 import NavTree from "blume/components/layout/NavTree.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
+import { withMountedBase } from "blume/components/islands/base-path.ts";
 import {
   hiddenDefaultLocale,
   navGroupIds,
@@ -1831,7 +2069,7 @@ if (!(variant && node && node.kind === "group")) {
 }
 const strings =
   locale === "default" ? data.ui.nav : (data.uiByLocale[locale] ?? data.ui).nav;
-const fragmentBase = withBase(\`/blume-nav/\${version}/\${locale}\`);
+const fragmentBase = withMountedBase(\`/blume-nav/\${version}/\${locale}\`);
 ---
 
 <NavTree
@@ -1855,6 +2093,7 @@ export const ogEndpointTemplate = (
      * Absent, every card renders on every build.
      */
     cache?: OgCache;
+    fallbacks?: OgGoogleFont[];
     families?: OgFontFamilies;
     fonts?: OgFont[];
     /**
@@ -1868,7 +2107,7 @@ export const ogEndpointTemplate = (
 ): string =>
   `// Generated by Blume. Do not edit.
 import { cachedOgImage } from "blume/og";
-import type { OgCache, OgFont, OgFontFamilies } from "blume/og";
+import type { OgCache, OgFont, OgFontFamilies, OgGoogleFont } from "blume/og";
 import data from "blume:data";
 
 export const prerender = true;
@@ -1886,6 +2125,9 @@ const fonts: OgFont[] = ${JSON.stringify(og.fonts ?? [])};
 const families: OgFontFamilies | undefined = ${
     og.families ? JSON.stringify(og.families) : "undefined"
   };
+// Script fallbacks (Noto families, the configured locales' first). A card
+// fetches them only when its text has a glyph Takumi's built-in font lacks.
+const fallbacks: OgGoogleFont[] = ${JSON.stringify(og.fallbacks ?? [])};
 
 // Rendered cards are kept on disk between builds, keyed by everything that
 // decides their pixels, so a rebuild renders only the cards whose title,
@@ -1958,6 +2200,7 @@ export async function GET({ props }: { props: CardProps }) {
     accent: data.config.og.palette?.accent ?? data.config.theme.accent.light,
     brand: data.config.title,
     description: props.description ?? data.config.og.description,
+    fallbacks,
     families,
     fonts,
     logo: data.config.og.logo,
@@ -2050,6 +2293,9 @@ const contentComponentsSource = (mathEnabled: boolean) => {
   return {
     imports: `import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
+import ApiEndpoint from "blume/components/content/ApiEndpoint.astro";
+import ApiPlayground from "blume/components/content/ApiPlayground.astro";
+import ApiRail from "blume/components/content/ApiRail.astro";
 import AutoTypeTable from "blume/components/content/AutoTypeTable.astro";
 import Badge from "blume/components/content/Badge.astro";
 import Callout from "blume/components/content/Callout.astro";
@@ -2069,7 +2315,11 @@ import FileTree from "blume/components/content/FileTree.astro";
 import Frame from "blume/components/content/Frame.astro";
 import GithubInfo from "blume/components/content/GithubInfo.astro";
 import Panel from "blume/components/content/Panel.astro";
+import ParamField from "blume/components/content/ParamField.astro";
 import Prompt from "blume/components/content/Prompt.astro";
+import RequestExample from "blume/components/content/RequestExample.astro";
+import ResponseExample from "blume/components/content/ResponseExample.astro";
+import ResponseField from "blume/components/content/ResponseField.astro";
 import Step from "blume/components/content/Step.astro";
 import Steps from "blume/components/content/Steps.astro";
 import Tab from "blume/components/content/Tab.astro";
@@ -2080,10 +2330,13 @@ import TreeRoot from "blume/components/content/Tree.astro";
 import TreeFile from "blume/components/content/TreeFile.astro";
 import TreeFolder from "blume/components/content/TreeFolder.astro";
 import TypeTable from "blume/components/content/TypeTable.astro";
+import View from "blume/components/content/View.astro";
 import Visibility from "blume/components/content/Visibility.astro";
 import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
 import LocaleLinks from "blume/components/layout/LocaleLinks.astro";
+import NarrationPlayer from "blume/components/layout/NarrationPlayer.astro";
+import ViewSwitcher from "blume/components/content/ViewSwitcher.astro";
 import ApiOverview from "blume/components/openapi/ApiOverview.astro";
 import ApiTagOperations from "blume/components/openapi/ApiTagOperations.astro";
 import Operation from "blume/components/openapi/Operation.astro";
@@ -2091,7 +2344,10 @@ ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../gener
     map: `{
   Accordion,
   AccordionItem,
+  ApiEndpoint,
   ApiOverview,
+  ApiPlayground,
+  ApiRail,
   ApiTagOperations,
   AutoTypeTable,
   Badge,
@@ -2112,7 +2368,11 @@ ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../gener
   Icon,
   Operation,
   Panel,
+  ParamField,
   Prompt,
+  RequestExample,
+  ResponseExample,
+  ResponseField,
   Step,
   Steps,
   Tab,
@@ -2121,6 +2381,7 @@ ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../gener
   Tooltip,
   Tree,
   TypeTable,
+  View,
   Visibility,
   YouTube,
   ${mathEntry}...userMdx,
@@ -2151,10 +2412,11 @@ export const catchAllPageTemplate = (options: {
   return `---
 // Generated by Blume. Do not edit.
 import { getEntry, render } from "astro:content";
+import { pageModeLayout } from "blume/core/page-modes.ts";
 import type { CollectionKey } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
-import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
+import { withBase, withMountedBase } from "blume/components/islands/base-path.ts";
+import { mountBasePath, stripBasePath } from "blume/core/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${componentImports}
 import data from "blume:data";
@@ -2202,6 +2464,13 @@ const { Content, headings: allHeadings, remarkPluginFrontmatter } = await render
 // frontmatter (see markdown/heading-anchors.ts). Only the plugin's array
 // counts: \`frontmatter.extend\` can declare the same key, and on a page with
 // no headings that user-supplied value would pass straight through.
+// A page written in \`<View>\` blocks gets their picker above the content;
+// the views plugin lists them through the render's frontmatter (see
+// markdown/views.ts), and only a list of titled entries counts.
+const viewsRaw = remarkPluginFrontmatter?.${VIEWS_KEY};
+const views = Array.isArray(viewsRaw)
+  ? viewsRaw.filter((view) => typeof view?.title === "string")
+  : [];
 const tocHiddenRaw = remarkPluginFrontmatter?.${TOC_HIDDEN_KEY};
 const tocHidden = new Set(Array.isArray(tocHiddenRaw) ? tocHiddenRaw : []);
 const headings =
@@ -2219,12 +2488,16 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const ogPath = data.config.og.enabled
   ? encodeURI(\`/og/\${route === "/" ? "index" : route.slice(1)}.png\`)
   : null;
-const ogRel = seo.image ?? ogPath;
 // Absolute URLs also carry the deployment base (the page is served under it):
 // \`site + base + path\`. Only absolutize root-relative paths: \`seo.image\` may be
-// an external URL, which passes through verbatim (mirrors PageLayout).
-const ogImage =
-  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${withBase(ogRel)}\` : ogRel;
+// an external URL, which passes through verbatim (mirrors PageLayout). An
+// authored \`seo.image\` keeps a base written by hand; the generated card is
+// always mounted under it.
+const absoluteOg = (path: string, based: (path: string) => string) =>
+  base && path.startsWith("/") ? \`\${base}\${based(path)}\` : path;
+const ogImage = seo.image
+  ? absoluteOg(seo.image, withBase)
+  : ogPath && absoluteOg(ogPath, withMountedBase);
 // Blume's generated card has known dimensions the layout can declare; a user's
 // \`seo.image\` could be any size or format, so it gets none.
 const ogGenerated = !seo.image && Boolean(ogPath);
@@ -2233,7 +2506,7 @@ const ogGenerated = !seo.image && Boolean(ogPath);
 // itself (a guest post crediting its own author) over the configured default.
 const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
-const basedRoute = withBase(route);
+const basedRoute = withMountedBase(route);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -2276,12 +2549,20 @@ const htmlLang = i18n ? locale : "en";
 // follows that language — not the (mirrored) page locale.
 const contentLocale =
   fallback && i18n?.fallbackLocale ? i18n.fallbackLocale : locale;
+// "Listen to this page", unless the page opts out. The spoken cues are read
+// between the content's own sentences, so they come from the content's
+// language (a fallback page's), while the player's labels follow the page.
+// A \`custom\` or \`frame\` page brings its own heading: no title, description,
+// or narration player above its content.
+const pageChrome = pageModeLayout(frontmatter.mode).chrome;
+const narration = pageChrome && frontmatter.narration ? data.config.narration : null;
+const narrationCues = (i18n ? (data.uiByLocale[contentLocale] ?? data.ui) : data.ui).narration;
 const contentDir = i18n
   ? (i18n.locales.find((l) => l.code === contentLocale)?.dir ?? "ltr")
   : "ltr";
 // The root route keeps its trailing slash (\`https://site/\`) so canonical and
 // hreflang URLs byte-match the sitemap's <loc> for the home page.
-const absolute = (path: string) => base + withBase(path);
+const absolute = (path: string) => base + withMountedBase(path);
 
 // A fallback page renders the fallback locale's page at this locale's URL, so
 // its canonical names the page it copies, and search engines never rank the
@@ -2326,7 +2607,7 @@ const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 // carries sits *after* the base (\`/docs/ja/guide\`), while \`localePrefix\` is
 // base-less (\`/ja\`). Stripping and re-adding a locale therefore happen in
 // base-less space, with the base re-applied at the end — the same
-// \`withBasePath(basePath, localizeRoute(...))\` composition the manifest uses to
+// \`mountBasePath(basePath, localizeRoute(...))\` composition the manifest uses to
 // build every real route. Done in based space, \`stripLocale\` matches nothing
 // and \`localizeRoute\` prepends a second prefix (\`/ja/docs/ja/guide\`). Only a
 // switcher entry for a locale with no real translation reaches this fallback:
@@ -2334,7 +2615,7 @@ const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 // generated reference (which has no \`alternates\` at all) for every locale
 // but its own.
 const mountLocalized = (logical: string, codeArg: string) =>
-  withBasePath(data.config.basePath, localizeRoute(logical, codeArg));
+  mountBasePath(data.config.basePath, localizeRoute(logical, codeArg));
 const logicalRoute = i18n
   ? stripLocale(stripBasePath(data.config.basePath, route), locale)
   : route;
@@ -2363,7 +2644,7 @@ const versionRootFor = (id: string) => {
   const logical = id ? \`/\${id}\` : "/";
   return i18n
     ? mountLocalized(logical, locale)
-    : withBasePath(data.config.basePath, logical);
+    : mountBasePath(data.config.basePath, logical);
 };
 const samePageSwitch = versionsConfig
   ? versionsConfig.switcher.redirect === "same-page"
@@ -2459,11 +2740,15 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   canonical={canonical}
   editUrl={editUrl}
   feedback={data.config.feedback}
+  feedbackComments={data.config.feedbackComments}
+  pagination={frontmatter.pagination}
+  related={frontmatter.related}
+  search={frontmatter.search}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}${
     options.navFragments
       ? `
-  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}`
+  navFragmentBase={withMountedBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}`
       : ""
   }
   openInChat={data.config.openInChat}
@@ -2471,13 +2756,25 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   discovery={data.config.discovery}
   siteUrl={data.config.site}
   pageType={frontmatter.type}
+  apiRail={remarkPluginFrontmatter?.${API_RAIL_KEY} === true}
+  pageMode={frontmatter.mode}
   published={frontmatter.date ?? frontmatter.changelog?.date ?? null}
   lastModified={lastModified}
   noindex={effectiveNoindex}
   structuredDataEnabled={data.config.structuredData}
 >
-  <h1>{title}</h1>
-  {frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
+  {pageChrome && <h1>{title}</h1>}
+  {pageChrome && frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
+  {narration && (
+    <NarrationPlayer
+      audioBase={narration.generated ? withMountedBase("/blume-narration/audio/") : undefined}
+      cues={narrationCues}
+      lang={i18n ? contentLocale : htmlLang}
+      manifest={narration.generated ? withMountedBase(encodeURI(\`/blume-narration/\${route === "/" ? "index" : route.slice(1)}.json\`)) : undefined}
+      strings={ui.narration}
+    />
+  )}
+  {views.length > 1 && <ViewSwitcher label={ui.content.selectView} views={views} />}
   <LocaleLinks locale={locale}>
     <Content components={components} />
   </LocaleLinks>
@@ -2516,7 +2813,7 @@ export const changelogIndexTemplate = (options: {
 // Generated by Blume. Do not edit.
 import { getCollection } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
+import { withMountedBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { resolveDateFormatOptions } from "blume/core/date-format.ts";
 import { layoutOverrides } from "../generated/components.ts";
@@ -2615,7 +2912,7 @@ const items = changelogEntries.map((entry) => {
   return {
     date: date ? formatRowDate(date) : null,
     dateTime: date ? date.toISOString().slice(0, 10) : null,
-    href: route ? withBase(route) : null,
+    href: route ? withMountedBase(route) : null,
     id: slugify(label),
     label,
     tag: entry.data.changelog?.category ?? null,
@@ -2651,14 +2948,14 @@ for (const item of items) {
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 // The canonical URL carries the deployment base (the page is served under it),
-// matching how the catch-all canonicalizes via \`withBase(route)\`.
-const basedRoute = withBase("/changelog");
+// matching how the catch-all canonicalizes via \`withMountedBase(route)\`.
+const basedRoute = withMountedBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
 // The generated OG card for this route (the /og endpoint emits it alongside
 // the content-route cards), absolutized like the catch-all's so crawlers get
 // a full URL when the site is known.
-const ogPath = data.config.og.enabled ? withBase("/og/changelog.png") : null;
+const ogPath = data.config.og.enabled ? withMountedBase("/og/changelog.png") : null;
 const ogImage = ogPath && base ? base + ogPath : ogPath;
 
 // The page chrome (h1, title, description) comes from the translatable
@@ -2780,8 +3077,8 @@ export const notFoundPageTemplate = (): string => `---
 // Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
 import Icon from "blume/components/Icon.astro";
 import PageLayout from "blume/components/layout/PageLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
-import { withBasePath } from "blume/core/base-path.ts";
+import { withMountedBase } from "blume/components/islands/base-path.ts";
+import { mountBasePath } from "blume/core/base-path.ts";
 import data from "blume:data";
 
 export const prerender = true;
@@ -2805,14 +3102,14 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 // their resolved target when the section has no index page of its own.
 const suggestions = [
   ...data.navigation.tabs.map((tab) => ({
-    href: withBase(tab.href ?? tab.path),
+    href: withMountedBase(tab.href ?? tab.path),
     label: tab.label,
   })),
   ...(data.config.discovery.sitemap
-    ? [{ href: withBase("/sitemap.xml"), label: nf.sitemap }]
+    ? [{ href: withMountedBase("/sitemap.xml"), label: nf.sitemap }]
     : []),
   ...(data.config.discovery.llmsTxt
-    ? [{ href: withBase("/llms.txt"), label: nf.llms }]
+    ? [{ href: withMountedBase("/llms.txt"), label: nf.llms }]
     : []),
 ];
 
@@ -2824,7 +3121,7 @@ const suggestions = [
 // Localized routes sit under both bases (\`{deployment.base}/{basePath}/ar/…\`),
 // so the script strips the two together, trailing slash included.
 const { basePath } = data.config;
-const siteRoot = withBase(withBasePath(basePath, "/"));
+const siteRoot = withMountedBase(mountBasePath(basePath, "/"));
 const localeBase = siteRoot.endsWith("/") ? siteRoot : siteRoot + "/";
 const localized = Object.fromEntries(
   (i18n?.locales ?? [])
@@ -2837,7 +3134,7 @@ const localized = Object.fromEntries(
           description: strings.description,
           dir: l.dir ?? "ltr",
           home: strings.home,
-          homeHref: withBase(withBasePath(basePath, "/" + l.code)),
+          homeHref: withMountedBase(mountBasePath(basePath, "/" + l.code)),
           suggestions: strings.suggestions,
           title: strings.title,
         },
@@ -2887,7 +3184,7 @@ const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
       <a
         class="mt-8 inline-flex items-center gap-1.5 rounded-full bg-accent py-2 pe-4 ps-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90"
         data-nf-home
-        href={withBase("/")}
+        href={withMountedBase("/")}
       >
         <Icon class="rtl:-scale-x-100" name="arrow-left" size={14} />
         <span data-nf="home">{nf.home}</span>
@@ -2969,7 +3266,7 @@ const localizedJson = JSON.stringify(localized).replaceAll("<", "\\\\u003c");
  */
 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 { withMountedBase } from "blume/components/islands/base-path.ts";
 import { absoluteUrl } from "blume/core/site-url.ts";
 import data from "blume:data";
 
@@ -2980,7 +3277,7 @@ 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);
+  const based = withMountedBase(path);
   return data.config.site && based.startsWith("/") && !based.startsWith("//")
     ? absoluteUrl(data.config.site, based)
     : based;
@@ -3039,7 +3336,7 @@ export function GET() {
 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 { withMountedBase } from "blume/components/islands/base-path.ts";
 import { absoluteUrl } from "blume/core/site-url.ts";
 import data from "blume:data";
 
@@ -3050,7 +3347,7 @@ 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);
+  const based = withMountedBase(path);
   return data.config.site && based.startsWith("/") && !based.startsWith("//")
     ? absoluteUrl(data.config.site, based)
     : based;
@@ -3225,7 +3522,7 @@ ${wrapperPropsType("Example")}
 /**
  * The route prefix `<Component />` preview frames are served under:
  * `{basePath}/blume-examples/<example path>`. `deployment.base` is layered on
- * top by Astro (components apply it with `withBase`).
+ * top by Astro (components apply it with `withMountedBase`).
  */
 export const examplesRouteBase = (basePath: string): string =>
   `${basePath}/blume-examples`;