@getvitops/astro 3.0.0 → 4.1.0

package/dist/routes/conversion.d.mts

@@ -0,0 +1,45 @@
+import { EmailBinding, NotifyContext, notify } from "@getvitops/utils/notify";
+
+//#region src/routes/conversion.d.ts
+/** The subset of Astro's `APIContext` this needs — typed structurally so the
+ * factory does not pin an Astro version. */
+interface ConversionRequestContext {
+  request: Request;
+  locals?: unknown;
+}
+interface ConversionRouteOptions {
+  /** Where notifications go. Build it from your site config. */
+  context: NotifyContext;
+  /**
+   * The Workers `send_email` binding for this request, e.g.
+   * `(locals) => locals.runtime.env.EMAIL`. Omit it in dev and the notification
+   * is printed instead of sent.
+   */
+  binding?: (locals: unknown) => EmailBinding | undefined;
+  /**
+   * Reject a submission before anything is sent. Return a message to refuse.
+   * This is where a consumer puts required-field checks and spam rules.
+   */
+  validate?: (body: Record<string, unknown>) => string | null;
+  /** Called with every channel outcome, delivered or not. Defaults to console. */
+  onResult?: (result: Awaited<ReturnType<typeof notify>>) => void;
+  /** Injected in tests. */
+  now?: () => number;
+}
+/**
+ * Build a POST handler for conversions.
+ *
+ * Returns 204 for a beacon and 200 with `{ success }` for a form, matching what
+ * `navigator.sendBeacon` and a fetch-submitting form each expect.
+ *
+ * **A failed notification does not fail the request.** The visitor has already
+ * submitted; refusing them because our mail did not go out turns a lost
+ * notification into a lost conversion. Failures are reported through `onResult`.
+ */
+declare function createConversionRoute(options: ConversionRouteOptions): ({
+  request,
+  locals
+}: ConversionRequestContext) => Promise<Response>;
+//#endregion
+export { ConversionRequestContext, ConversionRouteOptions, createConversionRoute };
+//# sourceMappingURL=conversion.d.mts.map

package/dist/routes/conversion.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.d.mts","names":[],"sources":["../../src/routes/conversion.ts"],"mappings":";;;;;UAgCiB,wBAAA;EACf,OAAA,EAAS,OAAO;EAChB,MAAA;AAAA;AAAA,UAGe,sBAAA;EAe+B;EAb9C,OAAA,EAAS,aAAA;EAeT;;AAAG;AA0BL;;EAnCE,OAAA,IAAW,MAAA,cAAoB,YAAA;EAmCc;;;;EA9B7C,QAAA,IAAY,IAAA,EAAM,MAAA;EAiC4C;EA/B9D,QAAA,IAAY,MAAA,EAAQ,OAAA,CAAQ,UAAA,QAAkB,MAAA;EA+BuB;EA7BrE,GAAA;AAAA;;;;;;;;;AA6B8E;;iBAHhE,qBAAA,CAAsB,OAAA,EAAS,sBAAA;EAG/B,OAAA;EAAA;AAAA,GAAqB,wBAAA,KAA2B,OAAA,CAAQ,QAAA"}

package/dist/routes/conversion.mjs

