@escape-game-over/atlas 0.1.77 → 0.1.78

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.77",
+    "version": "0.1.78",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -48,7 +48,7 @@
         "check-fmt": "biome check . --error-on-warnings"
     },
     "dependencies": {
-        "@types/google.maps": "3.66.4"
+        "@types/google.maps": "3.66.5"
     },
     "peerDependencies": {
         "@types/node": ">=22",
@@ -60,7 +60,7 @@
         "@biomejs/biome": "2.5.15",
         "@types/node": "26.6.4",
         "@vitest/coverage-istanbul": "5.0.3",
-        "astro": "7.3.5",
+        "astro": "7.3.6",
         "typescript": "6.0.3",
         "vitest": "5.0.3"
     }

package/src/analytics/google.ts

@@ -8,6 +8,7 @@ import {
 } from "./consent-storage.ts";
 import googleTag from "./google-tag.ts?raw";
 import { type GoogleTagId, invalidId, type TagManagerId } from "./ids.ts";
+import type { StorageVendor } from "./storage.ts";
 import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
@@ -150,6 +151,16 @@ export interface GoogleSettings {
      * ads has no click id to carry.
      */
     readonly urlPassthrough?: true;
+    /**
+     * The vendors these tags bring that their ids do not name: whatever a
+     * Tag Manager container fires, or a `GT-` tag's destinations. Lib cannot
+     * see inside either, so `storedItems` lists only what is stated here — a
+     * `G-` id already implies Google Analytics and an `AW-` id Google Ads.
+     *
+     * A statement about someone else's configuration, so it goes stale the day
+     * they add a tag: whoever runs the container should know it is here.
+     */
+    readonly alsoLoads?: readonly StorageVendor[];
 }
 
 /**

package/src/analytics/storage-keys.ts

@@ -0,0 +1,14 @@
+/**
+ * The keys Atlas keeps on a visitor's device besides the consent record
+ * (`CONSENT_KEY`). On their own so the browser scripts that use them import
+ * two strings, not the catalog `storedItems` lists them from.
+ */
+
+/**
+ * The `localStorage` key `RememberLocale` keeps the chosen locale under. Its
+ * script is inline and imports nothing; `inlineScript` declares this around it.
+ */
+export const LOCALE_KEY = "atlas-locale";
+
+/** The `sessionStorage` key `rememberCampaign` keeps a visit's `utm_*` under. */
+export const CAMPAIGN_KEY = "atlas-campaign";

package/src/analytics/storage.ts

