@escape-game-over/atlas 0.1.77 → 0.1.79

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.77",
+    "version": "0.1.79",
     "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,386 @@
+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)
+    );
+}
+
+/**
+ * Each row with what the project says it is for — a message key, usually,
+ * since the words are the project's and in every locale.
+ *
+ * Throws, naming every row without one, so a vendor switched on, or a row a
+ * new Atlas adds, fails the build until the site has said what it is for: a
+ * notice that lists a cookie without a purpose is the one thing it must not
+ * publish. `purposes` may name rows this deployment does not have; a site
+ * keeps its wording when a vendor is switched off.
+ */
+export function withPurposes<K>(
+    rows: readonly StoredItem[],
+    purposes: Partial<Record<StoredId, K>>
+): readonly (StoredItem & { readonly purpose: K })[] {
+    const missing = rows.filter((row) => purposes[row.id] === undefined);
+    if (missing.length > 0) {
+        throw new Error(
+            `The storage table has no purpose for ${missing.map((row) => `"${row.id}"`).join(", ")}. Add one for each to the purposes given to withPurposes.`
+        );
+    }
+    return rows.map((row) => ({ ...row, purpose: purposes[row.id] as K }));
+}
+
+/**
+ * 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/Document.astro

@@ -30,11 +30,13 @@
 import { Font } from "astro:assets";
 import type { HTMLAttributes } from "astro/types";
 import type { Fonts } from "../fonts.ts";
+import { iconLinks } from "../meta/index.ts";
 import type { PageMeta } from "../site/index.ts";
 import MetaTags from "./MetaTags.astro";
 import RememberCampaign from "./RememberCampaign.astro";
 import RememberLocale from "./RememberLocale.astro";
 import ScrollRestore from "./ScrollRestore.astro";
+import { siteIcons } from "./site-icons.ts";
 
 interface Props {
     readonly meta: PageMeta;
@@ -65,6 +67,9 @@ if (meta.consentVendors.length > 0 && !Astro.slots.has("consent")) {
         `${meta.consentVendors.join(", ")} ${meta.consentVendors.length === 1 ? "needs" : "need"} permission, but this page has no consent banner. Pass one to Document: <ConsentBanner slot="consent" …>.`
     );
 }
+
+// Here rather than in `meta.tags`: cutting the icon to size needs the build.
+const icons = iconLinks(await siteIcons(meta.icon));
 ---
 
 <!doctype html>
@@ -76,6 +81,7 @@ if (meta.consentVendors.length > 0 && !Astro.slots.has("consent")) {
     <head>
         <slot name="head-start" />
         <MetaTags tags={meta.tags} />
+        <MetaTags tags={icons} />
         {rememberLocale && <RememberLocale />}
         {Object.entries(fonts).map(([key, font]) => (
             <Font

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/background-video.ts

@@ -26,7 +26,12 @@
  * quietly wrong:
  *
  * - **Reduced motion starts it paused.** A reader who asked their system for
- *   less motion should not get a full-width loop behind the headline.
+ *   less motion should not get a full-width loop behind the headline. So does
+ *   Data Saver, where the browser says so: a loop is megabytes nobody asked for.
+ * - **Not before the page has loaded.** A hero loop is the heaviest thing on
+ *   the page, and started at once it shares the connection with the poster —
+ *   usually the largest paint — and with everything else the page needs first.
+ *   It starts on `load`, unless the reader pressed play before that.
  * - **A way to stop it.** WCAG 2.2.2 asks for one on anything that moves for
  *   more than five seconds, and a loop moves forever. The control is the
  *   project's; the state it shows is this.
@@ -45,7 +50,9 @@
  * `aria-hidden="true"` and `tabindex="-1"`. `autoplay` is better left out: this
  * starts the video itself, and without this script there is no control to stop
  * it with, while with the attribute a reduced-motion reader sees the first
- * frames move before this gets to pause them. Left in, everything still works.
+ * frames move before this gets to pause them, and the download starts before
+ * the page has loaded. Left in, everything else still works. `preload="none"`
+ * or `"metadata"` keeps the browser from fetching the loop on its own.
  */
 
 export interface BackgroundVideoState {
@@ -99,6 +106,27 @@ export interface BackgroundVideo {
 
 const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
 
+/**
+ * Whether the video starts paused when the reader has not chosen: they asked
+ * their system for less motion, or for less data. Data Saver is Chromium's,
+ * the only engine that says; elsewhere this is reduced motion alone.
+ */
+function stillByDefault(): boolean {
+    const connection = (
+        navigator as Navigator & { connection?: { saveData?: boolean } }
+    ).connection;
+    return matchMedia(REDUCED_MOTION).matches || connection?.saveData === true;
+}
+
+/** Runs `then` once the page has loaded: now if it has, else on `load`. */
+function whenLoaded(then: () => void, signal: AbortSignal): void {
+    if (document.readyState === "complete") {
+        then();
+        return;
+    }
+    addEventListener("load", then, { once: true, signal });
+}
+
 /**
  * `HTMLMediaElement.NETWORK_NO_SOURCE`, as a literal.
  *
@@ -278,7 +306,19 @@ export function backgroundVideo(
                 );
             }
 
-            apply(chosen ?? !matchMedia(REDUCED_MOTION).matches);
+            if (chosen !== undefined) {
+                apply(chosen);
+            } else if (stillByDefault()) {
+                apply(false);
+            } else {
+                // Not before the page has loaded: a loop of a few megabytes
+                // started now shares the connection with the poster the reader
+                // is waiting for, and on a phone the poster loses.
+                whenLoaded(() => {
+                    // Unless the reader chose meanwhile, or it moved on.
+                    if (video === element && chosen === undefined) apply(true);
+                }, signal);
+            }
             sync();
 
             return () => {

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/astro/site-icons.ts

@@ -0,0 +1,61 @@
+/**
+ * The site icon, cut to size. `Document`'s, and in `astro/` because cutting
+ * needs `astro:assets`, which only exists inside the build.
+ */
+
+import { getImage } from "astro:assets";
+import type { ImageAsset } from "../image.ts";
+import type { SiteIcons } from "../meta/index.ts";
+
+/**
+ * The favicon sizes, for `rel="icon"`.
+ *
+ * 48 for the tab: a browser scales it down to 16 or 32 itself, sharply, and 48
+ * is also the smallest Google takes for a search result. 192 for everything
+ * that shows the icon large — a search result on a dense screen, an Android
+ * home screen. A browser picks between them from `sizes`, fetching one.
+ */
+const FAVICON_SIZES = [48, 192] as const;
+
+/** Apple's size for `apple-touch-icon`, which it scales down from. */
+const TOUCH_SIZE = 180;
+
+/**
+ * `icon` at `size` square, as PNG.
+ *
+ * Never larger than the source: Astro's image service does not enlarge, so a
+ * size past the source's comes back as the source, and is reported at its
+ * own width rather than the one asked for.
+ */
+async function cut(icon: ImageAsset, size: number): Promise<ImageAsset> {
+    if (size >= icon.width) return icon;
+    const image = await getImage({
+        src: icon as ImageMetadata,
+        width: size,
+        height: size,
+        format: "png",
+    });
+    return { src: image.src, width: size, height: size, format: "png" };
+}
+
+/**
+ * Every icon a page links, from the project's one square source.
+ *
+ * Cut here rather than linked as given because the source is sized for the
+ * largest use — 480px is common — and a browser fetches a favicon on every
+ * first visit, before anything it actually shows. Linked as-is, that was the
+ * same tens-of-kilobytes PNG for a 16px tab.
+ */
+export async function siteIcons(icon: ImageAsset): Promise<SiteIcons> {
+    const favicons = await Promise.all(
+        FAVICON_SIZES.map((size) => cut(icon, size))
+    );
+    return {
+        // A small source makes two sizes one; linking it twice says nothing.
+        favicons: favicons.filter(
+            (each, index) =>
+                favicons.findIndex((other) => other.src === each.src) === index
+        ),
+        touch: await cut(icon, TOUCH_SIZE),
+    };
+}

package/src/index.ts

@@ -43,6 +43,18 @@ 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,
+    withPurposes,
+} from "./analytics/storage.ts";
 export type {
     LanguageTag,
     LocaleMeta,

package/src/meta/index.ts

@@ -29,7 +29,6 @@ import {
     notFoundAnalytics,
 } from "../analytics/index.ts";
 import type { ResolvedLocaleMeta } from "../config.ts";
-import type { ImageAsset } from "../image.ts";
 import {
     article,
     type BreadcrumbStep,
@@ -41,7 +40,6 @@ import type { HttpsUrl } from "../url.ts";
 import type { MetaContentBase, PageKind, ThemeColor } from "./content.ts";
 import { robotsContent, warnAboutRobots } from "./robots.ts";
 import {
-    iconLinks,
     type OgImage,
     warnAboutShareImage,
     warnIfClipped,
@@ -60,8 +58,10 @@ export type { RobotsDirective, RobotsPolicy } from "./robots.ts";
 export {
     fitDescription,
     fitTitle,
+    iconLinks,
     resolveShareImage,
     type ShareImage,
+    type SiteIcons,
 } from "./share-image.ts";
 export type { MetaTag } from "./tag.ts";
 export type { SiteVerification } from "./verification.ts";
@@ -153,8 +153,6 @@ interface MetaInputDerived<L extends string> extends ChromeInput {
  * from the chrome that they left.
  */
 export interface ChromeInput {
-    /** The site's square icon, used for every icon link. */
-    readonly icon: ImageAsset;
     /**
      * Tints the browser UI — Android Chrome's bar, iOS Safari, an installed PWA.
      * Two values emit one tag per `prefers-color-scheme`.
@@ -184,18 +182,18 @@ export interface DocumentTags {
 }
 
 /**
- * What the browser dresses its own furniture with: the tab's icon, the tint of
- * the address bar, and which schemes the page renders form controls for.
+ * What the browser dresses its own furniture with: the tint of the address
+ * bar, and which schemes the page renders form controls for. The tab's icon is
+ * furniture too, but it has to be cut to size first, which only the build can
+ * do: `Document` emits it, from `PageMeta.icon`.
  *
  * Pulled out of `buildMeta` because the 404 needs exactly this and nothing else
  * around it. Sharing the code is the point rather than a convenience: these are
- * the tags a reader sees *as* the site — a 404 with a different tab icon looks
- * like it came from somewhere else, which is the opposite of what a 404 is for —
- * and two copies of a four-branch block is how one of them quietly stops
- * matching the other.
+ * the tags a reader sees *as* the site, and two copies of a four-branch block
+ * is how one of them quietly stops matching the other.
  */
 function chromeTags(input: ChromeInput): MetaTag[] {
-    const tags: MetaTag[] = [...iconLinks(input.icon)];
+    const tags: MetaTag[] = [];
 
     if (input.colorScheme !== undefined) {
         tags.push(meta({ name: "color-scheme", content: input.colorScheme }));

package/src/meta/share-image.ts

@@ -222,26 +222,39 @@ export function resolveShareImage(
 }
 
 /**
- * The icon links: one asset, two `rel`s.
+ * The site icon, cut to the sizes its readers ask for — see `siteIcons` in
+ * `astro/`, which cuts them from the one square source a project gives.
+ */
+export interface SiteIcons {
+    /** For `rel="icon"`, smallest first: the tab's, and the search result's. */
+    readonly favicons: readonly ImageAsset[];
+    /** For `apple-touch-icon`, which Apple scales from 180. */
+    readonly touch: ImageAsset;
+}
+
+/**
+ * The icon links: each favicon, and the touch icon.
  *
- * Browsers read `icon`, Apple reads `apple-touch-icon` and scales it, and both
- * point at the same file — so they are built together rather than left to a
- * layout to remember the second one. `sizes` is stated so a browser need not
- * fetch the file to find out what it is choosing between.
+ * Built together rather than left to a layout to remember the second `rel`.
+ * `sizes` is stated so a browser picks without fetching each file to find out
+ * what it is choosing between — which, with the source served as-is, was a
+ * 480px PNG of tens of kilobytes for a 16px tab.
  *
  * The href stays as written. Unlike `og:image` these are read by a browser that
  * already has the page, so root-relative is correct and making it absolute would
  * only hard-code the origin.
  */
-export function iconLinks(icon: ImageAsset): MetaTag[] {
-    const mime = imageMime(icon.format);
-    const attrs = {
-        href: icon.src,
-        sizes: `${icon.width}x${icon.height}`,
-        ...(mime !== undefined ? { type: mime } : {}),
+export function iconLinks(icons: SiteIcons): MetaTag[] {
+    const attrs = (icon: ImageAsset) => {
+        const mime = imageMime(icon.format);
+        return {
+            href: icon.src,
+            sizes: `${icon.width}x${icon.height}`,
+            ...(mime !== undefined ? { type: mime } : {}),
+        };
     };
     return [
-        link({ rel: "icon", ...attrs }),
-        link({ rel: "apple-touch-icon", ...attrs }),
+        ...icons.favicons.map((icon) => link({ rel: "icon", ...attrs(icon) })),
+        link({ rel: "apple-touch-icon", ...attrs(icons.touch) }),
     ];
 }

package/src/site/create.ts

@@ -326,18 +326,17 @@ export function createSite<
             // Umami only, tagged so the misses read on their own — the point
             // of measuring this page is finding a redirect somebody forgot,
             // not counting the people who mistype. See `notFoundAnalytics`.
-            //
-            // `checkedIcon()` rather than `project.icon`: the 404 is held to the
-            // same square-and-PNG rules as every other page. It is also the one
-            // page that could plausibly render before any other, so letting it
-            // read the icon unchecked would move where a bad one is caught.
             tags: buildNotFoundMeta({
                 title,
                 analytics: project.analytics,
-                icon: checkedIcon(),
                 themeColor: project.themeColor,
                 colorScheme: project.colorScheme,
             }),
+            // `checkedIcon()` rather than `project.icon`: the 404 is held to the
+            // same square-and-PNG rules as every other page. It is also the one
+            // page that could plausibly render before any other, so letting it
+            // read the icon unchecked would move where a bad one is caught.
+            icon: checkedIcon(),
             // Nothing. The body channel exists for Tag Manager's `<noscript>`,
             // and no Google tag reaches this page.
             bodyTags: [],
@@ -407,7 +406,6 @@ export function createSite<
             ),
             siteName: project.siteName,
             twitterSite: project.twitterSite,
-            icon: checkedIcon(),
             verification: project.verification,
             analytics: project.analytics,
             llmsUrl,
@@ -419,6 +417,7 @@ export function createSite<
             dir: localeMeta[locale].dir,
             tags: document.head,
             bodyTags: document.body,
+            icon: checkedIcon(),
             consentVendors: consentVendors(project.analytics),
         };
     }

package/src/site/page.ts

@@ -1,3 +1,4 @@
+import type { ImageAsset } from "../image.ts";
 import type { MetaContent, MetaTag } from "../meta/index.ts";
 import type { HttpsUrl, UrlPath } from "../url.ts";
 
@@ -65,6 +66,12 @@ export interface PageMeta {
      * both, and cannot put either in the other's place.
      */
     readonly bodyTags: MetaTag[];
+    /**
+     * The site's square icon, as the project gave it. `Document` cuts it to
+     * each size a browser asks for and links those; the source itself, often
+     * hundreds of pixels across, is never linked.
+     */
+    readonly icon: ImageAsset;
     /** The vendors that need a consent banner on this page; `Document` fails without one. */
     readonly consentVendors: readonly string[];
 }