@tokenoftrust/storefront-runner 4.9.3 → 4.10.0

package/apps/storefront/src/lib/measurement/admin/analyticsRegionPolicy.ts

@@ -0,0 +1,151 @@
+/**
+ * The EU/UK visitor policy a tenant declares in its own `analytics.json` (`euUkVisitors`), read and
+ * rewritten as TEXT for the admin consent page.
+ *
+ * The rewrite touches only the top-level `euUkVisitors` member: every other byte of the file —
+ * `destinations` above all — is carried through unchanged, so a policy change never reformats or
+ * re-serializes the tenant's destination ids. `ask` is the default and is expressed by ABSENCE, so
+ * choosing it removes the key.
+ */
+import {
+  EU_UK_VISITOR_POLICIES,
+  TENANT_ANALYTICS_SCHEMA_VERSION,
+  isEuUkVisitorPolicy,
+  tenantAnalyticsDeclarationFindings,
+  type EuUkVisitorPolicy,
+  type TenantAnalyticsFinding,
+} from "@tot/public-runtime";
+
+export { EU_UK_VISITOR_POLICIES, isEuUkVisitorPolicy, type EuUkVisitorPolicy };
+
+const POLICY_KEY = "euUkVisitors";
+
+/** The declared policy, `ask` when the file or the key is absent. `null` when the file is not a JSON object. */
+export function readEuUkVisitorPolicy(text: string | null): EuUkVisitorPolicy | null {
+  if (text === null) return "ask";
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    if (err instanceof SyntaxError) return null;
+    throw err;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const value = (parsed as Record<string, unknown>)[POLICY_KEY];
+  if (value === undefined) return "ask";
+  return isEuUkVisitorPolicy(value) ? value : null;
+}
+
+/** Value-free violations for a requested policy: empty when it is one of the four policies. */
+export function euUkVisitorPolicyViolations(value: unknown): TenantAnalyticsFinding[] {
+  if (isEuUkVisitorPolicy(value)) return [];
+  return tenantAnalyticsDeclarationFindings(JSON.stringify({ [POLICY_KEY]: value ?? 0, destinations: [] }));
+}
+
+interface Member {
+  key: string;
+  start: number;
+  valueStart: number;
+  end: number;
+}
+
+function skipWhitespace(text: string, i: number): number {
+  while (i < text.length && /\s/.test(text[i]!)) i += 1;
+  return i;
+}
+
+function stringEnd(text: string, i: number): number {
+  let j = i + 1;
+  while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+  return j + 1;
+}
+
+function valueEnd(text: string, i: number): number {
+  if (text[i] === '"') return stringEnd(text, i);
+  if (text[i] === "{" || text[i] === "[") {
+    let depth = 0;
+    let j = i;
+    while (j < text.length) {
+      const c = text[j]!;
+      if (c === '"') {
+        j = stringEnd(text, j);
+        continue;
+      }
+      if (c === "{" || c === "[") depth += 1;
+      if (c === "}" || c === "]") depth -= 1;
+      j += 1;
+      if (depth === 0) return j;
+    }
+    return j;
+  }
+  let j = i;
+  while (j < text.length && !/[\s,}\]]/.test(text[j]!)) j += 1;
+  return j;
+}
+
+/** The top-level members of a JSON object text already known to parse, with their byte spans. */
+function topLevelMembers(text: string): { open: number; close: number; members: Member[] } {
+  const open = skipWhitespace(text, 0);
+  const members: Member[] = [];
+  let i = skipWhitespace(text, open + 1);
+  while (text[i] === '"') {
+    const keyEnd = stringEnd(text, i);
+    const key = JSON.parse(text.slice(i, keyEnd)) as string;
+    const valueStart = skipWhitespace(text, skipWhitespace(text, keyEnd) + 1);
+    const end = valueEnd(text, valueStart);
+    members.push({ key, start: i, valueStart, end });
+    i = skipWhitespace(text, end);
+    if (text[i] === ",") i = skipWhitespace(text, i + 1);
+  }
+  return { open, close: i, members };
+}
+
+export type PolicyEdit =
+  | { ok: true; changed: false }
+  | { ok: true; changed: true; text: string }
+  | { ok: false; violations: TenantAnalyticsFinding[] };
+
+/**
+ * Rewrite `analytics.json` so its `euUkVisitors` is `policy`, changing no other byte. An absent file
+ * gains a minimal valid declaration only when the policy is not the `ask` default. The result is
+ * validated as a whole file; a file the publish validator would refuse is returned as violations.
+ */
+export function editEuUkVisitorPolicy(text: string | null, policy: unknown): PolicyEdit {
+  const requested = euUkVisitorPolicyViolations(policy);
+  if (requested.length > 0) return { ok: false, violations: requested };
+  const next = policy as EuUkVisitorPolicy;
+  if (readEuUkVisitorPolicy(text) === next) return { ok: true, changed: false };
+
+  let updated: string;
+  if (text === null) {
+    updated = `${JSON.stringify({ schemaVersion: TENANT_ANALYTICS_SCHEMA_VERSION, [POLICY_KEY]: next, destinations: [] }, null, 2)}\n`;
+  } else {
+    const current = readEuUkVisitorPolicy(text);
+    if (current === null && tenantAnalyticsDeclarationFindings(text).some((f) => f.path === "(root)")) {
+      return { ok: false, violations: tenantAnalyticsDeclarationFindings(text) };
+    }
+    updated = rewrite(text, next);
+  }
+  const findings = tenantAnalyticsDeclarationFindings(updated);
+  if (findings.length > 0) return { ok: false, violations: findings };
+  return { ok: true, changed: true, text: updated };
+}
+
+function rewrite(text: string, policy: EuUkVisitorPolicy): string {
+  const { open, close, members } = topLevelMembers(text);
+  const index = members.findIndex((m) => m.key === POLICY_KEY);
+  const literal = JSON.stringify(policy);
+  if (index >= 0) {
+    const member = members[index]!;
+    if (policy !== "ask") return text.slice(0, member.valueStart) + literal + text.slice(member.end);
+    const following = members[index + 1];
+    if (following) return text.slice(0, member.start) + text.slice(following.start);
+    const previous = members[index - 1];
+    if (previous) return text.slice(0, previous.end) + text.slice(member.end);
+    return text.slice(0, open + 1) + text.slice(close);
+  }
+  const first = members[0];
+  if (!first) return `${text.slice(0, open + 1)}"${POLICY_KEY}": ${literal}${text.slice(close)}`;
+  const separator = text.slice(open + 1, first.start);
+  return `${text.slice(0, first.start)}"${POLICY_KEY}": ${literal},${separator}${text.slice(first.start)}`;
+}

