From 0dea85166c10edcb2823b418d03b1d233dd49295 Mon Sep 17 00:00:00 2001
From: Gautam Ahuja <gautamahuja1909@gmail.com>
Date: Mon, 7 Sep 2026 01:56:21 +0530
Subject: [PATCH 1/2] feat(consent): gate host-side visitor recognition on
 cookieTracking consent

Adds `cookieTracking` as a third category of `SurfaceSetConsent`, mirroring
the new Cookie Tracking privacy control in Forms (trysurface/surface_forms#5811).
Every call is a complete snapshot, so an older two-field call denies cookies.

Pages that load the tag with `data-consent-mode` get a tag that does no
visitor recognition until that category is granted: no identify or
fingerprint, no `surfaceLeadData` cache read/write, no journey cookies or
page-view beacons, and an empty cookie snapshot in STORE_UPDATE. A grant
starts all of it; withdrawal clears the journey cookies and lead cache.
Frames still receive their handshake so forms render and submit as before.

Without the attribute nothing changes for existing installs.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                          |  16 +++-
 README.md                          |  21 +++++
 src/consent/consent.test.ts        |   8 ++
 src/consent/consent.ts             |  18 +++--
 src/index.ts                       |   4 +-
 src/lead/identify.ts               |   4 +
 src/runtime-config.ts              |  10 ++-
 src/store/message-listener.test.ts |  14 ++++
 src/store/message-listener.ts      |   2 +-
 src/store/store.test.ts            |  79 +++++++++++++++++-
 src/store/store.ts                 | 123 +++++++++++++++++++----------
 surface_embed_v1.js                | 116 +++++++++++++++++++--------
 surface_tag.js                     | 116 +++++++++++++++++++--------
 test/consent.html                  |   4 +
 test/consent.js                    |  12 ++-
 15 files changed, 419 insertions(+), 128 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index cdc3614..85a63f7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -87,15 +87,23 @@ Forms whose Privacy settings put a category on "On consent" load no scripts for
 it until the host page reports the visitor's answer:
 
 ```js
-window.SurfaceSetConsent({ adTracking: true, surfaceAnalytics: true });
+window.SurfaceSetConsent({ adTracking: true, surfaceAnalytics: true, cookieTracking: true });
 ```
 
 `consent.ts` holds the answer in module state and notifies `src/index.ts`, which
 relays `surface:consent` to every Surface iframe (and re-sends it on each
 `SEND_DATA` handshake, for forms that mount after the banner was answered).
-Omitted categories count as not granted. The categories mirror the form-render
-gate in `surface_forms` (`lib/client/thirdParty/`) — keep the message shape in
-sync with its `hostConsent.ts`.
+Every call is a complete snapshot: omitted categories count as not granted. The
+categories mirror the form-render gate in `surface_forms`
+(`lib/client/thirdParty/`) — keep the message shape in sync with its
+`hostConsent.ts`.
+
+`cookieTracking` also gates the tag's own host-side work, but only when the
+`<script>` carries `data-consent-mode` (read in `runtime-config.ts`). Until that
+page grants it, `SurfaceStore` skips identify, the `surfaceLeadData` cache, the
+journey cookies and forwards an empty cookie snapshot; `applyConsent()` starts
+them on a grant and clears them on withdrawal. Without the attribute nothing
+changes for existing installs.
 
 ### Key APIs
 
diff --git a/README.md b/README.md
index ff03381..8bf4bd1 100644
--- a/README.md
+++ b/README.md
@@ -68,3 +68,24 @@ See [docs](https://docs.withsurface.com/docs/surface-tag/installation) for integ
 3. Identity API call completes in <0.5s on slow 4G; no issues if blocked/failed
 4. PostMessage to iframe: query params, prefilled email, cookies, URL/origin/referrer
 5. Form loading speed on withsurface.com
+
+## Cookie consent
+
+Pages that run a consent banner load the tag with `data-consent-mode` and report
+the visitor's answer, in full, on every load and every change:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/.../surface_tag.min.js"
+  site-id="your-environment-id"
+  data-consent-mode>
+</script>
+<script>
+  window.SurfaceSetConsent({ adTracking: true, surfaceAnalytics: true, cookieTracking: true });
+</script>
+```
+
+With the attribute, the tag does no visitor recognition, sets no journey cookies
+and forwards no page cookies to Surface forms until `cookieTracking` is granted.
+Form rendering and submission work regardless. Without the attribute the tag
+behaves exactly as before. See `CLAUDE.md` for the message contract.
diff --git a/src/consent/consent.test.ts b/src/consent/consent.test.ts
index 579d449..acd4bb6 100644
--- a/src/consent/consent.test.ts
+++ b/src/consent/consent.test.ts
@@ -20,9 +20,16 @@ describe("surface consent", () => {
     expect(getSurfaceConsent()).toEqual({
       adTracking: true,
       surfaceAnalytics: false,
+      cookieTracking: false,
     });
   });
 
+  it("treats each answer as a complete snapshot, so an older two-field call denies cookies", () => {
+    setSurfaceConsent({ adTracking: true, surfaceAnalytics: true, cookieTracking: true });
+    setSurfaceConsent({ adTracking: true, surfaceAnalytics: true });
+    expect(getSurfaceConsent()?.cookieTracking).toBe(false);
+  });
+
   it("ignores non-boolean values", () => {
     setSurfaceConsent({ adTracking: "yes" as unknown as boolean });
     expect(getSurfaceConsent()?.adTracking).toBe(false);
@@ -34,6 +41,7 @@ describe("surface consent", () => {
     expect(getSurfaceConsent()).toEqual({
       adTracking: false,
       surfaceAnalytics: true,
+      cookieTracking: false,
     });
   });
 
diff --git a/src/consent/consent.ts b/src/consent/consent.ts
index 9c8f39c..2c537c8 100644
--- a/src/consent/consent.ts
+++ b/src/consent/consent.ts
@@ -3,13 +3,18 @@
 export const SURFACE_CONSENT_MESSAGE_TYPE = "surface:consent";
 
 /**
- * Categories of third-party calls a Surface form can be told to wait for. They
+ * Categories of optional tracking a Surface form can be told to wait for. They
  * mirror the form's Privacy settings: a category set to "On consent" there stays
  * off until this page reports it as granted.
+ *
+ * `cookieTracking` also gates this tag's own host-side work — visitor
+ * recognition, the journey cookies and forwarding the page's cookies — when the
+ * script is loaded with `data-consent-mode`.
  */
 export interface SurfaceConsent {
   adTracking: boolean;
   surfaceAnalytics: boolean;
+  cookieTracking: boolean;
 }
 
 let consent: SurfaceConsent | null = null;
@@ -23,19 +28,22 @@ export const onSurfaceConsentChange = (callback: () => void): void => {
 };
 
 /**
- * Public API — call from a consent banner once the visitor answers:
+ * Public API — call from a consent banner once the visitor answers, and again
+ * whenever the answer changes:
  *
  * ```js
- * window.SurfaceSetConsent({ adTracking: true, surfaceAnalytics: true });
+ * window.SurfaceSetConsent({ adTracking: true, surfaceAnalytics: true, cookieTracking: true });
  * ```
  *
- * Omitted categories count as not granted. Calling again with `false` stops
- * further tracking, but cannot unload vendor scripts a form already started.
+ * Every call is a complete snapshot: omitted categories count as not granted.
+ * Calling again with `false` stops further tracking, but cannot unload vendor
+ * scripts a form already started.
  */
 export const setSurfaceConsent = (granted: Partial<SurfaceConsent>): void => {
   consent = {
     adTracking: granted?.adTracking === true,
     surfaceAnalytics: granted?.surfaceAnalytics === true,
+    cookieTracking: granted?.cookieTracking === true,
   };
   onChange?.();
 };
diff --git a/src/index.ts b/src/index.ts
index 521ecf2..0d1fca2 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -34,8 +34,10 @@ w.SurfaceSetConsent = setSurfaceConsent;
 
 // Relay a consent answer to the forms on the page. The store push goes with it
 // so a form that was blocked until now still gets the parent URL params it
-// needs to fire conversions in first-party context.
+// needs to fire conversions in first-party context. Under data-consent-mode the
+// tag's own recognition and journey work start or stop here too.
 onSurfaceConsentChange(() => {
+  SurfaceTagStore.applyConsent();
   SurfaceTagStore.sendConsentToIframes();
   SurfaceTagStore.sendPayloadToIframes("STORE_UPDATE");
 });
diff --git a/src/lead/identify.ts b/src/lead/identify.ts
index b2b4c28..eb1278e 100644
--- a/src/lead/identify.ts
+++ b/src/lead/identify.ts
@@ -29,6 +29,10 @@ export function setLeadDataWithTTL(data: Omit<LeadData, "expiry">): void {
   localStorage.setItem("surfaceLeadData", JSON.stringify(item));
 }
 
+export function clearLeadData(): void {
+  localStorage.removeItem("surfaceLeadData");
+}
+
 export function getLeadDataWithTTL(): LeadData | null {
   const itemStr = localStorage.getItem("surfaceLeadData");
   if (!itemStr) return null;
diff --git a/src/runtime-config.ts b/src/runtime-config.ts
index 2c36beb..dacfc05 100644
--- a/src/runtime-config.ts
+++ b/src/runtime-config.ts
@@ -6,6 +6,10 @@ import {
 } from "./constants";
 
 export const CUSTOM_DOMAIN_ATTRIBUTE = "data-custom-domain";
+// Present on the <script> when the page's cookie banner will call
+// SurfaceSetConsent: the tag then does no visitor recognition, journey cookies
+// or cookie forwarding until `cookieTracking` is granted.
+export const CONSENT_MODE_ATTRIBUTE = "data-consent-mode";
 
 export interface SurfaceRuntimeConfig {
   apiBaseUrl: string;
@@ -13,6 +17,7 @@ export interface SurfaceRuntimeConfig {
   userJourneyTrackingApi: string;
   surfaceDomains: readonly string[];
   customOrigin: string | null;
+  waitForCookieConsent: boolean;
 }
 
 export const DEFAULT_SURFACE_RUNTIME_CONFIG: SurfaceRuntimeConfig = {
@@ -21,6 +26,7 @@ export const DEFAULT_SURFACE_RUNTIME_CONFIG: SurfaceRuntimeConfig = {
   userJourneyTrackingApi: USER_JOURNEY_TRACKING_API,
   surfaceDomains: SURFACE_DOMAINS,
   customOrigin: null,
+  waitForCookieConsent: false,
 };
 
 let runtimeConfig = DEFAULT_SURFACE_RUNTIME_CONFIG;
@@ -51,10 +57,11 @@ function normalizeCustomOrigin(value: string): string | null {
 export function resolveSurfaceRuntimeConfig(
   scriptElement: HTMLScriptElement | null
 ): SurfaceRuntimeConfig {
+  const waitForCookieConsent = scriptElement?.hasAttribute(CONSENT_MODE_ATTRIBUTE) ?? false;
   const customOrigin = normalizeCustomOrigin(
     scriptElement?.getAttribute(CUSTOM_DOMAIN_ATTRIBUTE) ?? ""
   );
-  if (!customOrigin) return DEFAULT_SURFACE_RUNTIME_CONFIG;
+  if (!customOrigin) return { ...DEFAULT_SURFACE_RUNTIME_CONFIG, waitForCookieConsent };
 
   const apiBaseUrl = `${customOrigin}/api/v1`;
   return {
@@ -63,6 +70,7 @@ export function resolveSurfaceRuntimeConfig(
     userJourneyTrackingApi: `${apiBaseUrl}/lead/track`,
     surfaceDomains: Array.from(new Set([...SURFACE_DOMAINS, customOrigin])),
     customOrigin,
+    waitForCookieConsent,
   };
 }
 
diff --git a/src/store/message-listener.test.ts b/src/store/message-listener.test.ts
index 657387e..01151d7 100644
--- a/src/store/message-listener.test.ts
+++ b/src/store/message-listener.test.ts
@@ -18,6 +18,7 @@ const makeStore = () =>
     sendPayloadToIframes: vi.fn(),
     sendConsentToIframes: vi.fn(),
     clearUserJourney: vi.fn(),
+    cookieTrackingAllowed: vi.fn(() => true),
     log: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
   }) as unknown as SurfaceStore;
 
@@ -73,6 +74,19 @@ describe("initializeMessageListener", () => {
     expect(store.sendPayloadToIframes).toHaveBeenLastCalledWith("LEAD_DATA_UPDATE");
   });
 
+  it("under consent mode without a cookie grant: pushes LEAD_DATA_UPDATE immediately, never identifies", () => {
+    vi.mocked(getEnvironmentId).mockReturnValue("env_123");
+    const store = makeStore();
+    vi.mocked(store.cookieTrackingAllowed).mockReturnValue(false);
+    initializeMessageListener(store);
+
+    dispatch({ type: "SEND_DATA", sender: "surface_form" });
+
+    // Listeners from earlier cases are still attached, so only this store's pushes are asserted.
+    const types = vi.mocked(store.sendPayloadToIframes).mock.calls.map((c) => c[0]);
+    expect(types).toEqual(["STORE_UPDATE", "LEAD_DATA_UPDATE"]);
+  });
+
   it("without an environment id: pushes LEAD_DATA_UPDATE immediately, never identifies", () => {
     vi.mocked(getEnvironmentId).mockReturnValue(null);
     const store = makeStore();
diff --git a/src/store/message-listener.ts b/src/store/message-listener.ts
index a28a51e..0b831fa 100644
--- a/src/store/message-listener.ts
+++ b/src/store/message-listener.ts
@@ -21,7 +21,7 @@ export function initializeMessageListener(store: SurfaceStore): void {
       store.sendConsentToIframes();
 
       const envId = getEnvironmentId();
-      if (envId) {
+      if (envId && store.cookieTrackingAllowed()) {
         const identify = store.config?.customOrigin
           ? identifyLead(envId, store.config)
           : identifyLead(envId);
diff --git a/src/store/store.test.ts b/src/store/store.test.ts
index c53032a..9295d93 100644
--- a/src/store/store.test.ts
+++ b/src/store/store.test.ts
@@ -1,7 +1,12 @@
 import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from "vitest";
 import { SurfaceStore } from "./store";
-import { identifyLead, getLeadDataWithTTL } from "../lead/identify";
-import { initializeUserJourneyTracking, updateUserJourneyOnRouteChange } from "./user-journey";
+import { identifyLead, getLeadDataWithTTL, clearLeadData } from "../lead/identify";
+import {
+  initializeUserJourneyTracking,
+  updateUserJourneyOnRouteChange,
+  clearUserJourney,
+} from "./user-journey";
+import { DEFAULT_SURFACE_RUNTIME_CONFIG } from "../runtime-config";
 import { onRouteChange } from "../utils/route-observer";
 import type { LeadData } from "../types";
 import { setSurfaceConsent } from "../consent/consent";
@@ -13,6 +18,7 @@ vi.mock("../lead/identify", () => ({
   identifyLead: vi.fn(async () => null),
   getLeadDataWithTTL: vi.fn((): LeadData | null => null),
   isIdentifyInProgress: vi.fn(() => false),
+  clearLeadData: vi.fn(),
 }));
 vi.mock("./user-journey", () => ({
   initializeUserJourneyTracking: vi.fn(),
@@ -203,10 +209,77 @@ describe("SurfaceStore postMessage protocol", () => {
       {
         type: "surface:consent",
         sender: "surface_tag",
-        consent: { adTracking: true, surfaceAnalytics: false },
+        consent: { adTracking: true, surfaceAnalytics: false, cookieTracking: false },
       },
       "https://forms.withsurface.com"
     );
     expect(otherPost).not.toHaveBeenCalled();
   });
 });
+
+// `data-consent-mode` on the script: the page's banner owns cookie consent, so
+// the tag does no visitor recognition or journey work until it hears a grant.
+describe("SurfaceStore under data-consent-mode", () => {
+  const consentModeConfig = { ...DEFAULT_SURFACE_RUNTIME_CONFIG, waitForCookieConsent: true };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+    document.body.innerHTML = "";
+    document.cookie = "hubspotutk=abc";
+    setSurfaceConsent({});
+    addIframe(SURFACE_IFRAME_SRC);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    document.cookie = "hubspotutk=; max-age=0";
+  });
+
+  it("before a grant: no journey, no identify, no lead cache read, and an empty cookie snapshot", async () => {
+    const store = new SurfaceStore("env_123", consentModeConfig);
+    const pushes = vi.spyOn(store, "sendPayloadToIframes");
+
+    await vi.runAllTimersAsync();
+
+    expect(initializeUserJourneyTracking).not.toHaveBeenCalled();
+    expect(identifyLead).not.toHaveBeenCalled();
+    expect(getLeadDataWithTTL).not.toHaveBeenCalled();
+    // The frame still gets its handshake so it can identify without recognition.
+    expect(pushedTypes(pushes)).toEqual(["STORE_UPDATE", "LEAD_DATA_UPDATE"]);
+    expect(store.getPayload()).toMatchObject({ cookies: {}, surfaceLeadData: null, userJourneyId: null });
+  });
+
+  it("a cookie grant starts the journey, identifies and forwards cookies; withdrawal clears them again", async () => {
+    const store = new SurfaceStore("env_123", consentModeConfig);
+    await vi.runAllTimersAsync();
+
+    setSurfaceConsent({ cookieTracking: true });
+    store.applyConsent();
+    await vi.runAllTimersAsync();
+
+    expect(initializeUserJourneyTracking).toHaveBeenCalledTimes(1);
+    expect(identifyLead).toHaveBeenCalledWith("env_123");
+    expect(store.getPayload().cookies).toEqual({ hubspotutk: "abc" });
+
+    setSurfaceConsent({ cookieTracking: false });
+    store.applyConsent();
+
+    expect(clearUserJourney).toHaveBeenCalledTimes(1);
+    expect(clearLeadData).toHaveBeenCalledTimes(1);
+    expect(store.getPayload()).toMatchObject({ cookies: {}, surfaceLeadData: null });
+
+    // Route changes keep pushing the store but no longer touch the journey.
+    capturedRouteChangeCallback()("http://localhost:3000/next-page");
+    expect(updateUserJourneyOnRouteChange).not.toHaveBeenCalled();
+  });
+
+  it("without the attribute the tag behaves as before, whatever the page reports", async () => {
+    const store = new SurfaceStore("env_123");
+    await vi.runAllTimersAsync();
+
+    expect(initializeUserJourneyTracking).toHaveBeenCalledTimes(1);
+    expect(identifyLead).toHaveBeenCalledWith("env_123");
+    expect(store.getPayload().cookies).toEqual({ hubspotutk: "abc" });
+  });
+});
diff --git a/src/store/store.ts b/src/store/store.ts
index eb9a3dd..3354b1b 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -8,7 +8,7 @@ import { createLogger } from "../utils/logger";
 import { parseCookies } from "../utils/cookies";
 import { getUrlParams } from "../utils/url";
 import { onRouteChange } from "../utils/route-observer";
-import { identifyLead, getLeadDataWithTTL, isIdentifyInProgress } from "../lead/identify";
+import { identifyLead, getLeadDataWithTTL, isIdentifyInProgress, clearLeadData } from "../lead/identify";
 import { initializeMessageListener } from "./message-listener";
 import {
   initializeUserJourneyTracking,
@@ -38,6 +38,7 @@ export class SurfaceStore {
   environmentId: string | null;
   config: SurfaceRuntimeConfig;
   log: Logger;
+  private journeyStarted = false;
 
   constructor(
     environmentId: string | null = null,
@@ -56,9 +57,9 @@ export class SurfaceStore {
     this.surfaceDomains = config.surfaceDomains;
     this.userJourneyId = null;
     this.userJourney = [];
-    this.cachedIdentifyData = getLeadDataWithTTL();
     this.environmentId = environmentId;
     this.log = createLogger("Surface Store");
+    this.cachedIdentifyData = this.cookieTrackingAllowed() ? getLeadDataWithTTL() : null;
 
     initializeMessageListener(this);
 
@@ -66,19 +67,7 @@ export class SurfaceStore {
       (this.cachedIdentifyData || !isIdentifyInProgress()) &&
       !this.isCurrentOriginSurfaceDomain()
     ) {
-      initializeUserJourneyTracking(
-        this.environmentId,
-        this.log,
-        () => this.userJourneyId,
-        (id) => {
-          const resolved = !!id && id !== this.userJourneyId;
-          this.userJourneyId = id;
-          // The journey id resolves async — iframes that already received a
-          // STORE_UPDATE need a refresh to stitch this pageview.
-          if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
-        },
-        this.config
-      );
+      if (this.cookieTrackingAllowed()) this.startJourneyTracking();
       this.setupRouteChangeDetection();
     }
 
@@ -91,13 +80,11 @@ export class SurfaceStore {
     const pushInitialData = () => {
       if (!this.hasSurfaceIframe()) return;
       this.sendPayloadToIframes("STORE_UPDATE");
-      if (this.environmentId) {
-        const identify = this.config.customOrigin
-          ? identifyLead(this.environmentId, this.config)
-          : identifyLead(this.environmentId);
-        identify
-          .then(() => this.sendPayloadToIframes("LEAD_DATA_UPDATE"))
-          .catch((e) => this.log.error({ message: "Initial identify failed", error: e }));
+      if (!this.cookieTrackingAllowed()) {
+        // Nothing to recognise the visitor with; release the frame's handshake anyway.
+        this.sendPayloadToIframes("LEAD_DATA_UPDATE");
+      } else if (this.environmentId) {
+        this.identifyAndPushLeadData();
       } else if (getLeadDataWithTTL()) {
         this.sendPayloadToIframes("LEAD_DATA_UPDATE");
       }
@@ -126,24 +113,78 @@ export class SurfaceStore {
     return this.surfaceDomains.includes(origin);
   }
 
+  /**
+   * Whether this tag may recognise the visitor: read or write the lead cache,
+   * the journey cookies and the page's cookies. Always true unless the script
+   * was loaded with `data-consent-mode`, in which case the page's banner has to
+   * grant `cookieTracking` first.
+   */
+  cookieTrackingAllowed(): boolean {
+    return !this.config.waitForCookieConsent || getSurfaceConsent()?.cookieTracking === true;
+  }
+
+  /** Re-evaluates host-side tracking after the page reports a consent change. */
+  applyConsent(): void {
+    if (!this.config.waitForCookieConsent) return;
+    if (this.cookieTrackingAllowed()) {
+      if (!this.isCurrentOriginSurfaceDomain()) this.startJourneyTracking();
+      if (this.environmentId && this.hasSurfaceIframe()) this.identifyAndPushLeadData();
+      return;
+    }
+    this.clearUserJourney();
+    this.journeyStarted = false;
+    this.cachedIdentifyData = null;
+    clearLeadData();
+  }
+
+  private startJourneyTracking(): void {
+    if (this.journeyStarted) return;
+    this.journeyStarted = true;
+    initializeUserJourneyTracking(
+      this.environmentId,
+      this.log,
+      () => this.userJourneyId,
+      (id) => {
+        const resolved = !!id && id !== this.userJourneyId;
+        this.userJourneyId = id;
+        // The journey id resolves async — iframes that already received a
+        // STORE_UPDATE need a refresh to stitch this pageview.
+        if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
+      },
+      this.config
+    );
+  }
+
+  identifyAndPushLeadData(): void {
+    if (!this.environmentId) return;
+    const identify = this.config.customOrigin
+      ? identifyLead(this.environmentId, this.config)
+      : identifyLead(this.environmentId);
+    identify
+      .then(() => this.sendPayloadToIframes("LEAD_DATA_UPDATE"))
+      .catch((e) => this.log.error({ message: "Initial identify failed", error: e }));
+  }
+
   private setupRouteChangeDetection(): void {
     onRouteChange((newUrl) => {
       this.windowUrl = new URL(newUrl).toString();
 
-      updateUserJourneyOnRouteChange(
-        this.environmentId,
-        newUrl,
-        this.log,
-        () => this.userJourneyId,
-        (id) => {
-          const resolved = !!id && id !== this.userJourneyId;
-          this.userJourneyId = id;
-          // A journey created/refreshed during the route change resolves after
-          // the push below — refresh iframes so they get the new id.
-          if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
-        },
-        this.config
-      );
+      if (this.cookieTrackingAllowed()) {
+        updateUserJourneyOnRouteChange(
+          this.environmentId,
+          newUrl,
+          this.log,
+          () => this.userJourneyId,
+          (id) => {
+            const resolved = !!id && id !== this.userJourneyId;
+            this.userJourneyId = id;
+            // A journey created/refreshed during the route change resolves after
+            // the push below — refresh iframes so they get the new id.
+            if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
+          },
+          this.config
+        );
+      }
 
       this.sendPayloadToIframes("STORE_UPDATE");
 
@@ -206,18 +247,20 @@ export class SurfaceStore {
   }
 
   getPayload(): StorePayload {
+    const allowed = this.cookieTrackingAllowed();
     return {
       windowUrl: this.windowUrl,
       referrer: this.referrer,
-      cookies:
-        Object.keys(this.cookies).length === 0
+      cookies: !allowed
+        ? {}
+        : Object.keys(this.cookies).length === 0
           ? parseCookies()
           : this.cookies,
       origin: this.origin,
       questionIds: this.partialFilledData,
       urlParams: this.urlParams,
-      surfaceLeadData: getLeadDataWithTTL(),
-      userJourneyId: this.userJourneyId,
+      surfaceLeadData: allowed ? getLeadDataWithTTL() : null,
+      userJourneyId: allowed ? this.userJourneyId : null,
     };
   }
 
diff --git a/surface_embed_v1.js b/surface_embed_v1.js
index 9d14ceb..9e3afd6 100644
--- a/surface_embed_v1.js
+++ b/surface_embed_v1.js
@@ -73,12 +73,14 @@
 
   // src/runtime-config.ts
   var CUSTOM_DOMAIN_ATTRIBUTE = "data-custom-domain";
+  var CONSENT_MODE_ATTRIBUTE = "data-consent-mode";
   var DEFAULT_SURFACE_RUNTIME_CONFIG = {
     apiBaseUrl: EXTERNAL_FORM_API,
     leadIdentifyApi: LEAD_IDENTIFY_API,
     userJourneyTrackingApi: USER_JOURNEY_TRACKING_API,
     surfaceDomains: SURFACE_DOMAINS,
-    customOrigin: null
+    customOrigin: null,
+    waitForCookieConsent: false
   };
   var runtimeConfig = DEFAULT_SURFACE_RUNTIME_CONFIG;
   function normalizeCustomOrigin(value) {
@@ -95,17 +97,19 @@
     }
   }
   function resolveSurfaceRuntimeConfig(scriptElement) {
+    const waitForCookieConsent = scriptElement?.hasAttribute(CONSENT_MODE_ATTRIBUTE) ?? false;
     const customOrigin = normalizeCustomOrigin(
       scriptElement?.getAttribute(CUSTOM_DOMAIN_ATTRIBUTE) ?? ""
     );
-    if (!customOrigin) return DEFAULT_SURFACE_RUNTIME_CONFIG;
+    if (!customOrigin) return { ...DEFAULT_SURFACE_RUNTIME_CONFIG, waitForCookieConsent };
     const apiBaseUrl = `${customOrigin}/api/v1`;
     return {
       apiBaseUrl,
       leadIdentifyApi: `${apiBaseUrl}/lead/identify`,
       userJourneyTrackingApi: `${apiBaseUrl}/lead/track`,
       surfaceDomains: Array.from(/* @__PURE__ */ new Set([...SURFACE_DOMAINS, customOrigin])),
-      customOrigin
+      customOrigin,
+      waitForCookieConsent
     };
   }
   function initializeSurfaceRuntimeConfig(scriptElement) {
@@ -135,6 +139,9 @@
     };
     localStorage.setItem("surfaceLeadData", JSON.stringify(item));
   }
+  function clearLeadData() {
+    localStorage.removeItem("surfaceLeadData");
+  }
   function getLeadDataWithTTL() {
     const itemStr = localStorage.getItem("surfaceLeadData");
     if (!itemStr) return null;
@@ -227,7 +234,8 @@
   var setSurfaceConsent = (granted) => {
     consent = {
       adTracking: granted?.adTracking === true,
-      surfaceAnalytics: granted?.surfaceAnalytics === true
+      surfaceAnalytics: granted?.surfaceAnalytics === true,
+      cookieTracking: granted?.cookieTracking === true
     };
     onChange?.();
   };
@@ -514,7 +522,7 @@
         store.sendPayloadToIframes("STORE_UPDATE");
         store.sendConsentToIframes();
         const envId = getEnvironmentId();
-        if (envId) {
+        if (envId && store.cookieTrackingAllowed()) {
           const identify = store.config?.customOrigin ? identifyLead(envId, store.config) : identifyLead(envId);
           identify.then(() => store.sendPayloadToIframes("LEAD_DATA_UPDATE")).catch((e) => console.log("Failed identify", e));
         } else {
@@ -683,6 +691,7 @@
   // src/store/store.ts
   var SurfaceStore = class {
     constructor(environmentId3 = null, config = getSurfaceRuntimeConfig()) {
+      this.journeyStarted = false;
       this.windowUrl = new URL(window.location.href).toString();
       this.origin = new URL(window.location.href).origin.toString();
       this.referrer = document.referrer || "";
@@ -696,30 +705,21 @@
       this.surfaceDomains = config.surfaceDomains;
       this.userJourneyId = null;
       this.userJourney = [];
-      this.cachedIdentifyData = getLeadDataWithTTL();
       this.environmentId = environmentId3;
       this.log = createLogger("Surface Store");
+      this.cachedIdentifyData = this.cookieTrackingAllowed() ? getLeadDataWithTTL() : null;
       initializeMessageListener(this);
       if ((this.cachedIdentifyData || !isIdentifyInProgress()) && !this.isCurrentOriginSurfaceDomain()) {
-        initializeUserJourneyTracking(
-          this.environmentId,
-          this.log,
-          () => this.userJourneyId,
-          (id) => {
-            const resolved = !!id && id !== this.userJourneyId;
-            this.userJourneyId = id;
-            if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
-          },
-          this.config
-        );
+        if (this.cookieTrackingAllowed()) this.startJourneyTracking();
         this.setupRouteChangeDetection();
       }
       const pushInitialData = () => {
         if (!this.hasSurfaceIframe()) return;
         this.sendPayloadToIframes("STORE_UPDATE");
-        if (this.environmentId) {
-          const identify = this.config.customOrigin ? identifyLead(this.environmentId, this.config) : identifyLead(this.environmentId);
-          identify.then(() => this.sendPayloadToIframes("LEAD_DATA_UPDATE")).catch((e) => this.log.error({ message: "Initial identify failed", error: e }));
+        if (!this.cookieTrackingAllowed()) {
+          this.sendPayloadToIframes("LEAD_DATA_UPDATE");
+        } else if (this.environmentId) {
+          this.identifyAndPushLeadData();
         } else if (getLeadDataWithTTL()) {
           this.sendPayloadToIframes("LEAD_DATA_UPDATE");
         }
@@ -743,21 +743,65 @@
       const origin = window.location?.origin ?? "";
       return this.surfaceDomains.includes(origin);
     }
+    /**
+     * Whether this tag may recognise the visitor: read or write the lead cache,
+     * the journey cookies and the page's cookies. Always true unless the script
+     * was loaded with `data-consent-mode`, in which case the page's banner has to
+     * grant `cookieTracking` first.
+     */
+    cookieTrackingAllowed() {
+      return !this.config.waitForCookieConsent || getSurfaceConsent()?.cookieTracking === true;
+    }
+    /** Re-evaluates host-side tracking after the page reports a consent change. */
+    applyConsent() {
+      if (!this.config.waitForCookieConsent) return;
+      if (this.cookieTrackingAllowed()) {
+        if (!this.isCurrentOriginSurfaceDomain()) this.startJourneyTracking();
+        if (this.environmentId && this.hasSurfaceIframe()) this.identifyAndPushLeadData();
+        return;
+      }
+      this.clearUserJourney();
+      this.journeyStarted = false;
+      this.cachedIdentifyData = null;
+      clearLeadData();
+    }
+    startJourneyTracking() {
+      if (this.journeyStarted) return;
+      this.journeyStarted = true;
+      initializeUserJourneyTracking(
+        this.environmentId,
+        this.log,
+        () => this.userJourneyId,
+        (id) => {
+          const resolved = !!id && id !== this.userJourneyId;
+          this.userJourneyId = id;
+          if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
+        },
+        this.config
+      );
+    }
+    identifyAndPushLeadData() {
+      if (!this.environmentId) return;
+      const identify = this.config.customOrigin ? identifyLead(this.environmentId, this.config) : identifyLead(this.environmentId);
+      identify.then(() => this.sendPayloadToIframes("LEAD_DATA_UPDATE")).catch((e) => this.log.error({ message: "Initial identify failed", error: e }));
+    }
     setupRouteChangeDetection() {
       onRouteChange((newUrl) => {
         this.windowUrl = new URL(newUrl).toString();
-        updateUserJourneyOnRouteChange(
-          this.environmentId,
-          newUrl,
-          this.log,
-          () => this.userJourneyId,
-          (id) => {
-            const resolved = !!id && id !== this.userJourneyId;
-            this.userJourneyId = id;
-            if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
-          },
-          this.config
-        );
+        if (this.cookieTrackingAllowed()) {
+          updateUserJourneyOnRouteChange(
+            this.environmentId,
+            newUrl,
+            this.log,
+            () => this.userJourneyId,
+            (id) => {
+              const resolved = !!id && id !== this.userJourneyId;
+              this.userJourneyId = id;
+              if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
+            },
+            this.config
+          );
+        }
         this.sendPayloadToIframes("STORE_UPDATE");
         this.log.info({ message: "Route changed, updated journey", response: { url: newUrl } });
       });
@@ -805,15 +849,16 @@
       return getUrlParams();
     }
     getPayload() {
+      const allowed = this.cookieTrackingAllowed();
       return {
         windowUrl: this.windowUrl,
         referrer: this.referrer,
-        cookies: Object.keys(this.cookies).length === 0 ? parseCookies() : this.cookies,
+        cookies: !allowed ? {} : Object.keys(this.cookies).length === 0 ? parseCookies() : this.cookies,
         origin: this.origin,
         questionIds: this.partialFilledData,
         urlParams: this.urlParams,
-        surfaceLeadData: getLeadDataWithTTL(),
-        userJourneyId: this.userJourneyId
+        surfaceLeadData: allowed ? getLeadDataWithTTL() : null,
+        userJourneyId: allowed ? this.userJourneyId : null
       };
     }
     clearUserJourney() {
@@ -2510,6 +2555,7 @@
   w2.SurfaceGetSiteIdFromScript = getSiteIdFromScript;
   w2.SurfaceSetConsent = setSurfaceConsent;
   onSurfaceConsentChange(() => {
+    SurfaceTagStore.applyConsent();
     SurfaceTagStore.sendConsentToIframes();
     SurfaceTagStore.sendPayloadToIframes("STORE_UPDATE");
   });
diff --git a/surface_tag.js b/surface_tag.js
index 9d14ceb..9e3afd6 100644
--- a/surface_tag.js
+++ b/surface_tag.js
@@ -73,12 +73,14 @@
 
   // src/runtime-config.ts
   var CUSTOM_DOMAIN_ATTRIBUTE = "data-custom-domain";
+  var CONSENT_MODE_ATTRIBUTE = "data-consent-mode";
   var DEFAULT_SURFACE_RUNTIME_CONFIG = {
     apiBaseUrl: EXTERNAL_FORM_API,
     leadIdentifyApi: LEAD_IDENTIFY_API,
     userJourneyTrackingApi: USER_JOURNEY_TRACKING_API,
     surfaceDomains: SURFACE_DOMAINS,
-    customOrigin: null
+    customOrigin: null,
+    waitForCookieConsent: false
   };
   var runtimeConfig = DEFAULT_SURFACE_RUNTIME_CONFIG;
   function normalizeCustomOrigin(value) {
@@ -95,17 +97,19 @@
     }
   }
   function resolveSurfaceRuntimeConfig(scriptElement) {
+    const waitForCookieConsent = scriptElement?.hasAttribute(CONSENT_MODE_ATTRIBUTE) ?? false;
     const customOrigin = normalizeCustomOrigin(
       scriptElement?.getAttribute(CUSTOM_DOMAIN_ATTRIBUTE) ?? ""
     );
-    if (!customOrigin) return DEFAULT_SURFACE_RUNTIME_CONFIG;
+    if (!customOrigin) return { ...DEFAULT_SURFACE_RUNTIME_CONFIG, waitForCookieConsent };
     const apiBaseUrl = `${customOrigin}/api/v1`;
     return {
       apiBaseUrl,
       leadIdentifyApi: `${apiBaseUrl}/lead/identify`,
       userJourneyTrackingApi: `${apiBaseUrl}/lead/track`,
       surfaceDomains: Array.from(/* @__PURE__ */ new Set([...SURFACE_DOMAINS, customOrigin])),
-      customOrigin
+      customOrigin,
+      waitForCookieConsent
     };
   }
   function initializeSurfaceRuntimeConfig(scriptElement) {
@@ -135,6 +139,9 @@
     };
     localStorage.setItem("surfaceLeadData", JSON.stringify(item));
   }
+  function clearLeadData() {
+    localStorage.removeItem("surfaceLeadData");
+  }
   function getLeadDataWithTTL() {
     const itemStr = localStorage.getItem("surfaceLeadData");
     if (!itemStr) return null;
@@ -227,7 +234,8 @@
   var setSurfaceConsent = (granted) => {
     consent = {
       adTracking: granted?.adTracking === true,
-      surfaceAnalytics: granted?.surfaceAnalytics === true
+      surfaceAnalytics: granted?.surfaceAnalytics === true,
+      cookieTracking: granted?.cookieTracking === true
     };
     onChange?.();
   };
@@ -514,7 +522,7 @@
         store.sendPayloadToIframes("STORE_UPDATE");
         store.sendConsentToIframes();
         const envId = getEnvironmentId();
-        if (envId) {
+        if (envId && store.cookieTrackingAllowed()) {
           const identify = store.config?.customOrigin ? identifyLead(envId, store.config) : identifyLead(envId);
           identify.then(() => store.sendPayloadToIframes("LEAD_DATA_UPDATE")).catch((e) => console.log("Failed identify", e));
         } else {
@@ -683,6 +691,7 @@
   // src/store/store.ts
   var SurfaceStore = class {
     constructor(environmentId3 = null, config = getSurfaceRuntimeConfig()) {
+      this.journeyStarted = false;
       this.windowUrl = new URL(window.location.href).toString();
       this.origin = new URL(window.location.href).origin.toString();
       this.referrer = document.referrer || "";
@@ -696,30 +705,21 @@
       this.surfaceDomains = config.surfaceDomains;
       this.userJourneyId = null;
       this.userJourney = [];
-      this.cachedIdentifyData = getLeadDataWithTTL();
       this.environmentId = environmentId3;
       this.log = createLogger("Surface Store");
+      this.cachedIdentifyData = this.cookieTrackingAllowed() ? getLeadDataWithTTL() : null;
       initializeMessageListener(this);
       if ((this.cachedIdentifyData || !isIdentifyInProgress()) && !this.isCurrentOriginSurfaceDomain()) {
-        initializeUserJourneyTracking(
-          this.environmentId,
-          this.log,
-          () => this.userJourneyId,
-          (id) => {
-            const resolved = !!id && id !== this.userJourneyId;
-            this.userJourneyId = id;
-            if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
-          },
-          this.config
-        );
+        if (this.cookieTrackingAllowed()) this.startJourneyTracking();
         this.setupRouteChangeDetection();
       }
       const pushInitialData = () => {
         if (!this.hasSurfaceIframe()) return;
         this.sendPayloadToIframes("STORE_UPDATE");
-        if (this.environmentId) {
-          const identify = this.config.customOrigin ? identifyLead(this.environmentId, this.config) : identifyLead(this.environmentId);
-          identify.then(() => this.sendPayloadToIframes("LEAD_DATA_UPDATE")).catch((e) => this.log.error({ message: "Initial identify failed", error: e }));
+        if (!this.cookieTrackingAllowed()) {
+          this.sendPayloadToIframes("LEAD_DATA_UPDATE");
+        } else if (this.environmentId) {
+          this.identifyAndPushLeadData();
         } else if (getLeadDataWithTTL()) {
           this.sendPayloadToIframes("LEAD_DATA_UPDATE");
         }
@@ -743,21 +743,65 @@
       const origin = window.location?.origin ?? "";
       return this.surfaceDomains.includes(origin);
     }
+    /**
+     * Whether this tag may recognise the visitor: read or write the lead cache,
+     * the journey cookies and the page's cookies. Always true unless the script
+     * was loaded with `data-consent-mode`, in which case the page's banner has to
+     * grant `cookieTracking` first.
+     */
+    cookieTrackingAllowed() {
+      return !this.config.waitForCookieConsent || getSurfaceConsent()?.cookieTracking === true;
+    }
+    /** Re-evaluates host-side tracking after the page reports a consent change. */
+    applyConsent() {
+      if (!this.config.waitForCookieConsent) return;
+      if (this.cookieTrackingAllowed()) {
+        if (!this.isCurrentOriginSurfaceDomain()) this.startJourneyTracking();
+        if (this.environmentId && this.hasSurfaceIframe()) this.identifyAndPushLeadData();
+        return;
+      }
+      this.clearUserJourney();
+      this.journeyStarted = false;
+      this.cachedIdentifyData = null;
+      clearLeadData();
+    }
+    startJourneyTracking() {
+      if (this.journeyStarted) return;
+      this.journeyStarted = true;
+      initializeUserJourneyTracking(
+        this.environmentId,
+        this.log,
+        () => this.userJourneyId,
+        (id) => {
+          const resolved = !!id && id !== this.userJourneyId;
+          this.userJourneyId = id;
+          if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
+        },
+        this.config
+      );
+    }
+    identifyAndPushLeadData() {
+      if (!this.environmentId) return;
+      const identify = this.config.customOrigin ? identifyLead(this.environmentId, this.config) : identifyLead(this.environmentId);
+      identify.then(() => this.sendPayloadToIframes("LEAD_DATA_UPDATE")).catch((e) => this.log.error({ message: "Initial identify failed", error: e }));
+    }
     setupRouteChangeDetection() {
       onRouteChange((newUrl) => {
         this.windowUrl = new URL(newUrl).toString();
-        updateUserJourneyOnRouteChange(
-          this.environmentId,
-          newUrl,
-          this.log,
-          () => this.userJourneyId,
-          (id) => {
-            const resolved = !!id && id !== this.userJourneyId;
-            this.userJourneyId = id;
-            if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
-          },
-          this.config
-        );
+        if (this.cookieTrackingAllowed()) {
+          updateUserJourneyOnRouteChange(
+            this.environmentId,
+            newUrl,
+            this.log,
+            () => this.userJourneyId,
+            (id) => {
+              const resolved = !!id && id !== this.userJourneyId;
+              this.userJourneyId = id;
+              if (resolved) this.sendPayloadToIframes("STORE_UPDATE");
+            },
+            this.config
+          );
+        }
         this.sendPayloadToIframes("STORE_UPDATE");
         this.log.info({ message: "Route changed, updated journey", response: { url: newUrl } });
       });
@@ -805,15 +849,16 @@
       return getUrlParams();
     }
     getPayload() {
+      const allowed = this.cookieTrackingAllowed();
       return {
         windowUrl: this.windowUrl,
         referrer: this.referrer,
-        cookies: Object.keys(this.cookies).length === 0 ? parseCookies() : this.cookies,
+        cookies: !allowed ? {} : Object.keys(this.cookies).length === 0 ? parseCookies() : this.cookies,
         origin: this.origin,
         questionIds: this.partialFilledData,
         urlParams: this.urlParams,
-        surfaceLeadData: getLeadDataWithTTL(),
-        userJourneyId: this.userJourneyId
+        surfaceLeadData: allowed ? getLeadDataWithTTL() : null,
+        userJourneyId: allowed ? this.userJourneyId : null
       };
     }
     clearUserJourney() {
@@ -2510,6 +2555,7 @@
   w2.SurfaceGetSiteIdFromScript = getSiteIdFromScript;
   w2.SurfaceSetConsent = setSurfaceConsent;
   onSurfaceConsentChange(() => {
+    SurfaceTagStore.applyConsent();
     SurfaceTagStore.sendConsentToIframes();
     SurfaceTagStore.sendPayloadToIframes("STORE_UPDATE");
   });
diff --git a/test/consent.html b/test/consent.html
index e579711..678c7b5 100644
--- a/test/consent.html
+++ b/test/consent.html
@@ -46,6 +46,9 @@
         const script = document.createElement("script");
         script.src = "../surface_tag.js";
         script.setAttribute("site-id", config.siteId);
+        // This page is the consent banner, so the tag must wait for it before
+        // recognising the visitor or forwarding cookies.
+        script.setAttribute("data-consent-mode", "");
         // The tag only posts to origins on its allowlist. Production origins are
         // built in; a preview deploy or custom domain has to be declared.
         if (!PRODUCTION_ORIGINS.includes(formOrigin)) {
@@ -159,6 +162,7 @@ <h2>Embedded Form</h2>
       <div class="cookie-prefs" id="cookiePrefs" hidden>
         <label><input type="checkbox" id="prefAdTracking"> Marketing &mdash; <code>adTracking</code></label>
         <label><input type="checkbox" id="prefSurfaceAnalytics"> Analytics &mdash; <code>surfaceAnalytics</code></label>
+        <label><input type="checkbox" id="prefCookieTracking"> Cookies &mdash; <code>cookieTracking</code></label>
         <button id="savePrefs">Save choices</button>
       </div>
     </div>
diff --git a/test/consent.js b/test/consent.js
index 474b329..eab160c 100644
--- a/test/consent.js
+++ b/test/consent.js
@@ -11,6 +11,7 @@ const status = document.getElementById("consentStatus");
 const statusText = document.getElementById("consentStatusText");
 const adTrackingPref = document.getElementById("prefAdTracking");
 const surfaceAnalyticsPref = document.getElementById("prefSurfaceAnalytics");
+const cookieTrackingPref = document.getElementById("prefCookieTracking");
 
 const text = (id, value) => {
   document.getElementById(id).textContent = value;
@@ -68,6 +69,7 @@ function answer(consent) {
   deliverConsent(consent);
   adTrackingPref.checked = consent.adTracking;
   surfaceAnalyticsPref.checked = consent.surfaceAnalytics;
+  cookieTrackingPref.checked = consent.cookieTracking;
   banner.hidden = true;
   status.hidden = false;
   statusText.textContent = `Consent — ${describe(consent)}`;
@@ -84,13 +86,17 @@ document.getElementById("managePrefs").addEventListener("click", () => {
   prefs.hidden = !prefs.hidden;
 });
 document.getElementById("acceptAll").addEventListener("click", () =>
-  answer({ adTracking: true, surfaceAnalytics: true })
+  answer({ adTracking: true, surfaceAnalytics: true, cookieTracking: true })
 );
 document.getElementById("rejectAll").addEventListener("click", () =>
-  answer({ adTracking: false, surfaceAnalytics: false })
+  answer({ adTracking: false, surfaceAnalytics: false, cookieTracking: false })
 );
 document.getElementById("savePrefs").addEventListener("click", () =>
-  answer({ adTracking: adTrackingPref.checked, surfaceAnalytics: surfaceAnalyticsPref.checked })
+  answer({
+    adTracking: adTrackingPref.checked,
+    surfaceAnalytics: surfaceAnalyticsPref.checked,
+    cookieTracking: cookieTrackingPref.checked,
+  })
 );
 document.getElementById("changePrefs").addEventListener("click", showBanner);
 document.getElementById("copyFilter").addEventListener("click", (event) => {

From ff7c61825cb23f988b39790ba8e29bb8306f7f07 Mon Sep 17 00:00:00 2001
From: Gautam Ahuja <gautamahuja1909@gmail.com>
Date: Mon, 7 Sep 2026 13:35:37 +0530
Subject: [PATCH 2/2] feat(consent): share each consent answer with a Forms SDK
 in the same document

`SurfaceSetConsent` now also writes the normalized snapshot to
`window.__SURFACE_CONSENT__` and dispatches a `surface:consent` DOM event, and
the tag reads a snapshot an SDK that loaded first left there. This is how a
customer-hosted SDK form and the tag agree on one banner answer without either
wrapping the other's API.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 CLAUDE.md                   |  4 ++++
 src/consent/consent.test.ts | 12 ++++++++++++
 src/consent/consent.ts      | 27 +++++++++++++++++++++------
 surface_embed_v1.js         | 18 ++++++++++++------
 surface_tag.js              | 18 ++++++++++++------
 5 files changed, 61 insertions(+), 18 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 85a63f7..8eb38e3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,6 +98,10 @@ categories mirror the form-render gate in `surface_forms`
 (`lib/client/thirdParty/`) — keep the message shape in sync with its
 `hostConsent.ts`.
 
+Each answer is also written to `window.__SURFACE_CONSENT__` and dispatched as a
+`surface:consent` DOM event, which is how a Forms SDK form on the same page hears
+it; the tag reads a snapshot the SDK left there if the SDK loaded first.
+
 `cookieTracking` also gates the tag's own host-side work, but only when the
 `<script>` carries `data-consent-mode` (read in `runtime-config.ts`). Until that
 page grants it, `SurfaceStore` skips identify, the `surfaceLeadData` cache, the
diff --git a/src/consent/consent.test.ts b/src/consent/consent.test.ts
index acd4bb6..282b16a 100644
--- a/src/consent/consent.test.ts
+++ b/src/consent/consent.test.ts
@@ -45,6 +45,18 @@ describe("surface consent", () => {
     });
   });
 
+  it("shares each answer with an SDK in the same document", () => {
+    const heard: unknown[] = [];
+    const listener = (event: Event) => heard.push((event as CustomEvent).detail);
+    window.addEventListener("surface:consent", listener);
+    setSurfaceConsent({ cookieTracking: true });
+    window.removeEventListener("surface:consent", listener);
+
+    const snapshot = { adTracking: false, surfaceAnalytics: false, cookieTracking: true };
+    expect(heard).toEqual([snapshot]);
+    expect((window as Window & { __SURFACE_CONSENT__?: unknown }).__SURFACE_CONSENT__).toEqual(snapshot);
+  });
+
   it("notifies the relay on every answer", () => {
     const onChange = vi.fn();
     onSurfaceConsentChange(onChange);
diff --git a/src/consent/consent.ts b/src/consent/consent.ts
index 2c537c8..e5ae85b 100644
--- a/src/consent/consent.ts
+++ b/src/consent/consent.ts
@@ -17,7 +17,22 @@ export interface SurfaceConsent {
   cookieTracking: boolean;
 }
 
-let consent: SurfaceConsent | null = null;
+// Shared with the Forms SDK when both run in one document: the latest snapshot
+// lives on `window.__SURFACE_CONSENT__` and every change dispatches this event.
+export const SURFACE_CONSENT_EVENT = "surface:consent";
+type ConsentWindow = Window & { __SURFACE_CONSENT__?: SurfaceConsent };
+
+const normalize = (granted: Partial<SurfaceConsent> | undefined): SurfaceConsent => ({
+  adTracking: granted?.adTracking === true,
+  surfaceAnalytics: granted?.surfaceAnalytics === true,
+  cookieTracking: granted?.cookieTracking === true,
+});
+
+// An SDK that loaded first may already hold the page's answer.
+let consent: SurfaceConsent | null =
+  typeof window !== "undefined" && (window as ConsentWindow).__SURFACE_CONSENT__
+    ? normalize((window as ConsentWindow).__SURFACE_CONSENT__)
+    : null;
 let onChange: (() => void) | null = null;
 
 /** Null until the page has answered — forms treat that as nothing granted. */
@@ -40,10 +55,10 @@ export const onSurfaceConsentChange = (callback: () => void): void => {
  * scripts a form already started.
  */
 export const setSurfaceConsent = (granted: Partial<SurfaceConsent>): void => {
-  consent = {
-    adTracking: granted?.adTracking === true,
-    surfaceAnalytics: granted?.surfaceAnalytics === true,
-    cookieTracking: granted?.cookieTracking === true,
-  };
+  consent = normalize(granted);
+  if (typeof window !== "undefined") {
+    (window as ConsentWindow).__SURFACE_CONSENT__ = { ...consent };
+    window.dispatchEvent(new CustomEvent(SURFACE_CONSENT_EVENT, { detail: { ...consent } }));
+  }
   onChange?.();
 };
diff --git a/surface_embed_v1.js b/surface_embed_v1.js
index 9e3afd6..c4fc8ae 100644
--- a/surface_embed_v1.js
+++ b/surface_embed_v1.js
@@ -225,18 +225,24 @@
 
   // src/consent/consent.ts
   var SURFACE_CONSENT_MESSAGE_TYPE = "surface:consent";
-  var consent = null;
+  var SURFACE_CONSENT_EVENT = "surface:consent";
+  var normalize = (granted) => ({
+    adTracking: granted?.adTracking === true,
+    surfaceAnalytics: granted?.surfaceAnalytics === true,
+    cookieTracking: granted?.cookieTracking === true
+  });
+  var consent = typeof window !== "undefined" && window.__SURFACE_CONSENT__ ? normalize(window.__SURFACE_CONSENT__) : null;
   var onChange = null;
   var getSurfaceConsent = () => consent;
   var onSurfaceConsentChange = (callback) => {
     onChange = callback;
   };
   var setSurfaceConsent = (granted) => {
-    consent = {
-      adTracking: granted?.adTracking === true,
-      surfaceAnalytics: granted?.surfaceAnalytics === true,
-      cookieTracking: granted?.cookieTracking === true
-    };
+    consent = normalize(granted);
+    if (typeof window !== "undefined") {
+      window.__SURFACE_CONSENT__ = { ...consent };
+      window.dispatchEvent(new CustomEvent(SURFACE_CONSENT_EVENT, { detail: { ...consent } }));
+    }
     onChange?.();
   };
 
diff --git a/surface_tag.js b/surface_tag.js
index 9e3afd6..c4fc8ae 100644
--- a/surface_tag.js
+++ b/surface_tag.js
@@ -225,18 +225,24 @@
 
   // src/consent/consent.ts
   var SURFACE_CONSENT_MESSAGE_TYPE = "surface:consent";
-  var consent = null;
+  var SURFACE_CONSENT_EVENT = "surface:consent";
+  var normalize = (granted) => ({
+    adTracking: granted?.adTracking === true,
+    surfaceAnalytics: granted?.surfaceAnalytics === true,
+    cookieTracking: granted?.cookieTracking === true
+  });
+  var consent = typeof window !== "undefined" && window.__SURFACE_CONSENT__ ? normalize(window.__SURFACE_CONSENT__) : null;
   var onChange = null;
   var getSurfaceConsent = () => consent;
   var onSurfaceConsentChange = (callback) => {
     onChange = callback;
   };
   var setSurfaceConsent = (granted) => {
-    consent = {
-      adTracking: granted?.adTracking === true,
-      surfaceAnalytics: granted?.surfaceAnalytics === true,
-      cookieTracking: granted?.cookieTracking === true
-    };
+    consent = normalize(granted);
+    if (typeof window !== "undefined") {
+      window.__SURFACE_CONSENT__ = { ...consent };
+      window.dispatchEvent(new CustomEvent(SURFACE_CONSENT_EVENT, { detail: { ...consent } }));
+    }
     onChange?.();
   };