@getvitops/astro 8.1.0 → 8.2.0-alpha.0

package/src/ads.ts

@@ -25,7 +25,13 @@
  * Everything decidable is here and unit-tested; `Ads.astro` renders what this
  * returns and chooses nothing.
  */
-import { AD_PLATFORMS, AD_PROVIDER_KEYS, type AdProvider } from '@getvitops/utils/ads';
+import {
+  AD_PLATFORMS,
+  AD_PROVIDER_KEYS,
+  normalizeConversionLabels,
+  type AdProvider,
+  type ConversionLabelMap,
+} from '@getvitops/utils/ads';
 import type { AnalyticsStrategy, ConsentCategory, GatedTag } from './analytics.ts';
 
 /**
@@ -38,7 +44,15 @@ import type { AnalyticsStrategy, ConsentCategory, GatedTag } from './analytics.t
 export interface GetvitopsAdProperty {
   accountId?: string;
   pixelId?: string;
-  conversionLabel?: string;
+  /**
+   * Google Ads only: the conversion action label(s) paired with `pixelId` (the
+   * `AW-…` conversion id) — a bare string (back-compat, treated as `call`) or a
+   * map of action → label. `<Tracking />`'s tel:/mailto: click handler and
+   * `vitopsFormConversion()` each fire `gtag('event', 'conversion', …)` for
+   * their own action at the moment of the interaction — see `gtagBootstrap` in
+   * `@getvitops/utils/ads`.
+   */
+  conversionLabel?: string | ConversionLabelMap;
   /** Default `marketing`. `analytics` for a property used purely for measurement. */
   category?: 'marketing' | 'analytics';
   /** False keeps the property on record without emitting its tag. */
@@ -113,6 +127,35 @@ export function resolveAds(
       continue;
     }
 