@@ -0,0 +1,363 @@
+import {
+    CONSENT_KEY,
+    CONSENT_MONTHS,
+    type ConsentCategory,
+} from "./consent-storage.ts";
+import { type AnalyticsSettings, consentVendors } from "./index.ts";
+import { CAMPAIGN_KEY, LOCALE_KEY } from "./storage-keys.ts";
+
+/**
+ * What a deployment keeps on a visitor's device, row by row, for the table a
+ * privacy notice owes them: each name, who sets it, how long it stays, and
+ * what has to be granted first.
+ *
+ * Here because the facts are the vendors' and the library's, not a site's.
+ * Cookie names and lifetimes change when a vendor changes its tag, and the
+ * three keys Atlas sets itself change when Atlas does; a table copied into
+ * each site is a table that is wrong in each site on a different day. The
+ * words — what each row is *for*, in each language — stay with the project,
+ * keyed by `StoredItem.id`.
+ *
+ * Built from the same settings that load the tags, so a vendor cannot run
+ * without a row. What lib cannot see — the tags inside a Tag Manager
+ * container — comes from `GoogleSettings.alsoLoads`.
+ */
+
+/** A vendor whose tag sets storage, by product rather than by company. */
+export type StorageVendor =
+    | "google-analytics"
+    | "google-ads"
+    | "linkedin"
+    | "meta"
+    | "tiktok"
+    | "snapchat"
+    | "axon"
+    | "drip"
+    | "clarity";
+
+/**
+ * Each vendor's product as it calls itself, for a table's "set by" column.
+ * Names, not copy: the same in every language, so a project translates only
+ * the site's own label.
+ */
+export const STORAGE_VENDOR_NAMES = {
+    "google-analytics": "Google Analytics",
+    "google-ads": "Google Ads",
+    linkedin: "LinkedIn",
+    meta: "Meta",
+    tiktok: "TikTok",
+    snapchat: "Snapchat",
+    axon: "AppLovin Axon",
+    drip: "Drip",
+    clarity: "Microsoft Clarity",
+} as const satisfies Record<StorageVendor, string>;
+
+/** A span `Intl.NumberFormat` can word in any locale: `{ 2, "year" }`. */
+export interface Lifetime {
+    readonly count: number;
+    readonly unit: "day" | "month" | "year";
+}
+
+/** The vendor-domain row of a vendor that has one. */
+type OwnRow = `${VendorWithOwn}-own`;
+
+/** The keys Atlas itself sets. */
+export type AtlasStoredId = "atlas-locale" | "atlas-campaign" | "atlas-consent";
+
+/** One row's id: what a project keys the row's wording by. */
+export type StoredId = AtlasStoredId | StorageVendor | OwnRow;
+
+export interface StoredItem {
+    readonly id: StoredId;
+    /** As the browser shows them; a pattern like `_ga_<id>` where the vendor appends one. */
+    readonly names: readonly string[];
+    /** Who sets it: this site, or the vendor. */
+    readonly provider: "site" | StorageVendor;
+    /** Set on the vendor's own domains rather than the site's; absent for the site's. */
+    readonly domains?: readonly string[];
+    /** A span; `tab` for session storage; `kept` until the visitor clears it. */
+    readonly lasts: Lifetime | "tab" | "kept";
+    /** What has to be granted first; `none` is kept without asking. */
+    readonly consent: ConsentCategory | "none";
+}
+
+export interface StoredItemsOptions {
+    /** As passed to `Document`, and with its default: `true`. */
+    readonly rememberLocale?: boolean;
+    /** As passed to `Document`, and with its default: `false`. */
+    readonly rememberCampaign?: boolean;
+    /**
+     * Rows the site sets first, then by what has to be granted — nothing,
+     * analytics, marketing — and otherwise in catalog order. Off, the rows
+     * come in catalog order: Atlas's own, then each vendor's site row before
+     * its vendor-domain one.
+     */
+    readonly sort?: boolean;
+}
+
+interface Stored {
+    readonly names: readonly string[];
+    /** The longest of the group's. */
+    readonly lasts: Lifetime;
+}
+
+interface VendorStorage {
+    readonly consent: ConsentCategory;
+    /** On the site's domain. */
+    readonly site: Stored;
+    /** On the vendor's, when its tag sets any there. */
+    readonly own?: Stored & { readonly domains: readonly string[] };
+}
+
+const day = (count: number): Lifetime => ({ count, unit: "day" });
+const month = (count: number): Lifetime => ({ count, unit: "month" });
+const year = (count: number): Lifetime => ({ count, unit: "year" });
+
+/**
+ * Each vendor's storage, from its own cookie documentation, read 2026-10-06.
+ * These go stale without anything failing, so each entry names its source;
+ * where the vendor's docs were silent, the source is its tag's own code.
+ *
+ * What a tag sets only in a mode Atlas does not configure — server-side
+ * tagging's `FPID`, Drip's pop-ups — is left out, and so is what a vendor
+ * documents only for its own sites or never names.
+ */
+const CATALOG = {
+    // support.google.com/analytics/answer/11397207. Two years as Google
+    // states it; Chrome caps any cookie at 400 days.
+    "google-analytics": {
+        consent: "analytics",
+        site: { names: ["_ga", "_ga_<id>"], lasts: year(2) },
+    },
+    // business.safety.google/adscookies, support.google.com/tagmanager/answer/7549390.
+    // `IDE` is 13 months in the EEA and UK, 24 elsewhere: the EEA's, since a
+    // notice that needs this table is written for it. Seen live 2026-10-06.
+    "google-ads": {
+        consent: "marketing",
+        site: {
+            names: [
+                "_gcl_au",
+                "_gcl_aw",
+                "_gcl_gs",
+                "_gcl_dc",
+                "_gcl_gb",
+                "_gcl_ag",
+                "_gcl_ls",
+            ],
+            lasts: day(90),
+        },
+        own: {
+            names: ["IDE", "GCL_AW_P", "DSID", "test_cookie", "ar_debug"],
+            lasts: month(13),
+            domains: ["doubleclick.net", "googleadservices.com", "google.com"],
+        },
+    },
+    // linkedin.com/legal/l/cookie-table. Seen live 2026-10-06.
+    linkedin: {
+        consent: "marketing",
+        site: { names: ["li_fat_id", "li_giant", "ln_or"], lasts: day(30) },
+        own: {
+            names: [
+                "bcookie",
+                "bscookie",
+                "li_gc",
+                "lidc",
+                "li_sugr",
+                "UserMatchHistory",
+                "AnalyticsSyncHistory",
+                "lms_ads",
+                "lms_analytics",
+                "_guid",
+            ],
+            lasts: year(1),
+            domains: ["linkedin.com"],
+        },
+    },
+    // developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc,
+    // facebook.com/privacy/policies/cookies. `datr` is facebook.com's own,
+    // there only for someone who has visited it; the pixel does not set it.
+    meta: {
+        consent: "marketing",
+        site: { names: ["_fbp", "_fbc"], lasts: day(90) },
+        own: { names: ["fr"], lasts: day(90), domains: ["facebook.com"] },
+    },
+    // ads.tiktok.com/help/article/using-cookies-with-tiktok-pixel.
+    tiktok: {
+        consent: "marketing",
+        site: {
+            names: [
+                "_ttp",
+                "_tt_enable_cookie",
+                "ttcsid",
+                "ttcsid_<id>",
+                "ttclid",
+            ],
+            lasts: month(13),
+        },
+        own: { names: ["_ttp"], lasts: month(13), domains: ["tiktok.com"] },
+    },
+    // snap.com/en-US/privacy/cookie-information gives `_scid` and `_sctr` a
+    // year; the pixel's own code sets 13 months, which is what lands.
+    snapchat: {
+        consent: "marketing",
+        site: {
+            names: ["_scid", "_sctr", "u_sclid", "u_scsid"],
+            lasts: month(13),
+        },
+        own: { names: ["sc_at"], lasts: year(1), domains: ["snapchat.com"] },
+    },
+    // support.applovin.com/en/ecommerce/google-tag-manager names `_axwrt`;
+    // the rest and the 365 days are from s.axon.ai/pixel.js. AppLovin lists
+    // no cookies of its own domains.
+    axon: {
+        consent: "marketing",
+        site: {
+            names: ["_axwrt", "_axeid", "_axart", "ax_visitor", "_axsid"],
+            lasts: day(365),
+        },
+    },
+    // help.drip.com/hc/en-us/articles/4424702605453 gives the year but not
+    // the name, which is cookiedatabase.org's.
+    drip: {
+        consent: "marketing",
+        site: { names: ["_drip_client_<id>"], lasts: year(1) },
+    },
+    // learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-cookies
+    // names them; the lifetimes are from microsoft/clarity's source, and
+    // `MUID`'s year from cookiedatabase.org.
+    clarity: {
+        consent: "analytics",
+        site: { names: ["_clck", "_clsk", "_cltk"], lasts: year(1) },
+        own: {
+            names: ["CLID", "MUID", "ANONCHK", "MR", "SM"],
+            lasts: year(1),
+            domains: ["clarity.ms"],
+        },
+    },
+} as const satisfies Record<StorageVendor, VendorStorage>;
+
+type VendorWithOwn = {
+    [V in keyof typeof CATALOG]: (typeof CATALOG)[V] extends { own: object }
+        ? V
+        : never;
+}[keyof typeof CATALOG];
+
+/** Catalog order, which is also the order rows come in unsorted. */
+const VENDOR_ORDER: readonly StorageVendor[] = [
+    "google-analytics",
+    "google-ads",
+    "linkedin",
+    "meta",
+    "tiktok",
+    "snapchat",
+    "axon",
+    "drip",
+    "clarity",
+];
+
+/** The vendors a deployment's settings load, in catalog order. */
+function loadedVendors(
+    analytics: AnalyticsSettings | undefined
+): readonly StorageVendor[] {
+    const loaded = new Set<StorageVendor>();
+    const google = analytics?.google;
+    for (const id of google?.tagIds ?? []) {
+        if (id.startsWith("G-")) loaded.add("google-analytics");
+        if (id.startsWith("AW-")) loaded.add("google-ads");
+    }
+    for (const vendor of google?.alsoLoads ?? []) loaded.add(vendor);
+    if (analytics?.meta !== undefined) loaded.add("meta");
+    if (analytics?.tiktok !== undefined) loaded.add("tiktok");
+    if (analytics?.snapchat !== undefined) loaded.add("snapchat");
+    if (analytics?.axon !== undefined) loaded.add("axon");
+    if (analytics?.drip !== undefined) loaded.add("drip");
+    if (analytics?.clarity !== undefined) loaded.add("clarity");
+    return VENDOR_ORDER.filter((vendor) => loaded.has(vendor));
+}
+
+const CONSENT_ORDER: readonly StoredItem["consent"][] = [
+    "none",
+    "analytics",
+    "marketing",
+];
+
+/** The rows the `sort` option puts first come first; ties keep their order. */
+export function compareStoredItems(a: StoredItem, b: StoredItem): number {
+    return (
+        Number(b.provider === "site") - Number(a.provider === "site") ||
+        CONSENT_ORDER.indexOf(a.consent) - CONSENT_ORDER.indexOf(b.consent)
+    );
+}
+
+/**
+ * Everything this deployment keeps on a device: Atlas's own keys, then each
+ * loaded vendor's.
+ *
+ * Atlas's rows follow what the page renders, which `Document` decides from
+ * its props, so pass the same `rememberLocale` and `rememberCampaign` here.
+ * The consent record is listed whenever there is a banner to answer.
+ */
+export function storedItems(
+    analytics: AnalyticsSettings | undefined,
+    options: StoredItemsOptions = {}
+): readonly StoredItem[] {
+    const {
+        rememberLocale = true,
+        rememberCampaign = false,
+        sort = false,
+    } = options;
+    const asked = consentVendors(analytics).length > 0;
+
+    const rows: StoredItem[] = [];
+    if (rememberLocale) {
+        rows.push({
+            id: "atlas-locale",
+            names: [LOCALE_KEY],
+            provider: "site",
+            lasts: "kept",
+            consent: "none",
+        });
+    }
+    // Kept only once analytics is granted, so only where it can be.
+    if (rememberCampaign && asked) {
+        rows.push({
+            id: "atlas-campaign",
+            names: [CAMPAIGN_KEY],
+            provider: "site",
+            lasts: "tab",
+            consent: "analytics",
+        });
+    }
+    if (asked) {
+        rows.push({
+            id: "atlas-consent",
+            names: [CONSENT_KEY],
+            provider: "site",
+            lasts: month(CONSENT_MONTHS),
+            consent: "none",
+        });
+    }
+
+    for (const vendor of loadedVendors(analytics)) {
+        const entry: VendorStorage = CATALOG[vendor];
+        rows.push({
+            id: vendor,
+            names: entry.site.names,
+            provider: vendor,
+            lasts: entry.site.lasts,
+            consent: entry.consent,
+        });
+        if (entry.own !== undefined) {
+            rows.push({
+                id: `${vendor}-own` as OwnRow,
+                names: entry.own.names,
+                provider: vendor,
+                domains: entry.own.domains,
+                lasts: entry.own.lasts,
+                consent: entry.consent,
+            });
+        }
+    }
+
+    return sort ? rows.toSorted(compareStoredItems) : rows;
+}

