@escape-game-over/atlas 0.1.76 → 0.1.78

package/docs/client-scripts.md

@@ -36,7 +36,7 @@ finding them.
 | ------------------ | -------------------------------------------------------------- | ----------------------------------------------- |
 | `carousel`         | which slide is current: modulo, swipe, autoplay, the move lock | the transform, dots, arrows, `aria`             |
 | `filters`          | which items match, and what the address bar says               | every DOM read and write                        |
-| `filters-view`     | the two DOM writes every filtered list turned out to share     | finding the elements, and everything else drawn |
+| `filters-view`     | the DOM writes every filtered list turned out to share         | finding the elements, and everything else drawn |
 | `youtube`          | the swap from poster to player, on the click and not before    | the poster, the button, the iframe's classes    |
 | `background-video` | playing or paused, playable or not, and which cut is loaded    | the play/pause control, its icons and its label |
 | `consent`          | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law  |
@@ -249,11 +249,12 @@ re-clicking the current tab does not add a history step to walk back through.
 
 ## `filters-view`
 
-Two helpers, and the bar for being here is not "a list might want this" but
+Three helpers, and the bar for being here is not "a list might want this" but
 "every list we have already written did, character for character, and getting it
 wrong was silent". Three filtered lists in one consuming project — a catalogue, a
-location directory and an FAQ — agree on exactly these and disagree about
-everything else they draw.
+location directory and an FAQ — agree on `searchBox` and `hideEmpty` and
+disagree about everything else they draw; `filtering` was copied between two
+sites before it came here.
 
 ### `searchBox`
 
@@ -334,6 +335,49 @@ recorded as behaviour rather than only as prose.
 A group with no children at all is hidden, by the same rule: there is nothing
 visible in it.
 
+### `filtering`
+
+A chip that narrows a grid in place, animated: what stays slides to its new
+place, what leaves or arrives fades. It wraps the `set` or `reset` the chip does
+in a view transition, and runs it plainly where the API is missing.
+
+```ts
+const items = refs(root, "[data-filter-item]");
+chip.addEventListener(
+    "click",
+    () => filtering(items, () => list.set("category", data(chip, "category"))),
+    { signal }
+);
+```
+
+Every item needs its own view-transition name for the move to animate, and
+`match-element` gives each one without the page minting ids. **Only while it
+runs**: named for good, every card would also pair up across page navigations,
+and one with no partner on the next page would linger over it. So the helper
+writes the name inline, and puts back whatever inline name the item had when
+the last transition ends.
+
+**The last, not each.** A second click skips the first transition, and the
+first one's end would otherwise strip the names out from under the one still
+running, which then animates nothing. The helper counts. `tests/filtering.test.ts`
+pins the overlap, including an item that had a name of its own.
+
+**One rule stays the project's.** A site that stops unpaired names animating
+across pages also stops filtering's fades, since a card hidden or shown has no
+partner either. The helper marks `<html>` with `data-atlas-filtering`
+(`FILTERING_ATTRIBUTE`) while it runs, for the site to scope that rule out:
+
+```css
+:root:not([data-atlas-filtering])::view-transition-new(*):only-child {
+    animation: none;
+}
+:root:not([data-atlas-filtering])::view-transition-old(*):only-child {
+    display: none;
+}
+```
+
+A site without such a rule needs no CSS at all.
+
 ### Why these write instead of calling back
 
 `filters.onChange` is already the callback that hands a consumer the answer and
@@ -632,6 +676,9 @@ right properties is a faithful stand-in.
   pins the write-back guard by counting *writes* — so deleting the guard fails
   rather than passing on an identical value — and pins the nesting order in
   both directions.
+- `tests/filtering.test.ts` stubs `document` with a `startViewTransition` whose
+  transitions finish when the test says, so two overlapping runs can be ended
+  in order.
 - `tests/youtube.test.ts` fakes the trigger, and a container whose
   `ownerDocument` makes the iframe — which is why the module reaches the
   document through the container rather than the global.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.76",
+    "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/filters-view.ts

@@ -1,14 +1,15 @@
 /**
- * The two DOM writes every filtered list turned out to share.
+ * The DOM writes every filtered list turned out to share.
  *
  * `filters` decides which items match; what a page does about that is its own.
- * These are the parts three lists wrote identically, and getting wrong was
- * silent. Both take elements, never selectors, so no attribute name in this
+ * These are the parts the lists wrote identically, and getting wrong was
+ * silent. All take elements, never selectors, so no attribute name in this
  * package has to be matched by a consumer.
  *
- * They write only what is binary and derived — an input's `value`, and `hidden`
- * on a clear button, an empty message or a section with nothing left. No class,
- * style or `aria`: that is where the choices live.
+ * They write only what is binary and derived — an input's `value`, `hidden` on
+ * a clear button, an empty message or a section with nothing left, and a
+ * view-transition name while a filter animates. No class or `aria`: that is
+ * where the choices live.
  *
  * **`hidden` needs help in a grid.** Any author rule setting `display` beats it.
  * Tailwind v4's preflight ships `[hidden] { display: none !important }`; without
@@ -124,3 +125,73 @@ export function hideEmpty<T extends HTMLElement>(
         group.hidden = !visible;
     }
 }
+
+/**
+ * On `<html>` while a `filtering` transition runs: what a stylesheet that
+ * treats unpaired view-transition names one way across pages tells the two
+ * cases apart by.
+ */
+export const FILTERING_ATTRIBUTE = "data-atlas-filtering";
+
+/** Each named item, and the inline name it had before, to put back after. */
+const named = new Map<HTMLElement, string>();
+let running = 0;
+
+/**
+ * Runs `update` — the `set` or `reset` a chip or tab does — as a view
+ * transition, so what stays slides into place and what leaves or arrives
+ * fades. Without the API, `update` just runs.
+ *
+ * ```ts
+ * chip.addEventListener("click", () =>
+ *     filtering(items, () => list.set("category", data(chip, "category")))
+ * );
+ * ```
+ *
+ * **`items` are named only while it runs**, `match-element` each, and put
+ * back after. Named for good, every one of them would be a pair across pages
+ * too, and linger over the next page on navigation.
+ *
+ * **Counted, not just started**: a second click skips the first transition,
+ * and that one's end would otherwise strip the names from the one still
+ * running.
+ *
+ * **One rule is the project's**, because only the project knows it wrote the
+ * other half. A site that stops unpaired names animating across pages — so a
+ * card on one page does not fade over the next — stops filtering's fades with
+ * it, since an item hidden or shown is unpaired too. Scope it out:
+ *
+ * ```css
+ * :root:not([data-atlas-filtering])::view-transition-new(*):only-child {
+ *     animation: none;
+ * }
+ * ```
+ */
+export function filtering(
+    items: Iterable<HTMLElement>,
+    update: () => void
+): void {
+    const doc = globalThis.document;
+    if (typeof doc?.startViewTransition !== "function") {
+        update();
+        return;
+    }
+
+    for (const item of items) {
+        if (!named.has(item)) named.set(item, item.style.viewTransitionName);
+        item.style.viewTransitionName = "match-element";
+    }
+
+    const root = doc.documentElement;
+    running += 1;
+    root.setAttribute(FILTERING_ATTRIBUTE, "");
+    doc.startViewTransition(update).finished.finally(() => {
+        running -= 1;
+        if (running > 0) return;
+        root.removeAttribute(FILTERING_ATTRIBUTE);
+        for (const [item, before] of named) {
+            item.style.viewTransitionName = before;
+        }
+        named.clear();
+    });
+}

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,