@escape-game-over/atlas 0.1.115 → 0.1.117

package/src/astro/google-map.ts

@@ -6,6 +6,7 @@ import { reportDevError } from "./dev-log.ts";
 import { element } from "./element.ts";
 import { triggered } from "./load-script.ts";
 import { data } from "./ref.ts";
+import { GOOGLE_MAPS_CALLBACK, vendors } from "./vendors.ts";
 
 /** What `GoogleMap.astro` hands the element, serialised. */
 export interface GoogleMapConfig {
@@ -27,20 +28,17 @@ export interface GoogleMapConfig {
     }[];
 }
 
-const CALLBACK = "__atlasGoogleMaps";
-
 let loading: Promise<typeof google.maps> | undefined;
 
 /** The Maps JavaScript API, fetched once per page however many maps ask. */
 export function loadGoogleMaps(apiKey: string): Promise<typeof google.maps> {
     loading ??= new Promise((resolve, reject) => {
-        (window as unknown as Record<string, () => void>)[CALLBACK] = () =>
-            resolve(google.maps);
+        vendors()[GOOGLE_MAPS_CALLBACK] = () => resolve(google.maps);
         const params = {
             key: apiKey,
             v: "weekly",
             loading: "async",
-            callback: CALLBACK,
+            callback: GOOGLE_MAPS_CALLBACK,
         };
         appendScript(
             `https://maps.googleapis.com/maps/api/js?${new URLSearchParams(params)}`

package/src/astro/images.ts

@@ -331,36 +331,22 @@ export async function photoSet(
 export type ImagePathOptions = Omit<Parameters<typeof getImage>[0], "src">;
 
 /**
- * The built URL of an optimised image, for the places that take a path rather
- * than an `<img>` — a JSON-LD node, a `<link>`, a manifest.
+ * The built URL of an optimised image, for places that take a path rather than
+ * an `<img>`: a CSS `url()` in an inline style or custom property, a
+ * `<link rel="preload">`, a manifest icon.
  *
- * ```ts
- * import logo from "~/assets/logo.png";
- * import { imagePath } from "@escape-game-over/atlas/astro/images";
- *
- * const company = organization({
- *     logo: await imagePath(logo, { width: 512, height: 512, format: "png" }),
- *     // …
- * });
+ * ```astro
+ * <section style={`--hero: url(${await imagePath(hero, { width: 1600, format: "webp" })})`}>
  * ```
  *
- * The narrowing is the reason this is a function rather than three lines at
- * each call site. `getImage().src` is typed `string`, every field it feeds here
- * is typed `UrlPath`, and a cast at each of those would put the same unchecked
- * assumption in as many places as there are consumers.
- *
- * **Not for entity data.** What comes back is `/_astro/logo.<hash>.png`, and the
- * hash moves every time the source file is touched. That is right for a page
- * resource, which is re-fetched from a document that was just re-fetched, and
- * wrong for anything a search engine stores against an identity — an
- * `Organization.logo` above all, which is held long after the build that
- * produced it. Those want a stable path out of `public/`, written as `/logo.png`
- * and joined to the site's own origin; both examples in this repository do that
- * deliberately and say so at the call site.
+ * A function rather than `getImage().src` at each call site because that is
+ * typed `string`, and a path is wanted as `UrlPath`: narrowed once here, with
+ * no cast at every caller.
  *
- * So the fit is: a `<link rel="preload">`, a manifest icon, an `<img>` built by
- * hand — resources fetched *with* the page. Long-lived references belong in
- * `public/`.
+ * **Not for structured data.** What comes back is `/_astro/hero.<hash>.webp`,
+ * and the hash moves whenever the source changes. Right for a resource fetched
+ * with the page; wrong for an `Organization.logo` or anything else a search
+ * engine stores against an identity, which wants a stable path in `public/`.
  */
 export async function imagePath(
     src: ImageMetadata,

package/src/astro/index.ts

@@ -27,12 +27,5 @@
  */
 
 export { siteFonts } from "./fonts.ts";
-export {
-    type PublicFilesOptions,
-    publicFiles,
-} from "./public-files.ts";
-export {
-    type SiteFiles,
-    type SiteRoutesOptions,
-    siteRoutes,
-} from "./site-routes.ts";
+export { publicFiles } from "./public-files.ts";
+export { siteRoutes } from "./site-routes.ts";

package/src/astro/meta-event.ts

@@ -1,5 +1,6 @@
 import type { CurrencyCode } from "../currency.ts";
 import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
+import { vendors } from "./vendors.ts";
 
 /** Meta's standard events, which its ad optimisation understands by name. */
 const META_STANDARD_EVENTS = [
@@ -66,9 +67,6 @@ type MetaEventArgs<E extends MetaEventName> = E extends MetaStandardEvent
     : EventDataArgs<MetaCustomEvents[E & keyof MetaCustomEvents]>;
 
 /** What `meta-pixel.ts` defines once marketing is granted. */
-interface MetaWindow {
-    fbq?: (...args: unknown[]) => void;
-}
 
 /**
  * Records an event with Meta's pixel — a lead sent, a booking made. A declared
@@ -83,7 +81,7 @@ export function metaEvent<E extends MetaEventName>(
     event: E,
     ...[data]: MetaEventArgs<E>
 ): void {
-    const fbq = (window as unknown as MetaWindow).fbq;
+    const fbq = vendors().fbq;
     const method = (META_STANDARD_EVENTS as readonly string[]).includes(event)
         ? "track"
         : "trackCustom";

package/src/astro/meta-pixel.ts

@@ -1,8 +1,9 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
+import { vendors } from "./vendors.ts";
 
 /** Meta's `fbq`: a queue until `fbevents.js` arrives and replays it. */
-interface Fbq {
+export interface Fbq {
     (...args: unknown[]): void;
     callMethod?: (...args: unknown[]) => void;
     queue: unknown[];
@@ -11,16 +12,11 @@ interface Fbq {
     version: string;
 }
 
-interface PixelWindow {
-    fbq?: Fbq;
-    _fbq?: Fbq;
-}
-
 const SCRIPT = "https://connect.facebook.net/en_US/fbevents.js";
 
 /** Meta's own base code, as it defines `fbq` before the script loads. */
 function defineFbq(): Fbq {
-    const global = window as unknown as PixelWindow;
+    const global = vendors();
     if (global.fbq !== undefined) return global.fbq;
     // `arguments` is the list of whatever a call passed, which every regular
     // `function` gets without declaring it (an arrow function does not). The
@@ -57,7 +53,7 @@ export function metaPixel(pixelIds: readonly string[]): ConsentGated {
             appendScript(SCRIPT);
         },
         revoke: () => {
-            (window as unknown as PixelWindow).fbq?.("consent", "revoke");
+            vendors().fbq?.("consent", "revoke");
         },
     };
 }

package/src/astro/public-files.ts

@@ -2,13 +2,8 @@ import type { Dirent } from "node:fs";
 import { readdir } from "node:fs/promises";
 import type { AstroIntegration } from "astro";
 
-/**
- * The module the generated union is declared in.
- *
- * Types only, so nothing has to exist at runtime: a consumer reaches it with
- * `import type`, which is erased before anything tries to resolve it.
- */
-const PUBLIC_MODULE = "atlas:public";
+/** The package the generated declaration merges into, as consumers import it. */
+const LIB_MODULE = "@escape-game-over/atlas";
 
 /** Files in `public/` that are not content: editor litter and placeholders. */
 const IGNORED = new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
@@ -38,13 +33,9 @@ async function walk(dir: URL, prefix = ""): Promise<string[]> {
 }
 
 /**
- * Types every file in `public/`, so linking to one is checked.
- *
- * ```ts
- * import type { PublicFile } from "atlas:public";
- *
- * const statement: PublicFile = "/reports/annual-2026.pdf";
- * ```
+ * Types every file in `public/`, so linking to one is checked: `site.fileUrl()`
+ * and a redirect's `{ file }` target take `PublicFilePath`, which this narrows
+ * from any path to the files that are there.
  *
  * `public/` is the one part of a site the compiler cannot see: files are copied
  * to the output verbatim, so a link to one is a string nothing verifies, and a
@@ -56,45 +47,19 @@ async function walk(dir: URL, prefix = ""): Promise<string[]> {
  * commit or add to a tsconfig. A file added while the dev server runs is picked
  * up when it restarts.
  */
-export interface PublicFilesOptions {
-    /**
-     * How the consuming project imports this package.
-     *
-     * Defaults to the published name, which is what a project installing it
-     * from the registry writes. State it only where that is not the specifier
-     * in the import statements — a path alias, or a fork under another name.
-     *
-     * Needed because the generated file *augments* that module: the union has to
-     * reach `fileUrl` and the redirect target, and a declaration can only be
-     * merged into a module named the way the consumer names it.
-     */
-    readonly libModule?: string;
-}
-
-export function publicFiles(
-    options: PublicFilesOptions = {}
-): AstroIntegration {
-    const libModule = options.libModule ?? "@escape-game-over/atlas";
-
+export function publicFiles(): AstroIntegration {
     return {
         name: "public-files",
         hooks: {
             "astro:config:done": async ({ config, injectTypes, logger }) => {
                 const files = (await walk(config.publicDir)).sort();
-                /**
-                 * The union, one file per line, indented by `spaces`.
-                 *
-                 * A count rather than the whitespace itself: the two call sites
-                 * sit at different depths in the emitted file, and passing the
-                 * indent as a literal means counting spaces by eye in a string
-                 * that looks identical whether it holds eight of them or nine.
-                 */
-                const union = (spaces: number) =>
+                // One file per line, at the depth the declaration sits.
+                const union =
                     files.length === 0
                         ? "never"
                         : files
                               .map((file) => `"${file}"`)
-                              .join(`\n${" ".repeat(spaces)}| `);
+                              .join("\n            | ");
 
                 injectTypes({
                     filename: "public-files.d.ts",
@@ -105,17 +70,11 @@ export function publicFiles(
                     // export lib has.
                     content: `export {};
 
-declare module "${PUBLIC_MODULE}" {
-    /** Every file in \`public/\`, as it is served. */
-    export type PublicFile =
-        | ${union(8)};
-}
-
-declare module "${libModule}" {
+declare module "${LIB_MODULE}" {
     /** Merged so \`fileUrl\` and redirect targets accept only these. */
     interface PublicFileRegistry {
         path:
-            | ${union(12)};
+            | ${union};
     }
 }
 `,

package/src/astro/site-routes.ts

@@ -119,16 +119,11 @@ export function siteRoutes<Id extends string, L extends string>(
     const describe = (file: GeneratedFile): string =>
         `${file.name} (${size(file.body)})`;
 
-    // Rebuilt per request in dev and once at the end of a build, rather than
-    // computed here.
-    //
-    // Worth knowing what that does *not* buy: it does not make dev current. The
-    // `site` and the `llms` file this closes over were built when the Astro
-    // config was evaluated, and nothing re-evaluates that until the server
-    // restarts — so rebuilding per request derives the same answer from the same
-    // frozen inputs. Measured: editing a message refreshes the page that renders
-    // it and leaves the same string in `llms.txt` untouched. A build is always
-    // right, since it evaluates the config in a fresh process.
+    // Built when the dev server starts and when a build ends. The `site` and
+    // `llms` this closes over are fixed when the Astro config is evaluated, so
+    // in dev these files change only on a restart: editing a message refreshes
+    // the page that renders it, not `llms.txt`. A build is always right, since
+    // it evaluates the config in a fresh process.
     const generate = (): GeneratedFile[] => {
         const files: GeneratedFile[] = [...site.sitemap().files, site.robots()];
         // Every page's head links to it, so one is written unless the config
@@ -352,35 +347,11 @@ export function siteRoutes<Id extends string, L extends string>(
              * them out of the page graph.
              */
             "astro:server:setup": ({ server, logger }) => {
-                /**
-                 * The paths this integration answers on, learned by generating
-                 * once and refreshed whenever we generate again.
-                 *
-                 * Its whole job is to keep `generate()` off the hot path. The
-                 * middleware sees every request the dev server takes — each
-                 * page, each asset, each Vite ping — and regenerating for all
-                 * of them rebuilds the sitemap three times over (once directly,
-                 * once inside `robots()`, once inside `llms()`) to answer a
-                 * request for `/favicon.ico`.
-                 *
-                 * A name that appears only later is the one thing this can
-                 * miss: a sitemap crossing `entryLimit` mid-session gains
-                 * `sitemap-0.xml` and friends, which are not in the set until
-                 * something regenerates. Acceptable because the set is
-                 * refreshed on every hit and the dev server restarts on a
-                 * config change — and because the alternative is paying for a
-                 * full generate on every asset request to catch it.
-                 */
-                const served = new Set<string>();
-                const remember = (files: readonly GeneratedFile[]) => {
-                    served.clear();
-                    for (const file of files) served.add(`/${file.name}`);
-                    return files;
-                };
-
-                remember(generate()).map((file) =>
-                    logger.info(`generated ${describe(file)}`)
-                );
+                const files = new Map<string, GeneratedFile>();
+                for (const file of generate()) {
+                    logger.info(`generated ${describe(file)}`);
+                    files.set(`/${file.name}`, file);
+                }
                 server.middlewares.use((request, response, next) => {
                     const path = (request.url ?? "").split("?")[0] ?? "";
 
@@ -406,23 +377,8 @@ export function siteRoutes<Id extends string, L extends string>(
                         return;
                     }
 
-                    // Nothing of ours sits at this path, so hand it on without
-                    // building anything. This is the check that keeps the cost
-                    // below off every page and asset request in dev.
-                    if (!served.has(path)) {
-                        next();
-                        return;
-                    }
-
-                    // Regenerated per request, so an edit to a route or a
-                    // message shows up on reload rather than at restart.
-                    const file = remember(generate()).find(
-                        (candidate) => `/${candidate.name}` === path
-                    );
+                    const file = files.get(path);
                     if (file === undefined) {
-                        // The set said this was ours and the fresh build
-                        // disagrees — a file that stopped being generated, so
-                        // it is now a 404 like any other missing path.
                         next();
                         return;
                     }

package/src/astro/snap-event.ts

@@ -1,5 +1,6 @@
 import type { CurrencyCode } from "../currency.ts";
 import { readConsent } from "./consent.ts";
+import { vendors } from "./vendors.ts";
 
 /** Snap's standard events that a website sends. */
 export type SnapStandardEvent =
@@ -37,9 +38,6 @@ type SnapEventArgs<E extends SnapStandardEvent> = E extends "PURCHASE"
     : [data?: SnapEventData];
 
 /** What `snap-pixel.ts` defines once marketing is granted. */
-interface SnapWindow {
-    snaptr?: (...args: unknown[]) => void;
-}
 
 /**
  * Records a standard event with Snap's pixel — a lead sent, a booking made.
@@ -53,7 +51,7 @@ export function snapEvent<E extends SnapStandardEvent>(
     ...[data]: SnapEventArgs<E>
 ): void {
     if (readConsent()?.marketing !== "granted") return;
-    const snaptr = (window as unknown as SnapWindow).snaptr;
+    const snaptr = vendors().snaptr;
     if (data === undefined) snaptr?.("track", event);
     else snaptr?.("track", event, data);
 }

package/src/astro/snap-pixel.ts

@@ -1,22 +1,19 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
+import { vendors } from "./vendors.ts";
 
 /** Snap's `snaptr`: a queue until `scevent.min.js` arrives and replays it. */
-interface Snaptr {
+export interface Snaptr {
     (...args: unknown[]): void;
     handleRequest?: (...args: unknown[]) => void;
     queue: unknown[];
 }
 
-interface PixelWindow {
-    snaptr?: Snaptr;
-}
-
 const SCRIPT = "https://sc-static.net/scevent.min.js";
 
 /** Snap's own base code, as it defines `snaptr` before the script loads. */
 function defineSnaptr(): Snaptr {
-    const global = window as unknown as PixelWindow;
+    const global = vendors();
     if (global.snaptr !== undefined) return global.snaptr;
     // `arguments` is the list of whatever a call passed, which every regular
     // `function` gets without declaring it (an arrow function does not). The

package/src/astro/tiktok-event.ts

@@ -1,5 +1,6 @@
 import type { CurrencyCode } from "../currency.ts";
 import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
+import { vendors } from "./vendors.ts";
 
 /** TikTok's standard events, by their current names (May 2025 onwards). */
 export type TikTokStandardEvent =
@@ -63,9 +64,6 @@ type TikTokEventArgs<E extends TikTokEventName> = E extends TikTokStandardEvent
     : EventDataArgs<TikTokCustomEvents[E & keyof TikTokCustomEvents]>;
 
 /** What `tiktok-pixel.ts` defines once marketing is granted. */
-interface TikTokWindow {
-    ttq?: { track(event: string, data?: object): void };
-}
 
 /**
  * Records an event with TikTok's pixel — a lead sent, a booking made. Declared
@@ -80,7 +78,7 @@ export function tiktokEvent<E extends TikTokEventName>(
     event: E,
     ...[data]: TikTokEventArgs<E>
 ): void {
-    const ttq = (window as unknown as TikTokWindow).ttq;
+    const ttq = vendors().ttq;
     if (data === undefined) ttq?.track(event);
     else ttq?.track(event, data);
 }

package/src/astro/tiktok-pixel.ts

@@ -1,8 +1,15 @@
 import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
+import { vendors } from "./vendors.ts";
+
+/** What a page calls on `ttq`: each queues, until `events.js` takes over. */
+type TtqMethods = Record<
+    (typeof METHODS)[number],
+    (...args: unknown[]) => void
+>;
 
 /** TikTok's `ttq`: a queue of calls until `events.js` arrives and replays it. */
-interface Ttq extends Array<unknown> {
+export interface Ttq extends Array<unknown>, TtqMethods {
     methods: readonly string[];
     setAndDefer(target: unknown[], method: string): void;
     instance(id: string): unknown[];
@@ -10,12 +17,6 @@ interface Ttq extends Array<unknown> {
     _i: Record<string, unknown[] & { _u?: string }>;
     _t: Record<string, number>;
     _o: Record<string, object>;
-    [method: string]: unknown;
-}
-
-interface PixelWindow {
-    ttq?: Ttq;
-    TiktokAnalyticsObject?: string;
 }
 
 const SCRIPT = "https://analytics.tiktok.com/i18n/pixel/events.js";
@@ -39,42 +40,73 @@ const METHODS = [
     "grantConsent",
 ] as const;
 
+/**
+ * Each method, queuing its call on `target`. Written out rather than looped
+ * over `METHODS`, so the type sees every one: the return type rejects a name
+ * missing here, or one `METHODS` lacks.
+ */
+function deferTo(target: unknown[]): TtqMethods {
+    const defer =
+        (method: string) =>
+        (...args: unknown[]) => {
+            target.push([method, ...args]);
+        };
+    return {
+        page: defer("page"),
+        track: defer("track"),
+        identify: defer("identify"),
+        instances: defer("instances"),
+        debug: defer("debug"),
+        on: defer("on"),
+        off: defer("off"),
+        once: defer("once"),
+        ready: defer("ready"),
+        alias: defer("alias"),
+        group: defer("group"),
+        enableCookie: defer("enableCookie"),
+        disableCookie: defer("disableCookie"),
+        holdConsent: defer("holdConsent"),
+        revokeConsent: defer("revokeConsent"),
+        grantConsent: defer("grantConsent"),
+    };
+}
+
 /** TikTok's own base code, as it defines `ttq` before the script loads. */
 function defineTtq(): Ttq {
-    const global = window as unknown as PixelWindow;
+    const global = vendors();
     if (global.ttq !== undefined) return global.ttq;
     global.TiktokAnalyticsObject = "ttq";
-    const ttq = [] as unknown as Ttq;
-    ttq.methods = METHODS;
-    ttq.setAndDefer = (target, method) => {
-        (target as unknown as Record<string, unknown>)[method] = (
-            ...args: unknown[]
-        ) => target.push([method, ...args]);
-    };
-    for (const method of METHODS) ttq.setAndDefer(ttq, method);
-    ttq.instance = (id) => {
-        const queue = ttq._i?.[id] ?? [];
-        for (const method of METHODS) ttq.setAndDefer(queue, method);
-        return queue;
-    };
-    ttq.load = (id, options = {}) => {
-        ttq._i ??= {};
-        ttq._i[id] = Object.assign([], { _u: SCRIPT });
-        ttq._t ??= {};
-        ttq._t[id] = Date.now();
-        ttq._o ??= {};
-        ttq._o[id] = options;
-        appendScript(
-            `${SCRIPT}?${new URLSearchParams({ sdkid: id, lib: "ttq" })}`
-        );
-    };
+    const queue: unknown[] = [];
+    const ttq: Ttq = Object.assign(queue, deferTo(queue), {
+        methods: METHODS,
+        // TikTok's script calls this itself, with any name, so it stays as
+        // loose as the snippet's.
+        setAndDefer: (target: unknown[], method: string) => {
+            Object.assign(target, {
+                [method]: (...args: unknown[]) =>
+                    target.push([method, ...args]),
+            });
+        },
+        instance: (id: string) => {
+            const instance = ttq._i[id] ?? [];
+            return Object.assign(instance, deferTo(instance));
+        },
+        load: (id: string, options: object = {}) => {
+            ttq._i[id] = Object.assign([], { _u: SCRIPT });
+            ttq._t[id] = Date.now();
+            ttq._o[id] = options;
+            appendScript(
+                `${SCRIPT}?${new URLSearchParams({ sdkid: id, lib: "ttq" })}`
+            );
+        },
+        _i: {},
+        _t: {},
+        _o: {},
+    });
     global.ttq = ttq;
     return ttq;
 }
 
-const call = (ttq: Ttq, method: (typeof METHODS)[number], ...args: unknown[]) =>
-    (ttq[method] as (...args: unknown[]) => void)(...args);
-
 /** The pixel: loaded on the first grant, paused and resumed by later answers. */
 export function tiktokPixel(pixelIds: readonly string[]): ConsentGated {
     let loaded = false;
@@ -83,15 +115,14 @@ export function tiktokPixel(pixelIds: readonly string[]): ConsentGated {
             const ttq = defineTtq();
             // Also lifts the hold of TikTok's Cookie Consent Mode, where a
             // pixel has it on in Events Manager.
-            call(ttq, "grantConsent");
+            ttq.grantConsent();
             if (loaded) return;
             loaded = true;
             for (const id of pixelIds) ttq.load(id);
-            call(ttq, "page");
+            ttq.page();
         },
         revoke: () => {
-            const ttq = (window as unknown as PixelWindow).ttq;
-            if (ttq !== undefined) call(ttq, "revokeConsent");
+            vendors().ttq?.revokeConsent();
         },
     };
 }

package/src/astro/umami-event.ts

@@ -1,4 +1,5 @@
 import type { DeclaredEvent, EventDataArgs } from "./event-data.ts";
+import { vendors } from "./vendors.ts";
 
 /**
  * The project's Umami events, each with the data it carries, `undefined` for
@@ -34,10 +35,5 @@ export function umamiEvent<E extends DeclaredEvent<UmamiEvents>>(
     // Flat string values; anything else in a declaration fails here.
     ...[data]: EventDataArgs<UmamiEvents[E] & Readonly<Record<string, string>>>
 ): void {
-    const umami = (
-        window as unknown as {
-            umami?: { track(event: string, data?: object): void };
-        }
-    ).umami;
-    umami?.track(name, data);
+    vendors().umami?.track(name, data);
 }