blume 1.7.2 → 2.0.0

package/dist/types/ai/mcp/tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Static metadata for the MCP tools Blume exposes. Shared by the server (which
+ * pairs each entry with a Zod input schema and handler) and the `.well-known`
+ * discovery documents, so tool names and descriptions never drift between the
+ * live server and its advertised capabilities.
+ */
+export interface McpToolMeta {
+    annotations: {
+        openWorldHint: boolean;
+        readOnlyHint: boolean;
+    };
+    description: string;
+    name: string;
+    title: string;
+}
+export declare const MCP_TOOLS: McpToolMeta[];

package/dist/types/ai/openapi-components.d.ts

@@ -0,0 +1,43 @@
+import type { OpenApiData } from "../openapi/model.ts";
+/**
+ * Agent-facing Markdown for the components a generated reference page is made
+ * of: `<Operation>`, `<ApiTagOperations>` and `<ApiOverview>`.
+ *
+ * `render-mdx.ts` builds each reference page as the operation's description in
+ * the body plus one of these components, deliberately: the structured UI is the
+ * component's job, and the prose stays Markdown so it indexes. That split is
+ * right for the rendered page and lossy everywhere else — `<route>.md`,
+ * llms-full.txt, MCP `get_page` and the Ask AI corpus all downlevel components
+ * to Markdown, and these three had no serializer, so an operation page reached
+ * an agent as its description followed by a bare tag. On a site whose reference
+ * is most of the corpus, that is most of the corpus: measured on one 449-page
+ * site, 266 pages and 266 raw `<Operation>` in llms-full.txt, so "which
+ * endpoint do I call?" had no answer anywhere in the agent surface.
+ *
+ * Each serializer emits what its component renders and no more: the endpoint
+ * in the spec kind's own notation ({@link operationSignature}), the version and
+ * addresses the overview shows ({@link specAddresses}), the linked list a tag
+ * section shows. Parameters, schemas and responses are deliberately left out:
+ * those are `operation-model.ts` plus each component's own preparation, and a
+ * second implementation here would be free to disagree with the page. The
+ * endpoint and what it does is the part that was missing altogether.
+ *
+ * `specs` is the parsed `blume:openapi` data — empty when the project has no
+ * API reference, in which case every serializer declines.
+ */
+export declare const openapiComponentSerializers: (specs: OpenApiData) => {
+    /**
+     * The spec-level block at the top of the overview page: its version and
+     * where the API lives. The tag sections that follow are real Markdown
+     * headings over `<ApiTagOperations>`, so they downlevel on their own.
+     */
+    ApiOverview: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    /** One tag's operations, mirroring the list the rendered page shows. */
+    ApiTagOperations: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    /**
+     * One operation. Declines when the spec carries no such key — Blume's own
+     * fallback, which leaves the JSX visible rather than publishing a page that
+     * silently lost its endpoint.
+     */
+    Operation: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+};

package/dist/types/ai/relative-links.d.ts

@@ -0,0 +1,26 @@
+import type { BlumeProject } from "../core/project-graph.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;
+/**
+ * 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 declare const relativeLinkRewriter: (project: BlumeProject) => RelativeLinkRewriter;

package/dist/types/ai/serializers.d.ts

@@ -0,0 +1,15 @@
+import type { BlumeProject } from "../core/project-graph.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 `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.
+ */
+export declare const projectComponentSerializers: (project: Pick<BlumeProject, "config" | "examples" | "sources">) => {
+    ApiOverview: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    ApiTagOperations: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    Operation: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+    Component: ({ props }: import("./component-markdown.ts").ComponentMarkdownContext) => string | null;
+};

