@escape-game-over/atlas 0.1.106 → 0.1.108

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.106",
+    "version": "0.1.108",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -22,6 +22,7 @@
         "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
         "./astro/document": "./src/astro/Document.astro",
         "./astro/element": "./src/astro/AtlasElement.astro",
+        "./astro/escape-navigator": "./src/astro/EscapeNavigator.astro",
         "./astro/four-escape": "./src/astro/FourEscape.astro",
         "./astro/google-map": "./src/astro/GoogleMap.astro",
         "./astro/image": "./src/astro/Image.astro",
@@ -65,7 +66,7 @@
         "@biomejs/biome": "2.6.6",
         "@types/node": "26.6.6",
         "@vitest/coverage-istanbul": "5.1.0",
-        "astro": "7.4.7",
+        "astro": "7.4.10",
         "typescript": "6.0.3",
         "vitest": "5.1.0"
     }

package/src/analytics/storage.ts

@@ -52,7 +52,9 @@ export const STORAGE_VENDOR_NAMES = {
     drip: "Drip",
     clarity: "Microsoft Clarity",
     "4escape": "4escape",
-} as const satisfies Record<StorageVendor | BookingVendor, string>;
+    escapenavigator: "Escape Navigator",
+    stripe: "Stripe",
+} as const satisfies Record<StorageVendor | BookingVendor | "stripe", string>;
 
 /** A span `Intl.NumberFormat` can word in any locale: `{ 2, "year" }`. */
 export interface Lifetime {
@@ -69,15 +71,23 @@ export type AtlasStoredId = "atlas-locale" | "atlas-campaign" | "atlas-consent";
 /** A booking widget's rows: what it keeps, and what it keeps for the tab. */
 type BookingRow = BookingVendor | `${BookingVendor}-tab`;
 
+/** Stripe's, for a booking widget that takes payment through it. */
+type StripeRow = "stripe" | "stripe-own";
+
 /** One row's id: what a project keys the row's wording by. */
-export type StoredId = AtlasStoredId | StorageVendor | OwnRow | BookingRow;
+export type StoredId =
+    | AtlasStoredId
+    | StorageVendor
+    | OwnRow
+    | BookingRow
+    | StripeRow;
 
 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 | BookingVendor;
+    readonly provider: "site" | StorageVendor | BookingVendor | "stripe";
     /** 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. */
@@ -267,11 +277,22 @@ const VENDOR_ORDER: readonly StorageVendor[] = [
 ];
 
 /** The vendors a deployment's settings load, in catalog order. */
+/** What a booking widget keeps, and what it brings with it. */
+interface BookingStorage {
+    /** In local storage on the site's domain, until cleared. */
+    readonly kept: readonly string[];
+    /** In session storage, for the tab. */
+    readonly tab: readonly string[];
+    /** Takes payment through Stripe, whose fraud check sets cookies unasked. */
+    readonly stripe?: true;
+    /** Tags it loads itself, with the store's own ids, once consent allows. */
+    readonly loads?: readonly StorageVendor[];
+}
+
 /**
- * Each booking widget's storage, all on the site's domain and none of it
- * cookies: what its script left after rendering, seen live 2026-11-11, since
- * the vendor documents none. Functional — the language, the cart — so nothing
- * has to be granted first.
+ * Each booking widget's storage: what its script left after rendering, seen
+ * live 2026-11-11, since neither vendor documents it. Its own keys are
+ * functional — the language, the cart — so nothing has to be granted first.
  */
 const BOOKING = {
     // `forescapeAnalytics` stayed empty, with no tracker loaded; listed because
@@ -280,10 +301,43 @@ const BOOKING = {
         kept: ["forescapeLayout", "forescapeStoreOrder", "forescapeAnalytics"],
         tab: ["forescape"],
     },
-} as const satisfies Record<
-    BookingVendor,
-    { readonly kept: readonly string[]; readonly tab: readonly string[] }
->;
+    // docs.escapenavigator.com/guides-and-tips/google-analytics-4 for the tags:
+    // the store's own, from its Escape Navigator settings.
+    escapenavigator: {
+        kept: [
+            "theme",
+            "escapeNavigatorBookingState_v1_<id>",
+            "lastExternalReferrer",
+            "lastExternalReferrerTime",
+        ],
+        tab: ["escapenavigator:consent-warned:<state>"],
+        stripe: true,
+        loads: ["google-analytics", "google-ads", "meta"],
+    },
+} as const satisfies Record<BookingVendor, BookingStorage>;
+
+/**
+ * Stripe's fraud-prevention cookies, which Stripe.js sets whether or not
+ * anything is paid: stripe.com/legal/cookies-policy. Seen live 2026-11-11;
+ * `m` lasts two years as Stripe states it, which Chrome caps at 400 days.
+ */
+const STRIPE_ROWS: readonly StoredItem[] = [
+    {
+        id: "stripe",
+        names: ["__stripe_mid", "__stripe_sid"],
+        provider: "stripe",
+        lasts: year(1),
+        consent: "none",
+    },
+    {
+        id: "stripe-own",
+        names: ["m"],
+        provider: "stripe",
+        domains: ["m.stripe.com"],
+        lasts: year(2),
+        consent: "none",
+    },
+];
 
 function loadedVendors(
     analytics: AnalyticsSettings | undefined
@@ -391,7 +445,35 @@ export function storedItems(
         });
     }
 
