@tokenoftrust/storefront-runner 2.2.75 → 2.2.77

package/apps/storefront/src/lib/cspStaticHashes.ts

@@ -19,7 +19,7 @@ export const STATIC_SCRIPT_HASHES: readonly string[] = [
   "'sha256-YicfxUFBkKrQapZ/tzZKlaKTdNHgwVfv7y2Wa0NC6/k='",
   "'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc='",
   "'sha256-elMLh/6Oubj8u9FRLwZLyRa6TqKikGs75mf0jfWcoxI='",
-  "'sha256-Rl3sizqw4AmEkfQgkgajKo4uJC7JkyVCYiPJY/DJbIE='",
+  "'sha256-ZxqYN/PbpT0W68E87+IwdGfcYJuAVXNPNVxVb3VX0hw='",
 ];
 
 export const STATIC_STYLE_HASHES: readonly string[] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.75",
+  "version": "2.2.77",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -140,7 +140,7 @@ export interface BootLifecycleOptions {
    */
   scheduleGa4Sandbox?: NativeGa4SandboxScheduler;
   /**
-   * The persistent store behind the Amplitude visitor id and session; defaults to the
+   * The persistent store behind the GA4 and Amplitude visitor id and session; defaults to the
    * window's origin storage. Read lazily and only while analytics is eligible.
    */
   visitorStorage?: () => VisitorContinuityStorage | undefined;

package/packages/public-runtime/src/integration/native-amplitude.ts

@@ -17,7 +17,8 @@
  * Storage is injected by the host and never touched by name here; when it is
  * unavailable the id lives in memory for this document only and the event carries
  * no session (`NO_SESSION_ID`), overcounting visitors rather than failing the event.
- * There is no `user_id`.
+ * There is no `user_id`. The same store backs the GA4 adapter's `client_id` and session
+ * (`native-ga4.ts`), so both destinations count the same visitors and sessions.
  *
  * Page views also carry channel ATTRIBUTION (UTM tokens + the referrer's origin)
  * and the page LOCATION (`page_hostname` / `page_url`, from the server-stamped
@@ -73,6 +74,8 @@ export const NO_SESSION_ID = -1 as const;
 export const VISITOR_CONTINUITY_STORAGE_KEY = "tot.analytics-continuity.v1" as const;
 export const VISITOR_ID_LIFETIME_MS = 90 * 24 * 60 * 60 * 1000;
 export const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
+/** Ceiling on the per-visitor session count; a 90-day id cannot plausibly reach it. */
+export const MAX_VISITOR_SESSION_COUNT = 100_000;
 export const AMPLITUDE_HTTP_EVENT_TYPES = Object.freeze([
   "storefront.page.viewed.v1",
   "storefront.page.viewed.v2",
@@ -171,9 +174,20 @@ export interface VisitorContinuityScope {
   siteSurface: string;
 }
 
+/**
+ * How the current session relates to this document: `first_visit` when this document
+ * minted the visitor, `new_session` when it started a new session for a known visitor,
+ * otherwise `continuing`. Recorded per continuity instance (one per document), so the
+ * first adapter to read the visitor does not hide the arrival from the others.
+ */
+export type VisitorSessionState = "first_visit" | "new_session" | "continuing";
+
 export interface VisitorContinuityIds {
   deviceId: string;
   sessionId: number;
+  sessionState: VisitorSessionState;
+  /** 1-based count of this visitor's sessions, current one included (GA4's session number). */
+  sessionCount: number;
 }
 
 export interface VisitorContinuity {
@@ -190,14 +204,17 @@ export interface CreateVisitorContinuityOptions {
 }
 
 interface VisitorRecord {
-  schemaVersion: 1;
+  schemaVersion: 2;
   deviceId: string;
   createdAt: number;
   sessionStartedAt: number;
   lastActivityAt: number;
+  sessionCount: number;
 }
 
-const VISITOR_RECORD_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionStartedAt";
+const VISITOR_RECORD_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionCount,sessionStartedAt";
+/** The exact schemaVersion-1 shape, written before the session number existed; upgraded in place. */
+const VISITOR_RECORD_V1_KEYS = "createdAt,deviceId,lastActivityAt,schemaVersion,sessionStartedAt";
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 export function visitorContinuityStorageKey(scope: VisitorContinuityScope): string {
@@ -205,22 +222,33 @@ export function visitorContinuityStorageKey(scope: VisitorContinuityScope): stri
   return `${VISITOR_CONTINUITY_STORAGE_KEY}:${encodeURIComponent(contextKey)}`;
 }
 
-/** A stored record that is malformed, from the future, or past its fixed lifetime is not a visitor. */
+/**
+ * A stored record that is malformed, from the future, or past its fixed lifetime is not a
+ * visitor. A valid record in the exact schemaVersion-1 shape keeps its id and session and
+ * becomes schemaVersion 2 at session number 1 (the caller writes it back); every other
+ * shape is still refused, so an upgraded visitor is not counted twice.
+ */
 function liveVisitorRecord(raw: string | null, now: number): VisitorRecord | null {
   if (!raw) return null;
   let parsed: unknown;
   try { parsed = JSON.parse(raw); } catch { return null; }
-  if (!isPlainObject(parsed) || Object.keys(parsed).sort().join(",") !== VISITOR_RECORD_KEYS) return null;
+  if (!isPlainObject(parsed)) return null;
+  const keys = Object.keys(parsed).sort().join(",");
   const { schemaVersion, deviceId, createdAt, sessionStartedAt, lastActivityAt } = parsed;
+  let sessionCount = parsed["sessionCount"];
+  if (keys === VISITOR_RECORD_V1_KEYS && schemaVersion === 1) sessionCount = 1;
+  else if (keys !== VISITOR_RECORD_KEYS || schemaVersion !== 2) return null;
   if (
-    schemaVersion !== 1 || typeof deviceId !== "string" || !UUID_PATTERN.test(deviceId) ||
+    typeof deviceId !== "string" || !UUID_PATTERN.test(deviceId) ||
+    typeof sessionCount !== "number" || !Number.isSafeInteger(sessionCount) ||
+    sessionCount < 1 || sessionCount > MAX_VISITOR_SESSION_COUNT ||
     typeof createdAt !== "number" || typeof sessionStartedAt !== "number" ||
     typeof lastActivityAt !== "number" ||
     !Number.isFinite(createdAt) || !Number.isFinite(sessionStartedAt) || !Number.isFinite(lastActivityAt) ||
     createdAt > now || now - createdAt >= VISITOR_ID_LIFETIME_MS ||
     sessionStartedAt < createdAt || lastActivityAt < sessionStartedAt
   ) return null;
-  return { schemaVersion, deviceId, createdAt, sessionStartedAt, lastActivityAt };
+  return { schemaVersion: 2, deviceId, createdAt, sessionStartedAt, lastActivityAt, sessionCount };
 }
 
 function defaultRandomUUID(): string {
@@ -235,6 +263,11 @@ function defaultRandomUUID(): string {
 export function createVisitorContinuity(options: CreateVisitorContinuityOptions = {}): VisitorContinuity {
   const randomUUID = options.randomUUID ?? defaultRandomUUID;
   const memory = new Map<string, string>();
+  const startedHere = new Map<string, { sessionId: number; sessionState: VisitorSessionState }>();
+  const stateOf = (key: string, sessionId: number): VisitorSessionState => {
+    const started = startedHere.get(key);
+    return started && started.sessionId === sessionId ? started.sessionState : "continuing";
+  };
   const storage = (): VisitorContinuityStorage | undefined => {
     try { return options.storage?.(); } catch { return undefined; }
   };
@@ -255,21 +288,30 @@ export function createVisitorContinuity(options: CreateVisitorContinuityOptions
         try {
           const existing = liveVisitorRecord(store.getItem(key), now);
           let record: VisitorRecord | null = existing;
+          let started: VisitorSessionState | null = null;
           if (!record) {
             const deviceId = mint();
             if (deviceId) {
-              record = { schemaVersion: 1, deviceId, createdAt: now, sessionStartedAt: now, lastActivityAt: now };
+              record = { schemaVersion: 2, deviceId, createdAt: now, sessionStartedAt: now, lastActivityAt: now, sessionCount: 1 };
+              started = "first_visit";
             }
           } else {
-            const sessionStartedAt = now - record.lastActivityAt > SESSION_INACTIVITY_MS
-              ? now
-              : record.sessionStartedAt;
-            record = { ...record, sessionStartedAt, lastActivityAt: Math.max(now, record.lastActivityAt) };
+            const rolled = now - record.lastActivityAt > SESSION_INACTIVITY_MS;
+            const sessionStartedAt = rolled ? now : record.sessionStartedAt;
+            if (rolled) started = "new_session";
+            const sessionCount = rolled ? Math.min(record.sessionCount + 1, MAX_VISITOR_SESSION_COUNT) : record.sessionCount;
+            record = { ...record, sessionStartedAt, sessionCount, lastActivityAt: Math.max(now, record.lastActivityAt) };
           }
           if (record) {
             store.setItem(key, JSON.stringify(record));
             memory.delete(key);
-            return { deviceId: record.deviceId, sessionId: record.sessionStartedAt };
+            if (started) startedHere.set(key, { sessionId: record.sessionStartedAt, sessionState: started });
+            return {
+              deviceId: record.deviceId,
+              sessionId: record.sessionStartedAt,
+              sessionState: stateOf(key, record.sessionStartedAt),
+              sessionCount: record.sessionCount,
+            };
           }
         } catch {
           // Blocked or full storage: fall through to this document's memory-only visitor.
@@ -278,15 +320,16 @@ export function createVisitorContinuity(options: CreateVisitorContinuityOptions
       let deviceId = memory.get(key);
       if (!deviceId) {
         const minted = mint();
-        if (!minted) return { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID };
+        if (!minted) return { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID, sessionState: "first_visit", sessionCount: 1 };
         deviceId = minted;
         memory.set(key, deviceId);
       }
-      return { deviceId, sessionId: NO_SESSION_ID };
+      return { deviceId, sessionId: NO_SESSION_ID, sessionState: "first_visit", sessionCount: 1 };
     },
     clear(scope) {
       const key = visitorContinuityStorageKey(scope);
       memory.delete(key);
+      startedHere.delete(key);
       try { storage()?.removeItem(key); } catch { /* the early consent boot clears on the next load */ }
     },
   };
@@ -456,7 +499,7 @@ function createAmplitudeHandler(input: AmplitudeHandlerInput): (event: CommerceE
     if (!mapped || input.dedupe.seenOrRemember(mapped.insert_id)) return;
     let identity: VisitorContinuityIds;
     try { identity = input.continuity.readOrMint(scope, mapped.time); }
-    catch { identity = { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID }; }
+    catch { identity = { deviceId: ANONYMOUS_DEVICE_ID, sessionId: NO_SESSION_ID, sessionState: "first_visit", sessionCount: 1 }; }
     const body = JSON.stringify({
       api_key: input.destinationId,
       events: [{ ...mapped, device_id: identity.deviceId, session_id: identity.sessionId }],

package/packages/public-runtime/src/integration/native-ga4-sandbox-entry.ts

@@ -10,6 +10,12 @@ import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-val
 const MEASUREMENT_ID = /^G-[A-Z0-9]{4,20}$/;
 const CAMPAIGN_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
 const GOVERNED_VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const CLIENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const SESSION_STATES: ReadonlySet<unknown> = new Set(["first_visit", "new_session", "continuing"]);
+/** Ceiling on the session number the parent may claim (its own record caps at the same value). */
+const MAX_SESSION_COUNT = 100_000;
+/** gtag's own session-inactivity window, in seconds. */
+const GTAG_SESSION_TIMEOUT_S = 30 * 60;
 const APPROVED_ACTIONS: ReadonlySet<string> = new Set(APPROVED_MARKETING_ACTION_NAMES);
 
 function plainRecord(value: unknown): Record<string, unknown> | null {
@@ -59,6 +65,95 @@ function validGovernedProperties(value: unknown): value is Record<string, string
     !resemblesManagedAnalyticsProtectedValue(item));
 }
 
+interface FrameVisitor {
+  clientId: string;
+  session?: { idSeconds: number; state: "first_visit" | "new_session" | "continuing"; count: number };
+}
+
+/**
+ * The visitor crosses the same hostile boundary: a lowercase UUID and, all together or
+ * not at all, a positive integer epoch-ms session start, its closed state, and a capped
+ * positive session number (1 exactly on a first visit, at least 2 on a new session).
+ * Anything else refuses the whole configure rather than falling back to an id gtag would
+ * invent.
+ */
+function parseVisitor(value: unknown): FrameVisitor | null {
+  const record = plainRecord(value);
+  if (!record || !exactKeys(record, ["clientId", "sessionId", "sessionState", "sessionCount"], ["clientId"])) return null;
+  const { clientId, sessionId, sessionState, sessionCount } = record;
+  if (typeof clientId !== "string" || !CLIENT_ID.test(clientId)) return null;
+  if (sessionId === undefined && sessionState === undefined && sessionCount === undefined) return { clientId };
+  if (
+    typeof sessionId !== "number" || !Number.isSafeInteger(sessionId) || sessionId <= 0 ||
+    !SESSION_STATES.has(sessionState) ||
+    typeof sessionCount !== "number" || !Number.isSafeInteger(sessionCount) ||
+    sessionCount < 1 || sessionCount > MAX_SESSION_COUNT ||
+    (sessionState === "first_visit" && sessionCount !== 1) ||
+    (sessionState === "new_session" && sessionCount < 2)
+  ) return null;
+  return {
+    clientId,
+    session: {
+      idSeconds: Math.floor(sessionId / 1000),
+      state: sessionState as "first_visit" | "new_session" | "continuing",
+      count: sessionCount,
+    },
+  };
+}
+
+/**
+ * gtag keeps its visitor and session in `_ga` / `_ga_<container>` cookies and ignores
+ * `client_storage: 'none'` (measured 2026-10-06 against the live gtag.js). This frame's
+ * origin is shared by every hosted tenant, so a cookie written here would link one
+ * browser across tenants. The frame's `document.cookie` is therefore replaced, before
+ * gtag loads, with a jar that lives only as long as this document.
+ */
+function installMemoryCookieJar(doc: Document): Map<string, string> {
+  const jar = new Map<string, string>();
+  Object.defineProperty(doc, "cookie", {
+    configurable: false,
+    enumerable: true,
+    get: () => Array.from(jar, ([name, value]) => `${name}=${value}`).join("; "),
+    set: (raw: unknown) => {
+      const [pair = "", ...attributes] = String(raw).split(";");
+      const split = pair.indexOf("=");
+      if (split <= 0) return;
+      const name = pair.slice(0, split).trim();
+      const expired = attributes.some((attribute) => {
+        const [key = "", value = ""] = attribute.split("=").map((part) => part.trim());
+        if (key.toLowerCase() === "max-age") return Number(value) <= 0;
+        if (key.toLowerCase() === "expires") return Date.parse(value) <= Date.now();
+        return false;
+      });
+      if (expired) jar.delete(name);
+      else jar.set(name, pair.slice(split + 1).trim());
+    },
+  });
+  return jar;
+}
+
+/**
+ * Seed gtag's session cookie so it reports the parent's session: `continuing` gets a
+ * live session (no `session_start`, no `first_visit`) at session number `count`;
+ * `new_session` gets an expired one at `count - 1`, which gtag increments as it starts
+ * the session for a returning visitor; `first_visit` gets none (gtag reports 1). The
+ * GS2 layout is gtag's own and undocumented (`o` is its session counter, measured
+ * 2026-10-06); if gtag stops parsing it, collection still carries the parent's
+ * `client_id` and session id and only the new-session / first-visit flags overcount.
+ */
+function seedSessionCookies(jar: Map<string, string>, ids: readonly string[], visitor: FrameVisitor | null): void {
+  jar.clear();
+  const session = visitor?.session;
+  if (!session || session.state === "first_visit") return;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const lastSeen = session.state === "continuing" ? nowSeconds : session.idSeconds - GTAG_SESSION_TIMEOUT_S - 1;
+  const sessionStart = session.state === "continuing" ? session.idSeconds : lastSeen;
+  const sessionNumber = session.state === "continuing" ? session.count : session.count - 1;
+  for (const id of ids) {
+    jar.set(`_ga_${id.slice("G-".length)}`, `GS2.1.s${sessionStart}$o${sessionNumber}$g0$t${lastSeen}$j0$l0$h0`);
+  }
+}
+
 function validCampaign(value: unknown): value is Record<string, string> {
   const record = plainRecord(value);
   if (!record || !exactKeys(record, ["source", "medium", "campaign", "term", "content"], [])) return false;
@@ -105,6 +200,7 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
   let lastPageLocation = "";
   let tagLoaded = false;
 
+  const cookieJar = installMemoryCookieJar(doc);
   const dataLayer: unknown[] = [];
   const gtag = function(..._args: unknown[]): void {
     dataLayer.push(arguments);
@@ -114,13 +210,20 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
 
   const configure = (message: Record<string, unknown>): void => {
     if (
-      !exactKeys(message, ["schemaVersion", "type", "destinationIds", "canonicalOrigin", "analyticsConsent", "governedProperties"]) ||
+      !exactKeys(
+        message,
+        ["schemaVersion", "type", "destinationIds", "canonicalOrigin", "analyticsConsent", "governedProperties", "visitor"],
+        ["schemaVersion", "type", "destinationIds", "canonicalOrigin", "analyticsConsent", "governedProperties"],
+      ) ||
       message["schemaVersion"] !== 1 || message["type"] !== "configure" ||
       message["analyticsConsent"] !== "granted" ||
       !validIds(message["destinationIds"]) || !validOrigin(message["canonicalOrigin"]) ||
       !validGovernedProperties(message["governedProperties"])
     ) return;
+    const visitor = message["visitor"] === undefined ? null : parseVisitor(message["visitor"]);
+    if (message["visitor"] !== undefined && !visitor) return;
     const ids = message["destinationIds"];
+    seedSessionCookies(cookieJar, ids, visitor);
     canonicalOrigin = message["canonicalOrigin"];
     governedProperties = { ...message["governedProperties"] };
     currentDestinations = [...ids];
@@ -149,6 +252,8 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
         allow_ad_personalization_signals: false,
         restricted_data_processing: true,
         ignore_referrer: true,
+        ...(visitor ? { client_id: visitor.clientId } : {}),
+        ...(visitor?.session ? { session_id: visitor.session.idSeconds } : {}),
       });
     }
     if (doc.querySelector('script[data-tot-ga4="1"]') === null) {
@@ -214,6 +319,7 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
           active = false;
           currentDestinations = [];
           lastPageLocation = "";
+          cookieJar.clear();
         }
         return;
       }
@@ -223,6 +329,7 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
           disposed = true;
           currentDestinations = [];
           lastPageLocation = "";
+          cookieJar.clear();
           port.close();
         }
         return;

package/packages/public-runtime/src/integration/native-ga4-sandbox.ts

@@ -17,6 +17,22 @@ export interface NativeGa4SandboxConfig {
    * life, so a per-event copy would only widen the hostile boundary.
    */
   governedProperties: GovernedEventProperties;
+  /**
+   * The parent's visitor continuity (shared with the Amplitude adapter). gtag keeps no
+   * state on the frame origin, which every hosted tenant shares, so the visitor and
+   * session arrive here instead. Absent when the browser cannot mint an id.
+   */
+  visitor?: NativeGa4SandboxVisitor;
+}
+
+export interface NativeGa4SandboxVisitor {
+  /** Lowercase random UUID, the GA4 `client_id`. */
+  clientId: string;
+  /** Session start in epoch ms; absent (with the other session fields) when origin storage is unavailable. */
+  sessionId?: number;
+  sessionState?: "first_visit" | "new_session" | "continuing";
+  /** 1-based session number, GA4's `sct`. */
+  sessionCount?: number;
 }
 
 export interface NativeGa4PageViewCommand {

package/packages/public-runtime/src/integration/native-ga4.ts

@@ -5,6 +5,14 @@
  * lifecycle subscription. It never loads Google code into the regulated parent.
  * Instead, a closed command crosses one private MessagePort into the reviewed,
  * isolated-origin GA4 sandbox after consent and logical-event dedupe have passed.
+ *
+ * VISITOR CONTINUITY. The GA4 `client_id` and session come from the same
+ * `VisitorContinuity` store as the Amplitude adapter's `device_id`/`session_id`
+ * (`native-amplitude.ts`), so both destinations count one visitor per browser, tenant,
+ * environment and site surface. They are read or minted only on the eligible bind path
+ * and cross into the frame in the `configure` message; the frame keeps gtag's cookies in
+ * memory, never on its origin (see `native-ga4-sandbox-entry.ts`). An update into
+ * ineligibility clears the visitor, so a later grant configures a fresh one.
  */
 import type { IntegrationLifecycleContext, IntegrationLifecycleModule, LifecycleUpdateReason } from "./lifecycle.js";
 import type { CommerceEventType } from "./events.js";
@@ -17,6 +25,12 @@ import {
 } from "./platform-adapters.js";
 import { INTEGRATION_ENVIRONMENTS, type IntegrationEnvironment } from "./environment.js";
 import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-value-safety.js";
+import {
+  createVisitorContinuity,
+  NO_SESSION_ID,
+  type VisitorContinuity,
+  type VisitorContinuityScope,
+} from "./native-amplitude.js";
 import {
   buildGovernedEventProperties,
   type GovernedEventProperties,
@@ -24,6 +38,7 @@ import {
 import type {
   NativeGa4SandboxCommand,
   NativeGa4SandboxConfig,
+  NativeGa4SandboxVisitor,
 } from "./native-ga4-sandbox.js";
 import {
   NATIVE_GA4_SANDBOX_ASSET_URL,
@@ -69,9 +84,14 @@ export type NativeGa4Observer = (observation: NativeGa4Observation) => void;
 export interface NativeGa4ModuleOptions {
   transport: NativeGa4Transport | NativeGa4TransportSend;
   observe?: NativeGa4Observer;
+  /** The host's visitor store, shared with Amplitude; defaults to memory-only (one visitor per document, no session). */
+  continuity?: VisitorContinuity;
+  /** Epoch-millisecond clock for session activity; defaults to the wall clock. */
+  now?: () => number;
 }
 
 interface ActiveGa4Config {
+  scope: VisitorContinuityScope;
   destinationIds: readonly string[];
   environment: IntegrationEnvironment;
   siteSurface: IntegrationLifecycleContext["environment"]["siteSurface"];
@@ -109,8 +129,10 @@ function configuredFor(ctx: IntegrationLifecycleContext): ActiveGa4Config | null
   // Unlabellable traffic is not collected: without a provable tenant and stage
   // every number downstream is unattributable, so this joins the other gates.
   const governedProperties = buildGovernedEventProperties(ctx.environment, ctx.tenantPublicId);
-  if (!governedProperties) return null;
+  const scope = continuityScope(ctx);
+  if (!governedProperties || !scope) return null;
   return {
+    scope,
     destinationIds,
     environment: ctx.environment.environment,
     siteSurface: ctx.environment.siteSurface,
@@ -119,6 +141,34 @@ function configuredFor(ctx: IntegrationLifecycleContext): ActiveGa4Config | null
   };
 }
 
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** The consent broker's context triple; null when the context cannot name one. */
+function continuityScope(ctx: IntegrationLifecycleContext): VisitorContinuityScope | null {
+  const { tenantPublicId } = ctx;
+  const { environment, siteSurface } = ctx.environment;
+  if (
+    typeof tenantPublicId !== "string" || tenantPublicId.length === 0 ||
+    typeof environment !== "string" || typeof siteSurface !== "string"
+  ) return null;
+  return { tenantPublicId, environment, siteSurface };
+}
+
+/** A visitor the frame accepts; a browser that cannot mint an id sends none and gtag keeps a per-document one. */
+function frameVisitor(continuity: VisitorContinuity, scope: VisitorContinuityScope, now: number): NativeGa4SandboxVisitor | undefined {
+  const ids = continuity.readOrMint(scope, now);
+  if (!UUID_PATTERN.test(ids.deviceId)) return undefined;
+  if (ids.sessionId === NO_SESSION_ID || !Number.isSafeInteger(ids.sessionId) || ids.sessionId <= 0) {
+    return { clientId: ids.deviceId };
+  }
+  return {
+    clientId: ids.deviceId,
+    sessionId: ids.sessionId,
+    sessionState: ids.sessionState,
+    sessionCount: ids.sessionCount,
+  };
+}
+
 function hasAnalyticsConsent(ctx: IntegrationLifecycleContext): boolean {
   const consent = parseConsentSnapshot(ctx.consent);
   return consent !== null && isPurposeEligible(consent, "analytics");
@@ -194,6 +244,8 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
   let currentPageLocation: string | null = null;
   const delivered = new Set<string>();
   const deliveredOrder: string[] = [];
+  const continuity = options.continuity ?? createVisitorContinuity();
+  const now = options.now ?? (() => Date.now());
 
   const transport = typeof options.transport === "function" ? undefined : options.transport;
   const send = typeof options.transport === "function" ? options.transport : options.transport.send.bind(options.transport);
@@ -221,11 +273,17 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
     }
   };
 
-  const apply = (ctx: IntegrationLifecycleContext): void => {
+  /** `clearIfIneligible`: an update that loses analytics eligibility forgets the visitor. */
+  const apply = (ctx: IntegrationLifecycleContext, clearIfIneligible: boolean): void => {
     if (!stop() || disposed) return;
     const next = configuredFor(ctx);
     if (!next) {
-      observeSafely(options.observe, hasAnalyticsConsent(ctx) ? "configuration_invalid" : "consent_ineligible");
+      const consented = hasAnalyticsConsent(ctx);
+      if (!consented && clearIfIneligible) {
+        const scope = continuityScope(ctx);
+        try { if (scope) continuity.clear(scope); } catch { /* the early consent boot clears on the next load */ }
+      }
+      observeSafely(options.observe, consented ? "configuration_invalid" : "consent_ineligible");
       return;
     }
     if (!ctx.subscribe) {
@@ -233,12 +291,14 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
       return;
     }
     try {
-      const configuration = {
+      const visitor = frameVisitor(continuity, next.scope, now());
+      const configuration: NativeGa4SandboxConfig = {
         schemaVersion: 1 as const,
         destinationIds: [...next.destinationIds],
         canonicalOrigin: next.canonicalOrigin,
         analyticsConsent: "granted" as const,
         governedProperties: { ...next.governedProperties },
+        ...(visitor ? { visitor } : {}),
       };
       runTransportEffect(transport?.configure ? () => transport.configure!(configuration) : undefined);
     } catch {
@@ -264,6 +324,8 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
             return;
           }
           if (command.type === "page_view") currentPageLocation = `${current.canonicalOrigin}${command.path}`;
+          // Record activity so the shared session rolls on inactivity, not on page-load age.
+          try { continuity.readOrMint(current.scope, now()); } catch { /* activity is best-effort */ }
           delivered.add(event.id);
           deliveredOrder.push(event.id);
           if (deliveredOrder.length > 1_024) {
@@ -284,8 +346,8 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
   };
 
   return {
-    init: apply,
-    update(_reason: LifecycleUpdateReason, ctx) { return apply(ctx); },
+    init(ctx) { return apply(ctx, false); },
+    update(_reason: LifecycleUpdateReason, ctx) { return apply(ctx, true); },
     dispose() {
       disposed = true;
       stop();

package/packages/public-runtime/src/integration/platform-adapter-runtime.ts

@@ -41,7 +41,7 @@ export interface PlatformAdapterEntryMarker {
 export interface PlatformAdapterRuntimeHost {
   fetch?: typeof fetch;
   nativeGa4Transport?: NativeGa4Transport;
-  /** The host's persistent visitor store for Amplitude; absent keeps visitors memory-only. */
+  /** The host's persistent visitor store, shared by GA4 and Amplitude; absent keeps visitors memory-only. */
   visitorContinuity?: VisitorContinuity;
 }
 
@@ -74,9 +74,9 @@ const AMPLITUDE_MARKER: PlatformAdapterEntryMarker = Object.freeze({
 export const PLATFORM_ADAPTER_RUNTIME_REGISTRY: readonly PlatformAdapterRuntimeRegistration[] = Object.freeze([
   Object.freeze({
     marker: GA4_MARKER,
-    create: ({ nativeGa4Transport }: PlatformAdapterRuntimeHost) => {
+    create: ({ nativeGa4Transport, visitorContinuity }: PlatformAdapterRuntimeHost) => {
       if (!nativeGa4Transport) throw new Error("platform_adapter_ga4_sandbox_unavailable");
-      return createNativeGa4Module({ transport: nativeGa4Transport });
+      return createNativeGa4Module({ transport: nativeGa4Transport, continuity: visitorContinuity });
     },
   }),
   Object.freeze({
@@ -154,9 +154,8 @@ export function makePlatformAdapterRuntimeLoader(
       nativeGa4Transport: registration.marker.appId === GOOGLE_MEASUREMENT_ADAPTER.adapterId
         ? options.nativeGa4Transport?.()
         : undefined,
-      visitorContinuity: registration.marker.appId === AMPLITUDE_HTTP_ADAPTER.adapterId
-        ? options.visitorContinuity
-        : undefined,
+      // One store for both destinations, so they agree on visitors and sessions.
+      visitorContinuity: options.visitorContinuity,
     });
   };
 }

package/scripts/dev/ga4-gs2-canary.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// ga4-gs2-canary.mjs — does gtag.js still read the GA4 sandbox's seeded session cookie?
+//
+// The sandbox frame seeds gtag's `_ga_<container>` cookie (Google's undocumented GS2 format)
+// into an in-memory jar so GA4 reports the parent's visitor and session. This loads the BUILT
+// sandbox document and the CURRENT live gtag.js in headless Chromium, drives three page loads
+// (first visit, continuing, new session) through the real bind/configure protocol, and asserts
+// what gtag puts on /g/collect. Every collect request is ABORTED: nothing reaches Google.
+//
+// Needs the network (gtag.js), so it is a canary, not a CI test. Exit 0 = gtag behaves as the
+// seed expects; 1 = drift (the docs say what GA4 then reports); 2 = could not run.
+//
+// Usage: node scripts/dev/ga4-gs2-canary.mjs
+import { createRequire } from "node:module";
+
+const storefrontRequire = createRequire(new URL("../../apps/storefront/package.json", import.meta.url));
+let chromium;
+let buildGoogleMeasurementSandboxHtml;
+try {
+  ({ chromium } = storefrontRequire("@playwright/test"));
+  ({ buildGoogleMeasurementSandboxHtml } = await import("../../apps/storefront/integrations/google-measurement-sandbox-asset.mjs"));
+} catch (error) {
+  console.error(`ga4-gs2-canary: cannot run — ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(2);
+}
+
+const PARENT = "https://shop.canary.test";
+const FRAME = "https://www.shop.canary.test/platform/google-measurement/v2/sandbox.html";
+const MEASUREMENT_ID = "G-CANARY0001";
+const CLIENT_ID = "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
+const FIRST_SESSION_MS = Date.now() - 5 * 60 * 1000;
+const SECOND_SESSION_MS = Date.now();
+const seconds = (ms) => String(Math.floor(ms / 1000));
+
+const LOADS = [
+  {
+    name: "first visit",
+    visitor: { clientId: CLIENT_ID, sessionId: FIRST_SESSION_MS, sessionState: "first_visit", sessionCount: 1 },
+    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: "1", _fv: "1" },
+  },
+  {
+    name: "next page, same session",
+    visitor: { clientId: CLIENT_ID, sessionId: FIRST_SESSION_MS, sessionState: "continuing", sessionCount: 1 },
+    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: null, _fv: null },
+  },
+  {
+    name: "return, new session",
+    visitor: { clientId: CLIENT_ID, sessionId: SECOND_SESSION_MS, sessionState: "new_session", sessionCount: 2 },
+    expect: { cid: CLIENT_ID, sid: seconds(SECOND_SESSION_MS), sct: "2", _ss: "1", _fv: null },
+  },
+];
+
+const parentPage = (visitor) => `<!doctype html><body><script>
+const frame = document.createElement("iframe");
+frame.setAttribute("sandbox", "allow-scripts allow-same-origin");
+frame.src = ${JSON.stringify(FRAME)};
+frame.addEventListener("load", () => {
+  const channel = new MessageChannel();
+  frame.contentWindow.postMessage({ protocol: "tot.ga4-sandbox/1", type: "bind", parentOrigin: location.origin }, new URL(frame.src).origin, [channel.port2]);
+  channel.port1.postMessage({ schemaVersion: 1, type: "configure", destinationIds: [${JSON.stringify(MEASUREMENT_ID)}],
+    canonicalOrigin: location.origin, analyticsConsent: "granted",
+    governedProperties: { tenant: "canary", environment: "live", site_surface: "storefront" },
+    visitor: ${JSON.stringify(visitor)} });
+  channel.port1.postMessage({ schemaVersion: 1, type: "page_view", path: "/canary" });
+});
+document.body.append(frame);
+</script></body>`;
+
+const html = await buildGoogleMeasurementSandboxHtml();
+const browser = await chromium.launch();
+const failures = [];
+let gtagLoaded = false;
+try {
+  const context = await browser.newContext();
+  const pageViews = new Map();
+  let current = 0;
+  await context.route("**/*", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    if (request.url().startsWith(FRAME)) return route.fulfill({ status: 200, contentType: "text/html", body: html });
+    if (url.origin === PARENT) return route.fulfill({ status: 200, contentType: "text/html", body: parentPage(LOADS[current].visitor) });
+    if (url.host === "www.googletagmanager.com" && url.pathname === "/gtag/js") {
+      gtagLoaded = true;
+      return route.continue();
+    }
+    if (url.pathname.endsWith("/g/collect")) {
+      for (const line of [url.search.slice(1), ...(request.postData() ?? "").split("\n")].filter(Boolean)) {
+        const params = new URLSearchParams(url.search);
+        for (const [key, value] of new URLSearchParams(line)) params.set(key, value);
+        if (params.get("en") === "page_view" && !pageViews.has(current)) {
+          pageViews.set(current, Object.fromEntries(["cid", "sid", "sct", "_ss", "_fv"].map((key) => [key, params.get(key)])));
+        }
+      }
+    }
+    return route.abort();
+  });
+  const page = await context.newPage();
+  for (current = 0; current < LOADS.length; current += 1) {
+    await page.goto(`${PARENT}/?load=${current}`);
+    for (let waited = 0; !pageViews.has(current) && waited < 15_000; waited += 250) await page.waitForTimeout(250);
+    await page.goto("about:blank");
+    await page.waitForTimeout(500);
+  }
+  const cookies = await context.cookies([FRAME, PARENT]);
+
+  if (!gtagLoaded) {
+    console.error("ga4-gs2-canary: cannot run — gtag.js never loaded (network?)");
+    process.exitCode = 2;
+  } else {
+    LOADS.forEach((load, index) => {
+      const actual = pageViews.get(index);
+      if (!actual) return failures.push(`${load.name}: no page_view reached /g/collect`);
+      for (const [key, value] of Object.entries(load.expect)) {
+        if (actual[key] !== value) failures.push(`${load.name}: ${key}=${actual[key]} (expected ${value})`);
+      }
+      console.log(`${load.name}: ${JSON.stringify({ ...actual, cid: actual.cid === CLIENT_ID ? "<seeded>" : actual.cid })}`);
+    });
+    if (cookies.length > 0) failures.push(`cookies written on the frame or parent origin: ${cookies.map((c) => c.name).join(", ")}`);
+    if (failures.length > 0) {
+      console.error("ga4-gs2-canary: DRIFT — gtag no longer honours the sandbox seed as expected:");
+      for (const failure of failures) console.error(`  - ${failure}`);
+      console.error("See docs/architecture/analytics-activation.md (GA4) for what GA4 reports in this state.");
+      process.exitCode = 1;
+    } else {
+      console.log("ga4-gs2-canary: OK — gtag reads the GS2 seed; cid, sid, sct, _ss and _fv match, no cookies written.");
+    }
+  }
+} finally {
+  await browser.close();
+}