@tokenoftrust/storefront-runner 4.9.2 → 4.10.0

package/packages/public-runtime/src/integration/managed-analytics.ts

@@ -16,6 +16,13 @@ import {
   type ContractResult,
 } from "./result.js";
 import { findForbiddenFields } from "./secrets.js";
+import {
+  GOOGLE_ADS_CLICK_ID_KEYS,
+  isGoogleAdsClickIdValue,
+  MANAGED_ANALYTICS_CAMPAIGN_FIELDS,
+  screenManagedAnalyticsCampaign,
+  type GoogleAdsClickIds,
+} from "./managed-analytics-value-safety.js";
 import type { CommerceEmitResult, CommerceEventBroker } from "./commerce-broker.js";
 import {
   APPROVED_MARKETING_ACTION_NAMES,
@@ -125,27 +132,11 @@ export interface AttributionSourceInput {
   routeUrl?: string | null;
 }
 
-const UTM_QUERY_FIELDS = [
-  ["utm_source", "source"],
-  ["utm_medium", "medium"],
-  ["utm_campaign", "campaign"],
-  ["utm_term", "term"],
-  ["utm_content", "content"],
-] as const;
-const SAFE_CAMPAIGN_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
-const PROTECTED_CAMPAIGN_TOKEN =
-  /(?:@|\d{7,}|(?:^|[._~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[._~-]))/i;
-
-function safeCampaignToken(value: string): string | undefined {
-  return SAFE_CAMPAIGN_TOKEN.test(value) && !PROTECTED_CAMPAIGN_TOKEN.test(value)
-    ? value
-    : undefined;
-}
-
 /**
  * Reduce explicit URL inputs to an origin-only referrer and the five standard UTM
- * tokens. Query keys outside the UTM allowlist, duplicate keys, unsafe free-form
- * values, credentials, paths, and fragments are discarded. No browser global is read.
+ * tokens. Query keys outside the UTM allowlist, duplicate keys, values the shared
+ * campaign policy rejects (`screenManagedAnalyticsCampaign`), credentials, paths, and
+ * fragments are discarded. No browser global is read.
  */
 export function minimizePageAttribution(input: AttributionSourceInput): ManagedPageAttribution | undefined {
   const result: ManagedPageAttribution = {};
@@ -168,14 +159,13 @@ export function minimizePageAttribution(input: AttributionSourceInput): ManagedP
   if (input.routeUrl) {
     try {
       const route = new URL(input.routeUrl, "https://route.invalid");
-      const utm: NonNullable<ManagedPageAttribution["utm"]> = {};
-      for (const [queryName, field] of UTM_QUERY_FIELDS) {
-        const values = route.searchParams.getAll(queryName);
-        if (values.length !== 1) continue;
-        const value = safeCampaignToken(values[0] ?? "");
-        if (value !== undefined) utm[field] = value;
+      const query: Record<string, string> = {};
+      for (const field of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
+        const values = route.searchParams.getAll(`utm_${field}`);
+        if (values.length === 1) query[field] = values[0]!;
       }
-      if (Object.keys(utm).length > 0) result.utm = utm;
+      const { kept } = screenManagedAnalyticsCampaign(query);
+      if (Object.keys(kept).length > 0) result.utm = kept;
     } catch {
       // Invalid route input contributes no attribution.
     }
@@ -184,6 +174,29 @@ export function minimizePageAttribution(input: AttributionSourceInput): ManagedP
   return result.referrer || result.utm ? result : undefined;
 }
 
+/**
+ * Read Google Ads click identifiers (`gclid`, `gbraid`, `wbraid`) from a landing URL.
+ * Each key counts only when it appears exactly once with a valid value; anything else
+ * is dropped silently, so no rejected value reaches a diagnostic. These never enter
+ * the analytics event contract: only the GA4 host capability carries them.
+ */
+export function readGoogleAdsClickIds(routeUrl: string | null | undefined): GoogleAdsClickIds | undefined {
+  if (!routeUrl) return undefined;
+  let route: URL;
+  try {
+    route = new URL(routeUrl, "https://route.invalid");
+  } catch (error) {
+    if (error instanceof TypeError) return undefined;
+    throw error;
+  }
+  const ids: GoogleAdsClickIds = {};
+  for (const key of GOOGLE_ADS_CLICK_ID_KEYS) {
+    const values = route.searchParams.getAll(key);
+    if (values.length === 1 && isGoogleAdsClickIdValue(values[0])) ids[key] = values[0];
+  }
+  return Object.keys(ids).length > 0 ? ids : undefined;
+}
+
 export type ManagedAnalyticsEmitResult =
   | CommerceEmitResult
   | {

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

@@ -41,7 +41,11 @@ import {
   type BrowserEnvironment,
   type IntegrationEnvironment,
 } from "./environment.js";
-import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+import {
+  resemblesManagedAnalyticsPii,
+  screenManagedAnalyticsCampaign,
+  type ManagedAnalyticsCampaignField,
+} from "./managed-analytics-value-safety.js";
 import {
   buildGovernedEventProperties,
   type GovernedEventProperties,
@@ -342,10 +346,10 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 /**
  * Flatten the already-validated `data.attribution` object (`events.ts`
  * `validatePageAttribution` — a minimized referrer origin plus up to five UTM
- * tokens) into Amplitude's flat `event_properties`. Re-screened for PII here
- * rather than trusted from upstream validation alone, matching `isSafePagePath`'s
- * own double-check: a field that resembles PII is dropped individually rather
- * than failing the whole page-view event.
+ * tokens) into Amplitude's flat `event_properties`. UTM values are re-screened with
+ * the same campaign policy GA4 applies (`screenManagedAnalyticsCampaign`) rather than
+ * trusted from upstream validation alone, so both destinations carry the same fields;
+ * a rejected field is dropped individually rather than failing the whole page view.
  */
 function extractAttributionProperties(data: Record<string, unknown>): AmplitudeAttributionProperties {
   const attribution = data["attribution"];
@@ -354,11 +358,8 @@ function extractAttributionProperties(data: Record<string, unknown>): AmplitudeA
 
   const utm = attribution["utm"];
   if (isPlainObject(utm)) {
-    for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
-      const value = utm[key];
-      if (typeof value === "string" && value.length > 0 && !resemblesManagedAnalyticsPii(value)) {
-        out[`utm_${key}`] = value;
-      }
+    for (const [key, value] of Object.entries(screenManagedAnalyticsCampaign(utm).kept)) {
+      out[`utm_${key as ManagedAnalyticsCampaignField}`] = value;
     }
   }
 

package/packages/public-runtime/src/integration/native-ga4-sandbox-asset.d.mts

@@ -1,4 +1,5 @@
 export const NATIVE_GA4_SANDBOX_ASSET_PATH: "platform/google-measurement/v2/sandbox.html";
 export const NATIVE_GA4_SANDBOX_ASSET_URL: "/platform/google-measurement/v2/sandbox.html";
 export const NATIVE_GA4_SANDBOX_ORIGIN: "https://analytics-frame.tokenoftrust.store";
+export const NATIVE_GA4_SANDBOX_FRAME_STYLE: Readonly<Record<string, string>>;
 export function resolveNativeGa4SandboxUrl(parentHref: string): string;

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

@@ -3,6 +3,26 @@ export const NATIVE_GA4_SANDBOX_ASSET_PATH = "platform/google-measurement/v2/san
 export const NATIVE_GA4_SANDBOX_ASSET_URL = `/${NATIVE_GA4_SANDBOX_ASSET_PATH}`;
 export const NATIVE_GA4_SANDBOX_ORIGIN = "https://analytics-frame.tokenoftrust.store";
 
+/**
+ * The frame's box: laid out, but invisible and inert. gtag's enhanced measurement
+ * reports a 90% `scroll` as soon as it loads in a frame with no layout (`display:none`
+ * or a 0x0 box), because the frame document's height guard then has no viewport to
+ * measure against. A 1px box gives it one (measured 2026-10-28 with the live gtag.js,
+ * collection null-routed: hidden and 0x0 frames each sent `scroll` at 90%, the 1px box
+ * sent only the page views). The parent sets it through the CSSOM, which its CSP does
+ * not govern.
+ */
+export const NATIVE_GA4_SANDBOX_FRAME_STYLE = Object.freeze({
+  position: "fixed",
+  top: "0",
+  left: "0",
+  width: "1px",
+  height: "1px",
+  border: "0",
+  opacity: "0",
+  "pointer-events": "none",
+});
+
 /**
  * Keep Google tag execution on a real, isolated origin. An opaque sandbox origin makes
  * gtag.js load successfully but silently suppresses every collection request. Production

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

@@ -5,10 +5,15 @@ import {
   NATIVE_GA4_SANDBOX_PROTOCOL,
   type NativeGa4SandboxPortMessage,
 } from "./native-ga4-sandbox.js";
-import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-value-safety.js";
+import {
+  isGoogleAdsClickIds,
+  MANAGED_ANALYTICS_CAMPAIGN_FIELDS,
+  resemblesManagedAnalyticsProtectedValue,
+  screenManagedAnalyticsCampaign,
+  type GoogleAdsClickIds,
+} from "./managed-analytics-value-safety.js";
 
 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"]);
@@ -155,11 +160,12 @@ function seedSessionCookies(jar: Map<string, string>, ids: readonly string[], vi
 }
 
 /**
- * gtag's enhanced measurement runs inside this frame and reports the frame's own
- * document: its URL, its title, and a `scroll` at 90% depth that a short hidden
- * document reaches on load (measured 2026-10-06 on a live stream). A frame taller than
- * any viewport never reaches that depth, so the fabricated scroll is never sent.
- * Setting height through the CSSOM is outside the frame's style CSP, which governs markup.
+ * gtag's enhanced measurement runs inside this frame and reports a `scroll` at 90% depth
+ * once the frame document fits its viewport. A document taller than any viewport never
+ * reaches that depth, so the fabricated scroll is never sent. The guard needs the frame
+ * to be laid out (`NATIVE_GA4_SANDBOX_FRAME_STYLE`); a frame with no layout reports the
+ * scroll regardless. Setting height through the CSSOM is outside the frame's style CSP,
+ * which governs markup.
  */
 function suppressFrameScroll(doc: Document): void {
   const root = doc.documentElement as HTMLElement | null | undefined;
@@ -168,9 +174,8 @@ function suppressFrameScroll(doc: Document): void {
 
 function validCampaign(value: unknown): value is Record<string, string> {
   const record = plainRecord(value);
-  if (!record || !exactKeys(record, ["source", "medium", "campaign", "term", "content"], [])) return false;
-  return Object.values(record).every((item) =>
-    typeof item === "string" && CAMPAIGN_VALUE.test(item) && !resemblesManagedAnalyticsProtectedValue(item));
+  return record !== null && exactKeys(record, MANAGED_ANALYTICS_CAMPAIGN_FIELDS, []) &&
+    screenManagedAnalyticsCampaign(record).rejected.length === 0;
 }
 
 export interface NativeGa4SandboxRuntimeWindow extends Pick<Window, "parent" | "location"> {
@@ -281,25 +286,31 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
   const deliver = (message: Record<string, unknown>): void => {
     if (!active || disposed || message["schemaVersion"] !== 1) return;
     if (message["type"] === "page_view") {
-      if (!exactKeys(message, ["schemaVersion", "type", "path", "referrerOrigin", "campaign"], ["schemaVersion", "type", "path"])) return;
+      if (!exactKeys(message, ["schemaVersion", "type", "path", "referrerOrigin", "campaign", "clickIds"], ["schemaVersion", "type", "path"])) return;
       if (!validPath(message["path"])) return;
       if (message["referrerOrigin"] !== undefined && !validOrigin(message["referrerOrigin"])) return;
       if (message["campaign"] !== undefined && !validCampaign(message["campaign"])) return;
+      if (message["clickIds"] !== undefined && !isGoogleAdsClickIds(message["clickIds"])) return;
       const pageLocation = `${canonicalOrigin}${message["path"]}`;
       lastPageLocation = pageLocation;
       // Events gtag collects on its own (engagement, enhanced measurement) take the page
       // from these defaults, not from the frame. The title crosses the boundary as the path:
       // the frame's own title would label every page "Analytics transport".
       gtag("set", { page_location: pageLocation, page_title: message["path"] });
+      // Click identifiers ride only this event's page_location, where GA4 reads ad-click
+      // information; the page default and the action anchor stay query-free.
+      const clickIds = message["clickIds"] as GoogleAdsClickIds | undefined;
       const params: Record<string, unknown> = {
         ...governedProperties,
-        page_location: pageLocation,
+        page_location: clickIds
+          ? `${pageLocation}?${new URLSearchParams(clickIds as Record<string, string>).toString()}`
+          : pageLocation,
         page_path: message["path"],
       };
       if (message["referrerOrigin"] !== undefined) params["page_referrer"] = message["referrerOrigin"];
       if (message["campaign"] !== undefined) {
         const campaign = message["campaign"] as Record<string, string>;
-        for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
+        for (const key of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
           const ga4Key = key === "campaign" ? "name" : key;
           if (campaign[key] !== undefined) params[`campaign_${ga4Key}`] = campaign[key];
         }

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

@@ -1,6 +1,7 @@
 /** Closed parent/iframe protocol for the reviewed GA4 isolated-origin sandbox. */
 import type { GovernedEventProperties } from "./governed-event-properties.js";
-import { resolveNativeGa4SandboxUrl } from "./native-ga4-sandbox-asset.mjs";
+import type { GoogleAdsClickIds, ManagedAnalyticsCampaign } from "./managed-analytics-value-safety.js";
+import { NATIVE_GA4_SANDBOX_FRAME_STYLE, resolveNativeGa4SandboxUrl } from "./native-ga4-sandbox-asset.mjs";
 
 export const NATIVE_GA4_SANDBOX_PROTOCOL = "tot.ga4-sandbox/1" as const;
 export const NATIVE_GA4_SANDBOX_MAX_DESTINATIONS = 4 as const;
@@ -40,13 +41,9 @@ export interface NativeGa4PageViewCommand {
   type: "page_view";
   path: string;
   referrerOrigin?: string;
-  campaign?: {
-    source?: string;
-    medium?: string;
-    campaign?: string;
-    term?: string;
-    content?: string;
-  };
+  campaign?: ManagedAnalyticsCampaign;
+  /** Landing-page Google Ads click identifiers; the frame adds them to this event's `page_location` only. */
+  clickIds?: GoogleAdsClickIds;
 }
 
 export interface NativeGa4ActionCommand {
@@ -75,7 +72,7 @@ export interface NativeGa4SandboxFrame {
   addEventListener(type: "load" | "error", listener: () => void, options?: { once?: boolean }): void;
   remove(): void;
   src: string;
-  hidden: boolean;
+  style: { setProperty(name: string, value: string): void };
 }
 
 export interface NativeGa4SandboxHost {
@@ -122,7 +119,7 @@ const IMMEDIATE_SCHEDULER: NativeGa4SandboxScheduler = (start) => {
 };
 
 /**
- * Mount one hidden same-site, cross-origin iframe and transfer exactly one MessagePort
+ * Mount one invisible same-site, cross-origin iframe and transfer exactly one MessagePort
  * after load. gtag suppresses collection in an opaque third-party frame, so the receiver
  * needs a real same-site origin. The exact origin, iframe window, and one-shot transfer
  * are the authority boundary. No general parent `message` listener is installed.
@@ -170,7 +167,7 @@ export function createNativeGa4SandboxTransport(
     mounted.setAttribute("aria-hidden", "true");
     mounted.setAttribute("tabindex", "-1");
     mounted.setAttribute("title", "Analytics transport");
-    mounted.hidden = true;
+    for (const [name, value] of Object.entries(NATIVE_GA4_SANDBOX_FRAME_STYLE)) mounted.style.setProperty(name, value);
     mounted.src = sandboxUrl;
 
     mounted.addEventListener("load", () => {

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

@@ -24,7 +24,12 @@ import {
   resolveAdapterDestinationIds,
 } from "./platform-adapters.js";
 import { INTEGRATION_ENVIRONMENTS, type IntegrationEnvironment } from "./environment.js";
-import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-value-safety.js";
+import {
+  resemblesManagedAnalyticsProtectedValue,
+  screenManagedAnalyticsCampaign,
+  isGoogleAdsClickIds,
+  type GoogleAdsClickIds,
+} from "./managed-analytics-value-safety.js";
 import {
   createVisitorContinuity,
   NO_SESSION_ID,
@@ -88,6 +93,11 @@ export interface NativeGa4ModuleOptions {
   continuity?: VisitorContinuity;
   /** Epoch-millisecond clock for session activity; defaults to the wall clock. */
   now?: () => number;
+  /**
+   * The host's one-shot landing click identifiers for a page view at `path`. The host
+   * owns the consent and region decision and returns them at most once per document.
+   */
+  takeLandingClickIds?: (path: string) => GoogleAdsClickIds | undefined;
 }
 
 interface ActiveGa4Config {
@@ -220,12 +230,8 @@ function mapEvent(
       }
       const utm = record["utm"];
       if (typeof utm === "object" && utm !== null && !Array.isArray(utm)) {
-        const campaign: NonNullable<typeof command.campaign> = {};
-        for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
-          const value = (utm as Record<string, unknown>)[key];
-          if (typeof value === "string" && !resemblesManagedAnalyticsProtectedValue(value)) campaign[key] = value;
-        }
-        if (Object.keys(campaign).length > 0) command.campaign = campaign;
+        const { kept } = screenManagedAnalyticsCampaign(utm as Record<string, unknown>);
+        if (Object.keys(kept).length > 0) command.campaign = kept;
       }
     }
     return Object.freeze(command);
@@ -332,8 +338,15 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
             const oldest = deliveredOrder.shift();
             if (oldest !== undefined) delivered.delete(oldest);
           }
+          let outgoing = command;
+          if (command.type === "page_view" && options.takeLandingClickIds) {
+            try {
+              const clickIds = options.takeLandingClickIds(command.path);
+              if (isGoogleAdsClickIds(clickIds)) outgoing = Object.freeze({ ...command, clickIds: { ...clickIds } });
+            } catch { /* a page view never waits on attribution */ }
+          }
           try {
-            const result = send(command);
+            const result = send(outgoing);
             if (result && typeof result.then === "function") {
               void result.catch(() => observeSafely(options.observe, "transport_failed"));
             }

package/packages/public-runtime/src/integration/plan.ts

@@ -83,11 +83,13 @@ export interface NormalizedContribution {
 /**
  * The tenant's analytics policy for visitors in the EU/EEA, the UK and Switzerland, and
  * for visitors whose region is unknown:
- *   - `count-only` (default): page views are delivered, nothing is stored on the device.
+ *   - `ask` (default): page views are counted without storing anything, and the visitor is
+ *     prompted; an Allow applies the default behavior for that visitor.
+ *   - `count-only`: page views are delivered, nothing is stored on the device, no prompt.
  *   - `full`: the tenant takes responsibility for EU/UK consent; the default behavior applies.
  *   - `none`: no analytics or marketing destination runs for those visitors.
  */
-export const EU_UK_VISITOR_POLICIES = ["count-only", "full", "none"] as const;
+export const EU_UK_VISITOR_POLICIES = ["ask", "count-only", "full", "none"] as const;
 export type EuUkVisitorPolicy = (typeof EU_UK_VISITOR_POLICIES)[number];
 
 export function isEuUkVisitorPolicy(value: unknown): value is EuUkVisitorPolicy {
@@ -102,9 +104,9 @@ export interface EffectivePlan {
   tenantPublicId: string;
   /**
    * The tenant's {@link EuUkVisitorPolicy}, present only when it is not the
-   * `count-only` default. It participates in `planRevision`.
+   * `ask` default. It participates in `planRevision`.
    */
-  euUkVisitors?: Exclude<EuUkVisitorPolicy, "count-only">;
+  euUkVisitors?: Exclude<EuUkVisitorPolicy, "ask">;
   integrations: PlanIntegration[];
   contributions: NormalizedContribution[];
   /** Resolved execution order over contribution ids. */

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

@@ -24,6 +24,7 @@ import {
   NATIVE_GA4_RUNTIME_ID,
   type NativeGa4Transport,
 } from "./native-ga4.js";
+import type { GoogleAdsClickIds } from "./managed-analytics-value-safety.js";
 import { AMPLITUDE_HTTP_ADAPTER, GOOGLE_MEASUREMENT_ADAPTER } from "./platform-adapters.js";
 
 export const PLATFORM_ADAPTER_ENTRY_SCHEMA_VERSION = 1 as const;
@@ -43,6 +44,8 @@ export interface PlatformAdapterRuntimeHost {
   nativeGa4Transport?: NativeGa4Transport;
   /** The host's persistent visitor store, shared by GA4 and Amplitude; absent keeps visitors memory-only. */
   visitorContinuity?: VisitorContinuity;
+  /** GA4 only: the host's consent- and region-gated one-shot landing click identifiers. */
+  takeLandingClickIds?: (path: string) => GoogleAdsClickIds | undefined;
 }
 
 export interface PlatformAdapterRuntimeRegistration {
@@ -74,9 +77,9 @@ const AMPLITUDE_MARKER: PlatformAdapterEntryMarker = Object.freeze({
 export const PLATFORM_ADAPTER_RUNTIME_REGISTRY: readonly PlatformAdapterRuntimeRegistration[] = Object.freeze([
   Object.freeze({
     marker: GA4_MARKER,
-    create: ({ nativeGa4Transport, visitorContinuity }: PlatformAdapterRuntimeHost) => {
+    create: ({ nativeGa4Transport, visitorContinuity, takeLandingClickIds }: PlatformAdapterRuntimeHost) => {
       if (!nativeGa4Transport) throw new Error("platform_adapter_ga4_sandbox_unavailable");
-      return createNativeGa4Module({ transport: nativeGa4Transport, continuity: visitorContinuity });
+      return createNativeGa4Module({ transport: nativeGa4Transport, continuity: visitorContinuity, takeLandingClickIds });
     },
   }),
   Object.freeze({
@@ -92,6 +95,7 @@ export interface PlatformAdapterRuntimeLoaderOptions {
   fetchCapability?: typeof fetch;
   nativeGa4Transport?: () => NativeGa4Transport;
   visitorContinuity?: VisitorContinuity;
+  takeLandingClickIds?: (path: string) => GoogleAdsClickIds | undefined;
   importModule?: (url: string) => Promise<unknown>;
   fallback: IntegrationModuleLoader;
 }
@@ -156,6 +160,9 @@ export function makePlatformAdapterRuntimeLoader(
         : undefined,
       // One store for both destinations, so they agree on visitors and sessions.
       visitorContinuity: options.visitorContinuity,
+      takeLandingClickIds: registration.marker.appId === GOOGLE_MEASUREMENT_ADAPTER.adapterId
+        ? options.takeLandingClickIds
+        : undefined,
     });
   };
 }

package/packages/public-runtime/src/integration/render-phases.ts

@@ -108,7 +108,7 @@ export interface IntegrationBootDescriptor {
   siteSurface: EffectivePlan["environment"]["siteSurface"];
   tenantPublicId: string;
   /**
-   * The tenant's EU/UK visitor policy when it is not the `count-only` default. The
+   * The tenant's EU/UK visitor policy when it is not the `ask` default. The
    * early consent boot reads it together with the edge's region class.
    */
   euUkVisitors?: EffectivePlan["euUkVisitors"];
@@ -182,7 +182,6 @@ export function renderIntegrationPhases(
   const bodyDeferred =
     phaseBoundary("document.deferred") +
     `<div data-tot-integration-deferred hidden></div>` +
-    viewerAnalyticsChoicesLink(plan) +
     lifecycleHostScript();
 
   return { head, bodyStart, bodyDeferred };
@@ -240,17 +239,23 @@ function inlineScript(source: string, nonce: string): string {
 
 /** Renderer-owned, provider-neutral viewer control: identical in both document mounts. */
 function viewerAnalyticsConsentStyle(nonce: string): string {
-  const style = `.tot-analytics-consent{position:fixed;z-index:900;right:1rem;bottom:1rem;display:flex;max-width:min(30rem,calc(100vw - 2rem));align-items:center;gap:.65rem;padding:.7rem .8rem;border:1px solid var(--color-border,#cbd5e1);border-radius:.75rem;background:var(--color-bg,#fff);color:var(--color-text,#111827);box-shadow:0 8px 30px rgba(15,23,42,.18);font:500 .75rem/1.25 system-ui,sans-serif}.tot-analytics-consent__copy{display:grid;gap:.15rem;min-width:8rem}.tot-analytics-consent__detail{color:var(--color-muted,#475569);font-size:.68rem}.tot-analytics-consent__actions{display:flex;gap:.4rem}.tot-analytics-consent button{border:1px solid currentColor;border-radius:999px;background:transparent;color:inherit;padding:.4rem .65rem;font:inherit;cursor:pointer}.tot-analytics-consent button:disabled{cursor:default;opacity:.45}@media(max-width:34rem){.tot-analytics-consent{left:1rem;right:1rem;align-items:flex-start;flex-direction:column}.tot-analytics-consent__actions{width:100%}.tot-analytics-consent button{flex:1}}.tot-analytics-consent[hidden]{display:none}.tot-analytics-choices{display:flex;justify-content:center;padding:.75rem 1rem;background:var(--color-bg,#fff)}.tot-analytics-choices__toggle{border:0;background:none;padding:.25rem;color:var(--color-muted,#475569);font:500 .75rem/1.25 system-ui,sans-serif;text-decoration:underline;cursor:pointer}`;
+  const style = `.tot-analytics-consent{position:fixed;z-index:900;right:1rem;bottom:1rem;display:flex;max-width:min(30rem,calc(100vw - 2rem));align-items:center;gap:.65rem;padding:.7rem .8rem;border:1px solid var(--color-border,#cbd5e1);border-radius:.75rem;background:var(--color-bg,#fff);color:var(--color-text,#111827);box-shadow:0 8px 30px rgba(15,23,42,.18);font:500 .75rem/1.25 system-ui,sans-serif}.tot-analytics-consent__copy{display:grid;gap:.15rem;min-width:8rem}.tot-analytics-consent__detail{color:var(--color-muted,#475569);font-size:.68rem}.tot-analytics-consent__actions{display:flex;gap:.4rem}.tot-analytics-consent button{border:1px solid currentColor;border-radius:999px;background:transparent;color:inherit;padding:.4rem .65rem;font:inherit;cursor:pointer}.tot-analytics-consent button:disabled{cursor:default;opacity:.45}@media(max-width:34rem){.tot-analytics-consent{left:1rem;right:1rem;align-items:flex-start;flex-direction:column}.tot-analytics-consent__actions{width:100%}.tot-analytics-consent button{flex:1}}.tot-analytics-consent[hidden]{display:none}`;
   return `<style${nonce ? ` nonce="${nonce}"` : ""}>${style}</style>`;
 }
 
-/** The id the persistent "Analytics choices" toggle names in `aria-controls`. */
+/**
+ * The id a tenant's Privacy Policy "Analytics choices" button names in `aria-controls`.
+ * The engine renders no visible route to the control: the tenant places that button in
+ * its own Privacy Policy, and the lifecycle host binds it
+ * (`bootViewerAnalyticsConsentControl`). Markup contract:
+ * `docs/architecture/analytics-activation.md`.
+ */
 const VIEWER_ANALYTICS_CONSENT_CONTROL_ID = "tot-analytics-consent";
 
 function viewerAnalyticsConsentControl(): string {
   return `<aside id="${VIEWER_ANALYTICS_CONSENT_CONTROL_ID}" class="tot-analytics-consent" data-tot-analytics-consent-control aria-label="Analytics privacy settings" hidden>` +
     `<span class="tot-analytics-consent__copy"><strong data-tot-analytics-consent-status aria-live="polite">Analytics off</strong>` +
-    `<span class="tot-analytics-consent__detail">Choose whether analytics may run on this site.</span></span>` +
+    `<span class="tot-analytics-consent__detail" data-tot-analytics-consent-detail>Choose whether analytics may run on this site.</span></span>` +
     `<span class="tot-analytics-consent__actions">` +
     `<button type="button" data-tot-analytics-consent-decision="granted" aria-pressed="false" disabled>Allow</button>` +
     `<button type="button" data-tot-analytics-consent-decision="denied" aria-pressed="true" disabled>Decline</button>` +
@@ -258,19 +263,6 @@ function viewerAnalyticsConsentControl(): string {
     `</span></aside>`;
 }
 
-/**
- * The persistent, platform-owned way to reach the control: a disclosure button placed
- * after the tenant's own footer, on every page whose plan asks for analytics consent.
- * The lifecycle host binds it (`bootViewerAnalyticsConsentControl`); no inline handler.
- */
-function viewerAnalyticsChoicesLink(plan: EffectivePlan): string {
-  if (!plan.consentNeeds.includes("analytics")) return "";
-  return `<div class="tot-analytics-choices">` +
-    `<button type="button" class="tot-analytics-choices__toggle" data-tot-analytics-choices-toggle ` +
-    `aria-controls="${VIEWER_ANALYTICS_CONSENT_CONTROL_ID}" aria-expanded="false">Analytics choices</button>` +
-    `</div>`;
-}
-
 /**
  * Replace every {@link INTEGRATION_NONCE_PLACEHOLDER} in `text` (an HTML body or a
  * CSP header value) with one fresh per-response `nonce`. Idempotent on text with no

package/packages/public-runtime/src/integration/resolve.ts

@@ -68,7 +68,7 @@ export interface ResolvePlanInput {
   tenantPublicId: string;
   environment: BrowserEnvironment;
   declarations: readonly IntegrationDeclarationInput[];
-  /** The tenant's EU/UK visitor policy; absent means `count-only`. */
+  /** The tenant's EU/UK visitor policy; absent means `ask`. */
   euUkVisitors?: EuUkVisitorPolicy;
 }
 
@@ -98,7 +98,7 @@ export function resolveEffectivePlan(
   }
 
   if (input.euUkVisitors !== undefined && !isEuUkVisitorPolicy(input.euUkVisitors)) {
-    v.add("euUkVisitors", "unknown_enum", 'euUkVisitors must be "count-only", "full", or "none".');
+    v.add("euUkVisitors", "unknown_enum", 'euUkVisitors must be "ask", "count-only", "full", or "none".');
   }
 
   if (!Array.isArray(input.declarations)) {
@@ -218,7 +218,7 @@ export function resolveEffectivePlan(
     schemaVersion: EFFECTIVE_PLAN_SCHEMA_VERSION,
     environment: envResult.ok ? envResult.value : input.environment,
     tenantPublicId: input.tenantPublicId,
-    ...(input.euUkVisitors === "full" || input.euUkVisitors === "none"
+    ...(isEuUkVisitorPolicy(input.euUkVisitors) && input.euUkVisitors !== "ask"
       ? { euUkVisitors: input.euUkVisitors }
       : {}),
     integrations,