blume 1.7.2 → 2.0.0

package/src/ai/llms.ts

@@ -6,9 +6,11 @@ import { absoluteUrl } from "../core/site-url.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { NavNode, Navigation, PageRecord } from "../core/types.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
+import { AI_CATALOG_PATH, hasAiCatalog } from "./ai-catalog.ts";
 import { API_CATALOG_PATH, hasApiCatalog } from "./api-catalog.ts";
 import { API_PAGES_PATH, OPENAPI_PATH } from "./api/paths.ts";
 import { downlevelComponents } from "./component-markdown.ts";
+import { relativeLinkRewriter } from "./relative-links.ts";
 import { projectComponentSerializers } from "./serializers.ts";
 import { AGENT_SKILLS_DIR, AGENT_SKILLS_INDEX_PATH } from "./skills.ts";
 import type { SkillArtifact } from "./skills.ts";
@@ -48,24 +50,24 @@ const oneLine = (text: string): string => text.replaceAll(/\s+/gu, " ").trim();
  */
 const agentResourceLines = (project: BlumeProject): string[] => {
   const { config } = project;
-  const { site } = config.deployment;
+  const { site } = config.deployment.options;
   const url = (path: string): string =>
-    pageUrl(path, site, normalizeBasePath(config.deployment.base));
+    pageUrl(path, site, normalizeBasePath(config.deployment.options.base));
   const lines = [
     `- [llms-full.txt](${url("/llms-full.txt")}): The full Markdown of every page in one file.`,
     `- [Page Markdown](${url("/index.md")}): Append \`.md\` to any page URL to fetch that page as raw Markdown.`,
   ];
-  if (config.ai.api) {
+  if (config.agents.api) {
     lines.push(
       `- [JSON API](${url(API_PAGES_PATH)}): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at ${url(OPENAPI_PATH)}.`
     );
   }
-  if (config.ai.mcp.enabled) {
+  if (config.agents.mcp.enabled) {
     lines.push(
-      `- [MCP server](${url(config.ai.mcp.route)}): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: ${url("/.well-known/mcp.json")}`
+      `- [MCP server](${url(config.agents.mcp.route)}): Streamable HTTP Model Context Protocol server with search_docs, get_page, list_pages, and get_navigation tools, plus every page as a resource. Discovery document: ${url("/.well-known/mcp.json")}`
     );
   }
-  if (config.ai.skills) {
+  if (config.agents.skills) {
     lines.push(
       `- [Agent skills](${url(AGENT_SKILLS_INDEX_PATH)}): Agent Skills discovery index of the skills this site publishes.`
     );
@@ -75,7 +77,12 @@ const agentResourceLines = (project: BlumeProject): string[] => {
       `- [API catalog](${url(API_CATALOG_PATH)}): RFC 9727 linkset of the APIs documented here.`
     );
   }
-  if (config.seo.agentReadability) {
+  if (hasAiCatalog(config)) {
+    lines.push(
+      `- [AI catalog](${url(AI_CATALOG_PATH)}): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).`
+    );
+  }
+  if (config.agents.agentReadability) {
     lines.push(
       `- [agent-readability.json](${url("/agent-readability.json")}): Manifest of every agent-facing artifact on this site.`
     );
@@ -90,7 +97,7 @@ const agentResourceLines = (project: BlumeProject): string[] => {
 
 // Drafts, hidden, and ordinary `noindex` pages are excluded. Generated API
 // references keep crawler visibility (`noindex`) separate from LLM visibility
-// (`ai.exclude`), and are excluded wholesale when `ai.llmsTxt.openapi` is off.
+// (`ai.exclude`), and are excluded wholesale when `agents.llmsTxt.openapi` is off.
 // `versions: "current"` additionally drops archived-snapshot pages — the flat
 // llms-full.txt dump serves agents the live docs, not every frozen copy.
 const eligiblePages = (
@@ -106,7 +113,7 @@ const eligiblePages = (
         (page.meta.seo.noindex && page.source.name !== "openapi") ||
         (options.versions === "current" && page.version !== "")
       ) &&
-      (project.config.ai.llmsTxt.openapi || page.source.name !== "openapi")
+      (project.config.agents.llmsTxt.openapi || page.source.name !== "openapi")
   );
 
 /**
@@ -160,8 +167,8 @@ export const buildLlmsIndex = (
   options: LlmsIndexOptions = {}
 ): string => {
   const { config } = project;
-  const { site } = config.deployment;
-  const base = normalizeBasePath(config.deployment.base);
+  const { site } = config.deployment.options;
+  const base = normalizeBasePath(config.deployment.options.base);
   const eligible = eligiblePages(project);
   const byRoute = new Map(eligible.map((page) => [page.route, page]));
   const seen = new Set<string>();
@@ -279,7 +286,7 @@ export const buildLlmsIndex = (
     : `# ${config.title}`;
   // `details` is the llms.txt spec's free-form block between the summary and
   // the file sections — "when to use this" guidance in the site's own words.
-  const { details } = config.ai.llmsTxt;
+  const { details } = config.agents.llmsTxt;
   const lead = details ? `${header}\n\n${details}` : header;
   return `${[lead, ...blocks].join("\n\n")}\n`;
 };
@@ -291,6 +298,7 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
     (a, b) => a.route.localeCompare(b.route)
   );
   const components = projectComponentSerializers(project);
+  const rewriteLinks = relativeLinkRewriter(project);
 
   const sections = await Promise.all(
     pages.map(async (page) => {
@@ -299,11 +307,14 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       // llms-full.txt; point them at the served originals instead.
       if (page.sourcePath) {
         raw = rewriteRelativeImages({
-          deployBase: config.deployment.base,
+          deployBase: config.deployment.options.base,
           projectRoot: project.context.root,
           source: raw,
           sourcePath: page.sourcePath,
         });
+        // Relative page links too: a reader of one flat file has no page URL
+        // to resolve `./install` against.
+        raw = rewriteLinks(raw, page);
       }
       // Resolve `<Visibility>` audiences (web-only content omitted from the
       // agent-facing output, agents-only unwrapped), then downlevel supported
@@ -316,8 +327,8 @@ const buildFull = async (project: BlumeProject): Promise<string> => {
       ).trim();
       const url = pageUrl(
         page.route,
-        config.deployment.site,
-        normalizeBasePath(config.deployment.base)
+        config.deployment.options.site,
+        normalizeBasePath(config.deployment.options.base)
       );
       return [`# ${page.title}`, `Source: ${url}`, "", body].join("\n");
     })

package/src/ai/markdown.ts

@@ -1,12 +1,17 @@
 import { readFile } from "node:fs/promises";
 
+import { hasGeneratedChangelog } from "../astro/pages.ts";
+import { CHANGELOG_INDEX_ROUTE } from "../core/changelog-index.ts";
 import { rewriteRelativeImages } from "../core/content-assets.ts";
+import { discoverPages, discoverPagesSync } from "../core/custom-pages.ts";
 import matter from "../core/frontmatter.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { readExpandedEntryText } from "../core/sources/read.ts";
 import type { RouteManifestEntry } from "../core/types.ts";
+import { buildChangelogIndexMarkdown } from "./changelog-markdown.ts";
 import { downlevelComponents } from "./component-markdown.ts";
 import { buildLlmsIndex } from "./llms.ts";
+import { relativeLinkRewriter } from "./relative-links.ts";
 import { projectComponentSerializers } from "./serializers.ts";
 import { applyAgentVisibility } from "./visibility.ts";
 
@@ -46,7 +51,8 @@ export const markdownTokenCount = (text: string): number =>
  * removed, agents-only unwrapped. Relative image references are rewritten to
  * their served `/blume-assets/content/…` URLs in both variants too — an agent
  * fetches these endpoints by URL, where a colocated `./diagram.png` resolves
- * to nothing.
+ * to nothing — and relative page links to the routes they mean, as the
+ * rendered page's are (see `relative-links.ts`).
  */
 export const buildRawMarkdown = async (
   project: BlumeProject
@@ -54,6 +60,7 @@ export const buildRawMarkdown = async (
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
   const components = projectComponentSerializers(project);
+  const rewriteLinks = relativeLinkRewriter(project);
 
   const readRoute = async (route: RouteManifestEntry): Promise<string> => {
     const page = pageById.get(route.id);
@@ -68,11 +75,17 @@ export const buildRawMarkdown = async (
       let text = await readRoute(route);
       if (route.sourcePath) {
         text = rewriteRelativeImages({
-          deployBase: project.config.deployment.base,
+          deployBase: project.config.deployment.options.base,
           projectRoot: project.context.root,
           source: text,
           sourcePath: route.sourcePath,
         });
+        // `./install` means the page's sibling, not whatever the `.md` URL
+        // an agent fetched resolves it to.
+        text = rewriteLinks(text, {
+          route: route.path,
+          sourcePath: route.sourcePath,
+        });
       }
       const source = applyAgentVisibility(text);
       // The `.md` variant keeps the front-matter block in the output, but its
@@ -92,18 +105,35 @@ export const buildRawMarkdown = async (
   if (!map["/"]) {
     map["/"] = { mdx: buildLlmsIndex(project) };
   }
+  // The generated changelog index has no source either; its release list is
+  // its mirror, so `/changelog.md` and `get_page` answer as the page does.
+  const userPages = project.context.pagesRoot
+    ? await discoverPages(project.context.pagesRoot)
+    : [];
+  if (hasGeneratedChangelog(project, userPages)) {
+    map[CHANGELOG_INDEX_ROUTE] = { mdx: buildChangelogIndexMarkdown(project) };
+  }
   return map;
 };
 
 /**
  * Every route path with a raw-Markdown mirror: the manifest routes, plus the
- * homepage when its mirror is the synthesized llms.txt fallback (see
- * `buildRawMarkdown`). This is the route list the negotiation surfaces (dev
+ * homepage when its mirror is the synthesized llms.txt fallback and the
+ * generated changelog index (see `buildRawMarkdown`). This is the route list the negotiation surfaces (dev
  * middleware, Vercel routing config) and the homepage `Link` header build
  * from, so `Accept: text/markdown` on `/` resolves even when the homepage is
  * a landing page.
  */
 export const markdownRoutePaths = (project: BlumeProject): string[] => {
   const paths = project.manifest.routes.map((route) => route.path);
-  return paths.includes("/") ? paths : [...paths, "/"];
+  if (!paths.includes("/")) {
+    paths.push("/");
+  }
+  const userPages = project.context.pagesRoot
+    ? discoverPagesSync(project.context.pagesRoot)
+    : [];
+  if (hasGeneratedChangelog(project, userPages)) {
+    paths.push(CHANGELOG_INDEX_ROUTE);
+  }
+  return paths;
 };

package/src/ai/mcp/data.ts

@@ -88,8 +88,12 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
   const pageById = new Map(graph.pages.map((page) => [page.id, page]));
 
   const routes: McpRoute[] = [];
+  // Fallback routes render the fallback locale's page at another locale's
+  // URL: listing them would pass that page off as a translation, once per
+  // locale. `get_page` still resolves them through `pages`, as llms.txt and
+  // search leave them out.
   for (const route of manifest.routes) {
-    if (route.hidden) {
+    if (route.hidden || route.fallback) {
       continue;
     }
     const page = pageById.get(route.id);
@@ -111,7 +115,7 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
   }
 
   const data: McpData = {
-    base: normalizeBasePath(config.deployment.base),
+    base: normalizeBasePath(config.deployment.options.base),
     defaultLocale: config.i18n?.defaultLocale,
     documents: documents.map((doc) => {
       const document: OramaDoc = {
@@ -128,12 +132,12 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
       }
       return document;
     }),
-    instructions: config.ai.mcp.instructions,
-    name: config.ai.mcp.name ?? config.title,
+    instructions: config.agents.mcp.instructions,
+    name: config.agents.mcp.name ?? config.title,
     navigation: graph.navigation,
     pages,
     routes,
-    site: config.deployment.site ?? null,
+    site: config.deployment.options.site ?? null,
     version: manifest.blumeVersion,
   };
   if (config.versions) {

package/src/ai/mcp/discovery.ts

@@ -56,7 +56,7 @@ const truncate = (text: string): string =>
 const NON_ASCII_SLUG = /[^a-z0-9]+/gu;
 const COMBINING_MARKS = /\p{M}+/gu;
 
-const asciiSlugify = (text: string): string =>
+export const asciiSlugify = (text: string): string =>
   trimChar(
     text
       .normalize("NFKD")

package/src/ai/openapi-components.ts

@@ -1,5 +1,6 @@
 import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
 import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
+import { asSentence } from "../openapi/sentence.ts";
 import { operationSignature } from "../openapi/signature.ts";
 import type {
   ComponentMarkdown,
@@ -25,7 +26,9 @@ const listItem = (
   operation: Pick<ApiOperationRef, "deprecated" | "route" | "summary">
 ): string => {
   const tail = [
-    inlineText(operation.summary),
+    // Title-like summaries ("Get a flag") need their own period before the
+    // "Deprecated." that may follow.
+    inlineText(asSentence(operation.summary.trim())),
     operation.deprecated ? "Deprecated." : "",
   ]
     .filter(Boolean)

package/src/ai/relative-links.ts

@@ -0,0 +1,170 @@
+import { basename } from "pathe";
+
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { nextFenceState } from "../core/code-fences.ts";
+import type { FenceState } from "../core/code-fences.ts";
+import {
+  buildFileRouteIndex,
+  isIndexFileName,
+  resolveRelativeHref,
+  routeOfLinkedFile,
+} from "../core/links.ts";
+import type { RelativeLinkBase } from "../core/links.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+import { extractLinks } from "../core/sources/normalize.ts";
+
+/**
+ * Relative page links on the agent surfaces — the `.md`/`.mdx` mirrors,
+ * llms-full.txt, MCP `get_page` and `resources/read`. An agent resolves
+ * `[Install](./install)` against the URL it fetched (`/guides.md`), so the
+ * link lands on `/install`; the rendered page rewrites it to the route it
+ * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
+ * the same rewrite from the same resolver (`resolveRelativeHref`), so both
+ * point at one page. Inline links and reference definitions are rewritten;
+ * fenced and inline code, images, and anything not a relative page link are
+ * left as written.
+ */
+
+/** The page a Markdown text was written for. */
+export interface LinkedPage {
+  route: string;
+  sourcePath?: string;
+}
+
+/** Rewrite a page's relative page links to the routes they mean. */
+export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
+
+/** A reference definition's target: `[label]: ./install` or `<./install>`. */
+const DEFINITION =
+  /^(?<lead> {0,3}\[(?:[^\]\\]|\\.)+\]:[\t ]*)(?:<(?<angled>[^>]*)>|(?<bare>\S+))/u;
+
+/**
+ * Whether a text could hold a relative page link at all: an inline link, a
+ * reference definition, or a component `href` whose target isn't a URL with
+ * a scheme, a root path, or a fragment. Most pages hold none, and those skip
+ * the link parse and the line-by-line fence scan entirely.
+ */
+const MAYBE_RELATIVE =
+  /\]\([\t ]*<?(?![a-z][\d+.a-z-]*:|\/|#)|^ {0,3}\[[^\]\n]+\]:[\t ]*<?(?![a-z][\d+.a-z-]*:|\/|#)|\shref=["'](?![a-z][\d+.a-z-]*:|\/|#)/imu;
+
+interface Splice {
+  column: number;
+  length: number;
+  text: string;
+}
+
+/** Apply same-line splices, right to left so earlier columns stay valid. */
+const spliceLine = (line: string, splices: readonly Splice[]): string => {
+  let out = line;
+  for (const splice of splices.toSorted((a, b) => b.column - a.column)) {
+    out =
+      out.slice(0, splice.column) +
+      splice.text +
+      out.slice(splice.column + splice.length);
+  }
+  return out;
+};
+
+/** One line's reference-definition splice, when it defines a routed target. */
+const definitionSplice = (
+  line: string,
+  routed: (target: string) => string | undefined
+): Splice | undefined => {
+  const groups = DEFINITION.exec(line)?.groups;
+  const lead = groups?.lead;
+  const target = groups?.angled ?? groups?.bare;
+  const route = target === undefined ? undefined : routed(target);
+  if (lead === undefined || target === undefined || route === undefined) {
+    return undefined;
+  }
+  // An angle-bracketed target starts one past its `<`.
+  const angled = groups?.angled === undefined ? 0 : 1;
+  return { column: lead.length + angled, length: target.length, text: route };
+};
+
+/** Every routed splice in `text`, by 0-based line: links, then definitions. */
+const collectSplices = (
+  text: string,
+  lines: readonly string[],
+  routed: (target: string) => string | undefined
+): Map<number, Splice[]> => {
+  const splices = new Map<number, Splice[]>();
+  const add = (index: number, splice: Splice): void => {
+    splices.set(index, [...(splices.get(index) ?? []), splice]);
+  };
+  for (const link of extractLinks(text)) {
+    const route = link.image ? undefined : routed(link.target);
+    if (route !== undefined) {
+      add(link.line - 1, {
+        column: link.column - 1,
+        length: link.target.length,
+        text: route,
+      });
+    }
+  }
+  let fence: FenceState = null;
+  for (const [index, line] of lines.entries()) {
+    const next = nextFenceState(line, fence);
+    const inFence = fence !== null || next !== null;
+    fence = next;
+    const splice = inFence ? undefined : definitionSplice(line, routed);
+    if (splice !== undefined) {
+      add(index, splice);
+    }
+  }
+  return splices;
+};
+
+/**
+ * Build the rewriter for a project: the file → route lookup a `.md`/`.mdx`
+ * link resolves through is built once. A file shared by every locale
+ * publishes once per locale, and the default locale's route stands for it;
+ * fallback copies render another locale's file, so they never stand for one.
+ */
+export const relativeLinkRewriter = (
+  project: BlumeProject
+): RelativeLinkRewriter => {
+  const { deployment, i18n } = project.config;
+  const deployBase = normalizeBasePath(deployment.options.base);
+  const localeTokens = i18n
+    ? ["$", ...i18n.locales.map((locale) => locale.code)]
+    : [];
+  const fileRoutes = buildFileRouteIndex(project.graph.pages, i18n ?? null);
+  const navPathBySource = new Map(
+    project.graph.pages.map((graphPage) => [
+      graphPage.sourcePath,
+      graphPage.navPath,
+    ])
+  );
+  const routes = new Set(project.manifest.routes.map((route) => route.path));
+
+  return (text, page) => {
+    const { sourcePath } = page;
+    if (!sourcePath || !MAYBE_RELATIVE.test(text)) {
+      return text;
+    }
+    const from: RelativeLinkBase = {
+      isIndex: isIndexFileName(basename(sourcePath), localeTokens),
+      route: page.route,
+    };
+    const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
+    const resolveFile = (path: string): string | undefined =>
+      routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
+    const routed = (target: string): string | undefined => {
+      const route = resolveRelativeHref(target, from, resolveFile, (path) =>
+        routes.has(path)
+      );
+      return route === undefined ? undefined : withBasePath(deployBase, route);
+    };
+
+    const lines = text.split("\n");
+    const splices = collectSplices(text, lines, routed);
+
+    return lines
+      .map((line, index) => {
+        const lineSplices = splices.get(index);
+        return lineSplices ? spliceLine(line, lineSplices) : line;
+      })
+      .join("\n");
+  };
+};

package/src/ai/serializers.ts

@@ -8,7 +8,7 @@ import { openapiComponentSerializers } from "./openapi-components.ts";
  * Every serializer a project brings to a downlevel pass, layered once for all
  * the agent surfaces (`<route>.md`, llms-full.txt, the search and Ask AI
  * corpora): the built-in families that read project data — examples, then the
- * API reference — under the user's `ai.markdownComponents`, which is spread
+ * API reference — under the user's `agents.markdownComponents`, which is spread
  * last so an entry of the same name still wins. One layering, so a new family
  * or a new surface cannot leave one consumer printing raw JSX.
  */
@@ -20,5 +20,5 @@ export const projectComponentSerializers = (
     ...openapiComponentSerializers(
       project.sources.find(isOpenApiSource)?.openApiData() ?? {}
     ),
-    ...project.config.ai.markdownComponents,
+    ...project.config.agents.markdownComponents,
   }) satisfies Record<string, ComponentMarkdown>;

package/src/ai/skills.ts

@@ -201,7 +201,7 @@ export const buildSkillsIndex = (
   skills: readonly SkillArtifact[],
   config: ResolvedConfig
 ): string => {
-  const deployBase = normalizeBasePath(config.deployment.base);
+  const deployBase = normalizeBasePath(config.deployment.options.base);
   const index = {
     $schema: AGENT_SKILLS_SCHEMA,
     skills: skills.map((skill) => ({

package/src/ai/web-bot-auth.ts

@@ -4,7 +4,7 @@ import type { ResolvedConfig } from "../core/schema.ts";
  * Web Bot Auth (IETF `webbotauth` WG): an org that runs agents publishes the
  * agents' HTTP Message Signature public keys in a JWKS at a well-known path
  * on its domain; sites receiving the signed requests fetch it to verify them.
- * Blume publishes the directory from `ai.webBotAuth.keys` — the schema admits
+ * Blume publishes the directory from `agents.webBotAuth.keys` — the schema admits
  * public keys only, so the site can never leak signing credentials.
  */
 
@@ -22,7 +22,7 @@ export const SIGNATURES_DIRECTORY_TYPE =
 export const buildSignaturesDirectory = (
   config: ResolvedConfig
 ): string | null => {
-  const { keys } = config.ai.webBotAuth;
+  const { keys } = config.agents.webBotAuth;
   if (keys.length === 0) {
     return null;
   }

package/src/analytics/adobe.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+
+/** Options for {@link adobe}. */
+export interface AdobeOptions {
+  /**
+   * The Launch (Adobe Experience Platform Tags) embed script URL for the
+   * environment to load, e.g. `https://assets.adobedtm.com/…/launch-….min.js`.
+   */
+  url: string;
+}
+
+export const adobeOptionsSchema = z.strictObject({
+  url: z.string().min(1),
+});
+
+export type AdobeAdapter = AdapterDescriptor<"adobe", AdobeOptions>;
+
+export const adobeAdapterSchema = adapterDescriptorSchema(
+  "adobe",
+  adobeOptionsSchema
+);
+
+/**
+ * Adobe Analytics through a Launch property: Blume loads the environment's
+ * embed script, and the property's own rules decide what to track. Copy the
+ * URL from the environment's install instructions in Data Collection.
+ */
+export const adobe = (options: AdobeOptions): AdobeAdapter => ({
+  kind: "adobe",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The async embed tag, as Launch's install instructions render it. Pageviews
+ * on client-router navigations are the property's business: give it a rule on
+ * history changes (or `_satellite.track` from a `script()` adapter).
+ */
+export const adobeHead = (options: AdobeOptions): HeadScript[] => [
+  { attributes: { async: true, src: options.url }, content: null },
+];

package/src/analytics/amplitude.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+import { inlineJson } from "./inline.ts";
+
+/** The options {@link amplitude} maps itself. */
+export interface AmplitudeNamedOptions {
+  /** Project API key. */
+  key: string;
+}
+
+/**
+ * Options for {@link amplitude}: the key plus any other Browser SDK
+ * `amplitude.init` option, forwarded verbatim (`serverZone`, `autocapture`,
+ * `defaultTracking`, …). JSON values only.
+ */
+export type AmplitudeOptions = AmplitudeNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export const amplitudeOptionsSchema = z
+  .object({
+    key: z.string().min(1),
+  })
+  .catchall(z.json());
+
+export type AmplitudeAdapter = AdapterDescriptor<"amplitude", AmplitudeOptions>;
+
+export const amplitudeAdapterSchema = adapterDescriptorSchema(
+  "amplitude",
+  amplitudeOptionsSchema
+);
+
+/**
+ * Amplitude product analytics through the Browser SDK's script loader. The
+ * project API key is public — it's what every browser event carries.
+ */
+export const amplitude = (options: AmplitudeOptions): AmplitudeAdapter => ({
+  kind: "amplitude",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/** The script loader's CDN; the key picks the bundle. */
+export const AMPLITUDE_SCRIPT_ORIGIN = "https://cdn.amplitude.com/script/";
+
+/**
+ * The init options the dashboard snippet ships with. `autocapture` covers page
+ * views, sessions, and history changes, so client-router navigations count
+ * without any extra hook; a passthrough option overrides either.
+ */
+export const AMPLITUDE_DEFAULT_INIT = {
+  autocapture: true,
+  fetchRemoteConfig: true,
+};
+
+/**
+ * The two tags from the dashboard's install snippet: the keyed SDK bundle
+ * (synchronous, so `window.amplitude` exists for the next tag) and the init
+ * call, with `key` mapped and everything else forwarded to `init` verbatim.
+ */
+export const amplitudeHead = (options: AmplitudeOptions): HeadScript[] => {
+  const { key, ...init } = options;
+  return [
+    {
+      attributes: {
+        src: `${AMPLITUDE_SCRIPT_ORIGIN}${encodeURIComponent(key)}.js`,
+      },
+      content: null,
+    },
+    {
+      attributes: {},
+      content: `window.amplitude.init(${inlineJson(key)},${inlineJson({ ...AMPLITUDE_DEFAULT_INIT, ...init })});`,
+    },
+  ];
+};

package/src/analytics/clarity.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+import { inlineJson } from "./inline.ts";
+
+/** Options for {@link clarity}. */
+export interface ClarityOptions {
+  /** Project ID, from the project's tracking code in the Clarity dashboard. */
+  id: string;
+}
+
+export const clarityOptionsSchema = z.strictObject({
+  id: z.string().min(1),
+});
+
+export type ClarityAdapter = AdapterDescriptor<"clarity", ClarityOptions>;
+
+export const clarityAdapterSchema = adapterDescriptorSchema(
+  "clarity",
+  clarityOptionsSchema
+);
+
+/**
+ * Microsoft Clarity session recordings and heatmaps. The project ID is public;
+ * it only picks the project the tag reports to.
+ */
+export const clarity = (options: ClarityOptions): ClarityAdapter => ({
+  kind: "clarity",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});
+
+/**
+ * The dashboard's tracking code: a `window.clarity` queue and the async tag
+ * load. Clarity follows history changes itself, so client-router navigations
+ * need no extra hook.
+ */
+export const clarityHead = (options: ClarityOptions): HeadScript[] => [
+  {
+    attributes: {},
+    content: `(function(c,l,a,r,i,t,y){c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);})(window,document,"clarity","script",${inlineJson(encodeURIComponent(options.id))});`,
+  },
+];