package/apps/storefront/src/lib/measurement/admin/analyticsRegionsClient.ts

@@ -0,0 +1,84 @@
+/**
+ * Client-side wiring for the Visitor regions card on `/admin/consent` (ADR 0013 client-island
+ * pattern). Reads and saves the EU/UK visitor policy through `GET`/`POST /api/admin/analytics-regions`;
+ * a save opens a preview change, so the status line says the live site changes only once it is
+ * published.
+ */
+
+interface RegionsRead {
+  ok: boolean;
+  euUkVisitors?: string;
+  pending?: boolean;
+  message?: string;
+}
+
+interface RegionsSave {
+  ok: boolean;
+  status?: string;
+  message?: string;
+  url?: string;
+  violations?: { message: string }[];
+}
+
+/** Wire the card. A no-op when the page did not render it. */
+export function initAnalyticsRegionsCard(apiPath: string): void {
+  const form = document.getElementById("regions-form") as HTMLFormElement | null;
+  const statusEl = document.getElementById("regions-status");
+  if (!form || !statusEl) return;
+
+  function setStatus(text: string, tone: "ok" | "error" | null): void {
+    statusEl!.textContent = text;
+    if (tone) statusEl!.setAttribute("data-tone", tone);
+    else statusEl!.removeAttribute("data-tone");
+  }
+
+  function select(policy: string): void {
+    const input = form!.querySelector<HTMLInputElement>(`input[name="euUkVisitors"][value="${policy}"]`);
+    if (input) input.checked = true;
+  }
+
+  async function load(): Promise<void> {
+    try {
+      const res = await fetch(apiPath, { headers: { accept: "application/json" } });
+      const data = (await res.json()) as RegionsRead;
+      if (!data.ok) {
+        setStatus(data.message || "Could not read analytics.json.", "error");
+        return;
+      }
+      select(data.euUkVisitors ?? "ask");
+      form!.setAttribute("data-loaded", "true");
+      setStatus(data.pending ? "A change is waiting in preview." : "", null);
+    } catch {
+      setStatus("Could not read analytics.json.", "error");
+    }
+  }
+  void load();
+
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    const choice = form.querySelector<HTMLInputElement>('input[name="euUkVisitors"]:checked')?.value ?? "ask";
+    const button = form.querySelector<HTMLButtonElement>("button.save");
+    if (button) button.disabled = true;
+    setStatus("Saving…", null);
+    try {
+      const res = await fetch(apiPath, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ euUkVisitors: choice }),
+      });
+      const data = (await res.json()) as RegionsSave;
+      if (!data.ok) {
+        const detail = data.violations?.map((v) => v.message).join(" ") ?? "";
+        setStatus(`${data.message || "Save failed."} ${detail}`.trim(), "error");
+      } else if (data.status === "unchanged") {
+        setStatus("No change: that is already the setting.", "ok");
+      } else {
+        setStatus("Saved to preview. The live site changes when you publish.", "ok");
+      }
+    } catch {
+      setStatus("Save failed: network error.", "error");
+    } finally {
+      if (button) button.disabled = false;
+    }
+  });
+}