package/dist/types/ai/skills.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+/**
+ * Agent Skills discovery (Cloudflare's Agent Skills Discovery RFC v0.2.0):
+ * the skills a site publishes are enumerated in an index at
+ * `/.well-known/agent-skills/index.json`, each entry pointing at its artifact
+ * with a SHA-256 digest. A skill that is only a `SKILL.md` publishes the file
+ * verbatim (`type: "skill-md"`); a skill with supporting resources (scripts,
+ * references, assets) is bundled into a deterministic `.tar.gz`
+ * (`type: "archive"`) so its relative references resolve after unpacking.
+ */
+export declare const AGENT_SKILLS_DIR = "/.well-known/agent-skills";
+export declare const AGENT_SKILLS_INDEX_PATH = "/.well-known/agent-skills/index.json";
+/** One publishable skill artifact plus its index entry. */
+export interface SkillArtifact {
+    /** Raw bytes to publish (the digest is computed over exactly these). */
+    content: Uint8Array;
+    description: string;
+    /** `sha256:{hex}` digest of `content`. */
+    digest: string;
+    name: string;
+    /** Path under the agent-skills dir: `{name}/SKILL.md` or `{name}.tar.gz`. */
+    path: string;
+    type: "archive" | "skill-md";
+}
+export interface CollectedSkills {
+    skills: SkillArtifact[];
+    /** Human-readable reasons for anything skipped. */
+    warnings: string[];
+}
+/**
+ * Collect the publishable skills from a directory whose subdirectories each
+ * hold a `SKILL.md` (the layout `npx skills add` consumes). Subdirectories
+ * without one are ignored silently — the directory may hold other assets —
+ * while a present-but-invalid skill earns a warning so it isn't dropped
+ * behind the publisher's back.
+ */
+export declare const collectSkills: (dir: string) => Promise<CollectedSkills>;
+/**
+ * The discovery index (v0.2.0 schema). Artifact URLs are path-absolute under
+ * `deployment.base` — the RFC resolves them against the index origin.
+ */
+export declare const buildSkillsIndex: (skills: readonly SkillArtifact[], config: ResolvedConfig) => string;

package/dist/types/ai/tar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `.tar.gz` writer for agent-skill archives, on nanotar's ustar writer.
+ * Deterministic by construction — fixed mtime/uid/gid/owner attrs,
+ * caller-ordered entries, and Node's gzip header carries no timestamp — so a
+ * skill's archive digest only changes when its content does. That holds per
+ * machine: the tar bytes are portable, but zlib's compressed stream differs
+ * across architectures, so gzip-layer digests are not comparable across
+ * platforms.
+ */
+/** One regular file to archive. Paths are `/`-separated, relative, no `..`. */
+export interface TarEntry {
+    /** Raw file bytes. */
+    content: Uint8Array;
+    /** Preserve the owner-execute bit (e.g. a skill's scripts). */
+    executable?: boolean;
+    /** Archive-relative path, e.g. `SKILL.md` or `references/FORMS.md`. */
+    path: string;
+}
+/**
+ * Build a gzipped ustar archive of the given files, in the given order. Paths
+ * longer than the ustar `name` field or escaping the archive root throw to
+ * surface a programming error — nanotar would silently truncate an oversized
+ * name into a corrupt archive, so the validation stays here.
+ */
+export declare const buildTarGz: (entries: readonly TarEntry[]) => Uint8Array;

package/dist/types/ai/visibility.d.ts

@@ -0,0 +1,17 @@
+/** The audience an output surface serves — the component's two `for` values. */
+export type VisibilityAudience = "agents" | "web";
+/**
+ * Resolve `<Visibility>` blocks for one audience: blocks addressed to the
+ * other audience are removed entirely and blocks addressed to `audience` are
+ * unwrapped (tags dropped, body kept), matching what the Astro component
+ * renders on the web. Other `for` values (the component's default) are left
+ * untouched, and markdown with no matching blocks is returned byte-identical,
+ * so raw sources stay raw.
+ */
+export declare const applyAudienceVisibility: (markdown: string, audience: VisibilityAudience) => string;
+/**
+ * Resolve `<Visibility>` blocks for agent-facing Markdown (llms-full.txt, the
+ * `.md`/`.mdx` mirrors, MCP tools, Ask AI grounding): `for="web"` content is
+ * removed and `for="agents"` content is unwrapped.
+ */
+export declare const applyAgentVisibility: (markdown: string) => string;

package/dist/types/ai/web-bot-auth.d.ts

@@ -0,0 +1,16 @@
+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 `agents.webBotAuth.keys` — the schema admits
+ * public keys only, so the site can never leak signing credentials.
+ */
+/** Well-known path (draft-meunier-http-message-signatures-directory). */
+export declare const SIGNATURES_DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+/** The directory's registered media type — extensionless, so static hosts
+ * need an explicit Content-Type rule (see `deploy/headers.ts` and the Vercel
+ * `overrides` injection) to serve anything better than octet-stream. */
+export declare const SIGNATURES_DIRECTORY_TYPE = "application/http-message-signatures-directory+json";
+/** The JWKS document to publish, or null when no keys are configured. */
+export declare const buildSignaturesDirectory: (config: ResolvedConfig) => string | null;

