@escape-game-over/atlas 0.1.61 → 0.1.63

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.61",
+    "version": "0.1.63",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/axon-pixel.ts

@@ -1,5 +1,4 @@
-import { warn } from "../warn.ts";
-import { UUID } from "./snap-pixel.ts";
+import { invalidId, UUID, type Uuid } from "./ids.ts";
 
 /**
  * AppLovin's Axon pixel. Marketing: it loads only once a visitor grants that.
@@ -9,17 +8,17 @@ import { UUID } from "./snap-pixel.ts";
  */
 export interface AxonPixelSettings {
     /** From the Axon dashboard: a UUID. */
-    readonly eventKey: string;
+    readonly eventKey: Uuid;
 }
 
-/** Warns about a key that is not an event key: it would report nowhere. */
+/** Fails the build on a key that is not an event key: it would report nowhere. */
 export function checkAxonPixel(
     axon: AxonPixelSettings | undefined,
     at: string
 ): void {
     if (axon === undefined || UUID.test(axon.eventKey)) return;
-    warn(
+    invalidId(
         at,
-        `Axon event key "${axon.eventKey}" is not a UUID, so it reports nowhere. Copy it from the Axon dashboard.`
+        `Axon event key "${axon.eventKey}" is not a UUID, so it would report nowhere. Copy it from the Axon dashboard.`
     );
 }

package/src/analytics/clarity.ts

@@ -1,4 +1,4 @@
-import { warn } from "../warn.ts";
+import { CLARITY_PROJECT_ID, invalidId } from "./ids.ts";
 
 /**
  * Microsoft Clarity. It has a cookieless mode, so like Google it loads for
@@ -14,16 +14,16 @@ export interface ClaritySettings {
     readonly projectId: string;
 }
 
-/** Warns about an id that is not a project id: it would report nowhere. */
+/** Fails the build on an id that is not a project id: it would report nowhere. */
 export function checkClarity(
     clarity: ClaritySettings | undefined,
     at: string
 ): void {
-    if (clarity === undefined || /^[a-z0-9]{10}$/.test(clarity.projectId)) {
+    if (clarity === undefined || CLARITY_PROJECT_ID.test(clarity.projectId)) {
         return;
     }
-    warn(
+    invalidId(
         at,
-        `Clarity project id "${clarity.projectId}" is not 10 lowercase letters and digits, so it reports nowhere. Copy it from the Clarity project's settings.`
+        `Clarity project id "${clarity.projectId}" is not 10 lowercase letters and digits, so it would report nowhere. Copy it from the Clarity project's settings.`
     );
 }

package/src/analytics/drip.ts

@@ -1,4 +1,4 @@
-import { warn } from "../warn.ts";
+import { DRIP_ACCOUNT_ID, invalidId, type NumericId } from "./ids.ts";
 
 /**
  * Drip's site tracking. Marketing: it loads only once a visitor grants that.
@@ -7,14 +7,14 @@ import { warn } from "../warn.ts";
  */
 export interface DripSettings {
     /** From Drip's Site Setup: digits, the `_dcs.account` of its snippet. */
-    readonly accountId: string;
+    readonly accountId: NumericId;
 }
 
-/** Warns about an id that is not an account id: it would report nowhere. */
+/** Fails the build on an id that is not an account id: it would report nowhere. */
 export function checkDrip(drip: DripSettings | undefined, at: string): void {
-    if (drip === undefined || /^\d+$/.test(drip.accountId)) return;
-    warn(
+    if (drip === undefined || DRIP_ACCOUNT_ID.test(drip.accountId)) return;
+    invalidId(
         at,
-        `Drip account id "${drip.accountId}" is not all digits, so it reports nowhere. Copy it from Drip's Site Setup.`
+        `Drip account id "${drip.accountId}" is not all digits, so it would report nowhere. Copy it from Drip's Site Setup.`
     );
 }

package/src/analytics/google.ts

@@ -7,6 +7,7 @@ import {
     type ConsentCategory,
 } from "./consent-storage.ts";
 import googleTag from "./google-tag.ts?raw";
+import { type GoogleTagId, invalidId, type TagManagerId } from "./ids.ts";
 import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
@@ -108,7 +109,7 @@ export interface GoogleSettings {
      * once, for the first, and the rest are configured against it — Google's
      * documented arrangement.
      */
-    readonly tagIds?: readonly string[];
+    readonly tagIds?: readonly GoogleTagId[];
     /**
      * Tag Manager container ids — `GTM-XXXXXXX`.
      *
@@ -117,7 +118,7 @@ export interface GoogleSettings {
      * which is most of why they are worth stating — they apply to tags nobody
      * here has seen.
      */
-    readonly containerIds?: readonly string[];
+    readonly containerIds?: readonly TagManagerId[];
     /**
      * What holds before a visitor has chosen. **Denied unless stated.**
      *
@@ -371,20 +372,21 @@ export function googleScripts(
     const containers = google.containerIds ?? [];
 
     // An id in the wrong field is the silent failure here: it is configured,
-    // it is emitted, and it reports nowhere — which reads as a quiet week.
+    // it is emitted, and it reports nowhere — which reads as a quiet week. So
+    // the build fails rather than warns.
     for (const id of tags) {
         if (id.startsWith("UA-")) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" is a Universal Analytics property, and those stopped processing data on 1 July 2023 (1 July 2024 for 360). It reports nowhere. The GA4 property that replaced it starts with "G-". https://support.google.com/analytics/answer/11583528`
             );
         } else if (id.startsWith("GTM-")) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" is a Tag Manager container, not something gtag can configure — it belongs in containerIds.`
             );
         } else if (!GTAG_PREFIXES.some((prefix) => id.startsWith(prefix))) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" does not look like anything gtag configures: those start with ${GTAG_PREFIXES.join(", ")}.`
             );
@@ -392,7 +394,7 @@ export function googleScripts(
     }
     for (const id of containers) {
         if (!id.startsWith("GTM-")) {
-            warn(
+            invalidId(
                 at,
                 `"${id}" is configured as a Tag Manager container but does not look like one — those start with "GTM-".`
             );

package/src/analytics/ids.ts

@@ -0,0 +1,41 @@
+/**
+ * What an analytics id is declared as, and the error a wrong one raises.
+ *
+ * A wrong id fails silently — configured, emitted, reporting nowhere — so the
+ * build fails instead of warning: an id is config, and there is no page worth
+ * shipping with one that is wrong.
+ */
+
+/**
+ * The shapes an id's setting is declared with. As close as a type can get
+ * without a literal to inspect: a UUID's dashes, a Google prefix, digits. The
+ * exact format is checked when a page is built, and a wrong id fails the build.
+ */
+export type Uuid = `${string}-${string}-${string}-${string}-${string}`;
+/** A `gtag` id: GA4 `G-`, Google tag `GT-`, Ads `AW-`, Floodlight `DC-`. */
+export type GoogleTagId = `${"G" | "GT" | "AW" | "DC"}-${string}`;
+/** A Tag Manager container. */
+export type TagManagerId = `GTM-${string}`;
+/** An id that is a number written out: Meta's pixels, Drip's accounts. */
+export type NumericId = `${number}`;
+
+/** The error for an id that is not what its vendor issues. */
+export function invalidId(at: string, message: string): never {
+    throw new Error(`${at}: ${message}`);
+}
+
+/** A Meta pixel id: 15 or 16 digits. */
+export const META_PIXEL_ID = /^\d{15,16}$/;
+
+/** A TikTok pixel id: 20 capital letters and digits. */
+export const TIKTOK_PIXEL_ID = /^[A-Z0-9]{20}$/;
+
+/** A Drip account id: digits. */
+export const DRIP_ACCOUNT_ID = /^\d+$/;
+
+/** A Clarity project id: 10 lowercase letters and digits. */
+export const CLARITY_PROJECT_ID = /^[a-z0-9]{10}$/;
+
+/** A UUID, as Umami, Snap and Axon issue them. */
+export const UUID =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/src/analytics/index.ts

@@ -38,6 +38,7 @@ export {
     type ConsentState,
     type GoogleSettings,
 } from "./google.ts";
+export type { GoogleTagId, NumericId, TagManagerId, Uuid } from "./ids.ts";
 export type { MetaPixelSettings } from "./meta-pixel.ts";
 export type { SnapPixelSettings } from "./snap-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";

package/src/analytics/meta-pixel.ts

@@ -1,5 +1,5 @@
 import type { NonEmpty } from "../types.ts";
-import { warn } from "../warn.ts";
+import { invalidId, META_PIXEL_ID, type NumericId } from "./ids.ts";
 
 /**
  * Meta's pixel. Marketing: it loads only once a visitor grants that.
@@ -10,19 +10,19 @@ import { warn } from "../warn.ts";
  */
 export interface MetaPixelSettings {
     /** From Events Manager: 15 or 16 digits. Several share one script. */
-    readonly pixelIds: NonEmpty<string>;
+    readonly pixelIds: NonEmpty<NumericId>;
 }
 
-/** Warns about an id that is not a pixel id: it would report nowhere. */
+/** Fails the build on 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(
+        if (!META_PIXEL_ID.test(id)) {
+            invalidId(
                 at,
-                `Meta pixel id "${id}" is not 15 or 16 digits, so it reports nowhere. Copy it from Events Manager.`
+                `Meta pixel id "${id}" is not 15 or 16 digits, so it would report nowhere. Copy it from Events Manager.`
             );
         }
     }

package/src/analytics/snap-pixel.ts

@@ -1,5 +1,5 @@
 import type { NonEmpty } from "../types.ts";
-import { warn } from "../warn.ts";
+import { invalidId, UUID, type Uuid } from "./ids.ts";
 
 /**
  * Snapchat's pixel. Marketing: it loads only once a visitor grants that.
@@ -9,22 +9,19 @@ import { warn } from "../warn.ts";
  */
 export interface SnapPixelSettings {
     /** From Snap's Events Manager: a UUID. */
-    readonly pixelIds: NonEmpty<string>;
+    readonly pixelIds: NonEmpty<Uuid>;
 }
 
-export const UUID =
-    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/** Warns about an id that is not a pixel id: it would report nowhere. */
+/** Fails the build on an id that is not a pixel id: it would report nowhere. */
 export function checkSnapPixel(
     snapchat: SnapPixelSettings | undefined,
     at: string
 ): void {
     for (const id of snapchat?.pixelIds ?? []) {
         if (!UUID.test(id)) {
-            warn(
+            invalidId(
                 at,
-                `Snap pixel id "${id}" is not a UUID, so it reports nowhere. Copy it from Snap's Events Manager.`
+                `Snap pixel id "${id}" is not a UUID, so it would report nowhere. Copy it from Snap's Events Manager.`
             );
         }
     }

package/src/analytics/tiktok-pixel.ts

@@ -1,5 +1,5 @@
 import type { NonEmpty } from "../types.ts";
-import { warn } from "../warn.ts";
+import { invalidId, TIKTOK_PIXEL_ID } from "./ids.ts";
 
 /**
  * TikTok's pixel. Marketing: it loads only once a visitor grants that.
@@ -13,16 +13,16 @@ export interface TikTokPixelSettings {
     readonly pixelIds: NonEmpty<string>;
 }
 
-/** Warns about an id that is not a pixel id: it would report nowhere. */
+/** Fails the build on an id that is not a pixel id: it would report nowhere. */
 export function checkTikTokPixel(
     tiktok: TikTokPixelSettings | undefined,
     at: string
 ): void {
     for (const id of tiktok?.pixelIds ?? []) {
-        if (!/^[A-Z0-9]{20}$/.test(id)) {
-            warn(
+        if (!TIKTOK_PIXEL_ID.test(id)) {
+            invalidId(
                 at,
-                `TikTok pixel id "${id}" is not 20 capital letters and digits, so it reports nowhere. Copy it from TikTok Events Manager.`
+                `TikTok pixel id "${id}" is not 20 capital letters and digits, so it would report nowhere. Copy it from TikTok Events Manager.`
             );
         }
     }

package/src/analytics/umami.ts

@@ -2,6 +2,7 @@ import type { MetaTag } from "../meta/tag.ts";
 import type { NonEmpty } from "../types.ts";
 import { type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
 import { warn } from "../warn.ts";
+import { invalidId, UUID, type Uuid } from "./ids.ts";
 import { preconnect } from "./tags.ts";
 
 /**
@@ -102,7 +103,7 @@ export interface UmamiSettings {
      * single site, and nobody notices until one venue's traffic appears to
      * double the week another launches.
      */
-    readonly websiteId: string;
+    readonly websiteId: Uuid;
     /**
      * Where the scripts are served from — `https://src.example.com`.
      *
@@ -188,7 +189,8 @@ const stated = (
     ) as Readonly<Record<string, string>>;
 
 /**
- * Warns when the `domains` list leaves out the host the site is served from.
+ * Fails the build on a website id that is not a UUID, and warns when the
+ * `domains` list leaves out the host the site is served from.
  *
  * Separate from building the scripts because the pages are not the only thing
  * that builds them — the 404 does too — and a check that ran per caller would
@@ -207,6 +209,12 @@ export function checkUmamiDomains(
     origin: HttpsUrl
 ): void {
     if (umami === undefined) return;
+    if (!UUID.test(umami.websiteId)) {
+        invalidId(
+            origin,
+            `Umami website id "${umami.websiteId}" is not a UUID, so it would record nowhere. Copy it from the Umami dashboard.`
+        );
+    }
     const site = new URL(origin).hostname;
     if (umami.domains.includes(site)) return;
 

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/append-script.ts

@@ -1,8 +1,14 @@
-/** Fetches a vendor's script without blocking the page. */
-export function appendScript(src: string): HTMLScriptElement {
+/**
+ * Fetches a vendor's script without blocking the page: into `<head>`, or into
+ * `into` for a widget that renders where its script stands.
+ */
+export function appendScript(
+    src: string,
+    into: Element = document.head
+): HTMLScriptElement {
     const script = document.createElement("script");
     script.async = true;
     script.src = src;
-    document.head.append(script);
+    into.append(script);
     return script;
 }

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/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/google-map.ts

@@ -3,6 +3,7 @@ import type { MapFrame } from "../map.ts";
 import { appendScript } from "./append-script.ts";
 import { reportDevError } from "./dev-log.ts";
 import { element } from "./element.ts";
+import { triggered } from "./load-script.ts";
 import { data } from "./ref.ts";
 
 /** What `GoogleMap.astro` hands the element, serialised. */
@@ -121,18 +122,10 @@ export const googleMap = element("atlas-google-map", ({ root, signal }) => {
         draw(root, config).catch((error) => reportDevError("GoogleMap", error));
     };
 
-    if (config.load === "click") {
-        root.addEventListener("click", show, { once: true, signal });
-        return;
-    }
-    const observer = new IntersectionObserver(
-        (entries) => {
-            if (!entries.some((entry) => entry.isIntersecting)) return;
-            observer.disconnect();
-            show();
-        },
-        { rootMargin: "200px" }
-    );
-    observer.observe(root);
-    return () => observer.disconnect();
+    triggered(
+        config.load === "click"
+            ? { on: "click", element: root }
+            : { on: "visible", element: root },
+        signal
+    ).then(show);
 });

package/src/astro/load-script.ts

@@ -0,0 +1,145 @@
+import { appendScript } from "./append-script.ts";
+
+/** When a script is fetched. All but `click` also wait for the page's `load`. */
+export type LoadTrigger =
+    /** At `load`. */
+    | { readonly on: "load" }
+    /** After `load`, once the browser has nothing else to do. */
+    | { readonly on: "idle" }
+    /** After `load`, `ms` later. */
+    | { readonly on: "delay"; readonly ms: number }
+    /** When `element` comes within `margin` of the viewport. */
+    | {
+          readonly on: "visible";
+          readonly element: Element;
+          readonly margin?: string;
+      }
+    /** At the visitor's first tap, click, key or scroll anywhere. */
+    | { readonly on: "interaction" }
+    /** When `element` is clicked: a visitor asking for it. */
+    | { readonly on: "click"; readonly element: Element };
+
+export interface LoadScriptOptions {
+    readonly when: LoadTrigger;
+    /** Where the script goes, for a widget that renders beside it. Defaults to `<head>`. */
+    readonly into?: Element;
+    /** Cancels a load not yet triggered. */
+    readonly signal?: AbortSignal;
+}
+
+const INTERACTIONS = ["pointerdown", "keydown", "scroll", "touchstart"];
+
+function afterLoad(signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+        if (document.readyState === "complete") resolve();
+        else addEventListener("load", () => resolve(), { once: true, signal });
+    });
+}
+
+/** Resolves when `when` fires, on its own. */
+function fires(when: LoadTrigger, signal?: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve) => {
+        const done = () => {
+            if (!signal?.aborted) resolve();
+        };
+        switch (when.on) {
+            case "load":
+                done();
+                return;
+            case "idle":
+                // Not in Safari: a frame later is its nearest equivalent.
+                if (typeof requestIdleCallback === "function") {
+                    requestIdleCallback(done);
+                } else {
+                    setTimeout(done, 1);
+                }
+                return;
+            case "delay":
+                setTimeout(done, when.ms);
+                return;
+            case "visible": {
+                const observer = new IntersectionObserver(
+                    (entries) => {
+                        if (!entries.some((entry) => entry.isIntersecting)) {
+                            return;
+                        }
+                        observer.disconnect();
+                        done();
+                    },
+                    { rootMargin: when.margin ?? "200px" }
+                );
+                observer.observe(when.element);
+                signal?.addEventListener("abort", () => observer.disconnect());
+                return;
+            }
+            case "interaction": {
+                const controller = new AbortController();
+                signal?.addEventListener("abort", () => controller.abort());
+                for (const type of INTERACTIONS) {
+                    addEventListener(
+                        type,
+                        () => {
+                            controller.abort();
+                            done();
+                        },
+                        { once: true, passive: true, signal: controller.signal }
+                    );
+                }
+                return;
+            }
+            case "click":
+                when.element.addEventListener("click", done, {
+                    once: true,
+                    signal,
+                });
+                return;
+        }
+    });
+}
+
+/**
+ * Resolves when `when` fires; never, if `signal` aborts first.
+ *
+ * A click is a visitor asking, so it is answered at once. Every other trigger
+ * also waits for `load`: an interaction is listened for from the start, so an
+ * early one still counts, and the rest start counting at `load`.
+ */
+export async function triggered(
+    when: LoadTrigger,
+    signal?: AbortSignal
+): Promise<void> {
+    if (when.on === "click") return fires(when, signal);
+    if (when.on === "interaction") {
+        await Promise.all([fires(when, signal), afterLoad(signal)]);
+        return;
+    }
+    await afterLoad(signal);
+    await fires(when, signal);
+}
+
+const scripts = new Map<string, Promise<HTMLScriptElement>>();
+
+/**
+ * Fetches `src` once `when` fires, and once per page however many callers ask:
+ * each gets the same promise, which settles when the script has run. A failed
+ * fetch is forgotten, so the next caller tries again.
+ */
+export async function loadScript(
+    src: string,
+    { when, into, signal }: LoadScriptOptions
+): Promise<HTMLScriptElement> {
+    await triggered(when, signal);
+    let loading = scripts.get(src);
+    if (loading === undefined) {
+        loading = new Promise((resolve, reject) => {
+            const script = appendScript(src, into);
+            script.addEventListener("load", () => resolve(script));
+            script.addEventListener("error", () => {
+                scripts.delete(src);
+                reject(new Error(`${src} failed to load`));
+            });
+        });
+        scripts.set(src, loading);
+    }
+    return loading;
+}

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/index.ts

@@ -31,12 +31,16 @@ export {
     consentVendors,
     type DripSettings,
     type GoogleSettings,
+    type GoogleTagId,
     type MetaPixelSettings,
+    type NumericId,
     type SnapPixelSettings,
+    type TagManagerId,
     type TikTokPixelSettings,
     type UmamiReplay,
     type UmamiSettings,
     type UmamiTracker,
+    type Uuid,
 } from "./analytics/index.ts";
 export type {
     LanguageTag,