package/apps/storefront/test/pipeline/publish-kinds.ts

@@ -40,13 +40,17 @@ type PointerRecord = Awaited<ReturnType<PointerWriter["read"]>>;
  * Production's ratios, in seconds: a CI window (45 min) outlasts the lease an evicted object waits
  * out before it resumes (10 min, here `leaseMs`), so a job resumed after an eviction is still inside
  * its window — as in production.
+ *
+ * A hotfix's stage window ends the job `stuck` when it expires, and the fault matrix answers the
+ * prebuild from a poll loop that a loaded host starves for several seconds at a time (a 30 ms sleep
+ * measured at 4–8 s on an oversubscribed machine). The window is sized well past that stall.
  */
 export const PUBLISH_HARNESS_TIMING: PublishTiming = {
   awaitWindowMs: 4_000,
   runGraceMs: 500,
   proofDelayMs: 30,
   proofProbes: { synchronous: 3, asynchronous: 5 },
-  stageWindowMs: 4_000,
+  stageWindowMs: 15_000,
   stageChecks: 3,
 };
 

package/apps/storefront/test/pipeline-faults/matrix-lib.ts

@@ -150,7 +150,7 @@ async function cloudFrontServesEarlier(t: Tenant, provider: Provider): Promise<v
 async function prerequisite(t: Tenant, kind: string, input: unknown): Promise<void> {
   const jobId = await t.submit(kind, input);
   const { job } = await drive(t, jobId);
-  if (job.state !== "succeeded") throw new Error(`setup ${kind} ended ${job.state}: ${JSON.stringify(job.error)}`);
+  if (job.state !== "succeeded") throw new Error(`setup ${kind} ended ${job.state}: ${JSON.stringify(job.error)} outcome: ${outcomeOf(job)}`);
 }
 
 async function goLive(t: Tenant, provider: Provider, sha: string, runId: string): Promise<void> {
@@ -578,6 +578,17 @@ export function overlapViolations(all: TransitionView[]): string[] {
   return [];
 }
 
+/**
+ * What the job's own outcome says about why it ended (a `JobEnded` error's reason only points at
+ * it): its reason code and message, or null when the job recorded none.
+ */
+export function outcomeOf(job: JobView): string | null {
+  const outcome = job.produces?.outcome as { reason?: unknown; message?: unknown } | undefined;
+  if (!outcome || typeof outcome !== "object") return null;
+  const parts = [outcome.reason, outcome.message].filter((p): p is string => typeof p === "string" && p.length > 0);
+  return parts.length ? parts.join(": ") : JSON.stringify(outcome);
+}
+
 function diffKeys(a: Record<string, unknown>, b: Record<string, unknown>, keys: string[]): string[] {
   return keys.filter((k) => JSON.stringify(a[k]) !== JSON.stringify(b[k]));
 }
@@ -615,7 +626,10 @@ export function convergence(cell: CellRun, base: CellRun, opts: ConvergenceOptio
   const v: string[] = [];
   const { job } = cell;
   if (job.state !== base.job.state || job.error?.code !== base.job.error?.code) {
-    v.push(`verdict: ${job.state}${job.error ? ` (${job.error.code}: ${job.error.reason})` : ""}, unfaulted ${base.job.state}`);
+    const outcome = outcomeOf(job);
+    v.push(
+      `verdict: ${job.state}${job.error ? ` (${job.error.code}: ${job.error.reason})` : ""}${outcome ? ` outcome: ${outcome}` : ""}, unfaulted ${base.job.state}`,
+    );
   }
   if (opts.expectKill && cell.kills.length === 0) v.push("fired: the armed fault never fired");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.9.3",
+  "version": "4.10.0",
   "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/consent-broker.ts

@@ -30,6 +30,7 @@ import { CONSENT_PURPOSES, type ConsentPurpose } from "../integration-capabiliti
 import { CONSENT_SNAPSHOT_SCHEMA_VERSION } from "./version.js";
 import type { EventConsentSnapshot } from "./events.js";
 import type { EuUkVisitorPolicy } from "./plan.js";
+import { schedulePostPaint, type PostPaintWindow } from "./post-paint.js";
 
 /** The purpose that is always on and cannot be gated (charter floor). */
 const ESSENTIAL: ConsentPurpose = "essential";
@@ -479,8 +480,10 @@ export class ConsentBroker {
  * The tenant configuration supplies the analytics default and a stored viewer choice
  * overrides it. Global Privacy Control always denies analytics. Visitors the edge
  * classes as EU/EEA/UK/CH, or cannot class, get the tenant's EU/UK visitor policy:
- * `count-only` (default) keeps page views but stores nothing on the device, `none`
- * denies analytics, and `full` applies the default behavior. The same synchronous
+ * `ask` (default) counts page views without storing anything and prompts the visitor,
+ * and an Allow lifts the restriction for this context; `count-only` keeps page views
+ * but stores nothing on the device; `none` denies analytics; and `full` applies the
+ * default behavior. The same synchronous
  * early boot runs in both document mounts before any integration or measurement loader
  * can execute.
  */
@@ -515,6 +518,16 @@ export interface ViewerAnalyticsConsentState {
    * visitor-continuity storage reads this and falls back to a per-page memory id.
    */
   visitorStorage: "persistent" | "none";
+  /**
+   * Whether the EU/UK visitor policy currently restricts this visitor: no device
+   * storage, no marketing or personalization, and no tenant-local code.
+   */
+  regionRestricted: boolean;
+  /**
+   * `pending` when the `ask` policy applies and the visitor has not decided; the
+   * control then opens itself after paint. `none` otherwise.
+   */
+  prompt: "pending" | "none";
   tenantPublicId: string;
   environment: string;
   siteSurface: string;
@@ -616,18 +629,31 @@ export function applyEarlyViewerAnalyticsConsent(
 
   // The edge sets a class-only `tot_rgn` cookie on every HTML response
   // (visitor-region.mjs). An absent or unreadable class is unknown, and unknown gets
-  // the EU/UK policy until the region is known.
+  // the EU/UK policy until the region is known. Several `tot_rgn` cookies that disagree
+  // (one planted with another Domain or Path beside the edge's) are unknown too, so a
+  // planted class can never widen the edge's.
   let regionClass = "u";
   try {
-    const regionMatch = /(?:^|;\s*)tot_rgn=(eu|x|u)(?:;|$)/.exec(String(win.document?.cookie ?? ""));
-    if (regionMatch) regionClass = regionMatch[1] as string;
+    const regionClasses: string[] = [];
+    for (const part of String(win.document?.cookie ?? "").split(";")) {
+      const separator = part.indexOf("=");
+      if (separator !== -1 && part.slice(0, separator).trim() === "tot_rgn") regionClasses.push(part.slice(separator + 1).trim());
+    }
+    const firstClass = regionClasses[0];
+    if (
+      (firstClass === "eu" || firstClass === "x" || firstClass === "u") &&
+      regionClasses.every((candidate) => candidate === firstClass)
+    ) {
+      regionClass = firstClass;
+    }
   } catch {
     // An unreadable cookie jar leaves the region unknown.
   }
+  // An absent or unrecognized policy is `ask`: it never widens collection.
   const euUkVisitors: EuUkVisitorPolicy =
-    plan?.euUkVisitors === "full" || plan?.euUkVisitors === "none" ? plan.euUkVisitors : "count-only";
-  const regionRestricted = regionClass !== "x" && euUkVisitors !== "full";
-  const regionDeniesAnalytics = regionRestricted && euUkVisitors === "none";
+    plan?.euUkVisitors === "count-only" || plan?.euUkVisitors === "full" || plan?.euUkVisitors === "none"
+      ? plan.euUkVisitors
+      : "ask";
 
   let stored: { decision: ViewerAnalyticsConsentDecision; expiresAt: number } | null = null;
   // A stored record that is present but unreadable may have been a denial, so it denies
@@ -679,8 +705,19 @@ export function applyEarlyViewerAnalyticsConsent(
     }
   }
 
+  // Under `ask`, a visitor's own Allow for this exact context lifts the restriction.
+  const regionSensitive = regionClass !== "x";
+  const askUpgraded =
+    euUkVisitors === "ask" && stored?.decision === "granted" && !globalPrivacyControl && tenantApprovedAnalytics;
+  const regionRestricted = regionSensitive && euUkVisitors !== "full" && !askUpgraded;
+  const regionDeniesAnalytics = regionRestricted && euUkVisitors === "none";
+  // Until the visitor allows, `ask` counts page views exactly as `count-only` does; a
+  // Decline, a Close or no answer leaves it there.
+  const askRestricted = regionRestricted && euUkVisitors === "ask";
+
   const decision: ViewerAnalyticsConsentDecision =
-    globalPrivacyControl || !tenantApprovedAnalytics || regionDeniesAnalytics || (!stored && storedInvalid)
+    globalPrivacyControl || !tenantApprovedAnalytics || regionDeniesAnalytics || askRestricted ||
+      (!stored && storedInvalid)
       ? "denied"
       : stored?.decision ?? (tenantDefaultAnalytics ? "granted" : "denied");
   const source: ViewerAnalyticsConsentState["source"] = globalPrivacyControl
@@ -691,9 +728,12 @@ export function applyEarlyViewerAnalyticsConsent(
       ? "stored"
       : storedInvalid
         ? "stored-invalid"
-        : tenantDefaultAnalytics
-          ? "tenant-default"
-          : "default-deny";
+        : askRestricted
+          ? "eu-uk-policy"
+          : tenantDefaultAnalytics
+            ? "tenant-default"
+            : "default-deny";
+  const prompt = askRestricted && !stored && !globalPrivacyControl && tenantApprovedAnalytics ? "pending" : "none";
 
   // Under the EU/UK policy, marketing and personalization never run: neither can work
   // without storing an identifier on the device.
@@ -701,7 +741,9 @@ export function applyEarlyViewerAnalyticsConsent(
     (purpose) =>
       purpose === "essential" ||
       (purpose === "analytics"
-        ? decision === "granted" && tenantApprovedAnalytics
+        ? askRestricted
+          ? tenantDefaultAnalytics && !globalPrivacyControl
+          : decision === "granted" && tenantApprovedAnalytics
         : !regionRestricted && rawEligible.includes(purpose)),
   );
   const approved = canonicalPurposes.filter((purpose) => rawApproved.includes(purpose));
@@ -735,6 +777,8 @@ export function applyEarlyViewerAnalyticsConsent(
     region: regionClass === "eu" ? "eu-uk" : regionClass === "x" ? "other" : "unknown",
     euUkVisitors,
     visitorStorage,
+    regionRestricted,
+    prompt,
     tenantPublicId,
     environment,
     siteSurface,
@@ -820,22 +864,33 @@ export function setViewerAnalyticsConsent(
 
 function renderControlState(root: HTMLElement, state: ViewerAnalyticsConsentState): void {
   const status = root.querySelector<HTMLElement>("[data-tot-analytics-consent-status]");
+  const detail = root.querySelector<HTMLElement>("[data-tot-analytics-consent-detail]");
   const grant = root.querySelector<HTMLButtonElement>('[data-tot-analytics-consent-decision="granted"]');
   const deny = root.querySelector<HTMLButtonElement>('[data-tot-analytics-consent-decision="denied"]');
+  const countingOnly = state.regionRestricted && state.euUkVisitors === "ask" && state.canGrant;
   if (status) {
     status.textContent = state.source === "global-privacy-control"
       ? "Analytics off — Global Privacy Control"
       : state.decision === "granted"
         ? "Analytics on"
-        : "Analytics off";
+        : countingOnly
+          ? "Page counts only"
+          : "Analytics off";
+  }
+  if (detail) {
+    detail.textContent = countingOnly
+      ? "Page views are counted without storing anything on this device. Allow analytics to remember this device between visits."
+      : "Choose whether analytics may run on this site.";
   }
   if (grant) {
     grant.disabled = !state.canGrant || state.decision === "granted";
     grant.setAttribute("aria-pressed", String(state.decision === "granted"));
   }
   if (deny) {
-    deny.disabled = state.decision === "denied";
-    deny.setAttribute("aria-pressed", String(state.decision === "denied"));
+    // A visitor counted under `ask` has not declined until they say so.
+    const declined = state.decision === "denied" && (!countingOnly || state.source === "stored");
+    deny.disabled = declined;
+    deny.setAttribute("aria-pressed", String(declined));
   }
 }
 
@@ -844,7 +899,7 @@ function firstEnabledButton(root: HTMLElement): HTMLButtonElement | null {
 }
 
 /**
- * Bind each persistent "Analytics choices" disclosure to the control its
+ * Bind each tenant Privacy Policy "Analytics choices" disclosure to the control its
  * `aria-controls` names: a click opens the control and moves focus into it; a second
  * click, the control's Close button, or Escape inside it closes it again, and the
  * latter two return focus to the toggle.
@@ -882,6 +937,38 @@ function bindViewerAnalyticsChoicesToggles(win: ViewerConsentWindow): void {
   });
 }
 
+/** Show or hide a control and keep every disclosure that names it in step. */
+function setControlVisible(win: ViewerConsentWindow, root: HTMLElement, visible: boolean): void {
+  root.hidden = !visible;
+  if (!root.id) return;
+  win.document?.querySelectorAll<HTMLElement>("[data-tot-analytics-choices-toggle]").forEach((toggle) => {
+    if (toggle.getAttribute("aria-controls") === root.id) toggle.setAttribute("aria-expanded", String(visible));
+  });
+}
+
+/**
+ * Open each control for a visitor the `ask` policy has not heard from. It runs after
+ * paint and idle so it never delays the page, and the control is a fixed overlay so it
+ * shifts no layout. Focus stays where the visitor left it.
+ */
+function scheduleViewerAnalyticsPrompt(
+  win: ViewerConsentWindow,
+  roots: NodeListOf<HTMLElement> | undefined,
+  state: ViewerAnalyticsConsentState,
+): void {
+  if (state.prompt !== "pending" || !roots || roots.length === 0) return;
+  if (typeof win["setTimeout"] !== "function" || typeof win.addEventListener !== "function") return;
+  schedulePostPaint(win as unknown as PostPaintWindow, () => {
+    const latest = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined;
+    if (latest?.prompt !== "pending") return;
+    roots.forEach((root) => {
+      renderControlState(root, latest);
+      root.dataset["totAnalyticsConsentPrompted"] = "true";
+      setControlVisible(win, root, true);
+    });
+  });
+}
+
 /** Bind the renderer-owned control once; safe when a document contains no analytics plan. */
 export function bootViewerAnalyticsConsentControl(
   win: ViewerConsentWindow,
@@ -897,15 +984,28 @@ export function bootViewerAnalyticsConsentControl(
     root.addEventListener("click", (event) => {
       const target = event.target;
       if (!(target instanceof Element)) return;
+      // Close records nothing, so an unanswered prompt returns on the next page.
+      if (target.closest("[data-tot-analytics-consent-close]")) {
+        delete root.dataset["totAnalyticsConsentPrompted"];
+        setControlVisible(win, root, false);
+        return;
+      }
       const button = target.closest<HTMLButtonElement>("[data-tot-analytics-consent-decision]");
       const decision = button?.dataset["totAnalyticsConsentDecision"];
       if (decision !== "granted" && decision !== "denied") return;
       renderControlState(root, setViewerAnalyticsConsent(win, decision, now()));
+      // An answered prompt goes away; the disclosure reopens the control on demand.
+      if (root.dataset["totAnalyticsConsentPrompted"] === "true") {
+        delete root.dataset["totAnalyticsConsentPrompted"];
+        setControlVisible(win, root, false);
+        return;
+      }
       // The pressed button is now disabled; keep keyboard focus inside the control.
       if (button?.disabled) firstEnabledButton(root)?.focus();
     });
   });
   bindViewerAnalyticsChoicesToggles(win);
+  scheduleViewerAnalyticsPrompt(win, roots, current);
 
   const storageBoundGlobal = "__TOT_VIEWER_ANALYTICS_CONSENT_STORAGE_BOUND__";
   if (win.addEventListener && win[storageBoundGlobal] !== true) {

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

@@ -57,8 +57,9 @@ import { INTEGRATION_ENVIRONMENTS, INTEGRATION_SITE_SURFACES } from "./environme
 import type { IntegrationEnvironment, IntegrationSiteSurface } from "./environment.js";
 import { findForbiddenFields } from "./secrets.js";
 import {
+  MANAGED_ANALYTICS_CAMPAIGN_FIELDS,
   resemblesManagedAnalyticsPii,
-  resemblesManagedAnalyticsProtectedValue,
+  screenManagedAnalyticsCampaign,
 } from "./managed-analytics-value-safety.js";
 
 /**
@@ -349,8 +350,6 @@ function validateLineItems(parent: Record<string, unknown>, v: Violations, path:
   });
 }
 
-const UTM_FIELDS = ["source", "medium", "campaign", "term", "content"] as const;
-const SAFE_UTM_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
 function validatePageAttribution(parent: Record<string, unknown>, v: Violations): void {
   const attribution = childObject(parent, "attribution", v, "data");
   if (!attribution) return;
@@ -389,27 +388,24 @@ function validatePageAttribution(parent: Record<string, unknown>, v: Violations)
   if ("utm" in attribution) {
     const utm = childObject(attribution, "utm", v, "data.attribution");
     if (utm) {
-      rejectUnknownKeys(utm, UTM_FIELDS, v, "data.attribution.utm");
+      rejectUnknownKeys(utm, MANAGED_ANALYTICS_CAMPAIGN_FIELDS, v, "data.attribution.utm");
       if (Object.keys(utm).length === 0) {
         v.add("data.attribution.utm", "empty", "UTM must contain at least one allowlisted field.");
       }
-      for (const key of UTM_FIELDS) {
+      const strings: Record<string, string> = {};
+      for (const key of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
         if (!(key in utm)) continue;
         const value = reqString(utm, key, v, "data.attribution.utm");
-        if (value !== undefined && !SAFE_UTM_VALUE.test(value)) {
-          v.add(
-            `data.attribution.utm.${key}`,
-            "format",
-            `UTM ${key} must be a 1-128 character opaque campaign token.`,
-          );
-        }
-        if (value !== undefined && resemblesManagedAnalyticsProtectedValue(value)) {
-          v.add(
-            `data.attribution.utm.${key}`,
-            "protected_value",
-            `UTM ${key} resembles PII or protected material and must not be emitted.`,
-          );
-        }
+        if (value !== undefined) strings[key] = value;
+      }
+      for (const { field, reason } of screenManagedAnalyticsCampaign(strings).rejected) {
+        v.add(
+          `data.attribution.utm.${field}`,
+          reason,
+          reason === "format"
+            ? `UTM ${field} must be a 1-128 character opaque campaign token.`
+            : `UTM ${field} resembles PII or protected material and must not be emitted.`,
+        );
       }
     }
   }

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

@@ -56,6 +56,7 @@ export * from "./manifest.js";
 export * from "./plan.js";
 export * from "./resolve.js";
 export * from "./platform-adapters.js";
+export * from "./tenant-analytics.js";
 export * from "./native-amplitude.js";
 export * from "./native-ga4.js";
 export * from "./native-ga4-sandbox.js";