@escape-game-over/atlas 0.1.1

package/src/analytics/umami.ts

@@ -0,0 +1,285 @@
+import { type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
+import { warn } from "../warn.ts";
+import type { AnalyticsTag } from "./tags.ts";
+
+/**
+ * Umami's tracker — the script that counts pageviews.
+ *
+ * Every attribute its source reads is here except one. `data-before-send`
+ * names a *global function* the page must also define, so the setting is only
+ * half the thing: a project that states it and forgets the function loses every
+ * event silently. That is a runtime coupling lib cannot check and a static
+ * config cannot express, so it stays out until something needs it badly enough
+ * to design the other half.
+ */
+export interface UmamiTracker {
+    /** Where it sits on the host. Defaults to `/script.js`. */
+    readonly path?: UrlPath;
+    /**
+     * Collect Core Web Vitals from real visitors. **Defaults to on here.**
+     *
+     * Umami's own default is off, and this overrides it — the same trade
+     * `max-image-preview:large` makes with Google's, and for the same reason: a
+     * conservative vendor default costs you something you would have wanted,
+     * and stating the better answer once beats every deployment remembering.
+     *
+     * What it buys is field data. Search Console reports against real devices,
+     * not a lab run, and this is a site made mostly of photographs — the pages
+     * that are slow are slow on somebody's phone, which is the only place that
+     * shows. The cost is a little more in each pageview payload.
+     *
+     * `false` turns it off, and writes the word rather than omitting it.
+     */
+    readonly performance?: boolean;
+    /** Leave `?query` out of recorded URLs. */
+    readonly excludeSearch?: boolean;
+    /** Leave `#hash` out of recorded URLs. */
+    readonly excludeHash?: boolean;
+    /** Honour the browser's Do Not Track setting. */
+    readonly doNotTrack?: boolean;
+    /**
+     * Whether the tracker starts itself at all. Umami's default is **on**.
+     *
+     * One of the two switches here that defaults on, which is why `false` has
+     * to be written rather than implied — the tracker reads
+     * `config('auto-track') !== 'false'`. Off means nothing is recorded until
+     * something calls Umami's API by hand.
+     */
+    readonly autoTrack?: boolean;
+    /**
+     * Whether a pageview is sent automatically. Umami's default is **on**.
+     *
+     * The other one that defaults on. Off leaves the tracker loaded and
+     * listening but silent until a pageview is sent deliberately — for a site
+     * that wants to decide what counts as a page.
+     */
+    readonly autoPageview?: boolean;
+    /** A name to group these events under, for filtering or an A/B split. */
+    readonly tag?: string;
+    /**
+     * What the tracker does with credentials when it posts.
+     *
+     * A closed vocabulary — it is `RequestCredentials` — so it is spelled out
+     * rather than left a string. Umami's default is `omit`, which is right for
+     * the `src.<domain>` convention: a subdomain is a different origin, and
+     * sending cookies to it would be sending them for nothing.
+     */
+    readonly fetchCredentials?: "omit" | "same-origin" | "include";
+}
+
+/**
+ * Umami's session replay — a *second* script, alongside the tracker rather than
+ * instead of it. Present means on; omit it and nothing is recorded.
+ *
+ * A path and nothing else, and this is settled rather than assumed: the
+ * recorder's source reads exactly two attributes off its own tag,
+ * `data-website-id` and `data-host-url`. Sample rate, mask level, max duration
+ * and block selector are real settings, and every one of them is read from the
+ * config the *server* returns —
+ *
+ * ```js
+ * if (typeof data.sampleRate === 'number') sampleRate = data.sampleRate;
+ * if (typeof data.maskLevel === 'string')  maskLevel  = data.maskLevel;
+ * ```
+ *
+ * — so they are set per site in Umami's own dashboard, under Replays &
+ * Heatmaps, and an attribute cannot override one. Fields for them here would
+ * look like they did something. Checked against `src/recorder/index.js` on
+ * `master`, August 2026.
+ */
+export interface UmamiReplay {
+    /** Where it sits on the host. Defaults to `/recorder.js`. */
+    readonly path?: UrlPath;
+}
+
+export interface UmamiSettings {
+    /**
+     * This deployment's site id, from its Umami dashboard.
+     *
+     * Per project: two deployments sharing an id report into one dashboard as a
+     * single site, and nobody notices until one venue's traffic appears to
+     * double the week another launches.
+     */
+    readonly websiteId: string;
+    /**
+     * Where the scripts are served from — `https://src.example.com`.
+     *
+     * First-party by convention, because an analytics domain is on every
+     * blocklist and a subdomain of the site is not: served from `src.` on a
+     * domain the site owns, the numbers do not quietly exclude every reader who
+     * blocks trackers.
+     *
+     * **Required, and deliberately not derived from `url`.** `src.<this site's
+     * own host>` is right only where the site sits at the domain root. A fleet
+     * that puts each site on a subdomain — `atlanta.example.com`,
+     * `lecce.example.it` — serves one `src.example.com` for all of them, so
+     * deriving would produce `src.atlanta.example.com`, which does not exist.
+     * The script 404s, nothing is recorded, and there is no error anywhere: the
+     * dashboard simply stays at zero.
+     *
+     * Nor can the parent be derived. Stripping a subdomain needs the public
+     * suffix list to know that `example.co.uk` is a site and `co.uk` is not,
+     * which is a registry lib will not carry. One line per deployment is the
+     * cheaper answer, and it is a line that cannot be wrong by accident.
+     */
+    readonly host: HttpsUrl;
+    /**
+     * Every hostname that serves this site.
+     *
+     * Required, and required for a reason the optional version taught: left
+     * out, Umami records from anywhere — so a preview deployment reports into
+     * the production dashboard, and so does every reload on localhost. Neither
+     * looks wrong; the numbers are simply too high, and nobody audits numbers
+     * that flatter.
+     *
+     * **Every host, not just the canonical one.** A site reachable at the apex
+     * and at `www.` needs both unless one only ever redirects — a visitor
+     * landing on the host you left out is not counted, and nothing says so.
+     *
+     * Not derived from `url`, though it nearly could be. That would make the
+     * safe-looking default "only the canonical host", which silently drops the
+     * `www.` traffic of every site serving both. Stating it is a moment's
+     * thought; the alternative is a number that reads low forever.
+     */
+    readonly domains: readonly [string, ...string[]];
+    /**
+     * Where the collected data is *sent*, if not where the script came from.
+     *
+     * `data-host-url` — the one option beyond the id that both scripts read.
+     * Distinct from `host` above: that is where the JavaScript is fetched, this
+     * is where it posts. Left out, Umami derives it from the script's own URL,
+     * which for the `src.<domain>` convention is already the right answer.
+     */
+    readonly collectUrl?: HttpsUrl;
+    readonly tracker?: UmamiTracker;
+    readonly replay?: UmamiReplay;
+}
+
+/**
+ * Three states, not two: `undefined` leaves the attribute out and takes Umami's
+ * own default, while `false` writes `"false"` and overrides it.
+ *
+ * Omitting is *not* a way to say false, and the tracker's source is explicit
+ * about why — the two kinds of switch are read differently:
+ *
+ * ```js
+ * const perf         = config('performance')   === 'true';   // omit ⇒ off
+ * const autoTrack    = config('auto-track')    !== 'false';  // omit ⇒ ON
+ * const autoPageview = config('auto-pageview') !== 'false';  // omit ⇒ ON
+ * ```
+ *
+ * For the first kind, leaving it out and writing `"false"` agree. For the
+ * other two, the literal word is the only thing that turns them off. A helper
+ * that collapsed `false` into "leave it out" would silently keep those enabled.
+ *
+ * Checked against `src/tracker/index.js` on `master`, August 2026.
+ */
+const flag = (on: boolean | undefined): string | undefined =>
+    on === undefined ? undefined : String(on);
+
+/** Drops the attributes this deployment did not ask for. */
+const stated = (
+    attributes: Readonly<Record<string, string | undefined>>
+): Readonly<Record<string, string>> =>
+    Object.fromEntries(
+        Object.entries(attributes).filter(([, value]) => value !== undefined)
+    ) as Readonly<Record<string, string>>;
+
+/**
+ * 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
+ * say the same thing several times about one mistake.
+ *
+ * The mistake is worth catching: a list without the real host records nothing
+ * at all. No error, no empty dashboard to notice, just a number that stays at
+ * zero, and a typo in one hostname is enough.
+ *
+ * Only the canonical host is checked. Whether `www.` or a second domain also
+ * serves is a fact about DNS lib cannot see, so listing extras is never
+ * questioned and leaving one out cannot be.
+ */
+export function checkUmamiDomains(
+    umami: UmamiSettings | undefined,
+    origin: HttpsUrl
+): void {
+    if (umami === undefined) return;
+    const site = new URL(origin).hostname;
+    if (umami.domains.includes(site)) return;
+
+    warn(
+        origin,
+        `analytics records only on ${umami.domains.join(", ")}, and this site is served from ${site} — which is not among them, so nothing will be recorded. Add every host that serves the site, including www. if it does.`
+    );
+}
+
+/**
+ * Umami's scripts: the tracker, and the recorder where one was asked for.
+ *
+ * `tag` overrides whatever the tracker configured, for a page that wants its
+ * traffic grouped separately — the 404 does. Umami's `data-tag` is a single
+ * string, so it is a replacement rather than an addition; there is no way to
+ * carry both.
+ */
+export function umamiScripts(
+    umami: UmamiSettings | undefined,
+    tag?: string
+): readonly AnalyticsTag[] {
+    if (umami === undefined) return [];
+
+    // Through `joinUrl`, not concatenation. `HttpsUrl` cannot express "without
+    // a trailing slash", so a host written `https://src.example.com/` — which
+    // type-checks, and is how anyone who copied it out of a browser bar would
+    // write it — would otherwise yield `https://src.example.com//script.js`.
+    // That is a different URL: it may 404, and if it does the failure is
+    // silent, because nothing on the page reports a script that did not load
+    // and the dashboard simply stays at zero.
+    const at = (path: UrlPath): string => joinUrl(umami.host, path);
+
+    // Both scripts read the same two: the id, and where to post. Everything
+    // after that is the tracker's alone — the recorder takes nothing else.
+    //
+    // Left unfiltered here so that each script's attributes are filtered once,
+    // where they are assembled, rather than here and then again on the way in.
+    const common = {
+        "data-website-id": umami.websiteId,
+        "data-host-url": umami.collectUrl,
+    };
+
+    return [
+        {
+            kind: "external",
+            src: at(umami.tracker?.path ?? "/script.js"),
+            attributes: stated({
+                ...common,
+                // The one default lib overrides — see `UmamiTracker`. The
+                // others are left to Umami: `auto-track` and `auto-pageview`
+                // are already on unless the word `false` appears, so stating
+                // them would be bytes that change nothing, and whether to
+                // honour Do Not Track or drop query strings is a decision about
+                // this business rather than about this kind of site.
+                "data-performance": flag(umami.tracker?.performance ?? true),
+                "data-exclude-search": flag(umami.tracker?.excludeSearch),
+                "data-exclude-hash": flag(umami.tracker?.excludeHash),
+                "data-do-not-track": flag(umami.tracker?.doNotTrack),
+                "data-auto-track": flag(umami.tracker?.autoTrack),
+                "data-auto-pageview": flag(umami.tracker?.autoPageview),
+                "data-tag": tag ?? umami.tracker?.tag,
+                "data-fetch-credentials": umami.tracker?.fetchCredentials,
+                // Comma-delimited, which is Umami's format and not a shape a
+                // project should have to know: it writes a list.
+                "data-domains": umami.domains.join(","),
+            }),
+        },
+        ...(umami.replay === undefined
+            ? []
+            : [
+                  {
+                      kind: "external" as const,
+                      src: at(umami.replay.path ?? "/recorder.js"),
+                      attributes: stated(common),
+                  },
+              ]),
+    ];
+}

package/src/astro/MetaTags.astro

@@ -0,0 +1,87 @@
+---
+/**
+ * Renders what `metaFor` described, one element per `MetaTag`.
+ *
+ * The other half of `asMetaTag` in `lib/meta/tag.ts`: that one converts *into*
+ * the union, this one out of it. Both enumerate the same kinds, and keeping
+ * them in different repositories is what let them drift — the converter had an
+ * exhaustiveness guard from the day it was written and this file did not, so a
+ * kind added to `MetaTag` would have rendered here as a bare `<meta>`.
+ *
+ * In `lib/astro/` rather than a project's `src/`, unlike every other component
+ * in this template, because it carries no design and no copy: no classes, no
+ * translated strings, nothing from `@config`. It is a `kind` → element switch,
+ * and the four things it knows are each a decision worth making once —
+ * `set:html` for pre-escaped JSON, `is:inline` so the bundler leaves a
+ * third-party URL alone, `defer` so measuring a page does not cost what it
+ * measures, and the zero-sized frame Tag Manager wants. Four chances for a
+ * repository to get one of them wrong.
+ *
+ * ```astro
+ * import MetaTags from "@escape-game-over/atlas/astro/meta-tags";
+ *
+ * <head><MetaTags tags={meta.tags} /></head>
+ * <body><MetaTags tags={meta.bodyTags} /> …
+ * ```
+ *
+ * Both lists, and in those places: `bodyTags` is usually empty and holds the
+ * one tag the head would ignore.
+ */
+// Relative, like every other file in the package: the bare specifier is the
+// 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";
+
+interface Props {
+    readonly tags: readonly MetaTag[];
+}
+
+const { tags } = Astro.props;
+---
+
+{
+  tags.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
+    // every less-than sign with its unicode escape, which is what stops a
+    // `</script` inside a description closing the block early. Escaping it
+    // again as HTML would turn each quote into an entity and leave a block no
+    // parser reads.
+    if (tag.kind === "script") {
+      return <script type={tag.type} is:inline set:html={tag.content} />;
+    }
+    // `is:inline` so the bundler leaves a third-party URL alone, and `defer`
+    // because a script that blocks the parser costs the thing it measures.
+    if (tag.kind === "externalScript") {
+      return <script is:inline defer src={tag.src} {...tag.attrs} />;
+    }
+    // Tag Manager's fallback, and only ever in the body list. Hidden the way
+    // Google's own snippet hides it — a zero-sized iframe nothing can see.
+    if (tag.kind === "noscriptFrame") {
+      return (
+        <noscript>
+          <iframe
+            src={tag.src}
+            title="Google Tag Manager"
+            height="0"
+            width="0"
+            style="display:none;visibility:hidden"
+          />
+        </noscript>
+      );
+    }
+    if (tag.kind === "meta") return <meta {...tag.attrs} />;
+    // Named rather than left to a trailing `return`, which used to catch
+    // `meta` and everything else alike: a kind added to `MetaTag` and forgotten
+    // here would have rendered as `<meta {...tag.attrs}>`, and for a kind
+    // carrying no `attrs` that is a bare `<meta>` — valid markup, nothing in
+    // the page, nothing in the build.
+    //
+    // `lib/meta/tag.ts` guards the mirror of this problem the same way, and
+    // this half matters more: that one is written once, while this file is
+    // copied into every project.
+    const unhandled: never = tag;
+    throw new Error(`Unhandled meta tag: ${JSON.stringify(unhandled)}`);
+  })
+}

