@escape-game-over/atlas 0.1.102 → 0.1.104

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.102",
+    "version": "0.1.104",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -21,6 +21,7 @@
         "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
         "./astro/document": "./src/astro/Document.astro",
         "./astro/element": "./src/astro/AtlasElement.astro",
+        "./astro/four-escape": "./src/astro/FourEscape.astro",
         "./astro/google-map": "./src/astro/GoogleMap.astro",
         "./astro/image": "./src/astro/Image.astro",
         "./astro/phone": "./src/astro/Phone.astro",

package/src/analytics/storage.ts

@@ -1,3 +1,4 @@
+import type { BookingVendor } from "../booking/widget.ts";
 import {
     CONSENT_KEY,
     CONSENT_MONTHS,
@@ -50,7 +51,8 @@ export const STORAGE_VENDOR_NAMES = {
     axon: "AppLovin Axon",
     drip: "Drip",
     clarity: "Microsoft Clarity",
-} as const satisfies Record<StorageVendor, string>;
+    "4escape": "4escape",
+} as const satisfies Record<StorageVendor | BookingVendor, string>;
 
 /** A span `Intl.NumberFormat` can word in any locale: `{ 2, "year" }`. */
 export interface Lifetime {
@@ -64,15 +66,18 @@ type OwnRow = `${VendorWithOwn}-own`;
 /** The keys Atlas itself sets. */
 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`;
+
 /** One row's id: what a project keys the row's wording by. */
-export type StoredId = AtlasStoredId | StorageVendor | OwnRow;
+export type StoredId = AtlasStoredId | StorageVendor | OwnRow | BookingRow;
 
 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;
+    readonly provider: "site" | StorageVendor | BookingVendor;
     /** 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. */
@@ -86,6 +91,12 @@ export interface StoredItemsOptions {
     readonly rememberLocale?: boolean;
     /** As passed to `Document`, and with its default: `false`. */
     readonly rememberCampaign?: boolean;
+    /**
+     * The vendors of the booking widgets the site embeds anywhere: their
+     * storage is on the site's domain, where the analytics settings cannot
+     * see it.
+     */
+    readonly booking?: readonly BookingVendor[];
     /**
      * Rows the site sets first, then by what has to be granted — nothing,
      * analytics, marketing — and otherwise in catalog order. Off, the rows
@@ -256,6 +267,24 @@ const VENDOR_ORDER: readonly StorageVendor[] = [
 ];
 
 /** The vendors a deployment's settings load, in catalog order. */
+/**
+ * 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.
+ */
+const BOOKING = {
+    // `forescapeAnalytics` stayed empty, with no tracker loaded; listed because
+    // it is set.
+    "4escape": {
+        kept: ["forescapeLayout", "forescapeStoreOrder", "forescapeAnalytics"],
+        tab: ["forescape"],
+    },
+} as const satisfies Record<
+    BookingVendor,
+    { readonly kept: readonly string[]; readonly tab: readonly string[] }
+>;
+
 function loadedVendors(
     analytics: AnalyticsSettings | undefined
 ): readonly StorageVendor[] {
@@ -327,6 +356,7 @@ export function storedItems(
     const {
         rememberLocale = true,
         rememberCampaign = false,
+        booking = [],
         sort = false,
     } = options;
     const asked = consentVendors(analytics).length > 0;
@@ -382,5 +412,23 @@ 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",
+        });
+    }
+
     return sort ? rows.toSorted(compareStoredItems) : rows;
 }

package/src/astro/FourEscape.astro

@@ -0,0 +1,67 @@
+---
+/**
+ * A 4escape catalog, and its cart below it unless `cart={false}`: the store's
+ * games and free slots, booked without leaving the page. See `four-escape.ts`
+ * for what the widgets are and where their contract comes from.
+ *
+ * `locale` is the page's; the widgets speak it when they can, and otherwise
+ * the account's language as 4escape sets it. The cart is one per page: give
+ * the second catalog on a page `cart={false}`.
+ *
+ * The widgets draw themselves, in 4escape's style. Attributes go on the
+ * element around the catalog, which is the place to give it room; the cart
+ * follows it.
+ *
+ * ```astro
+ * <FourEscape widgetId={id} domain="acme.4escape.io" locale={locale} class="my-8" />
+ * ```
+ */
+import type { HTMLAttributes } from "astro/types";
+import {
+    checkFourEscape,
+    FOUR_ESCAPE_SCRIPT,
+    FOUR_ESCAPE_STYLESHEET,
+    type FourEscapeWidget,
+    fourEscapeLanguage,
+    fourEscapeSettings,
+} from "../booking/four-escape.ts";
+
+type Props = HTMLAttributes<"div"> &
+    FourEscapeWidget & {
+        readonly locale: string;
+        readonly cart?: boolean;
+    };
+
+const { widgetId, domain, locale, cart = true, ...attrs } = Astro.props;
+
+checkFourEscape({ widgetId, domain }, Astro.url.pathname);
+
+const settings = fourEscapeSettings(domain);
+const language = fourEscapeLanguage(locale);
+---
+
+<link
+    rel="stylesheet"
+    href={FOUR_ESCAPE_STYLESHEET}
+    crossorigin="anonymous"
+>
+<div {...attrs}>
+    <div
+        class="forescape-catalog"
+        data-widget-id={widgetId}
+        data-settings={settings}
+        data-language={language}
+    ></div>
+</div>
+{cart && (
+    <div
+        class='forescape-cart'
+        data-settings={settings}
+        data-language={language}
+    />
+)}
+<script
+    is:inline
+    type="module"
+    src={FOUR_ESCAPE_SCRIPT}
+></script>

package/src/booking/four-escape.ts

@@ -0,0 +1,81 @@
+import { invalidId, UUID, type Uuid } from "../analytics/ids.ts";
+
+/**
+ * 4escape's booking widgets: a catalog of a store's games and slots, and the
+ * cart a booking goes through. Not 4escape's older iframe, which cannot share
+ * a page with them; the widgets are what 4escape builds for an account, so
+ * the catalog's id comes from 4escape.
+ *
+ * Plain markup and one module script, which the browser runs once however
+ * many widgets a page has: there is nothing to load on demand. They set no
+ * cookies and need no consent; what they keep is in `storedItems`.
+ *
+ * Their help shows the embed only as screenshots, so the contract here is the
+ * widget script's own, read 2026-11-11: it looks for `.forescape-<type>`
+ * elements and reads `data-settings` as `b64.` plus base64 JSON with the
+ * `domain`. The language is `data-language`, as the help gives it for the
+ * iframe; the widgets read it the same way.
+ *
+ * @see https://help.4escape.io/en/articles/259019-how-to-integrate-the-reservation-widget-on-your-website
+ */
+export interface FourEscapeWidget {
+    /** The catalog's id, from 4escape. */
+    readonly widgetId: Uuid;
+    /** The account's 4escape address: `acme.4escape.io`. */
+    readonly domain: string;
+}
+
+/** The languages the widgets are translated into, as `data-language` takes them. */
+export const FOUR_ESCAPE_LANGUAGES = [
+    "fr",
+    "en",
+    "es",
+    "nl",
+    "de",
+    "it",
+    "pt",
+] as const;
+
+export type FourEscapeLanguage = (typeof FOUR_ESCAPE_LANGUAGES)[number];
+
+/** The stylesheet and script the widgets need, as 4escape serves them. */
+export const FOUR_ESCAPE_STYLESHEET = "https://widgets.4escape.app/main.css";
+export const FOUR_ESCAPE_SCRIPT = "https://widgets-mirror.4escape.app/main.js";
+
+/** An account's address on 4escape. */
+const FOUR_ESCAPE_DOMAIN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.4escape\.io$/;
+
+/**
+ * Fails the build on a widget that would render nothing: a catalog id that is
+ * not a UUID, or a domain that is not an account's on 4escape.
+ */
+export function checkFourEscape(widget: FourEscapeWidget, at: string): void {
+    if (!UUID.test(widget.widgetId)) {
+        invalidId(
+            at,
+            `4escape widget id "${widget.widgetId}" is not a UUID, so the catalog would render nothing. 4escape gives it with the widget's embed code.`
+        );
+    }
+    if (!FOUR_ESCAPE_DOMAIN.test(widget.domain)) {
+        invalidId(
+            at,
+            `4escape domain "${widget.domain}" is not an account's address on 4escape, like "acme.4escape.io".`
+        );
+    }
+}
+
+/** `data-settings` for an account: `b64.` and the settings as base64 JSON. */
+export function fourEscapeSettings(domain: string): string {
+    return `b64.${btoa(JSON.stringify({ domain }))}`;
+}
+
+/**
+ * The widgets' language for a page's locale, or `undefined` for one they are
+ * not translated into: the account's own language then, as 4escape sets it.
+ */
+export function fourEscapeLanguage(
+    locale: string
+): FourEscapeLanguage | undefined {
+    const { language } = new Intl.Locale(locale);
+    return FOUR_ESCAPE_LANGUAGES.find((supported) => supported === language);
+}

package/src/booking/widget.ts

@@ -0,0 +1,10 @@
+import type { 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;
+
+/** Who makes a booking widget: what `storedItems` takes for their rows. */
+export type BookingVendor = BookingWidget["vendor"];

package/src/index.ts

@@ -55,6 +55,17 @@ export {
     storedItems,
     withPurposes,
 } from "./analytics/storage.ts";
+export {
+    checkFourEscape,
+    FOUR_ESCAPE_LANGUAGES,
+    FOUR_ESCAPE_SCRIPT,
+    FOUR_ESCAPE_STYLESHEET,
+    type FourEscapeLanguage,
+    type FourEscapeWidget,
+    fourEscapeLanguage,
+    fourEscapeSettings,
+} from "./booking/four-escape.ts";
+export type { BookingVendor, BookingWidget } from "./booking/widget.ts";
 export type {
     LanguageTag,
     LocaleMeta,