-    for (const vendor of loadedVendors(analytics)) {
+    // Each widget's own rows, and what it brings: tags it loads, which join
+    // the site's own below, and Stripe's cookies, listed once however many.
+    const vendors = new Set(loadedVendors(analytics));
+    const widgetRows: StoredItem[] = [];
+    let stripe = false;
+    for (const widget of new Set(booking)) {
+        const entry: BookingStorage = BOOKING[widget];
+        widgetRows.push(
+            {
+                id: widget,
+                names: entry.kept,
+                provider: widget,
+                lasts: "kept",
+                consent: "none",
+            },
+            {
+                id: `${widget}-tab`,
+                names: entry.tab,
+                provider: widget,
+                lasts: "tab",
+                consent: "none",
+            }
+        );
+        for (const vendor of entry.loads ?? []) vendors.add(vendor);
+        if (entry.stripe) stripe = true;
+    }
+    if (stripe) widgetRows.push(...STRIPE_ROWS);
+
+    for (const vendor of vendors) {
         const entry: VendorStorage = CATALOG[vendor];
         rows.push({
             id: vendor,
@@ -412,23 +494,7 @@ export function storedItems(
         }
     }
 
-    for (const widget of new Set(booking)) {
-        const entry = BOOKING[widget];
-        rows.push({
-            id: widget,
-            names: entry.kept,
-            provider: widget,
-            lasts: "kept",
-            consent: "none",
-        });
-        rows.push({
-            id: `${widget}-tab`,
-            names: entry.tab,
-            provider: widget,
-            lasts: "tab",
-            consent: "none",
-        });
-    }
+    rows.push(...widgetRows);
 
     return sort ? rows.toSorted(compareStoredItems) : rows;
 }

package/src/analytics/umami.ts

@@ -47,6 +47,19 @@ export interface UmamiTracker {
      * `false` turns it off, and writes the word rather than omitting it.
      */
     readonly excludeHash?: boolean;
+    /**
+     * Record uncaught exceptions and unhandled promise rejections, grouped into
+     * issues in Umami's dashboard. **Defaults to on here.**
+     *
+     * Umami's own default is off — the tracker reads `config('errors') ===
+     * 'true'`. Overridden for the reason `performance` is: a script error on a
+     * visitor's phone happens nowhere else, and this is the only place it can
+     * be seen. Needs Umami 3.5 on the server; an older one serves a tracker that
+     * ignores the attribute, so it is harmless before the upgrade.
+     *
+     * `false` turns it off, and writes the word rather than omitting it.
+     */
+    readonly errors?: boolean;
     /** Honour the browser's Do Not Track setting. */
     readonly doNotTrack?: boolean;
     /**
@@ -276,7 +289,7 @@ export function umamiScripts(
             src: at(umami.tracker?.path ?? "/script.js"),
             attrs: stated({
                 ...common,
-                // The two defaults lib overrides — see `UmamiTracker`. The
+                // The three defaults 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
@@ -284,6 +297,7 @@ export function umamiScripts(
                 // this business rather than about this kind of site.
                 "data-performance": flag(umami.tracker?.performance ?? true),
                 "data-exclude-hash": flag(umami.tracker?.excludeHash ?? true),
+                "data-errors": flag(umami.tracker?.errors ?? true),
                 "data-exclude-search": flag(umami.tracker?.excludeSearch),
                 "data-do-not-track": flag(umami.tracker?.doNotTrack),
                 "data-auto-track": flag(umami.tracker?.autoTrack),

package/src/astro/BookingWidget.astro

@@ -14,6 +14,7 @@
  */
 import type { HTMLAttributes } from "astro/types";
 import type { BookingWidget, BookingWidgetVars } from "../booking/widget.ts";
+import EscapeNavigator from "./EscapeNavigator.astro";
 import FourEscape from "./FourEscape.astro";
 
 type Props<W extends BookingWidget = BookingWidget> = HTMLAttributes<"div"> & {
@@ -22,9 +23,11 @@ type Props<W extends BookingWidget = BookingWidget> = HTMLAttributes<"div"> & {
     readonly locale: string;
     /** The widget's vendor's CSS variables, set on its widgets. */
     readonly vars?: BookingWidgetVars<W>;
+    /** The site's light or dark look, for a vendor that draws both. */
+    readonly colorScheme?: "light" | "dark";
 };
 
-const { widget, locale, vars, ...attrs } = Astro.props;
+const { widget, locale, vars, colorScheme, ...attrs } = Astro.props;
 ---
 
 {widget.vendor === "4escape" && (
@@ -36,3 +39,11 @@ const { widget, locale, vars, ...attrs } = Astro.props;
         vars={vars}
     />
 )}
+{widget.vendor === "escapenavigator" && (
+    <EscapeNavigator
+        {...attrs}
+        widgetId={widget.widgetId}
+        locale={locale}
+        colorScheme={colorScheme}
+    />
+)}

package/src/astro/EscapeNavigator.astro

@@ -0,0 +1,39 @@
+---
+/**
+ * An Escape Navigator schedule: the store's rooms and their free slots,
+ * booked in a drawer on the page. See `escape-navigator.ts` for what the
+ * widget loads, and how it learns the visitor's consent.
+ *
+ * `locale` is the page's; `colorScheme` picks the widget's light or dark look,
+ * the site's own. Attributes go on the widget's element.
+ *
+ * ```astro
+ * <EscapeNavigator widgetId="W0000000AB" locale={locale} colorScheme="dark" />
+ * ```
+ */
+import type { HTMLAttributes } from "astro/types";
+import {
+    checkEscapeNavigator,
+    type EscapeNavigatorWidget,
+    escapeNavigatorLanguage,
+} from "../booking/escape-navigator.ts";
+
+type Props = HTMLAttributes<"div"> &
+    EscapeNavigatorWidget & {
+        readonly locale: string;
+        readonly colorScheme?: "light" | "dark";
+    };
+
+const { widgetId, locale, colorScheme = "light", ...attrs } = Astro.props;
+
+checkEscapeNavigator({ widgetId }, Astro.url.pathname);
+---
+
+<script src="./escape-navigator-consent.ts"></script>
+<div
+    {...attrs}
+    data-widget-id={widgetId}
+    data-widget-type="schedule"
+    data-language={escapeNavigatorLanguage(locale)}
+    data-theme={colorScheme}
+></div>

package/src/astro/escape-navigator-consent.ts

@@ -0,0 +1,38 @@
+import { ESCAPE_NAVIGATOR_LOADER } from "../booking/escape-navigator.ts";
+import { appendScript } from "./append-script.ts";
+import { CONSENT_EVENT, type ConsentChoices, readConsent } from "./consent.ts";
+
+/**
+ * Escape Navigator's consent, from the visitor's answer on this site: its
+ * analytics tags with ours, its ad tags with marketing. Denied until answered.
+ */
+function escapeNavigatorConsent(choices: ConsentChoices | undefined) {
+    return {
+        analytics: choices?.analytics === "granted",
+        ads: choices?.marketing === "granted",
+    };
+}
+
+interface EscapeNavigatorGlobal {
+    __pendingConsent?: { analytics: boolean; ads: boolean };
+    setConsent?: (consent: { analytics: boolean; ads: boolean }) => void;
+}
+
+const host = window as unknown as { EscapeNavigator?: EscapeNavigatorGlobal };
+
+// Before the loader runs, which reads the pending answer as it starts: its
+// tags never load on an answer the visitor has not given.
+host.EscapeNavigator ??= {};
+host.EscapeNavigator.__pendingConsent = escapeNavigatorConsent(readConsent());
+
+addEventListener(CONSENT_EVENT, (event) => {
+    const consent = escapeNavigatorConsent(
+        (event as CustomEvent<ConsentChoices>).detail
+    );
+    const navigator = host.EscapeNavigator ?? {};
+    if (navigator.setConsent) navigator.setConsent(consent);
+    else navigator.__pendingConsent = consent;
+});
+
+// Once per page, however many widgets: this module runs once.
+appendScript(ESCAPE_NAVIGATOR_LOADER);

package/src/booking/escape-navigator.ts

@@ -0,0 +1,57 @@
+import { invalidId, UUID } from "../analytics/ids.ts";
+
+/**
+ * Escape Navigator's booking widget: a store's schedule, every room's free
+ * slots, booked in a drawer on the page and paid through Stripe.
+ *
+ * Plain markup and one loader script. The widget runs the store's own Google
+ * Analytics, Google Ads and Meta tags, set up in Escape Navigator, and sends
+ * the visitor's email and phone to Google before a purchase (Enhanced
+ * Conversions). It loads them only once told the visitor's consent: the
+ * component tells it the answer given on this site, before the loader runs
+ * and on every change. Stripe's fraud check sets its cookies without asking.
+ * All of it is in `storedItems`.
+ *
+ * The embed is Escape Navigator's documented one. The consent call
+ * (`EscapeNavigator.setConsent`) is not documented: it is its loader's own,
+ * read 2026-11-11, and seen to hold the tags back until consent is given.
+ *
+ * @see https://docs.escapenavigator.com/guides-and-tips/use-widgets-like-a-pro
+ * @see https://docs.escapenavigator.com/guides-and-tips/google-analytics-4
+ */
+export interface EscapeNavigatorWidget {
+    /**
+     * The widget's id, from its card in Escape Navigator: a UUID, or `W` and
+     * nine capitals and digits as older widgets have. A widget for one room is
+     * a widget of its own, with its own id.
+     */
+    readonly widgetId: string;
+}
+
+/** Escape Navigator's own CSS variables: none it documents, so none taken. */
+export type EscapeNavigatorVars = Readonly<Partial<Record<string, never>>>;
+
+/** The loader every Escape Navigator widget on a page shares. */
+export const ESCAPE_NAVIGATOR_LOADER =
+    "https://widget.escapenavigator.com/widget-loader.js";
+
+/** The older form of widget id; newer ones are UUIDs. */
+const SHORT_ID = /^W[A-Z0-9]{9}$/;
+
+/** Fails the build on an id that is not a widget's: it would render nothing. */
+export function checkEscapeNavigator(
+    widget: EscapeNavigatorWidget,
+    at: string
+): void {
+    if (!(UUID.test(widget.widgetId) || SHORT_ID.test(widget.widgetId))) {
+        invalidId(
+            at,
+            `Escape Navigator widget id "${widget.widgetId}" is neither a UUID nor "W" and nine capitals and digits, so it would render nothing. Copy it from the widget's card in Escape Navigator.`
+        );
+    }
+}
+
+/** The widget's language for a page's locale: its language subtag. */
+export function escapeNavigatorLanguage(locale: string): string {
+    return new Intl.Locale(locale).language;
+}

package/src/booking/widget.ts

@@ -1,10 +1,16 @@
+import type {
+    EscapeNavigatorVars,
+    EscapeNavigatorWidget,
+} from "./escape-navigator.ts";
 import type { FourEscapeVars, FourEscapeWidget } from "./four-escape.ts";
 
 /**
  * A booking widget a site embeds, by its vendor: what a site's config names,
  * and what picks the component that draws it.
  */
-export type BookingWidget = { readonly vendor: "4escape" } & FourEscapeWidget;
+export type BookingWidget =
+    | ({ readonly vendor: "4escape" } & FourEscapeWidget)
+    | ({ readonly vendor: "escapenavigator" } & EscapeNavigatorWidget);
 
 /** Who makes a booking widget: what `storedItems` takes for their rows. */
 export type BookingVendor = BookingWidget["vendor"];
@@ -12,6 +18,7 @@ export type BookingVendor = BookingWidget["vendor"];
 /** Each vendor's CSS variables, as a page sets them on its widgets. */
 export interface BookingVendorVars {
     readonly "4escape": FourEscapeVars;
+    readonly escapenavigator: EscapeNavigatorVars;
 }
 
 /** The CSS variables a widget takes: its own vendor's, and no other's. */

package/src/index.ts

@@ -55,6 +55,13 @@ export {
     storedItems,
     withPurposes,
 } from "./analytics/storage.ts";
+export {
+    checkEscapeNavigator,
+    ESCAPE_NAVIGATOR_LOADER,
+    type EscapeNavigatorVars,
+    type EscapeNavigatorWidget,
+    escapeNavigatorLanguage,
+} from "./booking/escape-navigator.ts";
 export {
     checkFourEscape,
     FOUR_ESCAPE_LANGUAGES,