@escape-game-over/atlas 0.1.60 → 0.1.62

package/docs/client-scripts.md

@@ -63,9 +63,7 @@ reloads on nearly every back. An inline script at the end of `<body>` saves the
 position on the history entry once scrolling settles, and puts it back before
 the first paint. On the entry, not in storage keyed by URL, so a link to the same
 page still opens at the top. Never on `pagehide`: WebKit fires it after moving to
-the previous entry, and the write wipes the position about to be restored. A
-site on Astro's `ClientRouter` turns it off; the router keeps its own position
-in the same history state.
+the previous entry, and the write wipes the position about to be restored.
 
 **Browser code has one import path: `@escape-game-over/atlas/client`**, which
 re-exports every module above. None of it touches the DOM at import, so an
@@ -102,16 +100,9 @@ undo and then the function again — so it has to be able to run twice. State th
 must survive a move goes in a `WeakMap` keyed by `root`, which is what the
 carousel example does with its index.
 
-**The trap this exists for is view transitions.** A bundled `<script src>` is an
-ES module, cached by URL, so it executes once per session — not once per
-navigation. Bind at module scope with `ClientRouter` on and the incoming page
-gets a live list and dead controls: the markup was swapped, the handlers still
-point at what was there before. Driving `attach` from `astro:page-load` and
-calling its return on teardown is the fix, and it is why none of these modules
-does anything at import time.
-
-Note that the abort half alone does not help. It makes the breakage look
-handled. Without a re-`attach` there is simply nothing wired.
+Astro's `ClientRouter`, which swaps pages without reloading them, is refused at
+build time by `siteRoutes()`: every module here, and every analytics vendor,
+assumes one full page load per navigation.
 
 ## `filters`
 

package/package.json

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

package/src/astro/ConsentBanner.astro

@@ -5,36 +5,37 @@
  * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
- * permission. Also loads the vendors that wait for consent, such as the Meta, TikTok, Snap and Axon pixels, Drip and Clarity. Otherwise the banner starts hidden and shows only to a visitor
+ * permission. 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.
+ *
+ * It also starts the vendors that wait on the answer — the Meta, TikTok, Snap
+ * and Axon pixels, Drip and Clarity — fetching each one's code only once its
+ * category is granted.
  */
 import type { HTMLAttributes } from "astro/types";
 import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";
-import AxonPixel from "./AxonPixel.astro";
-import Clarity from "./Clarity.astro";
 import ConsentElement from "./ConsentElement.astro";
-import Drip from "./Drip.astro";
-import MetaPixel from "./MetaPixel.astro";
-import SnapPixel from "./SnapPixel.astro";
-import TikTokPixel from "./TikTokPixel.astro";
+import type { ConsentVendors } from "./consent-vendors.ts";
 
 type Props = HTMLAttributes<"div"> & {
     readonly analytics: AnalyticsSettings | undefined;
 };
 
 const { analytics, ...attrs } = Astro.props;
+const vendors: ConsentVendors = {
+    meta: analytics?.meta,
+    tiktok: analytics?.tiktok,
+    snapchat: analytics?.snapchat,
+    axon: analytics?.axon,
+    drip: analytics?.drip,
+    clarity: analytics?.clarity,
+};
 ---
 
 {consentRequired(analytics) && (
-    <>
-        <ConsentElement {...attrs}>
-            <slot />
-        </ConsentElement>
-        {analytics?.meta && <MetaPixel settings={analytics.meta} />}
-        {analytics?.tiktok && <TikTokPixel settings={analytics.tiktok} />}
-        {analytics?.snapchat && <SnapPixel settings={analytics.snapchat} />}
-        {analytics?.axon && <AxonPixel settings={analytics.axon} />}
-        {analytics?.drip && <Drip settings={analytics.drip} />}
-        {analytics?.clarity && <Clarity settings={analytics.clarity} />}
-    </>
+    <ConsentElement
+        {...attrs}
+        vendors={vendors}>
+        <slot />
+    </ConsentElement>
 )}

package/src/astro/ConsentElement.astro

@@ -3,15 +3,21 @@
 import type { HTMLAttributes } from "astro/types";
 import AtlasElement from "./AtlasElement.astro";
 import { consentBanner } from "./consent-element.ts";
