blume 2.0.3 → 2.1.0

package/src/astro/generate.ts

@@ -27,6 +27,8 @@ import type { RawMarkdownEntry } 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 { captchaSettings } from "../captcha/schema.ts";
+import { parseApiEndpoint } from "../components/content/api-page.ts";
 import {
   hasDeferrableGroups,
   navVariants,
@@ -44,6 +46,7 @@ import {
 } from "../core/content-assets.ts";
 import type {
   BlumeBanner,
+  BlumeDataConfig,
   BlumeData,
   BlumeFavicon,
   BlumeLogo,
@@ -58,6 +61,7 @@ import {
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
 import { buildIncludeGraph } from "../core/includes.ts";
+import { resolveLocalizable } from "../core/localizable.ts";
 import {
   validateNavTargets,
   validateSearchPopularIcons,
@@ -85,6 +89,7 @@ import type { AsyncApiSpecValue } from "../openapi/asyncapi.ts";
 import type { ApiSpecData, HttpMethod, OpenApiData } from "../openapi/model.ts";
 import { HTTP_METHODS, withServerDefaults } from "../openapi/model.ts";
 import {
+  apiPagesUseBuiltinProxy,
   builtinProxyReferences,
   hasScalarReferences,
   needsPlaygroundProxy,
@@ -159,6 +164,7 @@ import {
   runtimeTsconfigTemplate,
   featuresTemplate,
   navFragmentTemplate,
+  consentClientTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
   stagedContentDir,
@@ -749,12 +755,12 @@ const isStringShorthand = <T>(value: T | string): value is string =>
   typeof value === "string";
 
 /**
- * The URL behind the header's repo mark. A string is used as-is: `github`
- * drives the per-page edit link, the header mark and the manifest's
+ * The URL behind the footer's repo mark. A string is used as-is: `github`
+ * drives the per-page edit link, the footer mark and the manifest's
  * `repository` together, so a project whose docs repo is private has to unset
  * all three, and would otherwise have no way to point the mark at anything.
  */
-const headerRepoUrl = (
+const footerRepoUrl = (
   repo: boolean | string,
   derived: string | null
 ): string | null => {
@@ -961,11 +967,53 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   return {
     content: banner.content,
     dismissible: banner.dismissible,
-    key: banner.id ?? banner.content,
+    key:
+      banner.id ??
+      resolveLocalizable(banner.content, undefined, config.i18n?.defaultLocale),
     link: banner.link,
   };
 };
 
+/** The URL the built-in proxy is injected at (see {@link planPlaygroundProxy}). */
+export const playgroundProxyPattern = (config: ResolvedConfig): string =>
+  withBasePath(config.basePath, "/_api-proxy");
+
+/**
+ * The hand-written endpoint defaults for the runtime, the playground's
+ * `proxy: true` resolved to the built-in route's URL, as an OpenAPI
+ * reference's is.
+ */
+const resolveApiPages = (config: ResolvedConfig): BlumeDataConfig["api"] => {
+  const { auth, playground, server } = config.api;
+  const resolved: BlumeDataConfig["api"] = {
+    playground: {
+      enabled: playground.enabled,
+      proxy:
+        playground.proxy === true
+          ? playgroundProxyPattern(config)
+          : playground.proxy,
+    },
+  };
+  if (auth) {
+    resolved.auth = auth;
+  }
+  if (server) {
+    resolved.server = server;
+  }
+  return resolved;
+};
+
+/** The footer config for the runtime: `null` when unset or empty, so no bare border renders. */
+const resolveFooter = (
+  config: ResolvedConfig
+): ResolvedConfig["footer"] | null => {
+  const { footer } = config;
+  return footer &&
+    (footer.links.length > 0 || Object.keys(footer.socials).length > 0)
+    ? footer
+    : null;
+};
+
 /**
  * The OG card's brand mark: a `seo.og.logo` of `false` opts out of any mark,
  * a configured SVG wins over the site logo, and a non-SVG value resolves to
@@ -1036,6 +1084,22 @@ const resolveGithubData = (
       }
     : null;
 
+/** The assistant's snapshot: what the panel needs, never a secret. */
+const resolveAssistant = (
+  config: ResolvedConfig
+): BlumeDataConfig["assistant"] => {
+  const { assistant } = config.ai;
+  if (!assistant?.enabled) {
+    return null;
+  }
+  return {
+    captcha: assistant.captcha ? captchaSettings(assistant.captcha) : null,
+    endpoint: assistant.endpoint ?? null,
+    suggestions: assistant.suggestions,
+    support: assistant.support ?? null,
+  };
+};
+
 /** Serialize the content graph into the data module the runtime consumes. */
 export const buildRuntimeData = (project: BlumeProject): string => {
   const { config, context, graph, manifest } = project;
@@ -1067,10 +1131,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   const { i18n } = config;
 
-  // Resolve the header repo link per locale. API references no longer add a tab
+  // Resolve the footer's repo link per locale. API references no longer add a tab
   // automatically — authors point a `navigation.tabs` entry at the reference
   // route to surface it (see `referenceRoutes`).
-  const markUrl = headerRepoUrl(config.navigation.repo, repoUrl);
+  const markUrl = footerRepoUrl(config.navigation.repo, repoUrl);
   const withRepoUrl = (nav: Navigation): Navigation => ({
     ...nav,
     repoUrl: markUrl,
@@ -1117,17 +1181,14 @@ export const buildRuntimeData = (project: BlumeProject): string => {
   const data: BlumeData = {
     config: {
       analytics: config.analytics,
+      api: resolveApiPages(config),
       appleIcon: resolveAppleIcon(project),
-      assistant: config.ai.assistant?.enabled
-        ? {
-            endpoint: config.ai.assistant.endpoint ?? null,
-            suggestions: config.ai.assistant.suggestions,
-          }
-        : null,
+      assistant: resolveAssistant(config),
       banner: resolveBanner(config),
       basePath: config.basePath,
       codeThemes: config.markdown.code.theme,
       codeWrap: config.markdown.code.wrap,
+      consent: config.consent,
       dateFormat: config.dateFormat,
       description: config.description,
       discovery: {
@@ -1139,7 +1200,9 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         sitemap: config.seo.sitemap && Boolean(config.deployment.options.site),
       },
       favicon: resolveFavicon(project),
-      feedback: config.feedback,
+      feedback: config.feedback.enabled,
+      feedbackComments: config.feedback.comments,
+      footer: resolveFooter(config),
       github: resolveGithubData(github),
       i18n: i18n
         ? {
@@ -1153,6 +1216,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
               dir,
               label,
             })),
+            routeByBrowserLanguage: i18n.routeByBrowserLanguage,
           }
         : null,
       // `undefined` members drop out of the JSON snapshot; the null keeps the
@@ -1172,6 +1236,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             route: config.agents.mcp.route,
           }
         : null,
+      metatags: config.seo.metatags ?? null,
+      narration: config.narration.enabled
+        ? { generated: config.narration.provider !== null }
+        : null,
       // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
       // the optional schema type so the serialized shape stays `boolean`.
       // Card fonts are baked into the generated OG endpoint (they can carry
@@ -1496,10 +1564,6 @@ const writeApiFiles = async (
 /** The proxy endpoint's file under the Astro `src/` dir (eject writes it too). */
 export const PLAYGROUND_PROXY_ENTRY = join("blume-openapi", "api-proxy.ts");
 
-/** The URL the built-in proxy is injected at (see {@link planPlaygroundProxy}). */
-export const playgroundProxyPattern = (config: ResolvedConfig): string =>
-  withBasePath(config.basePath, "/_api-proxy");
-
 /**
  * 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
@@ -1592,6 +1656,47 @@ type DocumentPathItem = { servers?: DocumentServer[] } & Partial<
 export const specOrigins = (data: OpenApiData): string[] =>
   [...new Set(Object.values(data).flatMap(specOriginsOf))].toSorted();
 
+/** The origin of an absolute URL, or `null` for a path or anything unparsable. */
+const originOf = (url: string): string | null => {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The origins hand-written endpoint pages send to through the built-in
+ * proxy: the site's `api.server`, and every page whose `api` names a full
+ * URL. Empty unless those pages use the built-in proxy.
+ */
+export const apiPageOrigins = (project: BlumeProject): string[] => {
+  const { config } = project;
+  if (!apiPagesUseBuiltinProxy(config)) {
+    return [];
+  }
+  const targets = project.graph.pages.map(
+    (page) => parseApiEndpoint(page.meta.api ?? "")?.target ?? ""
+  );
+  return [config.api.server ?? "", ...targets].flatMap((target) => {
+    const origin = originOf(target);
+    return origin ? [origin] : [];
+  });
+};
+
+/**
+ * A warning when the hand-written endpoint pages send through the built-in
+ * proxy but name no absolute origin for it to allow, so it would refuse every
+ * request they send.
+ */
+export const apiPageProxyWarnings = (project: BlumeProject): string[] =>
+  apiPagesUseBuiltinProxy(project.config) &&
+  apiPageOrigins(project).length === 0
+    ? [
+        "api.playground.proxy is true, but api.server isn't an absolute URL and no page's api frontmatter names one, so the built-in proxy has no origin to allow and will refuse every request the endpoint pages send. Set api.server to the API's URL, like https://api.acme.com/v1.",
+      ]
+    : [];
+
 /**
  * Build-time diagnostics for playground sends the built-in proxy would refuse.
  * The baked-in allowlist pools every documented origin, but each spec's
@@ -1644,9 +1749,12 @@ const writeAskFiles = async (
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
     askEndpointTemplate(backend, {
+      captcha: assistant.captcha,
       cors: assistant.cors,
       instructions: assistant.instructions,
+      rateLimit: project.config.rateLimit,
       retrieval: assistant.retrieval,
+      tools: assistant.tools ?? backend.toolsByDefault,
     })
   );
 };
@@ -1863,6 +1971,7 @@ export const generateRuntime = async (
   const askPath = join(srcDir, "generated", "Ask.astro");
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
+  const consentClientPath = join(srcDir, "generated", "consent-client.ts");
   const featuresPath = join(srcDir, "generated", "features.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
   const examplesThemePath = join(srcDir, "generated", "examples.css");
@@ -2000,7 +2109,9 @@ export const generateRuntime = async (
   // Computed once: the endpoint template bakes it in below. A spec that
   // contributes no origin of its own gets a per-spec diagnostic
   // (`proxyAllowlistWarnings`) — the proxy would refuse its every send.
-  const proxyOrigins = specOrigins(openApiData);
+  const proxyOrigins = [
+    ...new Set([...specOrigins(openApiData), ...apiPageOrigins(project)]),
+  ].toSorted();
 
   const hasStaged = staged.size > 0;
   // Only emit a project-scanning `docs` collection when a filesystem source
@@ -2022,6 +2133,7 @@ export const generateRuntime = async (
           aliases: resolveTsconfigAliases(context.root),
           askPath,
           config,
+          consentClientPath,
           contentRoot: docsCollection.base,
           contentRoutes,
           context,
@@ -2186,6 +2298,7 @@ export const generateRuntime = async (
     }),
     writeNotFoundPage(write, srcDir, pages, project.graph.pages),
     write(searchClientPath, searchClientTemplate(config)),
+    write(consentClientPath, consentClientTemplate(config.consent)),
     write(featuresPath, featuresTemplate(clientFeatures)),
   ]);
 
@@ -2258,6 +2371,7 @@ export const generateRuntime = async (
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...proxyAllowlistWarnings(config, openApiData),
+    ...apiPageProxyWarnings(project),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
     ...mcp.warnings,
     ...islandDiscovery.warnings,

package/src/astro/index.ts

@@ -2,6 +2,7 @@ export { withAdapterRoot } from "./adapter-root.ts";
 export { generateRuntime, prerenderDepsPlugin } from "./generate.ts";
 export { includeHmrPlugin } from "./include-hmr.ts";
 export { withIncludeRefresh } from "./include-refresh.ts";
+export { variablesVitePlugin } from "./variables.ts";
 export type { GenerateResult } from "./generate.ts";
 export {
   blumeIntegration,

package/src/astro/integration.ts

@@ -9,6 +9,11 @@ import type { CustomPageRoute } from "../core/custom-pages.ts";
 import { enrichDiagnostic } from "../core/diagnostics.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import {
+  matchCompiledRedirect,
+  requestPath,
+} from "../core/redirect-patterns.ts";
+import type { CompiledRedirect } from "../core/redirect-patterns.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { publishBuildArtifacts } from "../deploy/artifacts.ts";
 import type { ArtifactLogger } from "../deploy/artifacts.ts";
@@ -336,6 +341,13 @@ export interface BlumeIntegrationOptions {
    * its already-scanned project instead.
    */
   buildArtifactsRoot?: string;
+  /**
+   * The pattern redirects (`/beta/:slug*`), compiled against base-less
+   * request paths (see `core/redirect-patterns.ts`). Astro's own `redirects`
+   * carry only the exact ones, since it can't prerender a pattern's pages, so
+   * the dev server answers these itself.
+   */
+  redirects?: CompiledRedirect[];
 }
 
 /**
@@ -397,6 +409,23 @@ const negotiateMarkdown =
     next();
   };
 
+/**
+ * Answer a pattern redirect in dev with its configured status, the way the
+ * server wrappers do in a build. Request URLs arrive base-less (see
+ * {@link negotiateMarkdown}), and the patterns were based to match.
+ */
+const answerPatternRedirects =
+  (redirects: readonly CompiledRedirect[]) =>
+  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
+    const answer = matchCompiledRedirect(redirects, requestPath(req.url ?? ""));
+    if (!answer) {
+      next();
+      return;
+    }
+    res.writeHead(answer[1], { Location: answer[0] });
+    res.end();
+  };
+
 /** The `.d.ts` the integration injects for the `blume:*` virtual modules. */
 const MODULE_TYPES_FILE = "modules.d.ts";
 
@@ -502,6 +531,12 @@ export const blumeIntegration = (
           }),
           route: "",
         });
+        if (options.redirects) {
+          server.middlewares.stack.unshift({
+            handle: answerPatternRedirects(options.redirects),
+            route: "",
+          });
+        }
       },
     },
     name: "blume",

package/src/astro/module-types.ts

@@ -75,6 +75,12 @@ declare module "blume:features" {
     | null;
 }
 
+declare module "blume:consent-client" {
+  export const startConsentClient: (
+    consent: import("blume/components/layout/consent/types.ts").BlumeConsent
+  ) => void;
+}
+
 declare module "blume:search-client" {
   export const createSearch: () =>
     | import("blume/components/layout/search/types.ts").SearchFn