package/src/astro/RememberLocale.astro

@@ -11,10 +11,11 @@
  * Rendered by `Document` after the head tags, whose alternates it reads.
  * Inline and blocking, so the wrong language is never painted.
  */
+import { LOCALE_KEY } from "../analytics/storage-keys.ts";
 import { inlineScript } from "./inline-script.ts";
 import source from "./remember-locale.ts?raw";
 
-const code = await inlineScript(source);
+const code = await inlineScript(source, { LOCALE_KEY });
 ---
 
 <script

package/src/astro/attribution.ts

@@ -19,6 +19,8 @@
  *   in its own `_gcl_aw` cookie once granted. `adClick()` reads it from there.
  */
 
+import { CAMPAIGN_KEY } from "../analytics/storage-keys.ts";
+
 /** The campaign tags a link can carry. */
 export type CampaignTag =
     | "utm_source"
@@ -43,9 +45,6 @@ const AD_CLICK_IDS: readonly AdClickId[] = ["gclid", "gbraid", "wbraid"];
 export type Campaign = Partial<Record<CampaignTag, string>>;
 export type AdClick = Partial<Record<AdClickId, string>>;
 
-/** The `sessionStorage` key the tags are kept under. */
-const KEY = "atlas-campaign";
-
 /** The given parameters present on this page's URL. */
 function fromUrl<K extends string>(
     names: readonly K[]
@@ -64,7 +63,7 @@ export function rememberCampaign(): void {
     const landed = fromUrl(CAMPAIGN_TAGS);
     if (Object.keys(landed).length === 0) return;
     try {
-        sessionStorage.setItem(KEY, JSON.stringify(landed));
+        sessionStorage.setItem(CAMPAIGN_KEY, JSON.stringify(landed));
     } catch {
         // Storage refused: the tags still count on the page they arrived on.
     }
@@ -75,7 +74,9 @@ export function campaign(): Campaign {
     const here = fromUrl(CAMPAIGN_TAGS);
     if (Object.keys(here).length > 0) return here;
     try {
-        const kept: unknown = JSON.parse(sessionStorage.getItem(KEY) ?? "{}");
+        const kept: unknown = JSON.parse(
+            sessionStorage.getItem(CAMPAIGN_KEY) ?? "{}"
+        );
         if (typeof kept !== "object" || kept === null) return {};
         const found: Campaign = {};
         for (const tag of CAMPAIGN_TAGS) {

package/src/astro/inline-script.ts

@@ -7,9 +7,20 @@ import { minifySync, transformWithOxc } from "vite";
  * 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.
+ *
+ * `constants` are declared around the source, which `declare const`s them: a
+ * classic script imports nothing, so this is how a value spelled once in the
+ * library reaches it. The outer block keeps them out of the page's globals.
  */
-export async function inlineScript(source: string): Promise<string> {
-    const { code } = await transformWithOxc(source, "inline.ts");
+export async function inlineScript(
+    source: string,
+    constants: Readonly<Record<string, unknown>> = {}
+): Promise<string> {
+    const declared = Object.entries(constants)
+        .map(([name, value]) => `const ${name}=${JSON.stringify(value)};`)
+        .join("");
+    const wrapped = declared === "" ? source : `{${declared}{\n${source}\n}}`;
+    const { code } = await transformWithOxc(wrapped, "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 });

package/src/astro/remember-locale.ts

@@ -1,18 +1,21 @@
 // The body of `RememberLocale.astro`'s inline script. A classic script: no
 // imports or exports, and the block keeps its names out of the global scope.
+// `LOCALE_KEY` is declared around it by `inlineScript`, from `storage-keys.ts`.
+
+declare const LOCALE_KEY: typeof import("../analytics/storage-keys.ts").LOCALE_KEY;
+
 {
-    const KEY = "atlas-locale";
     const current = document.documentElement.lang;
 
     const remember = () => {
         // Came from this site: the visitor is browsing, or just switched
         // language. Either way, this locale is their choice.
         if (document.referrer.startsWith(`${location.origin}/`)) {
-            localStorage.setItem(KEY, current);
+            localStorage.setItem(LOCALE_KEY, current);
             return;
         }
 
-        const chosen = localStorage.getItem(KEY);
+        const chosen = localStorage.getItem(LOCALE_KEY);
         if (chosen === null || chosen === current) return;
 
         // No alternate means this page is not built in that locale.

package/src/index.ts

@@ -43,6 +43,17 @@ export {
     type UmamiTracker,
     type Uuid,
 } from "./analytics/index.ts";
+export {
+    type AtlasStoredId,
+    compareStoredItems,
+    type Lifetime,
+    STORAGE_VENDOR_NAMES,
+    type StorageVendor,
+    type StoredId,
+    type StoredItem,
+    type StoredItemsOptions,
+    storedItems,
+} from "./analytics/storage.ts";
 export type {
     LanguageTag,
     LocaleMeta,