@escape-game-over/atlas 0.1.53 → 0.1.55

package/docs/client-scripts.md

@@ -43,7 +43,8 @@ finding them.
 | `element`          | registering a custom element, and ending what it started       | what the element does while it is on the page   |
 
 `consent` is the one module that ships its own behaviour: `<ConsentBanner
-analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`) renders the
+slot="consent" analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`),
+passed to `Document`, which fails the build when a page needs one and has none. It renders the
 site's markup as its children, skips itself — script included — when the
 analytics need no permission, and remembers, expires and applies the answer. The
 answer is two, one per category: `analytics` (Google's `analytics_storage`) and

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.53",
+    "version": "0.1.55",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/index.ts

@@ -1,6 +1,7 @@
 import type { MetaTag } from "../meta/tag.ts";
 import type { HttpsUrl } from "../url.ts";
 import { type GoogleSettings, googleEmits, googleScripts } from "./google.ts";
+import { checkMetaPixel, type MetaPixelSettings } from "./meta-pixel.ts";
 import type { AnalyticsTags } from "./tags.ts";
 import {
     checkUmamiDomains,
@@ -29,6 +30,7 @@ export {
     type ConsentState,
     type GoogleSettings,
 } from "./google.ts";
+export type { MetaPixelSettings } from "./meta-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";
 export type {
     UmamiReplay,
@@ -40,6 +42,8 @@ export type {
 export interface AnalyticsSettings {
     readonly umami?: UmamiSettings;
     readonly google?: GoogleSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly meta?: MetaPixelSettings;
 }
 
 /**
@@ -60,6 +64,7 @@ export function analyticsScripts(
     if (analytics === undefined) return { head: [], body: [] };
 
     checkUmamiDomains(analytics.umami, origin);
+    checkMetaPixel(analytics.meta, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -70,7 +75,7 @@ export function analyticsScripts(
 }
 
 /**
- * Whether this deployment loads anything a visitor has to be asked about.
+ * The vendors this deployment loads that a visitor has to be asked about.
  *
  * The one place that question is answered, and at build time: a project leaves
  * the banner — script and all — out of the HTML, rather than shipping a script
@@ -88,19 +93,30 @@ export function analyticsScripts(
  * permission — which is the failure worth having, since the alternative is a
  * new vendor silently setting cookies behind a banner that never appears.
  */
-export function consentRequired(
+export function consentVendors(
     analytics: AnalyticsSettings | undefined
-): boolean {
-    if (analytics === undefined) return false;
+): readonly (keyof AnalyticsSettings)[] {
+    if (analytics === undefined) return [];
 
     const VENDORS: Readonly<Record<keyof AnalyticsSettings, boolean>> = {
         // Cookieless by design — nothing to permit, nothing to withdraw.
         umami: false,
         // Consent Mode, but only once there is a tag reading it.
         google: googleEmits(analytics.google),
+        // No cookieless mode: nothing loads until marketing is granted.
+        meta: analytics.meta !== undefined,
     };
 
-    return Object.values(VENDORS).some(Boolean);
+    return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(
+        (vendor) => VENDORS[vendor]
+    );
+}
+
+/** Whether any vendor this deployment loads needs permission. */
+export function consentRequired(
+    analytics: AnalyticsSettings | undefined
+): boolean {
+    return consentVendors(analytics).length > 0;
 }
 
 /**

package/src/analytics/meta-pixel.ts

@@ -0,0 +1,23 @@
+import type { NonEmpty } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/** Meta's pixel. Marketing: it loads only once a visitor grants that. */
+export interface MetaPixelSettings {
+    /** From Events Manager: 15 or 16 digits. Several share one script. */
+    readonly pixelIds: NonEmpty<string>;
+}
+
+/** Warns about an id that is not a pixel id: it would report nowhere. */
+export function checkMetaPixel(
+    meta: MetaPixelSettings | undefined,
+    at: string
+): void {
+    for (const id of meta?.pixelIds ?? []) {
+        if (!/^\d{15,16}$/.test(id)) {
+            warn(
+                at,
+                `Meta pixel id "${id}" is not 15 or 16 digits, so it reports nowhere. Copy it from Events Manager.`
+            );
+        }
+    }
+}

package/src/astro/ConsentBanner.astro

@@ -5,12 +5,13 @@
  * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
- * permission. Otherwise the banner starts hidden and shows only to a visitor
+ * permission. Also loads the vendors that wait for consent, such as Meta's pixel. Otherwise the banner starts hidden and shows only to a visitor
  * with no answer on record, or when a `data-consent-reopen` control is pressed.
  */
 import type { HTMLAttributes } from "astro/types";
 import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";
 import ConsentElement from "./ConsentElement.astro";
+import MetaPixel from "./MetaPixel.astro";
 
 type Props = HTMLAttributes<"div"> & {
     readonly analytics: AnalyticsSettings | undefined;
@@ -20,7 +21,10 @@ const { analytics, ...attrs } = Astro.props;
 ---
 
 {consentRequired(analytics) && (
-    <ConsentElement {...attrs}>
-        <slot />
-    </ConsentElement>
+    <>
+        <ConsentElement {...attrs}>
+            <slot />
+        </ConsentElement>
+        {analytics?.meta && <MetaPixel settings={analytics.meta} />}
+    </>
 )}

package/src/astro/Document.astro

@@ -16,6 +16,9 @@
  * It sends a reader arriving from elsewhere to the page in the language they
  * last chose; see `RememberLocale.astro`. `rememberLocale={false}` turns it off.
  *
+ * A deployment whose analytics need permission must pass its banner in the
+ * `consent` slot — `<ConsentBanner slot="consent" …>` — or the build fails.
+ *
  * `fonts={site.fonts}` writes the `@font-face` rules and preloads for the
  * faces `siteFonts(site)` registered in the Astro config.
  *
@@ -58,6 +61,12 @@ const {
     rememberCampaign = false,
     rememberLocale = true,
 } = Astro.props;
+
+if (meta.consentVendors.length > 0 && !Astro.slots.has("consent")) {
+    throw new Error(
+        `${meta.consentVendors.join(", ")} ${meta.consentVendors.length === 1 ? "needs" : "need"} permission, but this page has no consent banner. Pass one to Document: <ConsentBanner slot="consent" …>.`
+    );
+}
 ---
 
 <!doctype html>
@@ -81,6 +90,7 @@ const {
     <body {...body}>
         <MetaTags tags={meta.bodyTags} />
         <slot />
+        <slot name="consent" />
         {restoreScroll && <ScrollRestore />}
         {rememberCampaign && <RememberCampaign />}
     </body>

package/src/astro/MetaPixel.astro

@@ -0,0 +1,18 @@
+---
+/** Internal to `ConsentBanner.astro`, so the pixel's script ships only where it is configured. */
+import type { MetaPixelSettings } from "../analytics/meta-pixel.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { metaPixelElement } from "./meta-pixel.ts";
+
+interface Props {
+    readonly settings: MetaPixelSettings;
+}
+---
+
+<script src="./meta-pixel.ts" />
+
+<AtlasElement
+    of={metaPixelElement}
+    data-pixel-ids={JSON.stringify(Astro.props.settings.pixelIds)}
+    hidden
+/>

package/src/astro/client.ts

@@ -23,6 +23,7 @@ export {
 } from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
+export * from "./meta-event.ts";
 export { data, ref, refs } from "./ref.ts";
 export * from "./umami-event.ts";
 export * from "./youtube.ts";

package/src/astro/consent-gate.ts

@@ -0,0 +1,48 @@
+import {
+    CONSENT_EVENT,
+    type ConsentCategory,
+    type ConsentChoices,
+    readConsent,
+} from "./consent.ts";
+
+/** What a vendor does as its category is granted and withdrawn. */
+export interface ConsentGated {
+    /** After `load`, each time the category is granted: a stored answer, or one given now. */
+    readonly grant: () => void;
+    /** Each time a grant is withdrawn on this page. */
+    readonly revoke?: () => void;
+}
+
+/** Runs `vendor` as the visitor's answer for `category` says, until `signal` aborts. */
+export function whenGranted(
+    category: ConsentCategory,
+    vendor: ConsentGated,
+    signal?: AbortSignal
+): void {
+    let granted = readConsent()?.[category] === "granted";
+
+    // After `load`, so a vendor does not compete with the page. Checked again
+    // then: an answer withdrawn before `load` cancels the grant.
+    const grantAfterLoad = () => {
+        const run = () => {
+            if (granted) vendor.grant();
+        };
+        if (document.readyState === "complete") run();
+        else addEventListener("load", run, { once: true, signal });
+    };
+
+    if (granted) grantAfterLoad();
+
+    addEventListener(
+        CONSENT_EVENT,
+        (event) => {
+            const choices = (event as CustomEvent<ConsentChoices>).detail;
+            const now = choices[category] === "granted";
+            if (now === granted) return;
+            granted = now;
+            if (now) grantAfterLoad();
+            else vendor.revoke?.();
+        },
+        { signal }
+    );
+}

package/src/astro/meta-event.ts

@@ -0,0 +1,61 @@
+import type { CurrencyCode } from "../money.ts";
+
+/** Meta's standard events, which its ad optimisation understands by name. */
+export type MetaStandardEvent =
+    | "AddPaymentInfo"
+    | "AddToCart"
+    | "AddToWishlist"
+    | "CompleteRegistration"
+    | "Contact"
+    | "CustomizeProduct"
+    | "Donate"
+    | "FindLocation"
+    | "InitiateCheckout"
+    | "Lead"
+    | "Purchase"
+    | "Schedule"
+    | "Search"
+    | "StartTrial"
+    | "SubmitApplication"
+    | "Subscribe"
+    | "ViewContent";
+
+/** Meta's standard parameters. What the visitor chose, never who they are. */
+export interface MetaEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+    readonly content_name?: string;
+    readonly content_category?: string;
+    readonly content_ids?: readonly string[];
+    readonly content_type?: "product" | "product_group";
+    readonly num_items?: number;
+    readonly search_string?: string;
+    readonly status?: boolean;
+}
+
+/** `Purchase` is the one event Meta rejects without a value and currency. */
+type MetaEventArgs<E extends MetaStandardEvent> = E extends "Purchase"
+    ? [data: MetaEventData & { value: number; currency: CurrencyCode }]
+    : [data?: MetaEventData];
+
+/** What `meta-pixel.ts` defines once marketing is granted. */
+interface MetaWindow {
+    fbq?: (...args: unknown[]) => void;
+}
+
+/**
+ * Records a standard event with Meta's pixel — a lead sent, a booking made.
+ *
+ * `fbq` exists only once the visitor granted marketing and the pixel loaded.
+ * Before that, without consent, or where Meta is not configured, the event is
+ * dropped: no consent means nothing to send, and an analytics call must never
+ * be the reason a page misbehaves.
+ */
+export function metaEvent<E extends MetaStandardEvent>(
+    event: E,
+    ...[data]: MetaEventArgs<E>
+): void {
+    const fbq = (window as unknown as MetaWindow).fbq;
+    if (data === undefined) fbq?.("track", event);
+    else fbq?.("track", event, data);
+}

package/src/astro/meta-pixel.ts

@@ -0,0 +1,76 @@
+import type { ConsentGated } from "./consent-gate.ts";
+import { whenGranted } from "./consent-gate.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** Meta's `fbq`: a queue until `fbevents.js` arrives and replays it. */
+interface Fbq {
+    (...args: unknown[]): void;
+    callMethod?: (...args: unknown[]) => void;
+    queue: unknown[];
+    push: Fbq;
+    loaded: boolean;
+    version: string;
+}
+
+interface PixelWindow {
+    fbq?: Fbq;
+    _fbq?: Fbq;
+}
+
+const SCRIPT = "https://connect.facebook.net/en_US/fbevents.js";
+
+/** Meta's own base code, as it defines `fbq` before the script loads. */
+function defineFbq(): Fbq {
+    const global = window as unknown as PixelWindow;
+    if (global.fbq !== undefined) return global.fbq;
+    const fbq = function () {
+        // biome-ignore lint/complexity/noArguments: Meta's queue takes the arguments object, as its snippet pushes it.
+        if (fbq.callMethod) Reflect.apply(fbq.callMethod, fbq, arguments);
+        // biome-ignore lint/complexity/noArguments: as above.
+        else fbq.queue.push(arguments);
+    } as Fbq;
+    fbq.push = fbq;
+    fbq.loaded = true;
+    fbq.version = "2.0";
+    fbq.queue = [];
+    global.fbq = fbq;
+    global._fbq ??= fbq;
+    return fbq;
+}
+
+/** The pixel: loaded on the first grant, paused and resumed by later answers. */
+export function metaPixel(pixelIds: readonly string[]): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            const fbq = defineFbq();
+            if (loaded) {
+                fbq("consent", "grant");
+                return;
+            }
+            loaded = true;
+            for (const id of pixelIds) fbq("init", id);
+            fbq("track", "PageView");
+            const script = document.createElement("script");
+            script.async = true;
+            script.src = SCRIPT;
+            document.head.append(script);
+        },
+        revoke: () => {
+            (window as unknown as PixelWindow).fbq?.("consent", "revoke");
+        },
+    };
+}
+
+/** Internal to `MetaPixel.astro`. */
+export const metaPixelElement = element(
+    "atlas-meta-pixel",
+    ({ root, signal }) => {
+        whenGranted(
+            "marketing",
+            metaPixel(JSON.parse(data(root, "pixel-ids"))),
+            signal
+        );
+    }
+);

package/src/index.ts

@@ -26,7 +26,9 @@ export {
     type ConsentDefaults,
     type ConsentState,
     consentRequired,
+    consentVendors,
     type GoogleSettings,
+    type MetaPixelSettings,
     type UmamiReplay,
     type UmamiSettings,
     type UmamiTracker,

package/src/site/create.ts

@@ -1,3 +1,4 @@
+import { consentVendors } from "../analytics/index.ts";
 import {
     type LocaleMeta,
     type LocalesOf,
@@ -342,6 +343,8 @@ export function createSite<
             // Nothing. The body channel exists for Tag Manager's `<noscript>`,
             // and no Google tag reaches this page.
             bodyTags: [],
+            // Umami only, which asks nobody.
+            consentVendors: [],
         };
     }
 
@@ -418,6 +421,7 @@ export function createSite<
             dir: localeMeta[locale].dir,
             tags: document.head,
             bodyTags: document.body,
+            consentVendors: consentVendors(project.analytics),
         };
     }
 

package/src/site/page.ts

@@ -65,6 +65,8 @@ export interface PageMeta {
      * both, and cannot put either in the other's place.
      */
     readonly bodyTags: MetaTag[];
+    /** The vendors that need a consent banner on this page; `Document` fails without one. */
+    readonly consentVendors: readonly string[];
 }
 
 /**