package/src/astro/consent.ts

@@ -0,0 +1,165 @@
+import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
+
+/**
+ * The browser half of consent: remembering an answer, expiring it, and handing
+ * it to Google.
+ *
+ * In `astro/` because it touches `window` and `localStorage`, which the core is
+ * type-checked without — this is the one folder allowed them. Imported by a
+ * consent banner's client script rather than emitted as head script, so a
+ * project gets real functions with real types instead of a global it has to
+ * know the name of.
+ *
+ * What is *not* here: the banner. Its markup, its wording, whether it has a
+ * reject button as prominent as accept, and whether a visitor can change their
+ * mind later are product and legal decisions, and lib would be guessing at all
+ * four. What is here is the part that is the same everywhere and easy to get
+ * subtly wrong.
+ */
+
+/** Granted or denied — the only two answers Consent Mode has. */
+export type ConsentChoice = "granted" | "denied";
+
+/** An answer, and when it was given. */
+export interface ConsentRecord {
+    readonly choice: ConsentChoice;
+    /** ISO 8601, so it is legible in devtools rather than a number. */
+    readonly at: string;
+}
+
+/**
+ * How long an answer stands before the question is asked again.
+ *
+ * Consent is not forever and regulators say so: France's CNIL puts the outside
+ * limit at 13 months and recommends six, and the EDPB's position is that a
+ * choice made long enough ago is no longer informed. Six is the conservative
+ * reading, and the reason the record carries a date at all — without one there
+ * is no way to expire it, and no way to answer "when did this visitor agree?",
+ * which is a question only ever asked when somebody is already unhappy.
+ */
+const DEFAULT_MONTHS = 6;
+
+/**
+ * Where the answer is kept.
+ *
+ * `localStorage` is already scoped to an origin, so this does not need to
+ * identify the site — what it needs is to not collide with something else on
+ * the page, and a bare `"consent"` is exactly the key a third-party consent
+ * tool or chat widget would reach for. The prefix matches
+ * `CONSENT_UPDATE_GLOBAL`, so one concept has one name on both sides.
+ *
+ * Overridable for the case the default cannot cover: two deployments sharing
+ * one origin — `example.com/rome` and `example.com/bucharest` — where one key
+ * would mean one answer for both. See `consentStore`.
+ */
+const DEFAULT_KEY = "__consent";
+
+export interface ConsentStoreOptions {
+    /** Overrides `DEFAULT_KEY`. See it for the one case that needs this. */
+    readonly key?: string;
+    /** Overrides the six-month window. See `DEFAULT_MONTHS`. */
+    readonly months?: number;
+}
+
+/**
+ * Reading and writing an answer, bound to one key and one window.
+ *
+ * A factory rather than two functions each taking options, because the key and
+ * the window have to *match* between them: a read that looked in one place and
+ * a write that filled another would ask a visitor on every page while
+ * faithfully recording each answer. Bound once, they cannot disagree.
+ */
+export function consentStore(options: ConsentStoreOptions = {}): {
+    read(): ConsentRecord | undefined;
+    record(choice: ConsentChoice): void;
+} {
+    const key = options.key ?? DEFAULT_KEY;
+    const months = options.months ?? DEFAULT_MONTHS;
+
+    return {
+        /**
+         * The answer this visitor gave, if it still counts.
+         *
+         * `undefined` for never asked, for an expired answer, and for anything
+         * unparseable — all three mean the same thing to a banner, and all
+         * three should ask rather than assume. Storage hand-edited, or written
+         * by an older version of this code, lands in the third case by design.
+         */
+        read(): ConsentRecord | undefined {
+            let raw: string | null = null;
+            try {
+                raw = localStorage.getItem(key);
+            } catch {
+                // Private browsing, or storage disabled. Nothing was
+                // remembered, so nothing is assumed.
+                return undefined;
+            }
+            if (raw === null) return undefined;
+
+            try {
+                const parsed = JSON.parse(raw) as Partial<ConsentRecord>;
+                if (parsed.choice !== "granted" && parsed.choice !== "denied") {
+                    return undefined;
+                }
+                if (typeof parsed.at !== "string") return undefined;
+
+                const expiry = new Date(parsed.at);
+                if (Number.isNaN(expiry.getTime())) return undefined;
+                expiry.setMonth(expiry.getMonth() + months);
+                if (expiry < new Date()) return undefined;
+
+                return { choice: parsed.choice, at: parsed.at };
+            } catch {
+                return undefined;
+            }
+        },
+
+        /**
+         * Remembers an answer, dated now, and tells Google about it.
+         *
+         * One call rather than two, because the two must not come apart: an
+         * answer stored but never applied leaves the visitor consented in name
+         * only, and one applied but never stored asks them again next page.
+         */
+        record(choice: ConsentChoice): void {
+            const record: ConsentRecord = {
+                choice,
+                at: new Date().toISOString(),
+            };
+            try {
+                localStorage.setItem(key, JSON.stringify(record));
+            } catch {
+                // Unable to remember it, which is a worse experience and not a
+                // wrong one — the choice still applies to this page.
+            }
+            applyConsent(choice);
+        },
+    };
+}
+
+/**
+ * Hands a choice to Google, if there is a Google tag on this deployment.
+ *
+ * Reaches the head script through a global, which is the only way the two can
+ * meet: that script runs before any module exists. The name lives in one place
+ * — `CONSENT_UPDATE_GLOBAL` — and is referenced here and where it is emitted,
+ * so a project never types it.
+ *
+ * What it updates is decided over there, from the same settings that decided
+ * what to deny. A payload built here would be a second copy of that list.
+ */
+export function applyConsent(choice: ConsentChoice): void {
+    const update = (
+        window as unknown as Record<string, ((c: string) => void) | undefined>
+    )[CONSENT_UPDATE_GLOBAL];
+    update?.(choice);
+}
+
+/** Whether this deployment has a Google tag to consent to at all. */
+export function consentApplies(): boolean {
+    return (
+        (window as unknown as Record<string, unknown>)[
+            CONSENT_UPDATE_GLOBAL
+        ] !== undefined
+    );
+}