blume 2.0.3 → 2.1.1

package/dist/cli/{chunk-5m5nmvyq.js → chunk-gb420vvz.js}

@@ -4,19 +4,26 @@ import {
   resolveDocsCollection,
   TOC_HIDDEN_KEY,
   deployPassthrough,
+  RATE_LIMIT_BINDING,
   fontLocaleCodes,
   buildFontEntries,
+  isPatternPath,
+  compileEveryRedirect,
+  hasVariables,
   SVG_ASSET_HEADERS,
   applyBaseToAstroRedirects,
+  withMirrorRedirects,
   distDir,
   adapterRoot,
-  deployPlatform,
-  BLUME_IGNORE_DIRS
-} from "./chunk-pv29h0wf.js";
+  deployPlatform
+} from "./chunk-ehweg4fr.js";
 import {
   trimChar,
   normalizeBasePath
-} from "./chunk-3em5wd2y.js";
+} from "./chunk-zccbjcj0.js";
+import {
+  BLUME_IGNORE_DIRS
+} from "./chunk-kwrg63tm.js";
 
 // src/deploy/adapter-output.ts
 import { existsSync } from "node:fs";
@@ -28,7 +35,7 @@ var deployOutputDir = (config, context) => {
 };
 var deployStaticDir = (config, context) => {
   const { deployment } = config;
-  return deployment.options.output === "server" ? deployPlatform(deployment).serverStaticDir(context) : distDir(context);
+  return deployment.options.output === "server" ? deployPlatform(deployment).serverStaticDir(context, normalizeBasePath(deployment.options.base)) : distDir(context);
 };
 var surfaceAdapterOutput = async (config, context) => {
   const { deployment } = config;
@@ -212,6 +219,23 @@ var publishRuntimeModules = (modules) => {
 import { existsSync as existsSync2, readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { dirname as dirname2, isAbsolute as isAbsolute2, join as join3, relative as relative2 } from "pathe";
+
+// src/ai/ask-limits.ts
+var ASK_MAX_MESSAGES = 40;
+var ASK_MAX_MESSAGES_CHARS = 24000;
+
+// src/consent/clients.ts
+var CONSENT_CLIENT_MODULES = new Map([
+  ["native", "blume/components/layout/consent/native.ts"]
+]);
+
+// src/markdown/api-rail.ts
+var API_RAIL_KEY = "blumeApiRail";
+
+// src/markdown/views.ts
+var VIEWS_KEY = "blumeViews";
+
+// src/astro/templates.ts
 var WORKSPACE_MARKERS = [
   ".git",
   "bun.lock",
@@ -254,13 +278,13 @@ var renderAstroAdapter = (deployment, context, ejected) => {
   const { astro } = platform;
   const args = {
     ...astro.options(context),
-    ...deployPassthrough(deployment.options)
+    ...deployPassthrough(deployment.options, astro.configOptions)
   };
   const argsLiteral = Object.keys(args).length > 0 ? JSON.stringify(args) : "";
   const construct = `adapter(${argsLiteral})`;
   const expression = platform.hiddenRuntime.showProjectRoot && !ejected ? `withAdapterRoot(${construct}, ${JSON.stringify(adapterRoot(context))})` : construct;
   return {
-    configEntries: Object.entries(astro.config).map(([key, value]) => `
+    configEntries: Object.entries(astro.config(deployment.options)).map(([key, value]) => `
   ${key}: ${JSON.stringify(value)},`).join(""),
     importLine: `import adapter from "${astro.package}";
 `,
@@ -288,7 +312,7 @@ var runtimeDependencies = (options) => {
   if (needsSvelte) {
     deps.push("@astrojs/svelte");
   }
-  deps.push(...new Set(config.reference.flatMap((adapter) => adapter.runtimeDeps)), ...config.search.provider.runtimeDeps, ...config.analytics.flatMap((adapter) => adapter.runtimeDeps));
+  deps.push(...new Set(config.reference.flatMap((adapter) => adapter.runtimeDeps)), ...config.search.provider.runtimeDeps, ...config.analytics.flatMap((adapter) => adapter.runtimeDeps), ...config.consent?.runtimeDeps ?? []);
   for (const source of config.content.sources) {
     for (const dep of source.runtimeDeps) {
       if (!deps.includes(dep)) {
@@ -319,7 +343,7 @@ var RENDER_EXTERNAL_DEPS = [
 ];
 var renderUserAliases = (aliases) => Object.entries(aliases ?? {}).toSorted(([a], [b]) => b.length - a.length).map(([find, replacement]) => `
         ${JSON.stringify(find)}: ${JSON.stringify(replacement)},`).join("");
-var REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//, /\/\.cache\/vite\//]`;
+var REACT_EXCLUDE = String.raw`exclude: [/\/\.cache\/vite\//]`;
 var runtimeCacheOptions = (context, generatedModulesDir) => {
   if (generatedModulesDir !== undefined) {
     return { astro: "", vite: "" };
@@ -331,7 +355,7 @@ var runtimeCacheOptions = (context, generatedModulesDir) => {
     cacheDir: ${JSON.stringify(`${context.outDir}/.cache/vite`)},`
   };
 };
-var reactIntegration = (compilerPath) => compilerPath ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] }, ${REACT_EXCLUDE} })` : `react({ ${REACT_EXCLUDE} })`;
+var reactIntegration = (compiler) => compiler ? `react({ compiler: true, ${REACT_EXCLUDE} })` : `react({ ${REACT_EXCLUDE} })`;
 var renderIntegrationBridge = (bridge) => {
   if (!bridge) {
     return {
@@ -377,7 +401,7 @@ var resolveOptimizeDeps = (options) => {
     ...features.mermaid ? ["blume > mermaid"] : [],
     ...features.epub ? ["blume > epub-gen-memory/bundle"] : [],
     ...searchDep ? [`blume > ${searchDep}`] : [],
-    ...options.needsReact && options.reactCompilerPath ? ["react/compiler-runtime"] : []
+    ...options.needsReact && options.reactCompiler ? ["react/compiler-runtime"] : []
   ];
   return { optimizeDepsEntries, optimizeDepsInclude };
 };
@@ -404,17 +428,24 @@ var renderRuntimeModuleWiring = (generatedModulesDir) => {
         ${JSON.stringify(id)}: ${configPath(`${generatedModulesDir}/${file}`, true)},`).join("");
   return { aliasLines, imports: [], pluginEntry: "" };
 };
-var blumeIntegrationOptions = (options) => options.ejected ? {
-  buildArtifactsRoot: ".",
-  contentRoutes: options.contentRoutes,
-  homeLinkHeader: buildHomeLinkHeader(options.config, options.contentRoutes, "dev") ?? undefined,
-  pages: options.pages
-} : { pages: options.pages };
+var blumeIntegrationOptions = (options) => {
+  const shared = { 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, "dev") ?? undefined
+  } : shared;
+};
 var astroConfigTemplate = (options) => {
   const { context, config, needsReact, pages, themePath } = options;
   const { astro: cacheOptions, vite: viteCacheOption } = runtimeCacheOptions(context, options.generatedModulesDir);
   const {
     askPath,
+    consentClientPath,
     contentRoutes,
     examplesPath,
     examplesThemePath,
@@ -439,7 +470,7 @@ var astroConfigTemplate = (options) => {
     context,
     features,
     needsReact,
-    reactCompilerPath: options.reactCompilerPath,
+    reactCompiler: options.reactCompiler,
     searchKind: config.search.provider.kind
   });
   const {
@@ -460,9 +491,11 @@ var astroConfigTemplate = (options) => {
       prefixDefaultLocale: !config.i18n.hideDefaultLocalePrefix
     }
   })},` : "";
-  const basedRedirects = applyBaseToAstroRedirects(config.redirects, config.basePath, deployment.options.base ?? "", new Set(contentRoutes));
-  const redirectsOption = basedRedirects.length > 0 ? `
-  redirects: ${JSON.stringify(Object.fromEntries(basedRedirects.map((redirect) => [
+  const redirectPages = new Set(contentRoutes);
+  const basedRedirects = withMirrorRedirects(applyBaseToAstroRedirects(config.redirects, config.basePath, deployment.options.base ?? "", redirectPages), redirectPages, { from: "", to: normalizeBasePath(deployment.options.base) });
+  const exactRedirects = basedRedirects.filter((redirect) => !isPatternPath(redirect.from));
+  const redirectsOption = exactRedirects.length > 0 ? `
+  redirects: ${JSON.stringify(Object.fromEntries(exactRedirects.map((redirect) => [
     redirect.from,
     { destination: redirect.to, status: redirect.status }
   ])))},` : "";
@@ -492,12 +525,15 @@ var astroConfigTemplate = (options) => {
 ` : "";
   const svelteImport = needsSvelte ? `import svelte from "@astrojs/svelte";
 ` : "";
+  const substitutesVariables = hasVariables(config.variables);
+  const variablesPluginEntry = substitutesVariables ? `variablesVitePlugin(${JSON.stringify(config.variables)}), ` : "";
   const blumeImports = [
     "blumeIntegration",
     "includeHmrPlugin",
     "prerenderDepsPlugin",
     ...runtimeModuleImports,
-    ...adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []
+    ...adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : [],
+    ...substitutesVariables ? ["variablesVitePlugin"] : []
   ];
   const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";
 `;
@@ -509,14 +545,15 @@ var astroConfigTemplate = (options) => {
     contentRoot: options.contentRoot,
     deployBase,
     externalLinks: config.markdown.externalLinks,
-    headingAnchors: config.markdown.headingAnchors
+    headingAnchors: config.markdown.headingAnchors,
+    variables: config.variables
   });
   const processorOptions = options.generatedModulesDir === undefined ? processorLiteral : `{ ...${processorLiteral}, dataFile: ${configPath(`${options.generatedModulesDir}/data.json`, true)} }`;
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${processorOptions}) })`
   ];
   if (needsReact) {
-    integrations.push(reactIntegration(options.reactCompilerPath));
+    integrations.push(reactIntegration(options.reactCompiler));
   }
   if (needsVue) {
     integrations.push("vue()");
@@ -528,7 +565,8 @@ var astroConfigTemplate = (options) => {
     config,
     contentRoutes,
     ejected,
-    pages
+    pages,
+    redirects: compileEveryRedirect(basedRedirects)
   }))})`);
   const {
     configSourceMarker,
@@ -584,7 +622,7 @@ ${userConfigSetup}export default defineConfig({
   // the overlap only adds memory.
   build: { concurrency: Math.min(8, availableParallelism()) },
   vite: {${viteCacheOption}
-    plugins: [${runtimeModulesPluginEntry}tailwindcss(), includeHmrPlugin(${configPath(`${context.outDir}/src/generated/includes.json`, ejected)}), prerenderDepsPlugin()],
+    plugins: [${runtimeModulesPluginEntry}${variablesPluginEntry}tailwindcss(), includeHmrPlugin(${configPath(`${context.outDir}/src/generated/includes.json`, ejected)}), prerenderDepsPlugin()],
     build: {${features.mermaid ? MERMAID_CHUNK_LIMIT : ""}
       rolldownOptions: {
         ${ROLLDOWN_ON_LOG},
@@ -593,8 +631,8 @@ ${userConfigSetup}export default defineConfig({
     // Everything hydration can reach must be part of the dev dep optimizer's
     // FIRST run. The Vite root is the generated runtime, so user pages,
     // islands, and aliased components live outside it and are only crawled
-    // when first requested — and \`react/compiler-runtime\` is Babel-injected,
-    // so no source scan can ever see it. A dependency discovered after
+    // when first requested — and \`react/compiler-runtime\` is injected by the
+    // React Compiler, so no source scan can ever see it. A dependency discovered after
     // hydration begins triggers a mid-session re-optimization whose new
     // generation imports React through new \`?v=\` URLs; the browser then
     // evaluates a second React copy and every island tears down with
@@ -640,6 +678,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)},
@@ -719,18 +758,73 @@ var askCorsTemplate = (cors = []) => cors.length > 0 ? {
   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)};
 
 export const OPTIONS: APIRoute = ({ request }) =>
   preflightResponse(request, ALLOWED_ORIGINS);
 `
-} : { close: "};", imports: [], open: "async ({ request }) => {", setup: "" };
+} : { close: "};", imports: [], open: "async (context) => {", setup: "" };
+var rateLimitTemplate = (adapter, scope) => {
+  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: `
+const limiter = createLimiter(${JSON.stringify(adapter)}${runtime});
+`
+  };
+};
+var askCaptchaTemplate = (adapter) => {
+  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: `
+const CAPTCHA = ${JSON.stringify(adapter)};
+`
+  };
+};
 var ASK_BODY_LIMIT_BYTES = 65536;
 var askEndpointTemplate = (backend, options) => {
   const { instructions, retrieval } = options ?? {};
   const { grounded } = backend;
+  const tools = grounded && Boolean(options?.tools);
   const fallbackPrompt = instructions ? `${ASK_FALLBACK_PROMPT}
 
 ${instructions}` : ASK_FALLBACK_PROMPT;
@@ -750,14 +844,33 @@ ${instructions}` : ASK_FALLBACK_PROMPT;
     if (retrieval) {
       groundFields.push(`retrieval: ${JSON.stringify(retrieval)}`);
     }
+    if (tools) {
+      groundFields.push("tools: true");
+    }
     const groundOptions = groundFields.length > 0 ? `, { ${groundFields.join(", ")} }` : "";
     setup += `
 const ground = createAskContext(askData${groundOptions});
 `;
+    if (tools) {
+      imports.push('import { stepCountIs } from "ai";', 'import { ASK_MAX_STEPS, createAskTools } from "blume/ai/ask-tools.ts";');
+      setup += `const askTools = createAskTools(askData);
+`;
+    }
   }
   const cors = askCorsTemplate(options?.cors);
   imports.push(...cors.imports);
-  const validate = `  const text = await readCappedText(request, ${ASK_BODY_LIMIT_BYTES});
+  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;
+  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,
@@ -773,7 +886,7 @@ const ground = createAskContext(askData${groundOptions});
   const valid =
     Array.isArray(raw) &&
     raw.length > 0 &&
-    raw.length <= 40 &&
+    raw.length <= ${ASK_MAX_MESSAGES} &&
     raw.every(
       (m: unknown) =>
         typeof m === "object" &&
@@ -781,10 +894,10 @@ const ground = createAskContext(askData${groundOptions});
         ("role" in m && (m.role === "user" || m.role === "assistant")) &&
         ("content" in m && typeof m.content === "string")
     ) &&
-    JSON.stringify(raw).length <= 24_000;
+    JSON.stringify(raw).length <= ${ASK_MAX_MESSAGES_CHARS};
   if (!valid) {
     return new Response(
-      "Invalid request: send 1-40 user/assistant messages with string content.",
+      "Invalid request: send 1-${ASK_MAX_MESSAGES} user/assistant messages with string content.",
       { status: 400 }
     );
   }
@@ -802,6 +915,7 @@ const ground = createAskContext(askData${groundOptions});
     grounded ? "instructions" : `instructions:
         ${JSON.stringify(fallbackPrompt)}`,
     "messages",
+    ...tools ? ["tools: askTools(body.page)", "stopWhen: stepCountIs(ASK_MAX_STEPS)"] : [],
     ...backend.template.fields
   ];
   const call = `    const result = streamText({
@@ -817,7 +931,7 @@ ${call}` : call;
   const handler = `export const POST: APIRoute = ${cors.open}
 ${validate}
 ${keyCheck}
-  try {
+${captcha.check}  try {
 ${stream}
     return createTextStreamResponse({
       stream: toTextStream({ stream: result.stream }),
@@ -844,9 +958,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}
 />
 ` : `---
 // Generated by Blume. Do not edit.
@@ -894,6 +1010,25 @@ ${features.epub ? `export const loadEpub:
   | (() => Promise<typeof import("epub-gen-memory/bundle")>)
   | null = () => import("epub-gen-memory/bundle");` : "export const loadEpub: (() => Promise<unknown>) | null = null;"}
 `;
+var consentClientTemplate = (consent) => {
+  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)});
+};
+`;
+};
 var searchClientTemplate = (config) => {
   const { provider } = config.search;
   switch (provider.mode) {
@@ -905,10 +1040,11 @@ var searchClientTemplate = (config) => {
       return hostedSearchClient(provider);
     }
     case "server": {
-      return `${SEARCH_CLIENT_HEADER}${searchClientImport("endpoint")}${SEARCH_BASE_IMPORT}
+      return `${SEARCH_CLIENT_HEADER}${searchClientImport("endpoint")}${SEARCH_BASE_IMPORT}import type { SearchClientOptions } from "blume/components/layout/search/types.ts";
 const api = joinBase(import.meta.env.BASE_URL, "api/search");
 
-export const createSearch = () => create({ api });
+export const createSearch = (options: SearchClientOptions = {}) =>
+  create({ ...options, api });
 `;
     }
     case "pagefind": {
@@ -925,21 +1061,47 @@ export const createSearch = () => create({ url });
     }
   }
 };