+    // `conversionLabel` lands inside the same inline `<script>` as `id` (Google's
+    // bootstrap embeds it to expose a conversion `send_to` target per action) —
+    // same injection surface, so every configured label gets the same check.
+    // Unlike an invalid `id`, an invalid label doesn't sink the whole tag: it
+    // just means that one action's conversion doesn't fire, which is worth a
+    // warning rather than dropping every other configured action too.
+    let safeEntry = entry;
+    const labels = normalizeConversionLabels(entry.conversionLabel);
+    const invalidActions = Object.entries(labels)
+      .filter(([, label]) => label && !SAFE_ID.test(label))
+      .map(([action]) => action);
+    if (invalidActions.length) {
+      for (const action of invalidActions) {
+        warnings.push(
+          `ads: ${provider} conversionLabel.${action} "${labels[action as keyof ConversionLabelMap]}" ` +
+            'is not a valid label. Conversion firing skipped for that action.',
+        );
+      }
+      const cleanLabels = Object.fromEntries(
+        Object.entries(labels).filter(([action]) => !invalidActions.includes(action)),
+      );
+      // Omit the key entirely rather than setting it `undefined` —
+      // `exactOptionalPropertyTypes` treats the two differently.
+      const { conversionLabel: _drop, ...rest } = entry;
+      safeEntry = Object.keys(cleanLabels).length
+        ? { ...rest, conversionLabel: cleanLabels }
+        : rest;
+    }
+
     const category: ConsentCategory = entry.category ?? 'marketing';
     tags.push({
       key: provider,
@@ -125,7 +168,7 @@ export function resolveAds(
       cookies: platform.tag.cookies,
       strategy,
       gated: ctx.consent === true,
-      inline: platform.tag.bootstrap(id, { provider, ...entry }),
+      inline: platform.tag.bootstrap(id, { provider, ...safeEntry }),
       src: platform.tag.src ? platform.tag.src(id) : null,
       attrs: {},
     });

package/src/analytics.ts

@@ -156,6 +156,39 @@ export interface ResolvedAnalytics {
 export interface ResolveAnalyticsContext {
   /** Is the consent gate enabled on this site (`vitops({ consent })`)? */
   consent?: boolean;
+  /**
+   * Enabled `site.experiments` entries, keyed the same way, each carrying the
+   * resolved cookie name `vitopsAbTesting()`'s middleware assigns
+   * (`_ab_<key>` unless overridden). When set, each provider's bootstrap
+   * reads these cookies client-side and reports the assignment via that
+   * provider's own custom-dimension/property mechanism — a no-op when this
+   * is empty, so a site not using experiments sees no behavior change.
+   */
+  experiments?: Record<string, { cookieName: string }>;
+  /** `site.analytics.matomo.abVariantDimensions` — Matomo's pre-created custom-dimension index per experiment key. */
+  matomoAbVariantDimensions?: Record<string, number>;
+}
+
+/**
+ * A small inline snippet reading each experiment's cookie into a plain
+ * object, skipping any experiment whose cookie isn't set (visitor not yet
+ * assigned, or the experiment disabled after this page was cached). Shared
+ * across providers so the cookie-parsing logic — and its `SAFE_ID` guard on
+ * both the experiment key and cookie name, the same discipline `bad()`
+ * already applies to provider IDs landing in an inline `<script>` — exists
+ * exactly once.
+ */
+function experimentCookieReads(experiments: Record<string, { cookieName: string }>): string {
+  const entries = Object.entries(experiments).filter(([key, e]) => !bad(key) && !bad(e.cookieName));
+  if (!entries.length) return '';
+  return (
+    `function _abrc(n){var m=document.cookie.match(new RegExp('(?:^|; )'+n+'=([^;]*)'));return m?decodeURIComponent(m[1]):null;}` +
+    `var _ab={};` +
+    entries
+      .map(([key, e]) => `_ab[${JSON.stringify(key)}]=_abrc(${JSON.stringify(e.cookieName)});`)
+      .join('') +
+    `for(var _k in _ab){if(_ab[_k]==null)delete _ab[_k];}`
+  );
 }
 
 /**
@@ -175,10 +208,23 @@ function literal(value: Record<string, string | number | boolean>): string {
   return JSON.stringify(value).replaceAll('<', '\\u003c');
 }
 
-function googleAnalytics(input: string | GoogleAnalyticsOptions): ResolvedTag | string {
+function googleAnalytics(
+  input: string | GoogleAnalyticsOptions,
+  experiments: Record<string, { cookieName: string }> = {},
+): ResolvedTag | string {
   const opts = typeof input === 'string' ? { id: input } : input;
   if (bad(opts.id)) return `googleAnalytics: "${opts.id}" is not a valid measurement ID. Skipped.`;
-  const config = opts.config ? `,${literal(opts.config)}` : '';
+  const staticConfig = opts.config ?? {};
+  const reads = experimentCookieReads(experiments);
+  // With no experiments configured, the config object is static, exactly as
+  // before — same output byte-for-byte, no runtime cost added. With
+  // experiments, the automatic pageview's `gtag('config', …)` call is built
+  // at runtime instead, merging each assigned variant in under its
+  // experiment key so it reaches GA4 as a custom parameter on that same hit
+  // (registered as a custom dimension in GA4 Admin by parameter name).
+  const gtagConfig = reads
+    ? `${reads}gtag('config','${opts.id}',Object.assign(${literal(staticConfig)},_ab));`
+    : `gtag('config','${opts.id}'${opts.config ? `,${literal(staticConfig)}` : ''});`;
   return {
     key: 'googleAnalytics',
     provider: 'Google Analytics',
@@ -191,7 +237,7 @@ function googleAnalytics(input: string | GoogleAnalyticsOptions): ResolvedTag |
       `window.dataLayer=window.dataLayer||[];` +
       `function gtag(){dataLayer.push(arguments)}` +
       `gtag('js',new Date());` +
-      `gtag('config','${opts.id}'${config});`,
+      gtagConfig,
     src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(opts.id)}`,
     attrs: {},
   };
@@ -230,7 +276,11 @@ function clarity(input: string | ClarityOptions): ResolvedTag | string {
   };
 }
 
-function matomo(opts: MatomoOptions): ResolvedTag | string {
+function matomo(
+  opts: MatomoOptions,
+  experiments: Record<string, { cookieName: string }> = {},
+  dimensions: Record<string, number> = {},
+): ResolvedTag | string {
   const siteId = String(opts.siteId);
   if (bad(siteId)) return `matomo: "${siteId}" is not a valid site ID. Skipped.`;
   let base: URL;
@@ -242,8 +292,26 @@ function matomo(opts: MatomoOptions): ResolvedTag | string {
   const url = `${base.origin}${base.pathname.replace(/\/*$/, '')}/`;
   const cookies = opts.cookies === true;
 
-  // `disableCookies` must be pushed *before* trackPageView, or the first request
-  // of the visit sets the cookies this option exists to avoid.
+  // Only experiments with a recorded dimension index push anything — one
+  // with no index is silently skipped here (validateConfig's
+  // `experimentDimensionWarnings` is what surfaces that as a build-time
+  // warning, not a hard error: the pageview still ships correctly).
+  const dimensionEntries = Object.entries(experiments).filter(([key]) => dimensions[key] != null);
+  const reads = experimentCookieReads(Object.fromEntries(dimensionEntries));
+  const dimensionPushes = reads
+    ? reads +
+      dimensionEntries
+        .map(
+          ([key]) =>
+            `if(_ab[${JSON.stringify(key)}]!=null)_paq.push(['setCustomDimension',${dimensions[key]},_ab[${JSON.stringify(key)}]]);`,
+        )
+        .join('')
+    : '';
+
+  // `disableCookies` and the experiment dimension pushes must both land
+  // *before* trackPageView — the former so the first request of the visit
+  // doesn't set the cookies it exists to avoid, the latter because a
+  // dimension pushed after trackPageView misses that pageview entirely.
   return {
     key: 'matomo',
     provider: 'Matomo',
@@ -255,6 +323,7 @@ function matomo(opts: MatomoOptions): ResolvedTag | string {
     inline:
       `var _paq=window._paq=window._paq||[];` +
       (cookies ? '' : `_paq.push(['disableCookies']);`) +
+      dimensionPushes +
       `_paq.push(['trackPageView']);_paq.push(['enableLinkTracking']);` +
       `(function(){var u="${url}";` +
       `_paq.push(['setTrackerUrl',u+'matomo.php']);_paq.push(['setSiteId','${siteId}']);` +
@@ -265,9 +334,24 @@ function matomo(opts: MatomoOptions): ResolvedTag | string {
   };
 }
 
-function plausible(input: string | PlausibleOptions): ResolvedTag | string {
+function plausible(
+  input: string | PlausibleOptions,
+  experiments: Record<string, { cookieName: string }> = {},
+): ResolvedTag | string {
   const opts = typeof input === 'string' ? { domain: input } : input;
   if (bad(opts.domain)) return `plausible: "${opts.domain}" is not a valid domain. Skipped.`;
+  // Plausible's current API (plausible.init({customProperties})) needs no
+  // special script variant and no manual-pageview mode — customProperties
+  // attaches to every tracked event, including the automatic pageview, so
+  // there's no double-counting risk to design around. The queueing stub
+  // mirrors gtag's own inline bootstrap above: the real script (loaded via
+  // `src`, async) picks up this call once it's ready, regardless of which
+  // one finishes loading first.
+  const reads = experimentCookieReads(experiments);
+  const inline = reads
+    ? `window.plausible=window.plausible||function(){(window.plausible.q=window.plausible.q||[]).push(arguments)};` +
+      `plausible.init({customProperties:function(){${reads}return _ab;}});`
+    : '';
   return {
     key: 'plausible',
     provider: 'Plausible Analytics',
@@ -278,7 +362,7 @@ function plausible(input: string | PlausibleOptions): ResolvedTag | string {
     cookies: [],
     strategy: 'idle',
     gated: true,
-    inline: '',
+    inline,
     src: opts.src ?? 'https://plausible.io/js/script.js',
     attrs: { 'data-domain': opts.domain },
   };
@@ -300,11 +384,14 @@ export function resolveAnalytics(
   if (!opts) return { tags, needsRuntime: false, warnings };
 
   const strategy = opts.strategy ?? 'idle';
+  const experiments = ctx.experiments ?? {};
   const results = [
-    opts.googleAnalytics === undefined ? null : googleAnalytics(opts.googleAnalytics),
+    opts.googleAnalytics === undefined ? null : googleAnalytics(opts.googleAnalytics, experiments),
     opts.clarity === undefined ? null : clarity(opts.clarity),
-    opts.matomo === undefined ? null : matomo(opts.matomo),
-    opts.plausible === undefined ? null : plausible(opts.plausible),
+    opts.matomo === undefined
+      ? null
+      : matomo(opts.matomo, experiments, ctx.matomoAbVariantDimensions ?? {}),
+    opts.plausible === undefined ? null : plausible(opts.plausible, experiments),
   ];
 
   for (const result of results) {

package/src/components/Analytics.astro

@@ -29,7 +29,11 @@ const { enabled = true, strategy } = Astro.props;
 
 const options = strategy ? { ...head.analytics, strategy } : head.analytics;
 const { tags } = enabled
-  ? resolveAnalytics(options, { consent: head.consent })
+  ? resolveAnalytics(options, {
+      consent: head.consent,
+      experiments: head.experiments,
+      matomoAbVariantDimensions: head.matomoAbVariantDimensions,
+    })
   : { tags: [] };
 ---
 

package/src/components/Icon.astro

@@ -27,8 +27,15 @@
  *   `inline-flex` with a `gap` — is a matter of child order, not a new class.
  *   Don't confuse this with `.icon-mask`, the CSS-only adornment path (see
  *   `.link--icon::before` in anchor-link.css).
+ *
+ * **Imports from `@getvitops/generator/icons-sprite`, never the root entry.**
+ * The root entry also re-exports `generate.ts`, which reaches lightningcss —
+ * a native binary Cloudflare Workers cannot `require()`. A *static* import of
+ * the root here dragged that into every SSR bundle rendering this component,
+ * regardless of `icons.engine`, and 500'd every request on a real consumer.
+ * The `icons-sprite` subpath has no such dependency — see its own docblock.
  */
-import { loadIconSvg, spriteId } from '@getvitops/generator';
+import { loadIconSvg, spriteId } from '@getvitops/generator/icons-sprite';
 import { resolveIcon } from '@getvitops/utils';
 import icons from 'virtual:getvitops/icons';
 

package/src/components/Tracking.astro

@@ -25,7 +25,7 @@
 // @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 
-const { enabled, category, cookies } = head.tracking ?? { enabled: false };
+const { enabled, category, cookies, abVariantCookie } = head.tracking ?? { enabled: false };
 ---
 
 {enabled && (
@@ -35,6 +35,7 @@ const { enabled, category, cookies } = head.tracking ?? { enabled: false };
       data-vitops-tracking
       data-consent={category}
       data-consent-cookies={cookies?.length ? cookies.join(',') : undefined}
+      data-ab-cookie={abVariantCookie ?? undefined}
     />
     <script>
       import '../scripts/tracking.ts';

package/src/scripts/tracking.ts

@@ -1,8 +1,10 @@
 // Ad conversion tracking: capture click IDs from the landing URL, track tel:
-// clicks. Form submission itself goes through `createConversionRoute()`
-// (`@getvitops/astro/routes`), which handles both the no-JS `<form
-// method="post">` path and a fetch-based one — there is no separate
-// form-enhancement script here.
+// and mailto: clicks. Form submission itself goes through
+// `createConversionRoute()` (`@getvitops/astro/routes`), which handles both
+// the no-JS `<form method="post">` path and a fetch-based one — there is no
+// form-enhancement script here, only `window.vitopsFormConversion()` (below),
+// which a consumer's own fetch-based submit handler may call once that POST
+// succeeds, to report the `form` Google Ads conversion action client-side.
 //
 // Runs early and ungated on purpose. Reading the query string is not storage and
 // needs nobody's permission; *keeping* it does. So the capture is synchronous —
@@ -27,9 +29,12 @@
 
 const COOKIE_NAME = '_ac';
 const COOKIE_DAYS = 90;
-const AB_COOKIE = '_ab';
+// Default when no experiment is configured, or the marker (below) carries no
+// `data-ab-cookie` override — kept as a literal fallback so a site with no
+// `site.experiments` behaves exactly as before.
+const DEFAULT_AB_COOKIE = '_ab';
 
-// Where the `tel:` conversion beacon goes. Mirrors TRACKING_ENDPOINT in
+// Where the `tel:`/`mailto:` conversion beacons go. Mirrors TRACKING_ENDPOINT in
 // ../tracking.ts (pinned by `tracking.test.ts`), copied for the same reason as
 // the parameter lists below — this file is inlined into the document.
 //
@@ -70,17 +75,35 @@ for (const key of [...CLICK_ID_PARAMS, ...UTM_PARAMS]) {
   if (value) trackingData[key] = value;
 }
 
-// Include A/B variant if assigned by the router Worker. A cookie present but
-// valueless yields undefined, which must not be written into the record.
-const abMatch = document.cookie.split(';').find((c) => c.trim().startsWith(`${AB_COOKIE}=`));
-const abVariant = abMatch?.split('=')[1]?.trim();
+/**
+ * Reads a raw cookie value by name. Splits on the *first* `=` only (a prior
+ * version split on every `=`, silently truncating any value containing one)
+ * and URL-decodes the result — a prior version didn't, so a variant name or
+ * attribution value containing a reserved character came back mangled.
+ */
+function rawCookie(name: string): string | undefined {
+  const match = document.cookie.split(';').find((c) => c.trim().startsWith(`${name}=`));
+  if (!match) return undefined;
+  const eq = match.indexOf('=');
+  const value = match.slice(eq + 1).trim();
+  return value ? decodeURIComponent(value) : undefined;
+}
+
+// <Tracking /> writes the experiment cookie name onto this marker (the first
+// *enabled* `site.experiments` entry — see `readSiteExperiments`'s own
+// docblock for why only one reaches the lead-attribution pipeline), so a
+// site with no experiments configured falls back to the same default this
+// always used.
+const trackingMarker = document.querySelector('[data-vitops-tracking]');
+const abCookieName = trackingMarker?.getAttribute('data-ab-cookie') || DEFAULT_AB_COOKIE;
+const abVariant = rawCookie(abCookieName);
 if (abVariant) trackingData['ab_variant'] = abVariant;
 
 function readCookie(): Record<string, unknown> | null {
-  const match = document.cookie.split(';').find((c) => c.trim().startsWith(`${COOKIE_NAME}=`));
-  if (!match) return null;
+  const raw = rawCookie(COOKIE_NAME);
+  if (!raw) return null;
   try {
-    const data: unknown = JSON.parse(decodeURIComponent(match.split('=').slice(1).join('=')));
+    const data: unknown = JSON.parse(raw);
     return typeof data === 'object' && data !== null && !Array.isArray(data)
       ? (data as Record<string, unknown>)
       : null;
@@ -121,10 +144,9 @@ const gate = (): ConsentLike | undefined =>
   (window as unknown as { vitopsConsent?: ConsentLike }).vitopsConsent;
 
 if (Object.keys(trackingData).length > 0) {
-  // <Tracking /> writes the category onto this marker, which also carries
-  // `data-consent-cookies` so revoking clears `_ac`.
-  const marker = document.querySelector('[data-vitops-tracking]');
-  const category = marker?.getAttribute('data-consent') ?? 'marketing';
+  // <Tracking /> writes the category onto this marker (looked up once,
+  // above), which also carries `data-consent-cookies` so revoking clears `_ac`.
+  const category = trackingMarker?.getAttribute('data-consent') ?? 'marketing';
 
   if (!gate()) {
     // No gate on this site: behave as it always has.
@@ -147,15 +169,86 @@ if (Object.keys(trackingData).length > 0) {
 }
 
 // ---------------------------------------------------------------------------
-// 2. Tel: click tracking via sendBeacon
+// 2. Tel:/mailto: click tracking via sendBeacon, plus a Google Ads conversion
 // ---------------------------------------------------------------------------
 
+/**
+ * Typed locally, matching `ConsentLike` above: a global augmentation here
+ * would widen `Window` package-wide for a shape only this file uses.
+ *
+ * `gtag` is a plain function global — it's declared inside the classic
+ * (non-module) inline `<script>` `gtagBootstrap` emits (`@getvitops/utils/ads`),
+ * which attaches it to `window`. This file runs as a module (`<Tracking />`
+ * imports it), so it must go through `window.gtag`, not a bare `gtag(...)` call.
+ * `vitopsAdsConversions.google` is the same bootstrap's per-action `send_to`
+ * map (`{call?, email?, form?}`) — each action carries its own target, so a
+ * call, an email click and a form submission report as distinct Google Ads
+ * conversion actions instead of all three sharing one.
+ */
+interface AdsGlobal {
+  gtag?: (...args: unknown[]) => void;
+  vitopsAdsConversions?: Record<string, Partial<Record<'call' | 'email' | 'form', string>>>;
+}
+const adsGlobal = (): AdsGlobal => window as unknown as AdsGlobal;
+
 document.addEventListener('click', (e) => {
-  const link = (e.target as Element).closest?.('a[href^="tel:"]') as HTMLAnchorElement | null;
+  const link = (e.target as Element).closest?.(
+    'a[href^="tel:"], a[href^="mailto:"]',
+  ) as HTMLAnchorElement | null;
   if (!link) return;
 
-  // Fire-and-forget beacon; don't block the tel: navigation
+  const isEmail = link.href.startsWith('mailto:');
+
+  // Fire-and-forget beacon; don't block the tel:/mailto: navigation.
   if (navigator.sendBeacon) {
-    navigator.sendBeacon(TRACK_ENDPOINT, JSON.stringify({ event: 'call', phone: link.href }));
+    const body = isEmail
+      ? { event: 'email', email: link.href }
+      : { event: 'call', phone: link.href };
+    navigator.sendBeacon(TRACK_ENDPOINT, JSON.stringify(body));
+  }
+
+  // Report the same click as a Google Ads conversion, when that action's
+  // `conversionLabel` is configured. `sendTo` is absent whenever the tag never
+  // loaded (gated and undecided, or `site.ads.google` unset) or that specific
+  // action has no label — silently skipped, same as every other
+  // optional-runtime check in this file.
+  const sendTo = adsGlobal().vitopsAdsConversions?.['google']?.[isEmail ? 'email' : 'call'];
+  if (sendTo && typeof adsGlobal().gtag === 'function') {
+    adsGlobal().gtag!('event', 'conversion', { send_to: sendTo });
   }
 });
+
+// ---------------------------------------------------------------------------
+// 3. Form-submission conversion, for a consumer's own fetch-based submit handler
+// ---------------------------------------------------------------------------
+
+const CONVERTED_ATTR = 'data-vitops-converted';
+
+/**
+ * Fires the Google Ads `form` conversion action (see `AdsGlobal` above) for a
+ * consumer's own fetch-based submit handler to call once its own POST to
+ * `createConversionRoute()` has succeeded — mirroring the tel:/mailto: click
+ * handler above, but for a form, which has no click to hook.
+ *
+ * Idempotent per element (`data-vitops-converted`): a handler that fires this
+ * more than once for the same submission (a retried network call, a
+ * double-invoked effect) reports the conversion once, not twice.
+ *
+ * There is deliberately no server-side equivalent for a no-JS
+ * `<form method="post">` submission — that path is a full-page redirect with no
+ * script execution to fire from, and reporting a Google-Ads-labelled
+ * conversion from the server needs the Google Ads API's click-conversion
+ * upload (developer token + MCC access), not a client-side pixel call. See the
+ * vNext backlog's §16 for that follow-up.
+ */
+function vitopsFormConversion(formEl: HTMLFormElement): void {
+  if (formEl.hasAttribute(CONVERTED_ATTR)) return;
+  formEl.setAttribute(CONVERTED_ATTR, '');
+  const sendTo = adsGlobal().vitopsAdsConversions?.['google']?.['form'];
+  if (sendTo && typeof adsGlobal().gtag === 'function') {
+    adsGlobal().gtag!('event', 'conversion', { send_to: sendTo });
+  }
+}
+
+(window as unknown as { vitopsFormConversion?: typeof vitopsFormConversion }).vitopsFormConversion =
+  vitopsFormConversion;

package/src/tracking.ts

@@ -28,7 +28,7 @@ export interface GetvitopsTrackingOptions {
 export const TRACKING_COOKIE = '_ac';
 
 /**
- * Where the capture script sends its `tel:` conversion beacon.
+ * Where the capture script sends its `tel:`/`mailto:` conversion beacons.
  *
  * The route itself is the consumer's to write (`createConversionRoute()` in
  * `@getvitops/astro/routes`), so this is the one place the two halves agree on

package/virtual.d.ts

@@ -11,6 +11,17 @@ declare module 'virtual:getvitops/head' {
     cssVariable: string;
     preload: boolean | { weight?: string | number; style?: string }[];
   }
+  /**
+   * Mirrors `HeadTrackingData` in src/integration.ts. Its own named interface
+   * (not inlined into `HeadData` below) so the drift guard's line-by-line key
+   * regex doesn't pick up its fields as false top-level `HeadData` matches.
+   */
+  interface HeadTrackingData {
+    enabled: boolean;
+    category: string;
+    cookies: string[];
+    abVariantCookie: string | null;
+  }
   // Keep these keys in step with `HeadData` in src/integration.ts — the two are
   // hand-duplicated (an ambient `declare module` in a shipped .d.ts cannot import
   // from src), and `head.test.ts` asserts the key sets match.
@@ -40,7 +51,12 @@ declare module 'virtual:getvitops/head' {
     // integration rather than the component because its warnings belong beside
     // the others, and the offered consent categories it checks against are known
     // only there.
-    tracking: { enabled: boolean; category: string; cookies: string[] } | null;
+    tracking: HeadTrackingData | null;
+    // Enabled `site.experiments`, keyed the same way, resolved to their cookie
+    // names — re-typed by <Analytics /> on the way into `resolveAnalytics`.
+    experiments: Record<string, { cookieName: string }>;
+    // `site.analytics.matomo.abVariantDimensions`, passed through unchanged.
+    matomoAbVariantDimensions: Record<string, number>;
     // The site config's `site.ads` block plus this environment's switch —
     // structurally `{ enabled, properties }` (src/ads.ts), re-typed by <Ads /> on
     // the way into `resolveAds`. Read in the integration because that is where the

package/dist/tracking-CmSfxWC3.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracking-CmSfxWC3.mjs","names":[],"sources":["../src/tracking.ts"],"sourcesContent":["/**\n * The `<Tracking />` resolution layer — tracking config in, what to emit out.\n *\n * Separate from `Tracking.astro` for the same reason `analytics.ts` is separate\n * from `Analytics.astro`: everything decidable is a pure function asserted in\n * `tracking.test.ts`, and the component only renders what this returns.\n *\n * The one decision here is **which consent category the `_ac` cookie waits on**,\n * and it is stated rather than inferred. `_ac` is a 90-day identifier tying a\n * visitor to the ad that brought them, so `marketing` is the default — but a site\n * using click IDs purely for its own campaign reporting may reasonably file it\n * under `analytics`, and that is the consumer's call to make, not ours to guess.\n */\n\n/** Which consent category the attribution cookie waits on. */\nexport type TrackingCategory = 'marketing' | 'analytics';\n\nexport interface GetvitopsTrackingOptions {\n  /** Capture ad click IDs and UTMs into `_ac`. */\n  enabled?: boolean;\n  /** Default `marketing`. */\n  category?: TrackingCategory;\n  /** Informational; capture recognises every known click-ID parameter regardless. */\n  platforms?: string[];\n}\n\n/** The cookie the capture script writes. Mirrors `TRACKING_COOKIE` in utils. */\nexport const TRACKING_COOKIE = '_ac';\n\n/**\n * Where the capture script sends its `tel:` conversion beacon.\n *\n * The route itself is the consumer's to write (`createConversionRoute()` in\n * `@getvitops/astro/routes`), so this is the one place the two halves agree on\n * a path. It was a bare literal inside the inlined script: a consumer who named\n * the file anything else got a silent 404 on every beacon and lost conversions\n * with no error anywhere to explain it. Exported so a consumer can assert\n * against it, mirrored in `scripts/tracking.ts` because that file is inlined\n * into the document and cannot import, and pinned by `tracking.test.ts`.\n */\nexport const TRACKING_ENDPOINT = '/api/track';\n\nexport interface ResolvedTracking {\n  enabled: boolean;\n  category: TrackingCategory;\n  /** Cookie names to clear on revoke — rides on `data-consent-cookies`. */\n  cookies: string[];\n  /** Configuration problems, as prose. The integration logs these. */\n  warnings: string[];\n}\n\nexport interface ResolveTrackingContext {\n  /** Is the consent gate enabled on this site (`vitops({ consent })`)? */\n  consent?: boolean;\n  /** Categories the banner offers, so we can catch a demand with no row. */\n  consentCategories?: readonly string[];\n}\n\n/**\n * Resolve the tracking config into what the component emits.\n *\n * Two warnings, both about the same failure — a persistent identifier written\n * with no way for the visitor to decline, or a permission asked for with no way\n * to answer. Returned as data rather than logged here so the check is a test\n * rather than a line someone might scroll past, exactly as `resolveAnalytics`\n * does.\n */\nexport function resolveTracking(\n  opts: GetvitopsTrackingOptions | undefined,\n  ctx: ResolveTrackingContext = {},\n): ResolvedTracking {\n  const warnings: string[] = [];\n  const category: TrackingCategory = opts?.category ?? 'marketing';\n  const enabled = opts?.enabled === true;\n\n  if (!enabled) return { enabled: false, category, cookies: [], warnings };\n\n  if (!ctx.consent) {\n    warnings.push(\n      `tracking is on, so this site writes the \\`${TRACKING_COOKIE}\\` cookie — a 90-day ` +\n        'identifier tying a visitor to the ad that brought them — and `consent` is off, so it ' +\n        'is written for every visitor with no way to decline. Set `consent: true`.',\n    );\n  } else if (ctx.consentCategories && !ctx.consentCategories.includes(category)) {\n    // The banner would be raised for a category it renders no row for: the\n    // visitor is asked a question the form does not show them.\n    warnings.push(\n      `tracking demands the \\`${category}\\` consent category, but the banner offers ` +\n        `${ctx.consentCategories.join(', ') || 'nothing'}. Add \\`${category}\\` to ` +\n        '`consent.categories`, or the visitor is asked about something the banner never names.',\n    );\n  }\n\n  return { enabled, category, cookies: [TRACKING_COOKIE], warnings };\n}\n"],"mappings":";;AA2BA,MAAa,kBAAkB;;;;;;;;;;;;AAa/B,MAAa,oBAAoB;;;;;;;;;;AA2BjC,SAAgB,gBACd,MACA,MAA8B,CAAC,GACb;CAClB,MAAM,WAAqB,CAAC;CAC5B,MAAM,WAA6B,MAAM,YAAY;CACrD,MAAM,UAAU,MAAM,YAAY;CAElC,IAAI,CAAC,SAAS,OAAO;EAAE,SAAS;EAAO;EAAU,SAAS,CAAC;EAAG;CAAS;CAEvE,IAAI,CAAC,IAAI,SACP,SAAS,KACP,mDAA6D,wLAG/D;MACK,IAAI,IAAI,qBAAqB,CAAC,IAAI,kBAAkB,SAAS,QAAQ,GAG1E,SAAS,KACP,0BAA0B,SAAS,6CAC9B,IAAI,kBAAkB,KAAK,IAAI,KAAK,UAAU,UAAU,SAAS,8FAExE;CAGF,OAAO;EAAE;EAAS;EAAU,SAAS,MAAgB;EAAG;CAAS;AACnE"}

package/dist/tracking-DdEKExlE.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracking-DdEKExlE.d.mts","names":[],"sources":["../src/tracking.ts"],"mappings":";;AAeA;;;;AAA4B;AAE5B;;;;;;;;KAFY,gBAAA;AAAA,UAEK,wBAAA;EAUJ;EARX,OAAA;;EAEA,QAAA,GAAW,gBAAgB;EAMD;EAJ1B,SAAA;AAAA;;cAIW,eAAA;AAaiB;AAE9B;;;;;;;;;;AAF8B,cAAjB,iBAAA;AAAA,UAEI,gBAAA;EACf,OAAA;EACA,QAAA,EAAU,gBAAgB;EAS1B;EAPA,OAAA;EAqBc;EAnBd,QAAA;AAAA;AAAA,UAGe,sBAAA;EAkBV;EAhBL,OAAA;EAiBiB;EAfjB,iBAAiB;AAAA;;;;;;AAeA;;;;iBAHH,eAAA,CACd,IAAA,EAAM,wBAAA,cACN,GAAA,GAAK,sBAAA,GACJ,gBAAA"}