+import type { ConsentVendors } from "./consent-vendors.ts";
 
-type Props = HTMLAttributes<"div">;
+type Props = HTMLAttributes<"div"> & {
+    readonly vendors: ConsentVendors;
+};
+
+const { vendors, ...attrs } = Astro.props;
 ---
 
 <script src="./consent-element.ts" />
 
 <AtlasElement
     of={consentBanner}
-    {...Astro.props}
+    {...attrs}
+    data-vendors={JSON.stringify(vendors)}
     hidden
     role="dialog"
     aria-modal="false"

package/src/astro/Document.astro

@@ -6,9 +6,7 @@
  * load ahead of the analytics goes there; `head` comes after.
  *
  * It also restores the scroll position on back and reload; see
- * `docs/client-scripts.md`. A site on Astro's `ClientRouter` passes
- * `restoreScroll={false}`: the router keeps its own position in the same
- * history state.
+ * `docs/client-scripts.md`. `restoreScroll={false}` leaves it to the browser.
  *
  * A site with a lead form passes `rememberCampaign`, so the `utm_*` tags a
  * visit landed with survive to the page the form is on; see `attribution.ts`.
@@ -44,10 +42,10 @@ interface Props {
     /** `lang` and `dir` are the page's locale's, from `meta`. */
     readonly html?: Omit<HTMLAttributes<"html">, "lang" | "dir">;
     readonly body?: HTMLAttributes<"body">;
-    /** Defaults to `true`; `false` for a site on `ClientRouter`. */
-    readonly restoreScroll?: boolean;
     /** Off unless stated: a site with no lead form has nothing to keep them for. */
     readonly rememberCampaign?: boolean;
+    /** Defaults to `true`; `false` leaves scroll restoration to the browser. */
+    readonly restoreScroll?: boolean;
     /** Defaults to `true`. */
     readonly rememberLocale?: boolean;
 }
@@ -57,8 +55,8 @@ const {
     fonts = {},
     html,
     body,
-    restoreScroll = true,
     rememberCampaign = false,
+    restoreScroll = true,
     rememberLocale = true,
 } = Astro.props;
 

package/src/astro/axon-pixel.ts

@@ -1,8 +1,5 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
-import { whenGranted } from "./consent-gate.ts";
-import { element } from "./element.ts";
-import { data } from "./ref.ts";
 
 /** Axon's `axon`: a queue until its scripts arrive and replay it. */
 interface Axon {
@@ -62,11 +59,3 @@ export function axonPixel(eventKey: string): ConsentGated {
         },
     };
 }
-
-/** Internal to `AxonPixel.astro`. */
-export const axonPixelElement = element(
-    "atlas-axon-pixel",
-    ({ root, signal }) => {
-        whenGranted("marketing", axonPixel(data(root, "event-key")), signal);
-    }
-);

package/src/astro/clarity.ts