-var mixedbreadSearchEndpointTemplate = (options) => `// 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";
+var mixedbreadSearchEndpointTemplate = (options, pages, rateLimit) => {
+  const { search_options: tuning, storeId, ...searchOptions } = options;
+  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(`
+`)}
 
 export const prerender = false;
 
 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
+const STORE_ID = ${JSON.stringify(storeId)};
+// Every other option reaches the search call verbatim.
+const SEARCH_OPTIONS = ${JSON.stringify(searchOptions)};
+const SEARCH_TUNING = ${JSON.stringify(tuning ?? {})};
+// Each page's source file, relative to the project root, and the page it renders.
+const PAGES = new Map<string, { title: string; url: string }>(${JSON.stringify(pages)});
+
+// The page a synced file renders. \`mxbai store sync\` records the path
+// relative to where it ran (the project root, or a monorepo root above it), so
+// the longest trailing run of that path that names a page's file wins.
+const pageFor = (path: string) => {
+  const segments = path.replaceAll("\\\\", "/").split("/");
+  for (let start = 0; start < segments.length; start += 1) {
+    const page = PAGES.get(segments.slice(start).join("/"));
+    if (page) {
+      return page;
+    }
+  }
+  return undefined;
+};
+${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) {
@@ -961,29 +1123,39 @@ export const POST: APIRoute = async ({ request }) => {
     });
   }
   // \`top_k\` defaults to 8 unless an option sets it; the query and store
-  // always come from the request and \`storeId\`.
+  // always come from the request and \`storeId\`. File metadata is always
+  // returned: it holds the path \`mxbai store sync\` recorded for the file.
   const response = await client.stores.search({
     top_k: 8,
     ...SEARCH_OPTIONS,
     query,
+    search_options: { ...SEARCH_TUNING, return_metadata: true },
     store_identifiers: [STORE_ID],
   });
-  const hits = (response.data ?? []).map((chunk) => {
+  const seen = new Set<string>();
+  const hits = (response.data ?? []).flatMap((chunk) => {
+    const { file_path: path } = (chunk.metadata ?? {}) as { file_path?: unknown };
+    const page = typeof path === "string" ? pageFor(path) : undefined;
+    // A file no page renders has nowhere to link, and a page's later chunks
+    // would repeat it: one hit per page, at its best chunk.
+    if (!page || seen.has(page.url)) {
+      return [];
+    }
+    seen.add(page.url);
     const meta = chunk.generated_metadata ?? {};
     // Only a text chunk carries \`text\`; image, audio, and video chunks fall
     // back to the excerpt the store generated for them.
     const text = "text" in chunk ? chunk.text : undefined;
-    return {
-      excerpt: text ?? meta.excerpt ?? "",
-      title: meta.title ?? chunk.filename ?? "",
-      url: meta.url ?? "",
-    };
+    return [
+      { excerpt: text ?? meta.excerpt ?? "", title: page.title, url: page.url },
+    ];
   });
   return new Response(JSON.stringify(hits), {
     headers: { "Content-Type": "application/json" },
   });
 };
 `;
