@escape-game-over/atlas 0.1.46 → 0.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.46",
+    "version": "0.1.48",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -48,7 +48,8 @@
     "peerDependencies": {
         "@types/node": ">=22",
         "astro": ">=7",
-        "typescript": ">=5"
+        "typescript": ">=5",
+        "vite": ">=8"
     },
     "devDependencies": {
         "@biomejs/biome": "2.5.14",

package/src/analytics/google-tag.ts

@@ -0,0 +1,123 @@
+// Google's inline head block, emitted by `googleScripts` in `google.ts`.
+//
+// A classic script, not a module: `google.ts` wraps this source in a block that
+// declares `config`, and `MetaTags` strips the types and minifies the result.
+// So no imports or exports — the type below is referenced, not imported.
+
+declare const config: import("./google.ts").GoogleTagConfig;
+
+// The banner's way in, under the name `astro/consent.ts` calls: spelled once,
+// in `CONSENT_UPDATE_GLOBAL`, so a rename there fails to compile here.
+type ConsentGlobal = {
+    [Name in typeof import("./google.ts").CONSENT_UPDATE_GLOBAL]?: (
+        choices: Readonly<Record<string, string>>
+    ) => void;
+};
+
+// biome-ignore lint/correctness/noUnusedVariables: merges into the global `Window`.
+interface Window extends ConsentGlobal {
+    dataLayer: unknown[];
+    gtag: (...args: unknown[]) => void;
+}
+
+{
+    type Consent = NonNullable<typeof config.consent>;
+    type Choices = Readonly<Record<string, string>>;
+
+    // Global, and pushing `arguments` itself: `gtag.js` tells a command from a
+    // data object by it, and a site's own code calls `gtag` as Google documents.
+    const defineGtag = () => {
+        window.dataLayer = window.dataLayer || [];
+        window.gtag = function gtag() {
+            // biome-ignore lint/complexity/noArguments: the queue wants the arguments object, not an array.
+            window.dataLayer.push(arguments);
+        };
+    };
+
+    // The way back out of the defaults: each signal from the answer for its
+    // category.
+    const updateConsent = (signals: Consent["signals"], choices: Choices) => {
+        const moved: Record<string, string | undefined> = {};
+        for (const [category, names] of Object.entries(signals)) {
+            for (const name of names) moved[name] = choices[category];
+        }
+        window.gtag("consent", "update", moved);
+    };
+
+    // A returning visitor's answer, or nothing. Anything unreadable, expired,
+    // or missing a category — an answer given before that category was asked
+    // — leaves the defaults standing, and the banner asks.
+    const storedChoices = ({ signals, key, months }: Consent) => {
+        try {
+            const stored = JSON.parse(localStorage.getItem(key) ?? "null");
+            const expires = new Date(stored.at);
+            expires.setMonth(expires.getMonth() + months);
+            const categories = Object.keys(signals);
+            const answered = categories.every(
+                (category) =>
+                    stored[category] === "granted" ||
+                    stored[category] === "denied"
+            );
+            // Negated rather than `<=`: an unreadable date is `NaN`, which
+            // compares false both ways and must count as expired.
+            if (!(answered && expires > new Date())) return undefined;
+            return Object.fromEntries(
+                categories.map((category) => [category, stored[category]])
+            );
+        } catch {
+            return undefined;
+        }
+    };
+
+    // A script from Google's host, fetched without blocking the page.
+    const fetchScript = (path: string) => {
+        const script = document.createElement("script");
+        script.async = true;
+        script.src = `${config.origin}${path}`;
+        document.head.appendChild(script);
+    };
+
+    // After `load`, so its first run does not compete with the page. The
+    // queue is replayed when it arrives.
+    const afterLoad = (run: () => void) => {
+        if (document.readyState === "complete") run();
+        else addEventListener("load", run);
+    };
+
+    defineGtag();
+
+    // Ahead of everything, which is the entire point of emitting this here.
+    for (const given of config.defaults) {
+        window.gtag("consent", "default", given);
+    }
+
+    const { consent } = config;
+    if (consent !== undefined) {
+        window.__consent = (choices) => updateConsent(consent.signals, choices);
+        // Still ahead of the first tag.
+        const choices = storedChoices(consent);
+        if (choices !== undefined) updateConsent(consent.signals, choices);
+    }
+
+    // Before any `config`, which is what reads it.
+    if (config.urlPassthrough) {
+        window.gtag("set", "url_passthrough", true);
+    }
+
+    // The library once, for the first id, and every id configured against it —
+    // Google's documented arrangement for several tag ids.
+    const [first] = config.tagIds;
+    if (first !== undefined) {
+        window.gtag("js", new Date());
+        for (const id of config.tagIds) window.gtag("config", id);
+        afterLoad(() =>
+            fetchScript(`/gtag/js?id=${encodeURIComponent(first)}`)
+        );
+    }
+
+    // Tag Manager's own bootstrap, once per container.
+    for (const id of config.containerIds) {
+        window.dataLayer.push({ "gtm.start": Date.now(), event: "gtm.js" });
+        fetchScript(`/gtm.js?id=${encodeURIComponent(id)}`);
+    }
+}

package/src/analytics/google.ts

@@ -6,6 +6,7 @@ import {
     CONSENT_MONTHS,
     type ConsentCategory,
 } from "./consent-storage.ts";
+import googleTag from "./google-tag.ts?raw";
 import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
@@ -249,65 +250,64 @@ const UNASKED = SIGNAL_KEYS.filter(
 );
 
 /**
- * `window.__consent(choices)`, updating precisely what was defaulted, each
- * signal from the answer for its category.
+ * What `google-tag.ts` is handed: the settings, already in Google's own names.
  *
- * Only signals a default mentioned. Updating one that was never defaulted is
- * legal and pointless — Google reads it as a change from its own implicit
- * grant, which was never in force here.
+ * Data rather than code, so the script is written once, readable and
+ * type-checked, and only these values differ between sites.
  */
-function consentUpdater(defaults: readonly ConsentDefaults[]): string {
-    const signals = CONSENT_CATEGORIES.flatMap((category) =>
-        CATEGORY_SIGNALS[category]
-            .filter((key) => defaults.some((given) => given[key] !== undefined))
-            .map((key) => `${literal(CONSENT_KEYS[key])}:c.${category}`)
-    );
+export interface GoogleTagConfig {
+    /** One `gtag('consent','default',…)` payload per stated default, in order. */
+    readonly defaults: readonly Readonly<Record<string, unknown>>[];
+    /**
+     * How an answer moves the signals, and where a returning visitor's answer is
+     * kept. Absent when no default mentions a signal an answer can move —
+     * there is then nothing to update.
+     */
+    readonly consent?: {
+        /** Per category, the signals its answer moves: only those defaulted. */
+        readonly signals: Readonly<Record<string, readonly string[]>>;
+        readonly key: string;
+        readonly months: number;
+    };
+    readonly urlPassthrough: boolean;
+    readonly tagIds: readonly string[];
+    readonly containerIds: readonly string[];
+    readonly origin: string;
+}
 
-    if (signals.length === 0) return "";
-    return `window.${CONSENT_UPDATE_GLOBAL}=function(c){gtag('consent','update',{${signals.join(",")}})};`;
+/** One default in Google's names, dropping what it does not state. */
+function consentDefault(
+    given: ConsentDefaults
+): Readonly<Record<string, unknown>> {
+    return Object.fromEntries(
+        (Object.entries(CONSENT_KEYS) as [keyof ConsentDefaults, string][])
+            .filter(([key]) => given[key] !== undefined)
+            .map(([key, name]) => [name, given[key]])
+    );
 }
 
 /**
- * A returning visitor's answer, handed to Google before any tag fires.
- *
- * It has to happen here, in the head, ahead of `gtag('config', …)`. Left to the
- * banner's module script it arrives after `gtag.js` has already sent the page
- * view on the defaults — so every page a consenting visitor opened was recorded
- * as denied: no cookie, no returning user, no session. Measured, not supposed:
- * `gcs=G100` on the `page_view`, `G111` only on the hits after it.
+ * Per category, the signals its answer moves — only those a default mentioned.
  *
- * The same key, expiry and categories `astro/consent.ts` reads, from the one
- * place both take them. Anything unreadable, expired, absent or missing a
- * category — an answer given before that category was asked — leaves the
- * defaults standing, and the banner will ask.
+ * Updating one that was never defaulted is legal and pointless: Google reads it
+ * as a change from its own implicit grant, which was never in force here.
  */
-function restoredConsent(): string {
-    const answered = CONSENT_CATEGORIES.map(
-        (category) => `(c.${category}==="granted"||c.${category}==="denied")`
-    ).join("&&");
-    const choices = CONSENT_CATEGORIES.map(
-        (category) => `${category}:c.${category}`
-    ).join(",");
-    return `try{var c=JSON.parse(localStorage.getItem(${literal(CONSENT_KEY)})),e=new Date(c.at);e.setMonth(e.getMonth()+${CONSENT_MONTHS});if(${answered}&&e>new Date())window.${CONSENT_UPDATE_GLOBAL}({${choices}})}catch(_){}`;
-}
-
-/** One `gtag('consent','default',{…})` per stated default, in order. */
-function consentCalls(defaults: readonly ConsentDefaults[]): string {
-    return defaults
-        .map((given) => {
-            const pairs = (
-                Object.entries(CONSENT_KEYS) as [
-                    keyof ConsentDefaults,
-                    string,
-                ][]
-            )
-                .filter(([key]) => given[key] !== undefined)
-                .map(
-                    ([key, name]) => `${literal(name)}:${literal(given[key])}`
-                );
-            return `gtag('consent','default',{${pairs.join(",")}});`;
-        })
-        .join("");
+function movedSignals(
+    defaults: readonly ConsentDefaults[]
+): Readonly<Record<string, readonly string[]>> | undefined {
+    const signals = Object.fromEntries(
+        CONSENT_CATEGORIES.map((category) => [
+            category,
+            CATEGORY_SIGNALS[category]
+                .filter((key) =>
+                    defaults.some((given) => given[key] !== undefined)
+                )
+                .map((key) => CONSENT_KEYS[key]),
+        ])
+    );
+    return Object.values(signals).some((names) => names.length > 0)
+        ? signals
+        : undefined;
 }
 
 /**
@@ -408,30 +408,27 @@ export function googleScripts(
             );
         }
     }
-    // The way back out of the defaults, covering what they denied.
-    const updater = consentUpdater(consent);
-    const inline = [
-        "window.dataLayer=window.dataLayer||[];",
-        "function gtag(){dataLayer.push(arguments)}",
-        // Ahead of everything, which is the entire point of emitting this here.
-        consentCalls(consent),
-        updater,
-        // Then a remembered answer, still ahead of the first tag.
-        updater === "" ? "" : restoredConsent(),
-        // Before any `config`, which is what reads it.
-        google.urlPassthrough === true
-            ? "gtag('set','url_passthrough',true);"
-            : "",
-        tags.length > 0 ? "gtag('js',new Date());" : "",
-        ...tags.map((id) => `gtag('config',${literal(id)});`),
-        loader(tags[0]),
-        // Tag Manager's own loader, once per container. It appends its script
-        // itself, so it runs after the consent calls already queued above.
-        ...containers.map(
-            (id) =>
-                `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='${TAG_ORIGIN}/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f)})(window,document,'script','dataLayer',${literal(id)});`
-        ),
-    ].join("");
+    const signals = movedSignals(consent);
+    const config: GoogleTagConfig = {
+        defaults: consent.map(consentDefault),
+        ...(signals === undefined
+            ? {}
+            : {
+                  consent: {
+                      signals,
+                      key: CONSENT_KEY,
+                      months: CONSENT_MONTHS,
+                  },
+              }),
+        urlPassthrough: google.urlPassthrough === true,
+        tagIds: tags,
+        containerIds: containers,
+        origin: TAG_ORIGIN,
+    };
+    // TypeScript, compiled and minified by `MetaTags`. The outer block keeps
+    // `config` out of the page's globals; the inner one holds the script's own
+    // `declare const config`, which compiles away and leaves this one.
+    const inline = `{const config=${literal(config)};{\n${googleTag}\n}}`;
 
     return {
         head: [
@@ -450,31 +447,3 @@ export function googleScripts(
         })),
     };
 }
-
-/**
- * `gtag.js`, appended once the page has loaded.
- *
- * Its parse and first run — including a forced reflow of its own — otherwise
- * compete with the page for the load window. Nothing is lost by waiting:
- * `dataLayer` is a queue, and every call above is replayed when it arrives.
- * What waiting costs is a visitor who leaves before `load`, who is not counted.
- *
- * The library is fetched once, for the first id, and every id gets its own
- * `config` above. That is Google's documented arrangement rather than a
- * shortcut: *"A single Google tag can have multiple tag IDs"*, and their
- * own example loads `gtag/js?id=G-XXXXXX` once and then configures
- * `GT-XXXXXX` and `DC-ZZZZZZ` against it. The `?id=` only bootstraps the
- * library; the `config` calls are what register a destination.
- *
- * Loading it per id would fetch the same script several times and re-run
- * its bootstrap — more bytes for nothing, and a second copy of a global.
- *
- * <https://developers.google.com/tag-platform/gtagjs/configure>
- */
-function loader(first: string | undefined): string {
-    if (first === undefined) return "";
-    const src = literal(
-        `${TAG_ORIGIN}/gtag/js?id=${encodeURIComponent(first)}`
-    );
-    return `(function(){function l(){var s=document.createElement('script');s.async=true;s.src=${src};document.head.appendChild(s)}document.readyState==='complete'?l():addEventListener('load',l)})();`;
-}

package/src/astro/MetaTags.astro

@@ -8,15 +8,25 @@
 // consumer's name for this package, and depending on it here would make the
 // library's own internals rely on how a project spells them.
 import type { MetaTag } from "../meta/index.ts";
+import { inlineScript } from "./inline-script.ts";
 
 interface Props {
     readonly tags: readonly MetaTag[];
 }
 
 const { tags } = Astro.props;
+
+// JavaScript only: a typed block is data, JSON-LD above all, and not code.
+const rendered = await Promise.all(
+    tags.map(async (tag) =>
+        tag.kind === "script" && tag.type === undefined
+            ? { ...tag, content: await inlineScript(tag.content) }
+            : tag
+    )
+);
 ---
 
-{tags.map((tag) => {
+{rendered.map((tag) => {
     if (tag.kind === "title") return <title>{tag.text}</title>;
     if (tag.kind === "link") return <link {...tag.attrs} />;
     // `set:html` writes the JSON raw. `serializeJsonLd` has already replaced

package/src/astro/ScrollRestore.astro

@@ -10,48 +10,13 @@
  * Rendered by `Document` after the page, where the layout already exists.
  * Inline, because a bundled module runs too late: after the first paint.
  */
----
-
-<script is:inline>
-{
-    history.scrollRestoration = "manual";
-
-    const save = () => {
-        try {
-            history.replaceState({ ...history.state, scrollY }, "");
-        } catch {
-            // Safari throttles replaceState; the last saved position stands.
-        }
-    };
+import { inlineScript } from "./inline-script.ts";
+import source from "./scroll-restore.ts?raw";
 
-    // Once scrolling settles, not per frame: Safari caps replaceState calls.
-    let settle = 0;
-    addEventListener(
-        "scroll",
-        () => {
-            clearTimeout(settle);
-            settle = setTimeout(save, 300);
-        },
-        { passive: true }
-    );
-    // No save on `pagehide`. WebKit fires it after moving to the previous entry,
-    // and Firefox on iOS restores a page at the top and reloads it at once, so
-    // either way the save would wipe the position about to be restored.
-
-    // `instant`, or a site with `scroll-behavior: smooth` glides down from the
-    // top — the jump this exists to remove, in slow motion.
-    const restore = (state) => {
-        if (typeof state?.scrollY === "number") {
-            scrollTo({ top: state.scrollY, behavior: "instant" });
-        }
-    };
-
-    restore(history.state);
+const code = await inlineScript(source);
+---
 
-    // Filters push entries on the same page; `manual` turned off restoring
-    // those too. A frame later, so the filtered list has re-rendered first.
-    addEventListener("popstate", (event) => {
-        requestAnimationFrame(() => restore(event.state));
-    });
-}
-</script>
+<script
+    is:inline
+    set:html={code}
+/>

package/src/astro/inline-script.ts

@@ -0,0 +1,22 @@
+import { minifySync, transformWithOxc } from "vite";
+
+/**
+ * TypeScript source as the body of a `<script is:inline>`: types stripped, then
+ * minified.
+ *
+ * Astro writes an inline script exactly as written, comments and all. Both
+ * steps are needed — the minifier accepts TypeScript and silently keeps its
+ * annotations, which a browser then fails to parse.
+ */
+export async function inlineScript(source: string): Promise<string> {
+    const { code } = await transformWithOxc(source, "inline.ts");
+    // A classic script, not a module: its top-level names are globals other
+    // scripts call — `gtag` above all — and a module's may be renamed.
+    const minified = minifySync("inline.js", code, { module: false });
+    if (minified.errors.length > 0) {
+        throw new Error(
+            `inline script failed to minify: ${minified.errors.map((error) => error.message).join("; ")}`
+        );
+    }
+    return minified.code;
+}

package/src/astro/scroll-restore.ts

@@ -0,0 +1,44 @@
+// The body of `ScrollRestore.astro`'s inline script, minified into the page by
+// `inlineScript`. No imports or exports: it runs as a classic script, and the
+// block keeps its names out of the page's global scope.
+{
+    history.scrollRestoration = "manual";
+
+    const save = () => {
+        try {
+            history.replaceState({ ...history.state, scrollY }, "");
+        } catch {
+            // Safari throttles replaceState; the last saved position stands.
+        }
+    };
+
+    // Once scrolling settles, not per frame: Safari caps replaceState calls.
+    let settle = 0;
+    addEventListener(
+        "scroll",
+        () => {
+            clearTimeout(settle);
+            settle = window.setTimeout(save, 300);
+        },
+        { passive: true }
+    );
+    // No save on `pagehide`. WebKit fires it after moving to the previous entry,
+    // and Firefox on iOS restores a page at the top and reloads it at once, so
+    // either way the save would wipe the position about to be restored.
+
+    // `instant`, or a site with `scroll-behavior: smooth` glides down from the
+    // top — the jump this exists to remove, in slow motion.
+    const restore = (state: { readonly scrollY?: unknown } | null) => {
+        if (typeof state?.scrollY === "number") {
+            scrollTo({ top: state.scrollY, behavior: "instant" });
+        }
+    };
+
+    restore(history.state);
+
+    // Filters push entries on the same page; `manual` turned off restoring
+    // those too. A frame later, so the filtered list has re-rendered first.
+    addEventListener("popstate", (event) => {
+        requestAnimationFrame(() => restore(event.state));
+    });
+}

package/src/astro/site-routes.ts

@@ -212,6 +212,7 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
             "astro:config:setup": ({
                 config: current,
                 updateConfig,
+                addWatchFile,
                 logger,
             }) => {
                 /**
@@ -290,6 +291,16 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                     `updated config: ${JSON.stringify(config, null, 2)}`
                 );
                 reportOrphans();
+
+                // `atlas use` swaps the project by relinking `config/project`,
+                // and nothing Vite watches changes when it does: the files
+                // behind the link are new, but every module already loaded
+                // through it stays cached, so a running `astro dev` keeps
+                // serving the old project — its messages, its routes, a map
+                // from one country with the pins of another. Watching the link
+                // itself turns the relink into a restart. A project without
+                // overlays has no such link, and the watch is simply idle.
+                addWatchFile(new URL("config/project", current.root));
             },
 
             /**

package/src/raw.d.ts

@@ -0,0 +1,7 @@
+// Vite's `?raw` suffix — a file's source as a string — for the type check that
+// runs without Vite's client types. `astro/client` declares the same for
+// `src/astro`.
+declare module "*?raw" {
+    const source: string;
+    export default source;
+}