package/dist/types/analytics/adobe.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import type { AdapterDescriptor } 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 declare const adobeOptionsSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strict>;
+export type AdobeAdapter = AdapterDescriptor<"adobe", AdobeOptions>;
+export declare const adobeAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"adobe">;
+    options: z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 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 declare const adobe: (options: AdobeOptions) => AdobeAdapter;
+/**
+ * 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 declare const adobeHead: (options: AdobeOptions) => HeadScript[];

package/dist/types/analytics/amplitude.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.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 declare const amplitudeOptionsSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type AmplitudeAdapter = AdapterDescriptor<"amplitude", AmplitudeOptions>;
+export declare const amplitudeAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"amplitude">;
+    options: z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Amplitude product analytics through the Browser SDK's script loader. The
+ * project API key is public — it's what every browser event carries.
+ */
+export declare const amplitude: (options: AmplitudeOptions) => AmplitudeAdapter;
+/** The script loader's CDN; the key picks the bundle. */
+export declare 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 declare const AMPLITUDE_DEFAULT_INIT: {
+    autocapture: boolean;
+    fetchRemoteConfig: boolean;
+};
+/**
+ * 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 declare const amplitudeHead: (options: AmplitudeOptions) => HeadScript[];

package/dist/types/analytics/clarity.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** Options for {@link clarity}. */
+export interface ClarityOptions {
+    /** Project ID, from the project's tracking code in the Clarity dashboard. */
+    id: string;
+}
+export declare const clarityOptionsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+export type ClarityAdapter = AdapterDescriptor<"clarity", ClarityOptions>;
+export declare const clarityAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"clarity">;
+    options: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Microsoft Clarity session recordings and heatmaps. The project ID is public;
+ * it only picks the project the tag reports to.
+ */
+export declare const clarity: (options: ClarityOptions) => ClarityAdapter;
+/**
+ * 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 declare const clarityHead: (options: ClarityOptions) => HeadScript[];

package/dist/types/analytics/clearbit.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** Options for {@link clearbit}. */
+export interface ClearbitOptions {
+    /** Publishable API key (`pk_…`). */
+    key: string;
+}
+export declare const clearbitOptionsSchema: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strict>;
+export type ClearbitAdapter = AdapterDescriptor<"clearbit", ClearbitOptions>;
+export declare const clearbitAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"clearbit">;
+    options: z.ZodObject<{
+        key: z.ZodString;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Clearbit's website tag (Reveal and the Clearbit tags it manages). The
+ * publishable key is meant for the browser.
+ */
+export declare const clearbit: (options: ClearbitOptions) => ClearbitAdapter;
+/** The tag origin; the key picks the tags bundle. */
+export declare const CLEARBIT_TAG_ORIGIN = "https://tag.clearbitscripts.com/v1/";
+/** The tag as Clearbit's install snippet renders it. */
+export declare const clearbitHead: (options: ClearbitOptions) => HeadScript[];

package/dist/types/analytics/cloudflare.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The beacon script Cloudflare's dashboard snippet loads. */
+export declare const CLOUDFLARE_BEACON_SRC = "https://static.cloudflareinsights.com/beacon.min.js";
+/** The options {@link cloudflare} maps itself. */
+export interface CloudflareNamedOptions {
+    /** Site token from the Web Analytics JS snippet (`data-cf-beacon`). */
+    token: string;
+}
+/**
+ * Options for {@link cloudflare}: the token plus any other `data-cf-beacon`
+ * setting, forwarded verbatim (`spa`, …). JSON values only.
+ */
+export type CloudflareOptions = CloudflareNamedOptions & {
+    [option: string]: JsonValue;
+};
+export declare const cloudflareOptionsSchema: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type CloudflareAdapter = AdapterDescriptor<"cloudflare", CloudflareOptions>;
+export declare const cloudflareAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"cloudflare">;
+    options: z.ZodObject<{
+        token: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Cloudflare Web Analytics in manual (JS snippet) mode, for a site Cloudflare
+ * doesn't proxy. A proxied zone with automatic RUM injection on needs no
+ * adapter at all — listing one there would count every pageview twice.
+ */
+export declare const cloudflare: (options: CloudflareOptions) => CloudflareAdapter;
+/**
+ * The beacon tag exactly as the dashboard's snippet renders it, with the whole
+ * option object as its `data-cf-beacon` JSON. The beacon tracks history
+ * changes itself, so client-router navigations need no extra hook.
+ */
+export declare const cloudflareHead: (options: CloudflareOptions) => HeadScript[];

package/dist/types/analytics/fathom.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The script Fathom's dashboard snippet loads. */
+export declare const FATHOM_SCRIPT_SRC = "https://cdn.usefathom.com/script.js";
+/** The options {@link fathom} maps itself. */
+export interface FathomNamedOptions {
+    /** Site ID, from the site's script settings. */
+    site: string;
+}
+/**
+ * Options for {@link fathom}: the site ID plus any other script setting,
+ * forwarded as a `data-` attribute on the tag (`spa` → `data-spa`,
+ * `"honor-dnt"` → `data-honor-dnt`, `"excluded-domains"`, `canonical`, …).
+ */
+export type FathomOptions = FathomNamedOptions & {
+    [setting: string]: string;
+};
+export declare const fathomOptionsSchema: z.ZodObject<{
+    site: z.ZodString;
+}, z.core.$catchall<z.ZodString>>;
+export type FathomAdapter = AdapterDescriptor<"fathom", FathomOptions>;
+export declare const fathomAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"fathom">;
+    options: z.ZodObject<{
+        site: z.ZodString;
+    }, z.core.$catchall<z.ZodString>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Fathom Analytics. The site ID is public — it's in the tag on every page.
+ */
+export declare const fathom: (options: FathomOptions) => FathomAdapter;
+/**
+ * The deferred tag from the dashboard, with `site` as `data-site` and every
+ * other option as its own `data-` attribute. Fathom only tracks history
+ * changes when the tag opts in, so `spa` defaults to `"auto"` — Blume's
+ * client router navigates without full loads — and an explicit `spa` wins.
+ */
+export declare const fathomHead: (options: FathomOptions) => HeadScript[];

package/dist/types/analytics/google-analytics.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The options {@link googleAnalytics} maps itself. */
+export interface GoogleAnalyticsNamedOptions {
+    /** Measurement ID of the GA4 web data stream (`G-…`). */
+    id: string;
+}
+/**
+ * Options for {@link googleAnalytics}: the measurement ID plus any other
+ * `gtag('config', …)` parameter, forwarded verbatim (`send_page_view`,
+ * `anonymize_ip`, `cookie_domain`, `debug_mode`, …). JSON values only.
+ */
+export type GoogleAnalyticsOptions = GoogleAnalyticsNamedOptions & {
+    [parameter: string]: JsonValue;
+};
+export declare const googleAnalyticsOptionsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type GoogleAnalyticsAdapter = AdapterDescriptor<"google-analytics", GoogleAnalyticsOptions>;
+export declare const googleAnalyticsAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"google-analytics">;
+    options: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Google Analytics 4 through the Google tag (`gtag.js`). The measurement ID is
+ * public; it names the data stream the tag reports to.
+ */
+export declare const googleAnalytics: (options: GoogleAnalyticsOptions) => GoogleAnalyticsAdapter;
+/** The Google tag loader; the measurement ID travels in its query string. */
+export declare const GOOGLE_TAG_SRC = "https://www.googletagmanager.com/gtag/js";
+/**
+ * The two tags from the data stream's install instructions: the async loader
+ * and the `dataLayer` bootstrap with the `config` call. Extra options ride on
+ * the `config` call, and it is emitted bare when there are none, exactly as
+ * the instructions print it. GA4's enhanced measurement counts history
+ * changes as page views by default, so client-router navigations need no
+ * extra hook here.
+ */
+export declare const googleAnalyticsHead: (options: GoogleAnalyticsOptions) => HeadScript[];

package/dist/types/analytics/google-tag-manager.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** Options for {@link googleTagManager}. */
+export interface GoogleTagManagerOptions {
+    /** Name of the data layer global the container reads. Defaults to `dataLayer`. */
+    dataLayer?: string;
+    /** Container ID (`GTM-…`). */
+    id: string;
+}
+export declare const googleTagManagerOptionsSchema: z.ZodObject<{
+    dataLayer: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export type GoogleTagManagerAdapter = AdapterDescriptor<"google-tag-manager", GoogleTagManagerOptions>;
+export declare const googleTagManagerAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"google-tag-manager">;
+    options: z.ZodObject<{
+        dataLayer: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Google Tag Manager. Blume loads the container; which tags fire, and on what,
+ * is the container's configuration. The container ID is public.
+ */
+export declare const googleTagManager: (options: GoogleTagManagerOptions) => GoogleTagManagerAdapter;
+/**
+ * The container snippet from the workspace's install instructions (the
+ * `<head>` half; the `<noscript>` iframe is for browsers without JavaScript,
+ * which never run analytics anyway). Client-router navigations reach the
+ * container as history changes — fire pageview tags from a History Change
+ * trigger rather than the page-load one. The snippet also keeps a reference
+ * to its data layer on `window.__blumeGtmLayer`, so `track()` pushes custom
+ * events into the layer this container reads rather than the default
+ * `dataLayer`.
+ */
+export declare const googleTagManagerHead: (options: GoogleTagManagerOptions) => HeadScript[];

package/dist/types/analytics/head.d.ts

@@ -0,0 +1,30 @@
+import type { AnalyticsAdapter } from "./schema.ts";
+import type { VercelOptions } from "./vercel.ts";
+/** One `<script>` tag an adapter emits into `<head>`. */
+export interface HeadScript {
+    /**
+     * Attributes on the tag, including `src` for an external script. `true`
+     * renders a bare boolean attribute (`async`, `defer`).
+     */
+    attributes: Record<string, string | boolean>;
+    /** Inline body, or `null` for an external script. */
+    content: string | null;
+}
+/**
+ * One thing `Analytics.astro` renders, in the adapters' declared order. Vercel
+ * is the one adapter that renders a component rather than a tag: the official
+ * component injects the first-party script and resolves the deployment's base
+ * path itself, so it travels as its props.
+ */
+export type HeadNode = (HeadScript & {
+    type: "script";
+}) | {
+    props: VercelOptions;
+    type: "vercel";
+};
+/**
+ * Map the configured adapters to what `Analytics.astro` renders, in declared
+ * order. A second `vercel()` is dropped — two copies of the component would
+ * count every pageview twice — so the first one keeps its position.
+ */
+export declare const analyticsHead: (adapters: AnalyticsAdapter[]) => HeadNode[];

package/dist/types/analytics/heap.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The options {@link heap} maps itself. */
+export interface HeapNamedOptions {
+    /** App ID (the environment ID), from the project's install settings. */
+    id: string;
+}
+/**
+ * Options for {@link heap}: the app ID plus any other `heap.load` config
+ * option, forwarded verbatim (`disableTextCapture`, `secureCookie`, …). JSON
+ * values only.
+ */
+export type HeapOptions = HeapNamedOptions & {
+    [option: string]: JsonValue;
+};
+export declare const heapOptionsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type HeapAdapter = AdapterDescriptor<"heap", HeapOptions>;
+export declare const heapAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"heap">;
+    options: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Heap autocapture analytics. The app ID is public — the tag carries it on
+ * every page.
+ */
+export declare const heap: (options: HeapOptions) => HeapAdapter;
+/**
+ * The loader plus `heap.load` with `id` mapped and everything else forwarded
+ * as the config object; the object is left off when there is nothing to pass,
+ * as the install snippet prints it. Heap autocaptures history changes as
+ * pageviews, so client-router navigations need no extra hook.
+ */
+export declare const heapHead: (options: HeapOptions) => HeadScript[];

package/dist/types/analytics/hightouch.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import type { HeadScript } from "./head.ts";
+/** The events API host `hightouch()` uses when `host` is unset. */
+export declare const HIGHTOUCH_DEFAULT_HOST = "us-east-1.hightouch-events.com";
+/** The options {@link hightouch} maps itself. */
+export interface HightouchNamedOptions {
+    /** Events API host, without a scheme. Defaults to the US East region. */
+    host?: string;
+    /** Write key of the event source. */
+    key: string;
+}
+/**
+ * Options for {@link hightouch}: the named options plus any other
+ * `htevents.load` option, forwarded verbatim. JSON values only.
+ */
+export type HightouchOptions = HightouchNamedOptions & {
+    [option: string]: JsonValue;
+};
+export declare const hightouchOptionsSchema: z.ZodObject<{
+    host: z.ZodOptional<z.ZodString>;
+    key: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+export type HightouchAdapter = AdapterDescriptor<"hightouch", HightouchOptions>;
+export declare const hightouchAdapterSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"hightouch">;
+    options: z.ZodObject<{
+        host: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Hightouch Events. The write key is meant for the browser — it identifies
+ * the event source the SDK reports to.
+ */
+export declare const hightouch: (options: HightouchOptions) => HightouchAdapter;
+/**
+ * The loader with `key` mapped to the write key and `host` to `apiHost`;
+ * everything else lands in the load options verbatim, after the mapped host
+ * so a raw `apiHost` still wins.
+ */
+export declare const hightouchHead: (options: HightouchOptions) => HeadScript[];