+};
 var rawMarkdownEndpointTemplate = (kind) => `// Generated by Blume. Do not edit.
 import raw from "blume:raw-markdown";
 
@@ -1128,16 +1300,22 @@ const handler = createMcpFetchHandler(data);
 
 export const ALL: APIRoute = ({ request }) => handler(request);
 `;
-var playgroundProxyTemplate = (origins) => `// Generated by Blume. Do not edit.
-import type { APIRoute } from "astro";
-import { createPlaygroundProxyHandler } from "blume/openapi/proxy.ts";
+var playgroundProxyTemplate = (origins, rateLimit) => {
+  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(`
+`)}
 
 export const prerender = false;
 
 const handler = createPlaygroundProxyHandler(${JSON.stringify(origins)});
-
-export const ALL: APIRoute = ({ request }) => handler(request);
+${limit.setup}
+${route}
 `;
+};
 var staticJsonEndpointTemplate = (payload) => `// Generated by Blume. Do not edit.
 export const prerender = true;
 
@@ -1378,6 +1556,9 @@ var contentComponentsSource = (mathEnabled) => {
   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";
@@ -1397,7 +1578,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";
@@ -1408,10 +1593,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";
@@ -1419,7 +1607,10 @@ ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../gener
     map: `{
   Accordion,
   AccordionItem,
+  ApiEndpoint,
   ApiOverview,
+  ApiPlayground,
+  ApiRail,
   ApiTagOperations,
   AutoTypeTable,
   Badge,
@@ -1440,7 +1631,11 @@ ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../gener
   Icon,
   Operation,
   Panel,
+  ParamField,
   Prompt,
+  RequestExample,
+  ResponseExample,
+  ResponseField,
   Step,
   Steps,
   Tab,
@@ -1449,6 +1644,7 @@ ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../gener
   Tooltip,
   Tree,
   TypeTable,
+  View,
   Visibility,
   YouTube,
   ${mathEntry}...userMdx,
@@ -1462,10 +1658,12 @@ var 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, withMountedBase } from "blume/components/islands/base-path.ts";
 import { mountBasePath, stripBasePath } from "blume/core/base-path.ts";
