blume 2.0.2 → 2.1.0

package/src/analytics/one-dollar-stats.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** The script OneDollarStats' install snippet loads. */
+export const ONE_DOLLAR_STATS_SCRIPT_SRC =
+  "https://assets.onedollarstats.com/stonks.js";
+
+/** The options {@link oneDollarStats} checks itself. */
+export interface OneDollarStatsNamedOptions {
+  /**
+   * A bare host name, e.g. `docs.example.com`. The tracker reports every
+   * event under it on every host, not just `localhost`.
+   */
+  hostname?: string;
+}
+
+/**
+ * Options for {@link oneDollarStats}: any tracker setting, forwarded as a
+ * `data-` attribute on the tag (`hostname` → `data-hostname`, `devmode`,
+ * `url`, `autocollect`, `"hash-routing"`, …).
+ */
+export type OneDollarStatsOptions = OneDollarStatsNamedOptions & {
+  [setting: string]: string;
+};
+
+export const oneDollarStatsOptionsSchema = z
+  .object({
+    hostname: z
+      .string()
+      .regex(/^[\p{L}\p{N}-]+(?:\.[\p{L}\p{N}-]+)*(?::\d+)?$/u, {
+        message:
+          "`hostname` must be a bare host name like `docs.example.com`, without `https://`, a path, a query, or a fragment.",
+      })
+      .optional(),
+  })
+  .catchall(z.string());
+
+export type OneDollarStatsAdapter = AdapterDescriptor<
+  "one-dollar-stats",
+  OneDollarStatsOptions
+>;
+
+export const oneDollarStatsAdapterSchema = adapterDescriptorSchema(
+  "one-dollar-stats",
+  oneDollarStatsOptionsSchema
+);
+
+/**
+ * OneDollarStats. Needs no keys — the dashboard matches events to a site by
+ * the domain they come from.
+ */
+export const oneDollarStats = (
+  options: OneDollarStatsOptions = {}
+): OneDollarStatsAdapter => ({
+  kind: "one-dollar-stats",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The deferred tag from the install instructions, with every option as its
+ * own `data-` attribute. The tracker reads them from `document.currentScript`,
+ * so the tag stays a classic external script. It hooks `pushState` and
+ * `popstate` itself, so client-router navigations need no extra hook.
+ *
+ * The tracker turns hash routing on whenever `data-hash-routing` is present,
+ * whatever its value, so `"hash-routing": "false"` leaves the attribute off.
+ */
+export const oneDollarStatsHead = (
+  options: OneDollarStatsOptions
+): HeadScript[] => {
+  const attributes: HeadScript["attributes"] = {};
+  for (const [setting, value] of Object.entries(options)) {
+    if (setting === "hash-routing" && value === "false") {
+      continue;
+    }
+    attributes[`data-${setting}`] = value;
+  }
+  attributes.defer = true;
+  attributes.src = ONE_DOLLAR_STATS_SCRIPT_SRC;
+  return [{ attributes, content: null }];
+};

package/src/analytics/schema.ts

@@ -14,6 +14,7 @@ import { hightouchAdapterSchema } from "./hightouch.ts";
 import { hotjarAdapterSchema } from "./hotjar.ts";
 import { logrocketAdapterSchema } from "./logrocket.ts";
 import { mixpanelAdapterSchema } from "./mixpanel.ts";
+import { oneDollarStatsAdapterSchema } from "./one-dollar-stats.ts";
 import { pirschAdapterSchema } from "./pirsch.ts";
 import { plausibleAdapterSchema } from "./plausible.ts";
 import { posthogAdapterSchema } from "./posthog.ts";
@@ -37,6 +38,7 @@ export const analyticsAdapterSchema = z.discriminatedUnion("kind", [
   hotjarAdapterSchema,
   logrocketAdapterSchema,
   mixpanelAdapterSchema,
+  oneDollarStatsAdapterSchema,
   pirschAdapterSchema,
   plausibleAdapterSchema,
   posthogAdapterSchema,

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");
@@ -1887,7 +1996,7 @@ export const generateRuntime = async (
   // `astro.config.mjs` — which would restart the dev server in place.
   const contentRoutes = markdownRoutePaths(project);
   const homeLinkHeader =
-    buildHomeLinkHeader(config, contentRoutes) ?? undefined;
+    buildHomeLinkHeader(config, contentRoutes, "dev") ?? undefined;
 
   const assistantEnabled = config.ai.assistant?.enabled ?? false;
   const exportPdf = config.export.pdf;
@@ -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/include-hmr.ts

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 
+import { resolve } from "pathe";
+
 import { refreshBlumeContent } from "./integration.ts";
 
 /**
@@ -18,12 +20,21 @@ import { refreshBlumeContent } from "./integration.ts";
  */
 
 /** The Vite module-graph slice the plugin touches (structurally typed, like
- * every Blume-authored Vite plugin — see `serverAppResolvePlugin`). */
+ * every Blume-authored Vite plugin — see `serverAppResolvePlugin`). Every
+ * environment keeps its own graph, and the server's own `moduleGraph` only
+ * covers `client` and `ssr`: with `@astrojs/cloudflare` the content pages
+ * render in the `prerender` environment instead. */
 interface IncludeHmrServer {
-  moduleGraph: {
-    getModulesByFile: (file: string) => Set<unknown> | undefined;
-    invalidateModule: (mod: never) => void;
-  };
+  config: { root: string };
+  environments: Record<
+    string,
+    {
+      moduleGraph: {
+        getModulesByFile: (file: string) => Set<unknown> | undefined;
+        invalidateModule: (mod: never) => void;
+      };
+    }
+  >;
   ws: { send: (payload: { type: "full-reload" }) => void };
 }
 
@@ -51,16 +62,24 @@ export const includeHmrPlugin = (graphPath: string): IncludeHmrPlugin => ({
       // No graph yet (first run) — nothing to invalidate.
       return;
     }
-    const includers = graph[ctx.file];
+    // An ejected app's graph is relative to the project, its Vite root; the
+    // hidden runtime's is absolute, which resolving leaves as it is.
+    const { config, environments, ws } = ctx.server;
+    const includers = Object.entries(graph).find(
+      ([partial]) => resolve(config.root, partial) === ctx.file
+    )?.[1];
     if (!includers || includers.length === 0) {
       return;
     }
-    const { moduleGraph, ws } = ctx.server;
-    for (const includer of includers) {
-      for (const mod of moduleGraph.getModulesByFile(includer) ?? []) {
-        // SAFETY: the module came out of this module graph; `never` only
-        // reflects that the structural slice doesn't model the node type.
-        moduleGraph.invalidateModule(mod as never);
+    for (const { moduleGraph } of Object.values(environments)) {
+      for (const includer of includers) {
+        for (const mod of moduleGraph.getModulesByFile(
+          resolve(config.root, includer)
+        ) ?? []) {
+          // SAFETY: the module came out of this module graph; `never` only
+          // reflects that the structural slice doesn't model the node type.
+          moduleGraph.invalidateModule(mod as never);
+        }
       }
     }
     // Plain `.md` pages have no Vite module: their HTML lives in the

package/src/astro/include-refresh.ts

@@ -29,7 +29,10 @@ type StoreEntry = ReturnType<LoaderContext["store"]["entries"]>[number][1];
 /** Meta-store key holding the recorded partials digest of an includer. */
 const stateKey = (id: string): string => `blume:include-state:${id}`;
 
-/** The generated include graph: absolute partial → absolute including pages. */
+/**
+ * The generated include graph: partial → including pages, absolute in the
+ * hidden runtime and relative to the project root in an ejected app.
+ */
 type IncludeGraph = Record<string, string[]>;
 
 /**
@@ -47,14 +50,22 @@ const readGraph = (graphPath: string): IncludeGraph => {
   }
 };
 
-/** Invert the graph: absolute including page → its partials, sorted. */
-const partialsByPage = (graph: IncludeGraph): Map<string, string[]> => {
+/**
+ * Invert the graph: absolute including page → its absolute partials, sorted.
+ * Each path resolves against the Astro root, which leaves the hidden runtime's
+ * absolute paths as they are.
+ */
+const partialsByPage = (
+  graph: IncludeGraph,
+  root: string
+): Map<string, string[]> => {
   const byPage = new Map<string, string[]>();
   for (const [partial, pages] of Object.entries(graph)) {
     for (const page of pages) {
-      const partials = byPage.get(page) ?? [];
-      partials.push(partial);
-      byPage.set(page, partials);
+      const abs = resolve(root, page);
+      const partials = byPage.get(abs) ?? [];
+      partials.push(resolve(root, partial));
+      byPage.set(abs, partials);
     }
   }
   for (const partials of byPage.values()) {
@@ -123,11 +134,11 @@ export const evictStaleIncluders = (
   context: LoaderContext,
   graphPath: string
 ): string[] => {
-  const byPage = partialsByPage(readGraph(graphPath));
+  const root = fileURLToPath(context.config.root);
+  const byPage = partialsByPage(readGraph(graphPath), root);
   if (byPage.size === 0) {
     return [];
   }
-  const root = fileURLToPath(context.config.root);
   const evicted: string[] = [];
   for (const [id, entry] of context.store.entries()) {
     if (evictIfStale(context, byPage, root, id, entry)) {

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,