@@ -0,0 +1,95 @@
+import { notify } from "@getvitops/utils/notify";
+import { parseTrackingCookie } from "@getvitops/utils/tracking";
+
+//#region src/routes/conversion.ts
+/**
+* The conversion endpoint, as a factory.
+*
+* A site's contact form and its `tel:` beacon both mean the same thing — someone
+* got in touch — and both want the same treatment: read the attribution cookie
+* off the request, build the event, notify whoever the config says. That is the
+* same three lines in every project, so it ships here.
+*
+* What deliberately does **not** ship here is validation and business rules. A
+* consumer's form has its own required fields, its own spam handling and its own
+* response shape, and baking a guess at those in would make the factory something
+* to fight rather than mount. The handler takes the parsed body and an optional
+* `validate`; everything else is the caller's.
+*
+* ```ts
+* // src/pages/api/track.ts
+* export const prerender = false;
+* import { createConversionRoute } from '@getvitops/astro/routes';
+* import config from '../../site.config.json';
+*
+* export const POST = createConversionRoute({
+*   context: toNotifyContext(config),
+*   binding: (locals) => locals.runtime?.env?.EMAIL,
+* });
+* ```
+*/
+/** Fields that are never part of a submission's meaning. */
+const CONTROL_FIELDS = new Set(["event", "phone"]);
+function toFormData(body) {
+	const out = {};
+	for (const [key, value] of Object.entries(body)) {
+		if (CONTROL_FIELDS.has(key)) continue;
+		if (value === void 0 || value === null) continue;
+		out[key] = String(value);
+	}
+	return out;
+}
+/**
+* Build a POST handler for conversions.
+*
+* Returns 204 for a beacon and 200 with `{ success }` for a form, matching what
+* `navigator.sendBeacon` and a fetch-submitting form each expect.
+*
+* **A failed notification does not fail the request.** The visitor has already
+* submitted; refusing them because our mail did not go out turns a lost
+* notification into a lost conversion. Failures are reported through `onResult`.
+*/
+function createConversionRoute(options) {
+	const { context, binding, validate, onResult, now = Date.now } = options;
+	return async ({ request, locals }) => {
+		let body;
+		try {
+			const parsed = await request.json();
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return Response.json({
+				success: false,
+				error: "Malformed request."
+			}, { status: 400 });
+			body = parsed;
+		} catch {
+			return Response.json({
+				success: false,
+				error: "Malformed request."
+			}, { status: 400 });
+		}
+		const isCall = body["event"] === "call";
+		if (isCall && typeof body["phone"] !== "string") return Response.json({
+			success: false,
+			error: "Missing phone."
+		}, { status: 400 });
+		const refusal = validate?.(body);
+		if (refusal) return Response.json({
+			success: false,
+			error: refusal
+		}, { status: 400 });
+		const result = await notify({
+			type: isCall ? "call" : "form",
+			...isCall ? { phone: String(body["phone"]).replace(/^tel:/, "") } : { formData: toFormData(body) },
+			tracking: parseTrackingCookie(request.headers.get("cookie")),
+			userAgent: request.headers.get("user-agent") ?? void 0,
+			ip: request.headers.get("cf-connecting-ip") ?? request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? void 0,
+			at: now()
+		}, context, { email: binding?.(locals) });
+		if (onResult) onResult(result);
+		else for (const r of result.results) if (!r.sent) console.warn(`[vitops] notification not sent (${r.channel}): ${r.reason}`);
+		return isCall ? new Response(null, { status: 204 }) : Response.json({ success: true });
+	};
+}
+
+//#endregion
+export { createConversionRoute };
+//# sourceMappingURL=conversion.mjs.map