+import { routeSetFor, servesRoute } from "blume/core/locale-links.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${componentImports}
 import data from "blume:data";
@@ -1513,6 +1711,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 =
@@ -1591,6 +1796,14 @@ 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";
@@ -1654,18 +1867,24 @@ const logicalRoute = i18n
   ? stripLocale(stripBasePath(data.config.basePath, route), locale)
   : route;
 // A page from a one-language source (GitHub Releases) gets no switcher: every
-// other locale would only repeat the same text.
+// other locale would only repeat the same text. A locale with no real
+// translation links the page's fallback copy, which exists only while
+// fallbacks are on; where nothing is served at that URL (\`fallbackLocale:
+// null\`), the locale is left out rather than linked to a 404.
 const localeSwitch = i18n && !monolingual
-  ? i18n.locales.map((l) => {
+  ? i18n.locales.flatMap((l) => {
       const alt = (alternates ?? []).find((x) => x.locale === l.code);
-      return {
-        code: l.code,
-        current: l.code === locale,
-        dir: l.dir,
-        href: alt ? alt.path : mountLocalized(logicalRoute, l.code),
-        label: l.label,
-        untranslated: !alt,
-      };
+      const href = alt ? alt.path : mountLocalized(logicalRoute, l.code);
+      return alt || servesRoute(routeSetFor(data.routes), href)
+        ? [{
+            code: l.code,
+            current: l.code === locale,
+            dir: l.dir,
+            href,
+            label: l.label,
+            untranslated: !alt,
+          }]
+        : [];
     })
   : [];
 
@@ -1774,6 +1993,10 @@ 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={withMountedBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}` : ""}
@@ -1782,13 +2005,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>
@@ -1949,13 +2184,15 @@ const canonical = base ? base + basedRoute : 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
-// \`changelog\` group; optional chaining tolerates a not-yet-regenerated data
-// snapshot from before these keys existed.
+// The page chrome (h1, title, description, empty state) comes from the
+// translatable \`changelog\` group, which carries the \`changelog\` config's title and
+// description when it sets them; optional chaining tolerates a
+// not-yet-regenerated data snapshot from before these keys existed.
 const changelogTitle = data.ui.changelog?.title ?? "Changelog";
 const changelogDescription =
   data.ui.changelog?.description ??
   "Product updates, new features, and fixes from every release.";
+const changelogEmpty = data.ui.changelog?.empty ?? "No changelog entries yet.";
 // The layout suffixes "- {site title}" itself, so the page title is just the
 // changelog's own name — prefixing the site title too would double it
 // ("Acme Changelog - Acme").
@@ -2008,7 +2245,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   <p class="text-lg text-muted-foreground">{changelogDescription}</p>
   {
     items.length === 0 ? (
-      <p>No changelog entries yet.</p>
+      <p>{changelogEmpty}</p>
     ) : (
       <div class="not-prose mt-10 divide-y divide-border border-border border-y">
         {groups.map((group) => (
@@ -2559,7 +2796,7 @@ var runtimeTsconfigTemplate = () => `${JSON.stringify({
 }, null, 2)}
 `;
 
-export { deployOutputDir, deployStaticDir, surfaceAdapterOutput, planComponentSlots, publishRuntimeModules, runtimeDependencies, EJECTED_CONFIG_HEADER, astroConfigTemplate, stagedContentDir, contentConfigTemplate, askEndpointTemplate, askComponentTemplate, searchEndpointTemplate, featuresTemplate, searchClientTemplate, mixedbreadSearchEndpointTemplate, rawMarkdownEndpointTemplate, contentAssetsEndpointTemplate, mcpPageFile, mcpEndpointTemplate, playgroundProxyTemplate, staticJsonEndpointTemplate, rssEndpointTemplate, navFragmentTemplate, ogEndpointTemplate, scalarReferenceTemplate, catchAllPageTemplate, changelogIndexTemplate, notFoundPageTemplate, notFoundMarkdownTemplate, notFoundJsonTemplate, apiPagesIndexTemplate, apiPageTemplate, apiNavigationTemplate, apiSearchTemplate, apiNotFoundTemplate, exampleSlug, exampleWrapperTemplate, examplesRouteBase, exampleMapTemplate, examplesPageTemplate, runtimePackageTemplate, runtimeTsconfigTemplate };
+export { deployOutputDir, deployStaticDir, surfaceAdapterOutput, planComponentSlots, publishRuntimeModules, runtimeDependencies, EJECTED_CONFIG_HEADER, astroConfigTemplate, stagedContentDir, contentConfigTemplate, askEndpointTemplate, askComponentTemplate, searchEndpointTemplate, featuresTemplate, consentClientTemplate, searchClientTemplate, mixedbreadSearchEndpointTemplate, rawMarkdownEndpointTemplate, contentAssetsEndpointTemplate, mcpPageFile, mcpEndpointTemplate, playgroundProxyTemplate, staticJsonEndpointTemplate, rssEndpointTemplate, navFragmentTemplate, ogEndpointTemplate, scalarReferenceTemplate, catchAllPageTemplate, changelogIndexTemplate, notFoundPageTemplate, notFoundMarkdownTemplate, notFoundJsonTemplate, apiPagesIndexTemplate, apiPageTemplate, apiNavigationTemplate, apiSearchTemplate, apiNotFoundTemplate, exampleSlug, exampleWrapperTemplate, examplesRouteBase, exampleMapTemplate, examplesPageTemplate, runtimePackageTemplate, runtimeTsconfigTemplate };
 
-//# debugId=D53DB1B1EA2E6A3764756E2164756E21
-//# sourceMappingURL=chunk-5m5nmvyq.js.map
+//# debugId=5E4553A34E0C7B9D64756E2164756E21
+//# sourceMappingURL=chunk-gb420vvz.js.map