@@ -1,8 +1,5 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentChoices } from "./consent.ts";
-import { withConsent } from "./consent-gate.ts";
-import { element } from "./element.ts";
-import { data } from "./ref.ts";
 
 /** Clarity's `clarity`: a queue until its script arrives and replays it. */
 interface Clarity {
@@ -39,22 +36,18 @@ const consentv2 = (choices: ConsentChoices) => ({
 });
 
 /**
- * Loads Clarity with the answer so far, then passes on every answer. Stated
+ * Clarity, loaded with the first answer passed to what this returns, which
+ * `startVendors` calls with the answer so far and then every new one. Stated
  * even when denied: a Clarity project set to use cookies by default would
  * otherwise set them before anyone was asked.
  */
-export function clarity(projectId: string, signal?: AbortSignal): void {
+export function clarity(projectId: string): (choices: ConsentChoices) => void {
     let loaded = false;
-    withConsent((choices) => {
+    return (choices) => {
         const queue = defineClarity();
         queue("consentv2", consentv2(choices));
         if (loaded) return;
         loaded = true;
         appendScript(`https://www.clarity.ms/tag/${projectId}`);
-    }, signal);
+    };
 }
-
-/** Internal to `Clarity.astro`. */
-export const clarityElement = element("atlas-clarity", ({ root, signal }) => {
-    clarity(data(root, "project-id"), signal);
-});

package/src/astro/consent-element.ts

@@ -7,6 +7,7 @@ import {
     readConsent,
     recordConsent,
 } from "./consent.ts";
+import { startVendors } from "./consent-vendors.ts";
 import { element } from "./element.ts";
 import { data, ref, refs } from "./ref.ts";
 
@@ -38,6 +39,8 @@ import { data, ref, refs } from "./ref.ts";
  * withdraw.
  */
 export const consentBanner = element(CONSENT_TAG, ({ root, signal }) => {
+    startVendors(JSON.parse(data(root, "vendors")), signal);
+
     const boxes = refs<HTMLInputElement>(root, "[data-consent-category]").map(
         (box) => {
             const category = data(box, "consent-category");

package/src/astro/consent-vendors.ts

@@ -0,0 +1,100 @@
+import type { AnalyticsSettings } from "../analytics/index.ts";
+import type { ConsentChoices } from "./consent.ts";
+import { type ConsentGated, whenGranted, withConsent } from "./consent-gate.ts";
+import { reportDevError } from "./dev-log.ts";
+
+/** The vendors the banner starts: the analytics settings loaded in the browser. */
+export type ConsentVendors = Pick<
+    AnalyticsSettings,
+    "meta" | "tiktok" | "snapchat" | "axon" | "drip" | "clarity"
+>;
+
+/**
+ * A vendor whose code is fetched on its first grant, not with the page. Calls
+ * wait on the one import, so they reach the vendor in the order they were made.
+ */
+function lazy(load: () => Promise<ConsentGated>): ConsentGated {
+    let vendor: Promise<ConsentGated | undefined> | undefined;
+    const loaded = () => {
+        vendor ??= load().catch((error) => {
+            reportDevError("consent vendors", error);
+            return undefined;
+        });
+        return vendor;
+    };
+    return {
+        grant: () => {
+            loaded().then((ready) => ready?.grant());
+        },
+        revoke: () => {
+            vendor?.then((ready) => ready?.revoke?.());
+        },
+    };
+}
+
+/**
+ * Starts every configured vendor. Nothing vendor-specific is downloaded until
+ * its consent category is granted — except Clarity, which runs cookieless
+ * without consent and so loads with the page.
+ */
+export function startVendors(
+    vendors: ConsentVendors,
+    signal?: AbortSignal
+): void {
+    const { meta, tiktok, snapchat, axon, drip, clarity } = vendors;
+    if (meta !== undefined) {
+        whenGranted(
+            "marketing",
+            lazy(async () =>
+                (await import("./meta-pixel.ts")).metaPixel(meta.pixelIds)
+            ),
+            signal
+        );
+    }
+    if (tiktok !== undefined) {
+        whenGranted(
+            "marketing",
+            lazy(async () =>
+                (await import("./tiktok-pixel.ts")).tiktokPixel(tiktok.pixelIds)
+            ),
+            signal
+        );
+    }
+    if (snapchat !== undefined) {
+        whenGranted(
+            "marketing",
+            lazy(async () =>
+                (await import("./snap-pixel.ts")).snapPixel(snapchat.pixelIds)
+            ),
+            signal
+        );
+    }
+    if (axon !== undefined) {
+        whenGranted(
+            "marketing",
+            lazy(async () =>
+                (await import("./axon-pixel.ts")).axonPixel(axon.eventKey)
+            ),
+            signal
+        );
+    }
+    if (drip !== undefined) {
+        whenGranted(
+            "marketing",
+            lazy(async () => (await import("./drip.ts")).drip(drip.accountId)),
+            signal
+        );
+    }
+    if (clarity !== undefined) {
+        let apply: Promise<((choices: ConsentChoices) => void) | undefined>;
+        withConsent((choices) => {
+            apply ??= import("./clarity.ts")
+                .then((module) => module.clarity(clarity.projectId))
+                .catch((error) => {
+                    reportDevError("consent vendors", error);
+                    return undefined;
+                });
+            apply.then((ready) => ready?.(choices));
+        }, signal);
+    }
+}

package/src/astro/dev-log.ts

@@ -41,9 +41,9 @@ function panel(): HTMLElement {
     const existing = document.getElementById(PANEL_ID);
     if (existing) return existing;
 
-    // Either nothing has failed yet, or the document this lived in was swapped
-    // out from under it — a client router replacing `<body>`. Either way every
-    // line in `seen` is detached, and counting into one would report nothing.
+    // Either nothing has failed yet, or the panel was removed from the page.
+    // Either way every line in `seen` is detached, and counting into one would
+    // report nothing.
     seen.clear();
 
     const created = document.createElement("div");

package/src/astro/drip.ts

@@ -1,8 +1,5 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
-import { whenGranted } from "./consent-gate.ts";
-import { element } from "./element.ts";
-import { data } from "./ref.ts";
 
 /** Drip's globals: a queue of calls, and the account its script reports to. */
 interface DripWindow {
@@ -30,8 +27,3 @@ export function drip(accountId: string): ConsentGated {
         },
     };
 }
-
-/** Internal to `Drip.astro`. */
-export const dripElement = element("atlas-drip", ({ root, signal }) => {
-    whenGranted("marketing", drip(data(root, "account-id")), signal);
-});

package/src/astro/element.ts

@@ -48,8 +48,8 @@ export interface ElementTag<Tag extends string = string> {
  * template imports the same file.
  *
  * - **An element can enter the page more than once.** Moving it runs the undo
- *   and `connect` again; Astro's `ClientRouter` does so on every navigation.
- *   State that must survive belongs in a `WeakMap` keyed by `root`.
+ *   and `connect` again. State that must survive belongs in a `WeakMap` keyed
+ *   by `root`.
  * - **The page's script must stay a bundled module** (a plain `<script>`), so
  *   the element has its children when it upgrades.
  * - **Failures show in dev.** A `connect` that throws leaves that one element

package/src/astro/filters.ts

@@ -336,8 +336,8 @@ export function filters<const F extends FieldMap, T>(
         const query = parts.join("&");
         // The bare path when nothing is left, rather than a trailing `?`.
         const url = query === "" ? window.location.pathname : `?${query}`;
-        // `null` on a pushed step, so Astro's `ClientRouter` leaves its popstate
-        // to this module; a replaced entry keeps whatever state it already had.
+        // `null` on a pushed step; a replaced entry keeps whatever state it
+        // already had, such as the position `ScrollRestore` saved there.
         if (history === "push") window.history.pushState(null, "", url);
         else window.history.replaceState(window.history.state, "", url);
     }

package/src/astro/meta-pixel.ts

@@ -1,8 +1,5 @@
 import { appendScript } from "./append-script.ts";
 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 {
@@ -64,15 +61,3 @@ export function metaPixel(pixelIds: readonly string[]): ConsentGated {
         },
     };
 }
-
-/** 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/astro/no-client-router.ts

@@ -0,0 +1,35 @@
+import type { Plugin } from "vite";
+
+/** What a site imports to turn Astro's `ClientRouter` on. */
+const CLIENT_ROUTER = new Set([
+    "astro:transitions",
+    "astro/components/ClientRouter.astro",
+]);
+
+/**
+ * Fails the build when a site imports `ClientRouter`.
+ *
+ * Atlas assumes a full page load per navigation: analytics count a page view
+ * per load, vendor scripts and widgets start once per page, and nothing tears
+ * them down. Under the router none of that holds, and nothing errors — the
+ * numbers and the widgets just go quietly wrong. The animation it gives is
+ * available without it: `@view-transition { navigation: auto; }` in CSS.
+ *
+ * Only the site's own imports are checked. Astro and other packages may name
+ * the module for their own reasons.
+ */
+export function noClientRouter(): Plugin {
+    return {
+        name: "atlas:no-client-router",
+        enforce: "pre",
+        resolveId(id, importer) {
+            if (!CLIENT_ROUTER.has(id)) return null;
+            if (importer === undefined || importer.includes("/node_modules/")) {
+                return null;
+            }
+            throw new Error(
+                `${importer} imports ${id}. Astro's ClientRouter is not supported: Atlas's analytics, consent and widgets expect a full page load per navigation. For the animation, use cross-document view transitions — \`@view-transition { navigation: auto; }\` in CSS.`
+            );
+        },
+    };
+}

package/src/astro/site-routes.ts

@@ -11,6 +11,7 @@ import type { Sitemap } from "../sitemap.ts";
 import type { HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
 import { buildCacheDir } from "./build-cache.ts";
+import { noClientRouter } from "./no-client-router.ts";
 
 /**
  * What this integration needs of a site, and no more.
@@ -282,7 +283,12 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                     },
                     cacheDir: buildCacheDir(),
                 };
-                updateConfig(config);
+                // The plugin is kept out of `config`, which is logged below: a
+                // plugin prints as noise.
+                updateConfig({
+                    ...config,
+                    vite: { plugins: [noClientRouter()] },
+                });
                 // Said out loud: a setting changed from under you is worth a
                 // line, and reading `astro.config.ts` would otherwise leave you
                 // to wonder why the output is not shaped the way its defaults

package/src/astro/snap-pixel.ts

@@ -1,8 +1,5 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
-import { whenGranted } from "./consent-gate.ts";
-import { element } from "./element.ts";
-import { data } from "./ref.ts";
 
 /** Snap's `snaptr`: a queue until `scevent.min.js` arrives and replays it. */
 interface Snaptr {
@@ -55,15 +52,3 @@ export function snapPixel(pixelIds: readonly string[]): ConsentGated {
         },
     };
 }
-
-/** Internal to `SnapPixel.astro`. */
-export const snapPixelElement = element(
-    "atlas-snap-pixel",
-    ({ root, signal }) => {
-        whenGranted(
-            "marketing",
-            snapPixel(JSON.parse(data(root, "pixel-ids"))),
-            signal
-        );
-    }
-);

package/src/astro/tiktok-pixel.ts

@@ -1,8 +1,5 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
-import { whenGranted } from "./consent-gate.ts";
-import { element } from "./element.ts";
-import { data } from "./ref.ts";
 
 /** TikTok's `ttq`: a queue of calls until `events.js` arrives and replays it. */
 interface Ttq extends Array<unknown> {
@@ -98,15 +95,3 @@ export function tiktokPixel(pixelIds: readonly string[]): ConsentGated {
         },
     };
 }
-
-/** Internal to `TikTokPixel.astro`. */
-export const tiktokPixelElement = element(
-    "atlas-tiktok-pixel",
-    ({ root, signal }) => {
-        whenGranted(
-            "marketing",
-            tiktokPixel(JSON.parse(data(root, "pixel-ids"))),
-            signal
-        );
-    }
-);

package/src/astro/AxonPixel.astro

@@ -1,18 +0,0 @@
----
-/** Internal to `ConsentBanner.astro`, so the pixel's script ships only where it is configured. */
-import type { AxonPixelSettings } from "../analytics/axon-pixel.ts";
-import AtlasElement from "./AtlasElement.astro";
-import { axonPixelElement } from "./axon-pixel.ts";
-
-interface Props {
-    readonly settings: AxonPixelSettings;
-}
----
-
-<script src="./axon-pixel.ts" />
-
-<AtlasElement
-    of={axonPixelElement}
-    data-event-key={Astro.props.settings.eventKey}
-    hidden
-/>

package/src/astro/Clarity.astro

@@ -1,18 +0,0 @@
----
-/** Internal to `ConsentBanner.astro`, so Clarity's script ships only where it is configured. */
-import type { ClaritySettings } from "../analytics/clarity.ts";
-import AtlasElement from "./AtlasElement.astro";
-import { clarityElement } from "./clarity.ts";
-
-interface Props {
-    readonly settings: ClaritySettings;
-}
----
-
-<script src="./clarity.ts" />
-
-<AtlasElement
-    of={clarityElement}
-    data-project-id={Astro.props.settings.projectId}
-    hidden
-/>

package/src/astro/Drip.astro

@@ -1,18 +0,0 @@
----
-/** Internal to `ConsentBanner.astro`, so Drip's script ships only where it is configured. */
-import type { DripSettings } from "../analytics/drip.ts";
-import AtlasElement from "./AtlasElement.astro";
-import { dripElement } from "./drip.ts";
-
-interface Props {
-    readonly settings: DripSettings;
-}
----
-
-<script src="./drip.ts" />
-
-<AtlasElement
-    of={dripElement}
-    data-account-id={Astro.props.settings.accountId}
-    hidden
-/>

package/src/astro/MetaPixel.astro

@@ -1,18 +0,0 @@
----
-/** 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/SnapPixel.astro

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

package/src/astro/TikTokPixel.astro

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