package/dist/routes/conversion.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.mjs","names":[],"sources":["../../src/routes/conversion.ts"],"sourcesContent":["/**\n * The conversion endpoint, as a factory.\n *\n * A site's contact form and its `tel:` beacon both mean the same thing — someone\n * got in touch — and both want the same treatment: read the attribution cookie\n * off the request, build the event, notify whoever the config says. That is the\n * same three lines in every project, so it ships here.\n *\n * What deliberately does **not** ship here is validation and business rules. A\n * consumer's form has its own required fields, its own spam handling and its own\n * response shape, and baking a guess at those in would make the factory something\n * to fight rather than mount. The handler takes the parsed body and an optional\n * `validate`; everything else is the caller's.\n *\n * ```ts\n * // src/pages/api/track.ts\n * export const prerender = false;\n * import { createConversionRoute } from '@getvitops/astro/routes';\n * import config from '../../site.config.json';\n *\n * export const POST = createConversionRoute({\n *   context: toNotifyContext(config),\n *   binding: (locals) => locals.runtime?.env?.EMAIL,\n * });\n * ```\n */\nimport { type EmailBinding, notify, type NotifyContext } from '@getvitops/utils/notify';\nimport { parseTrackingCookie } from '@getvitops/utils/tracking';\nimport type { ConversionEvent } from '@getvitops/utils/tracking';\n\n/** The subset of Astro's `APIContext` this needs — typed structurally so the\n * factory does not pin an Astro version. */\nexport interface ConversionRequestContext {\n  request: Request;\n  locals?: unknown;\n}\n\nexport interface ConversionRouteOptions {\n  /** Where notifications go. Build it from your site config. */\n  context: NotifyContext;\n  /**\n   * The Workers `send_email` binding for this request, e.g.\n   * `(locals) => locals.runtime.env.EMAIL`. Omit it in dev and the notification\n   * is printed instead of sent.\n   */\n  binding?: (locals: unknown) => EmailBinding | undefined;\n  /**\n   * Reject a submission before anything is sent. Return a message to refuse.\n   * This is where a consumer puts required-field checks and spam rules.\n   */\n  validate?: (body: Record<string, unknown>) => string | null;\n  /** Called with every channel outcome, delivered or not. Defaults to console. */\n  onResult?: (result: Awaited<ReturnType<typeof notify>>) => void;\n  /** Injected in tests. */\n  now?: () => number;\n}\n\n/** Fields that are never part of a submission's meaning. */\nconst CONTROL_FIELDS = new Set(['event', 'phone']);\n\nfunction toFormData(body: Record<string, unknown>): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of Object.entries(body)) {\n    if (CONTROL_FIELDS.has(key)) continue;\n    if (value === undefined || value === null) continue;\n    out[key] = String(value);\n  }\n  return out;\n}\n\n/**\n * Build a POST handler for conversions.\n *\n * Returns 204 for a beacon and 200 with `{ success }` for a form, matching what\n * `navigator.sendBeacon` and a fetch-submitting form each expect.\n *\n * **A failed notification does not fail the request.** The visitor has already\n * submitted; refusing them because our mail did not go out turns a lost\n * notification into a lost conversion. Failures are reported through `onResult`.\n */\nexport function createConversionRoute(options: ConversionRouteOptions) {\n  const { context, binding, validate, onResult, now = Date.now } = options;\n\n  return async ({ request, locals }: ConversionRequestContext): Promise<Response> => {\n    let body: Record<string, unknown>;\n    try {\n      const parsed: unknown = await request.json();\n      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n        return Response.json({ success: false, error: 'Malformed request.' }, { status: 400 });\n      }\n      body = parsed as Record<string, unknown>;\n    } catch {\n      return Response.json({ success: false, error: 'Malformed request.' }, { status: 400 });\n    }\n\n    const isCall = body['event'] === 'call';\n    if (isCall && typeof body['phone'] !== 'string') {\n      return Response.json({ success: false, error: 'Missing phone.' }, { status: 400 });\n    }\n\n    const refusal = validate?.(body);\n    if (refusal) return Response.json({ success: false, error: refusal }, { status: 400 });\n\n    const event: ConversionEvent = {\n      type: isCall ? 'call' : 'form',\n      ...(isCall\n        ? { phone: String(body['phone']).replace(/^tel:/, '') }\n        : { formData: toFormData(body) }),\n      tracking: parseTrackingCookie(request.headers.get('cookie')),\n      userAgent: request.headers.get('user-agent') ?? undefined,\n      // Cloudflare's own header first; `x-forwarded-for` is the portable fallback\n      // and may carry a proxy chain, whose first entry is the client.\n      ip:\n        request.headers.get('cf-connecting-ip') ??\n        request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??\n        undefined,\n      at: now(),\n    };\n\n    const result = await notify(event, context, { email: binding?.(locals) });\n\n    if (onResult) onResult(result);\n    else\n      for (const r of result.results) {\n        if (!r.sent) console.warn(`[vitops] notification not sent (${r.channel}): ${r.reason}`);\n      }\n\n    return isCall ? new Response(null, { status: 204 }) : Response.json({ success: true });\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,MAAM,iBAAiB,IAAI,IAAI,CAAC,SAAS,OAAO,CAAC;AAEjD,SAAS,WAAW,MAAuD;CACzE,MAAM,MAA8B,CAAC;CACrC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,GAAG;EAC/C,IAAI,eAAe,IAAI,GAAG,GAAG;EAC7B,IAAI,UAAU,UAAa,UAAU,MAAM;EAC3C,IAAI,OAAO,OAAO,KAAK;CACzB;CACA,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,sBAAsB,SAAiC;CACrE,MAAM,EAAE,SAAS,SAAS,UAAU,UAAU,MAAM,KAAK,QAAQ;CAEjE,OAAO,OAAO,EAAE,SAAS,aAA0D;EACjF,IAAI;EACJ,IAAI;GACF,MAAM,SAAkB,MAAM,QAAQ,KAAK;GAC3C,IAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,MAAM,GACvE,OAAO,SAAS,KAAK;IAAE,SAAS;IAAO,OAAO;GAAqB,GAAG,EAAE,QAAQ,IAAI,CAAC;GAEvF,OAAO;EACT,QAAQ;GACN,OAAO,SAAS,KAAK;IAAE,SAAS;IAAO,OAAO;GAAqB,GAAG,EAAE,QAAQ,IAAI,CAAC;EACvF;EAEA,MAAM,SAAS,KAAK,aAAa;EACjC,IAAI,UAAU,OAAO,KAAK,aAAa,UACrC,OAAO,SAAS,KAAK;GAAE,SAAS;GAAO,OAAO;EAAiB,GAAG,EAAE,QAAQ,IAAI,CAAC;EAGnF,MAAM,UAAU,WAAW,IAAI;EAC/B,IAAI,SAAS,OAAO,SAAS,KAAK;GAAE,SAAS;GAAO,OAAO;EAAQ,GAAG,EAAE,QAAQ,IAAI,CAAC;EAkBrF,MAAM,SAAS,MAAM,OAAO;GAf1B,MAAM,SAAS,SAAS;GACxB,GAAI,SACA,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,QAAQ,SAAS,EAAE,EAAE,IACpD,EAAE,UAAU,WAAW,IAAI,EAAE;GACjC,UAAU,oBAAoB,QAAQ,QAAQ,IAAI,QAAQ,CAAC;GAC3D,WAAW,QAAQ,QAAQ,IAAI,YAAY,KAAK;GAGhD,IACE,QAAQ,QAAQ,IAAI,kBAAkB,KACtC,QAAQ,QAAQ,IAAI,iBAAiB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,KAC5D;GACF,IAAI,IAAI;EAGsB,GAAG,SAAS,EAAE,OAAO,UAAU,MAAM,EAAE,CAAC;EAExE,IAAI,UAAU,SAAS,MAAM;OAE3B,KAAK,MAAM,KAAK,OAAO,SACrB,IAAI,CAAC,EAAE,MAAM,QAAQ,KAAK,mCAAmC,EAAE,QAAQ,KAAK,EAAE,QAAQ;EAG1F,OAAO,SAAS,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,SAAS,KAAK,CAAC;CACvF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/astro",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Astro integration for the Vitops design system — favicons/PWA, web-component scripts, and CSS, via a getvitops() integration + <Head /> component.",
   "license": "MIT",
   "files": [
@@ -9,8 +9,11 @@
     "src/components/Seo.astro",
     "src/seo.ts",
     "src/components/Analytics.astro",
+    "src/components/Ads.astro",
+    "src/components/GatedTags.astro",
     "src/components/CookieConsent.astro",
     "src/analytics.ts",
+    "src/ads.ts",
     "src/components/Subgrid.astro",
     "src/components/Cards.astro",
     "src/components/NodeRenderer.astro",
@@ -23,7 +26,13 @@
     "src/components/NavShellToggle.astro",
     "src/schemas",
     "virtual.d.ts",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "src/components/Tracking.astro",
+    "src/scripts/tracking.ts",
+    "src/tracking.ts",
+    "src/components/Tree.astro",
+    "src/components/TreeNode.astro",
+    "src/components/tree.ts"
   ],
   "type": "module",
   "types": "./dist/index.d.mts",
@@ -32,10 +41,16 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
+    "./routes": {
+      "types": "./dist/routes/conversion.d.mts",
+      "import": "./dist/routes/conversion.mjs"
+    },
     "./Head.astro": "./src/components/Head.astro",
     "./Seo.astro": "./src/components/Seo.astro",
     "./Analytics.astro": "./src/components/Analytics.astro",
+    "./Ads.astro": "./src/components/Ads.astro",
     "./CookieConsent.astro": "./src/components/CookieConsent.astro",
+    "./Tracking.astro": "./src/components/Tracking.astro",
     "./components/Subgrid.astro": "./src/components/Subgrid.astro",
     "./components/Cards.astro": "./src/components/Cards.astro",
     "./components/NodeRenderer.astro": "./src/components/NodeRenderer.astro",
@@ -46,6 +61,8 @@
     "./components/Drawer.astro": "./src/components/Drawer.astro",
     "./components/NavShell.astro": "./src/components/NavShell.astro",
     "./components/NavShellToggle.astro": "./src/components/NavShellToggle.astro",
+    "./components/Tree.astro": "./src/components/Tree.astro",
+    "./components/tree.ts": "./src/components/tree.ts",
     "./schemas/*": "./src/schemas/*",
     "./package.json": "./package.json"
   },
@@ -53,10 +70,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/core": "3.0.0",
-    "@getvitops/utils": "3.0.0",
-    "@getvitops/generator": "3.0.0",
-    "@getvitops/vite": "3.0.0"
+    "@getvitops/core": "4.1.0",
+    "@getvitops/generator": "4.1.0",
+    "@getvitops/vite": "4.1.0",
+    "@getvitops/utils": "4.1.0"
   },
   "devDependencies": {
     "@astrojs/sitemap": "^3.7.3",

package/src/ads.ts

@@ -0,0 +1,156 @@
+/**
+ * The `<Ads />` resolution layer — the site's ad properties in, the exact tags to
+ * emit out.
+ *
+ * A sibling of `analytics.ts`, deliberately not part of it. The two render the
+ * same gated markup, but they answer different questions and four things differ:
+ *
+ *  - **Where they come from.** Analytics providers are integration options
+ *    (`vitops({ analytics })`); ad properties are `site.ads` in the site config,
+ *    because the ad account is a fact about the site that `vitops ads setup`,
+ *    `vitops ads lint` and the generated cookie notice all read too.
+ *  - **Who decides the consent category.** `resolveAnalytics` *derives* it from
+ *    whether the provider sets cookies, so a consumer cannot mark Google Analytics
+ *    `necessary` to dodge a banner. Every ad pixel sets cookies and is advertising,
+ *    so the answer is `marketing` unless the config says `analytics` — a stated
+ *    fact, not a derivation.
+ *  - **What the key means.** `ResolvedTag['key']` is the four analytics providers,
+ *    and `analytics.ts` pairs that set against the generator's processor table.
+ *    Widening it to eight ad platforms would make that check answer for tags it
+ *    does not govern.
+ *  - **When they fire.** Analytics is gated per environment by
+ *    `environments.<env>.analytics`; a preview deployment sending pageviews is
+ *    survivable, one firing conversion pixels is not, so ads gets its own switch.
+ *
+ * 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 type { AnalyticsStrategy, ConsentCategory, GatedTag } from './analytics.ts';
+
+/**
+ * One ad property, mirroring a `site.ads` entry field for field.
+ *
+ * Structural rather than `SiteAdProperty` imported from the generator, matching
+ * how `GetvitopsSeoOptions` and `GetvitopsTrackingOptions` already work: the
+ * component surface must stay usable by a consumer who passes a plain object.
+ */
+export interface GetvitopsAdProperty {
+  accountId?: string;
+  pixelId?: string;
+  conversionLabel?: string;
+  /** Default `marketing`. `analytics` for a property used purely for measurement. */
+  category?: 'marketing' | 'analytics';
+  /** False keeps the property on record without emitting its tag. */
+  enabled?: boolean;
+}
+
+export type GetvitopsAdsOptions = Partial<Record<AdProvider, GetvitopsAdProperty>>;
+
+/** One ad tag. `key` is the platform, so a caller can find one without matching prose. */
+export interface ResolvedAdTag extends GatedTag {
+  key: AdProvider;
+}
+
+export interface ResolvedAds {
+  tags: ResolvedAdTag[];
+  /** Does anything here need `@getvitops/core/consent` loaded? */
+  needsRuntime: boolean;
+  /** Configuration problems, as prose. The integration logs these. */
+  warnings: string[];
+}
+
+export interface ResolveAdsContext {
+  /** Is the consent gate enabled on this site (`vitops({ consent })`)? */
+  consent?: boolean;
+  /** Categories the banner offers, so we can catch a demand with no row. */
+  consentCategories?: readonly string[];
+  /** `environments.<env>.ads` — false switches every tag off for this build. */
+  enabled?: boolean;
+  /** When the tags load. Default `idle`: a pixel is never worth the critical path. */
+  strategy?: AnalyticsStrategy;
+}
+
+/**
+ * IDs land inside an inline `<script>`, so they are checked rather than trusted —
+ * the same guard, for the same reason, as `analytics.ts`'s `SAFE_ID`. A `</script>`
+ * in a pixel ID is not a plausible accident; arbitrary script injection from a
+ * config file is not a plausible thing to allow either.
+ */
+const SAFE_ID = /^[\w.-]+$/;
+
+/** Resolve the configured ad properties into the tags `<Ads />` emits. */
+export function resolveAds(
+  ads: GetvitopsAdsOptions | undefined,
+  ctx: ResolveAdsContext = {},
+): ResolvedAds {
+  const warnings: string[] = [];
+  const tags: ResolvedAdTag[] = [];
+  const strategy = ctx.strategy ?? 'idle';
+
+  const configured = AD_PROVIDER_KEYS.filter((p) => ads?.[p] != null);
+  if (configured.length === 0) return { tags, needsRuntime: false, warnings };
+
+  // A whole-environment switch, checked before anything else: a preview deploy
+  // must be able to carry the same config without firing a single pixel.
+  if (ctx.enabled === false) return { tags, needsRuntime: false, warnings };
+
+  for (const provider of configured) {
+    const entry = ads![provider]!;
+    if (entry.enabled === false) continue;
+
+    const platform = AD_PLATFORMS[provider];
+    const id = entry[platform.tag.needs];
+    if (!id) {
+      warnings.push(
+        `ads: ${provider} has no ${platform.tag.needs}, so no tag is emitted. ` +
+          `Run \`vitops ads setup\` to be prompted for it.`,
+      );
+      continue;
+    }
+    if (!SAFE_ID.test(id)) {
+      warnings.push(`ads: ${provider} ${platform.tag.needs} "${id}" is not a valid ID. Skipped.`);
+      continue;
+    }
+
+    const category: ConsentCategory = entry.category ?? 'marketing';
+    tags.push({
+      key: provider,
+      provider: platform.name,
+      category,
+      // Every platform in the table sets cookies; the tag is gated whenever the
+      // site has a gate. With no gate the tag still renders — and the warning
+      // below says what that means, rather than silently declining to advertise.
+      setsCookies: true,
+      cookies: platform.tag.cookies,
+      strategy,
+      gated: ctx.consent === true,
+      inline: platform.tag.bootstrap(id, { provider, ...entry }),
+      src: platform.tag.src ? platform.tag.src(id) : null,
+      attrs: {},
+    });
+  }
+
+  if (tags.length === 0) return { tags, needsRuntime: false, warnings };
+
+  if (ctx.consent !== true) {
+    warnings.push(
+      `ads: ${tags.map((t) => t.provider).join(', ')} ${tags.length === 1 ? 'sets' : 'set'} ` +
+        'advertising cookies, and `consent` is off — so they load for every visitor with no way ' +
+        'to decline. Set `consent: true`.',
+    );
+  } else {
+    const missing = [...new Set(tags.map((t) => t.category))].filter(
+      (c) => ctx.consentCategories && !ctx.consentCategories.includes(c),
+    );
+    if (missing.length)
+      warnings.push(
+        `ads: the tags demand the ${missing.join(', ')} consent categor${missing.length === 1 ? 'y' : 'ies'}, ` +
+          `but the banner offers ${ctx.consentCategories?.join(', ') || 'nothing'}. Add ` +
+          `${missing.join(', ')} to \`consent.categories\`, or the tags wait on a question the ` +
+          'banner never asks.',
+      );
+  }
+
+  return { tags, needsRuntime: true, warnings };
+}

package/src/analytics.ts

@@ -105,9 +105,22 @@ export interface GetvitopsConsentOptions {
   policyUrl?: string;
 }
 
-/** One tag, fully resolved. */
-export interface ResolvedTag {
-  key: 'googleAnalytics' | 'clarity' | 'matomo' | 'plausible';
+/**
+ * A third-party tag, fully resolved — everything `<GatedTags />` needs to render
+ * one, with nothing left to decide.
+ *
+ * Shared by `<Analytics />` and `<Ads />` on purpose: the inert-markup rule
+ * (`type="text/plain"`, the URL on `data-src`, never a live `src`) is the whole
+ * consent gate, and it must have exactly one implementation. What differs between
+ * the two is where the tag comes from and who decides its category, which is why
+ * they have separate resolvers over one shape rather than one resolver over two
+ * vocabularies.
+ *
+ * `key` is left to each resolver: analytics keys are its four providers, ads keys
+ * are `AdProvider`. Widening it into one union here would let a provider from
+ * either side satisfy a check meant for the other.
+ */
+export interface GatedTag {
   /** The provider as a reader would recognise it — used in warnings. */
   provider: string;
   category: ConsentCategory;
@@ -127,6 +140,11 @@ export interface ResolvedTag {
   attrs: Record<string, string>;
 }
 
+/** One analytics tag. */
+export interface ResolvedTag extends GatedTag {
+  key: 'googleAnalytics' | 'clarity' | 'matomo' | 'plausible';
+}
+
 export interface ResolvedAnalytics {
   tags: ResolvedTag[];
   /** Does anything here need `@getvitops/core/consent` loaded? */
@@ -316,7 +334,7 @@ export function resolveAnalytics(
 }
 
 /** Which optional categories a set of tags actually needs a visitor to decide. */
-export function consentCategories(tags: ResolvedTag[]): OptionalConsentCategory[] {
+export function consentCategories(tags: GatedTag[]): OptionalConsentCategory[] {
   const used = new Set<OptionalConsentCategory>();
   for (const tag of tags) {
     if (tag.category !== 'necessary') used.add(tag.category);

package/src/components/Ads.astro

@@ -0,0 +1,47 @@
+---
+/**
+ * <Ads /> — the site's advertising pixels, off the critical path and behind the
+ * consent gate. Place in your layout's <head>; requires the vitops()
+ * integration, which supplies `virtual:getvitops/head`.
+ *
+ * A dumb renderer over `resolveAds()` (src/ads.ts) — which properties, which
+ * consent category, which cookies and whether this environment fires at all are
+ * decided there and unit-tested. Nothing in this file chooses anything.
+ *
+ * The properties come from the site config's `site.ads` block, not from an
+ * integration option: the ad account is a fact about the site, and the same block
+ * drives `vitops ads setup` (the domain-verification record), `vitops ads lint`
+ * and the cookie notice `vitops legal` generates. One source, so a pixel cannot be
+ * running while the site's own notice omits it.
+ *
+ * Pairs with <Tracking />, which captures the click ID the pixel's platform
+ * stamped on the landing URL. Neither implies the other — attribution works with
+ * no pixel, and a pixel works with no attribution — but a site running ads
+ * normally wants both.
+ */
+import { resolveAds } from '../ads.ts';
+import type { AnalyticsStrategy } from '../analytics.ts';
+import GatedTags from './GatedTags.astro';
+// @ts-ignore — virtual module provided by the vitops() integration at build time
+import head from 'virtual:getvitops/head';
+
+interface Props {
+  /** Render nothing on this page. Defaults to true (the per-environment switch is `environments.<env>.ads`). */
+  enabled?: boolean;
+  /** Override the load strategy for this page. */
+  strategy?: AnalyticsStrategy;
+}
+const { enabled = true, strategy } = Astro.props;
+
+// `head.ads` is already environment-resolved by the integration; `enabled` here is
+// the per-page override on top of it.
+const { tags } = enabled
+  ? resolveAds(head.ads?.properties, {
+      consent: head.consent,
+      enabled: head.ads?.enabled,
+      ...(strategy ? { strategy } : {}),
+    })
+  : { tags: [] };
+---
+
+<GatedTags tags={tags} />

package/src/components/Analytics.astro

@@ -8,17 +8,14 @@
  * about which tag, which consent category and which cookies lives there and is
  * unit-tested. Nothing in this file chooses anything.
  *
- * The gated tags are `type="text/plain"`, which is the whole trick: the browser
- * never parses the body as script and never fetches the library, so an undecided
- * or declining visitor's page issues no third-party request at all. Consent
- * implemented by *asking a tracker not to track* is a promise; this is a fact
- * about the document. `@getvitops/core/consent` (loaded by <Head />) activates
- * them when their category is granted and their strategy has fired.
- *
- * Emits no `preconnect` on purpose: warming a connection at parse time is exactly
- * the critical-path cost the `idle` strategy exists to avoid.
+ * The markup itself is <GatedTags />, shared with <Ads />: the inert
+ * `type="text/plain"` + `data-src` shape is the whole gate, and it has exactly one
+ * implementation. <Ads /> is a sibling rather than part of this component because
+ * ad properties come from the site config, state their own consent category and
+ * switch per environment separately — see src/ads.ts.
  */
 import { type AnalyticsStrategy, resolveAnalytics } from '../analytics.ts';
+import GatedTags from './GatedTags.astro';
 // @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 
@@ -36,24 +33,4 @@ const { tags } = enabled
   : { tags: [] };
 ---
 
-{tags.map((tag) => tag.gated
-  ? (
-      <script
-        is:inline
-        type="text/plain"
-        data-vitops-tag
-        data-consent={tag.category}
-        data-strategy={tag.strategy}
-        data-src={tag.src}
-        data-consent-cookies={tag.cookies.length ? tag.cookies.join(',') : undefined}
-        {...tag.attrs}
-        set:html={tag.inline}
-      />
-    )
-  : (
-      <>
-        {tag.inline && <script is:inline set:html={tag.inline} />}
-        {tag.src && <script is:inline async src={tag.src} {...tag.attrs}></script>}
-      </>
-    )
-)}
+<GatedTags tags={tags} />

package/src/components/CookieConsent.astro

@@ -14,6 +14,13 @@
  * writes one — otherwise the thing asking permission would be the thing needing
  * it.
  *
+ * **`categories` is what the banner *can* ask, not what it will.** A row here is
+ * markup, and a hidden row costs nothing, so the default is generous — every
+ * category the site could plausibly gate. `<wc-consent>` reveals only the rows
+ * something has actually demanded and the visitor hasn't answered, so being
+ * generous here buys coverage without buying interruptions. Narrow it only to
+ * refuse a category outright.
+ *
  * **Consent is not an analytics feature.** The same gate covers A/B assignment,
  * personalisation and embedded third-party content: mark any of them
  * `data-consent="<category>"` and they wait on the same choice. Which categories
@@ -50,7 +57,7 @@ const DEFAULT_LABELS: Record<OptionalConsentCategory, string> = {
 };
 
 const {
-  categories = head.consentCategories ?? ['analytics'],
+  categories = head.consentCategories ?? ['analytics', 'preferences'],
   policyUrl = head.consentPolicyUrl ?? undefined,
   policyLabel = 'Cookie notice',
   heading = 'Cookies on this site',
@@ -62,9 +69,6 @@ const {
 } = Astro.props;
 
 const wording = { ...DEFAULT_LABELS, ...labels };
-// One category is a yes/no question; checkboxes for it would be a form standing in
-// for two buttons that already say the same thing.
-const choose = categories.length > 1;
 ---
 
 <wc-consent hidden {...noReloadOnRevoke ? { 'reload-on-revoke': 'false' } : {}}>
@@ -86,20 +90,24 @@ const choose = categories.length > 1;
       {policyUrl && <a class="link" href={policyUrl}>{policyLabel}</a>}
     </div>
 
-    {choose && (
-      <div class="consent__options">
-        {categories.map((category) => (
-          <label>
-            <input type="checkbox" name={category} />
-            {wording[category]}
-          </label>
-        ))}
-      </div>
-    )}
+    {/*
+      A row per offered category, always rendered. Which of them the visitor
+      actually sees is a runtime decision — `data-consent-row` is how
+      `<wc-consent>` addresses one to reveal or hide it, and it hides the whole
+      group when a showing is about a single category.
+    */}
+    <div class="consent__options">
+      {categories.map((category) => (
+        <label data-consent-row={category}>
+          <input type="checkbox" name={category} />
+          {wording[category]}
+        </label>
+      ))}
+    </div>
 
     <div class="consent__actions">
       <button type="button" class="btn" data-consent-reject>{rejectLabel}</button>
-      {choose && <button type="button" class="btn" data-consent-save>{saveLabel}</button>}
+      <button type="button" class="btn" data-consent-save>{saveLabel}</button>
       <button type="button" class="cta" data-consent-accept>{acceptLabel}</button>
     </div>
   </form>

package/src/components/GatedTags.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * <GatedTags /> — the one place a third-party tag becomes markup.
+ *
+ * Shared by <Analytics /> and <Ads />, and shared deliberately: the gate is
+ * `type="text/plain"` with the URL on `data-src`, so the browser never parses the
+ * body as script and never fetches the library. An undecided or declining
+ * visitor's page issues no third-party request at all. Consent implemented by
+ * *asking a tracker not to track* is a promise; this is a fact about the document
+ * — and a fact with two implementations is one rewrite away from being neither.
+ *
+ * Decides nothing. Every tag arrives fully resolved from `analytics.ts` or
+ * `ads.ts`, both of which are pure and unit-tested.
+ *
+ * Emits no `preconnect` on purpose: warming a connection at parse time is exactly
+ * the critical-path cost the `idle` strategy exists to avoid.
+ */
+import type { GatedTag } from '../analytics.ts';
+
+interface Props {
+  tags: GatedTag[];
+}
+const { tags } = Astro.props;
+---
+
+{tags.map((tag) => tag.gated
+  ? (
+      <script
+        is:inline
+        type="text/plain"
+        data-vitops-tag
+        data-consent={tag.category}
+        data-strategy={tag.strategy}
+        data-src={tag.src}
+        data-consent-cookies={tag.cookies.length ? tag.cookies.join(',') : undefined}
+        {...tag.attrs}
+        set:html={tag.inline}
+      />
+    )
+  : (
+      <>
+        {tag.inline && <script is:inline set:html={tag.inline} />}
+        {tag.src && <script is:inline async src={tag.src} {...tag.attrs}></script>}
+      </>
+    )
+)}