@escape-game-over/atlas 0.1.41 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.41",
+    "version": "0.1.43",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/Document.astro

@@ -10,6 +10,9 @@
  * `restoreScroll={false}`: the router keeps its own position in the same
  * history state.
  *
+ * A site with a lead form passes `rememberCampaign`, so the `utm_*` tags a
+ * visit landed with survive to the page the form is on; see `attribution.ts`.
+ *
  * ```astro
  * <Document meta={meta} html={{ class: "scroll-smooth" }} body={{ class: "…" }}>
  *     <Fragment slot="head"><link rel="preload" … /></Fragment>
@@ -20,6 +23,7 @@
 import type { HTMLAttributes } from "astro/types";
 import type { PageMeta } from "../site/index.ts";
 import MetaTags from "./MetaTags.astro";
+import RememberCampaign from "./RememberCampaign.astro";
 import ScrollRestore from "./ScrollRestore.astro";
 
 interface Props {
@@ -29,9 +33,17 @@ interface Props {
     readonly body?: HTMLAttributes<"body">;
     /** Defaults to `true`; `false` for a site on `ClientRouter`. */
     readonly restoreScroll?: boolean;
+    /** Off unless stated: a site with no lead form has nothing to keep them for. */
+    readonly rememberCampaign?: boolean;
 }
 
-const { meta, html, body, restoreScroll = true } = Astro.props;
+const {
+    meta,
+    html,
+    body,
+    restoreScroll = true,
+    rememberCampaign = false,
+} = Astro.props;
 ---
 
 <!doctype html>
@@ -49,5 +61,6 @@ const { meta, html, body, restoreScroll = true } = Astro.props;
         <MetaTags tags={meta.bodyTags} />
         <slot />
         {restoreScroll && <ScrollRestore />}
+        {rememberCampaign && <RememberCampaign />}
     </body>
 </html>

package/src/astro/RememberCampaign.astro

@@ -0,0 +1,11 @@
+---
+/**
+ * Keeps the campaign tags a visit landed with for the tab, so a lead form on
+ * another page can still report them — see `attribution.ts`.
+ *
+ * Rendered by `Document` when asked for. A bundled module rather than inline:
+ * the tags are wanted by a form, which cannot be sent before it runs.
+ */
+---
+
+<script src="./remember-campaign.ts" />

package/src/astro/attribution.ts

@@ -87,6 +87,14 @@ export function campaign(): Campaign {
     }
 }
 
+/**
+ * A moment as a Google Ads conversion import reads it:
+ * `2026-09-24 12:42:10+00:00`. In UTC, so the file needs no time zone setting.
+ */
+export function conversionTime(at: Date = new Date()): string {
+    return `${at.toISOString().slice(0, 19).replace("T", " ")}+00:00`;
+}
+
 /**
  * A cookie's value. `document.cookie` is always `name=value; name=value`, so a
  * split reads it — `cookieStore.get` would too, but is async and newer than

package/src/astro/client.ts

@@ -24,4 +24,5 @@ export {
 export * from "./filters.ts";
 export * from "./filters-view.ts";
 export { data, ref, refs } from "./ref.ts";
+export * from "./umami-event.ts";
 export * from "./youtube.ts";

package/src/astro/remember-campaign.ts

@@ -0,0 +1,4 @@
+// Every page: a visit can land anywhere before it reaches a form.
+import { rememberCampaign } from "./attribution.ts";
+
+rememberCampaign();

package/src/astro/umami-event.ts

@@ -0,0 +1,24 @@
+/**
+ * Records a named event with Umami — a form sent, a deck downloaded — from a
+ * client script.
+ *
+ * Umami's own script defines `window.umami` once it has loaded; atlas emits
+ * that script from `analytics.umami`. Before then, or where a blocker stopped
+ * it, there is nothing to call, and the event is dropped rather than thrown:
+ * an analytics call must never be the reason a page misbehaves.
+ *
+ * The data goes to Umami as it is, so it should carry what the visitor chose,
+ * never who they are. For an event on a plain click, Umami's
+ * `data-umami-event` attribute needs no script at all.
+ */
+export function umamiEvent(
+    name: string,
+    data?: Readonly<Record<string, string>>
+): void {
+    const umami = (
+        window as unknown as {
+            umami?: { track(event: string, data?: object): void };
+        }
+    ).umami;
+    umami?.track(name, data);
+}