@probat/react 0.1.5 → 0.2.1

package/dist/index.js

@@ -21,6 +21,475 @@ function detectEnvironment() {
   return "prod";
 }
 
+// src/utils/heatmapTracker.ts
+function getStoredExperimentInfo() {
+  if (typeof window === "undefined") return {};
+  try {
+    const proposalId = window.localStorage.getItem("probat_active_proposal_id") || void 0;
+    const variantLabel = window.localStorage.getItem("probat_active_variant_label") || void 0;
+    return { proposalId, variantLabel };
+  } catch {
+    return {};
+  }
+}
+var HeatmapTracker = class {
+  constructor(config) {
+    this.clicks = [];
+    this.movements = [];
+    this.batchTimer = null;
+    this.cursorBatchTimer = null;
+    this.lastCursorTime = 0;
+    this.isInitialized = false;
+    this.handleMouseMove = (event) => {
+      if (!this.config.enabled || !this.config.trackCursor) return;
+      if (typeof window === "undefined") return;
+      const stored = getStoredExperimentInfo();
+      const activeProposalId = this.config.proposalId || stored.proposalId;
+      const activeVariantLabel = stored.proposalId === activeProposalId ? stored.variantLabel || this.config.variantLabel : this.config.variantLabel || stored.variantLabel;
+      const now2 = Date.now();
+      const cursorThrottle = this.config.cursorThrottle ?? 100;
+      if (now2 - this.lastCursorTime < cursorThrottle) {
+        return;
+      }
+      this.lastCursorTime = now2;
+      console.log("[PROBAT Heatmap] Cursor movement captured:", {
+        x: event.pageX,
+        y: event.pageY,
+        movementsInBatch: this.movements.length + 1
+      });
+      const pageUrl = window.location.href;
+      const siteUrl = window.location.origin;
+      const x = event.pageX;
+      const y = event.pageY;
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
+      const movementEvent = {
+        page_url: pageUrl,
+        site_url: siteUrl,
+        x_coordinate: x,
+        y_coordinate: y,
+        viewport_width: viewportWidth,
+        viewport_height: viewportHeight,
+        session_id: this.sessionId,
+        proposal_id: activeProposalId,
+        variant_label: activeVariantLabel
+      };
+      this.movements.push(movementEvent);
+      const cursorBatchSize = this.config.cursorBatchSize ?? 50;
+      if (this.movements.length >= cursorBatchSize) {
+        this.sendCursorBatch();
+      } else {
+        this.scheduleCursorBatchSend();
+      }
+    };
+    this.handleClick = (event) => {
+      if (!this.config.enabled) return;
+      if (typeof window === "undefined") return;
+      const stored = getStoredExperimentInfo();
+      const activeProposalId = this.config.proposalId || stored.proposalId;
+      const activeVariantLabel = stored.proposalId === activeProposalId ? stored.variantLabel || this.config.variantLabel : this.config.variantLabel || stored.variantLabel;
+      const target = event.target;
+      if (!target) return;
+      if (this.shouldExcludeElement(target)) {
+        return;
+      }
+      const pageUrl = window.location.href;
+      const siteUrl = window.location.origin;
+      const x = event.pageX;
+      const y = event.pageY;
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
+      const elementInfo = this.extractElementInfo(target);
+      const clickEvent = {
+        page_url: pageUrl,
+        site_url: siteUrl,
+        x_coordinate: x,
+        y_coordinate: y,
+        viewport_width: viewportWidth,
+        viewport_height: viewportHeight,
+        element_tag: elementInfo.tag,
+        element_class: elementInfo.class,
+        element_id: elementInfo.id,
+        session_id: this.sessionId,
+        proposal_id: activeProposalId,
+        variant_label: activeVariantLabel
+      };
+      this.clicks.push(clickEvent);
+      const batchSize = this.config.batchSize ?? 10;
+      if (this.clicks.length >= batchSize) {
+        this.sendBatch();
+      } else {
+        this.scheduleBatchSend();
+      }
+    };
+    this.sessionId = this.getOrCreateSessionId();
+    const stored = getStoredExperimentInfo();
+    this.config = {
+      apiBaseUrl: config.apiBaseUrl,
+      batchSize: config.batchSize || 10,
+      batchInterval: config.batchInterval || 5e3,
+      enabled: config.enabled !== false,
+      excludeSelectors: config.excludeSelectors || [
+        "[data-heatmap-exclude]",
+        'input[type="password"]',
+        'input[type="email"]',
+        "textarea"
+      ],
+      trackCursor: config.trackCursor !== false,
+      // Enable cursor tracking by default
+      cursorThrottle: config.cursorThrottle || 100,
+      // Capture cursor position every 100ms
+      cursorBatchSize: config.cursorBatchSize || 50,
+      // Send every 50 movements
+      proposalId: config.proposalId || stored.proposalId,
+      variantLabel: config.variantLabel || stored.variantLabel
+    };
+  }
+  getOrCreateSessionId() {
+    if (typeof window === "undefined") return "";
+    const storageKey = "probat_heatmap_session_id";
+    let sessionId = localStorage.getItem(storageKey);
+    if (!sessionId) {
+      sessionId = `heatmap_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+      localStorage.setItem(storageKey, sessionId);
+    }
+    return sessionId;
+  }
+  shouldExcludeElement(element) {
+    if (!this.config.excludeSelectors) return false;
+    for (const selector of this.config.excludeSelectors) {
+      if (element.matches(selector) || element.closest(selector)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  extractElementInfo(element) {
+    return {
+      tag: element.tagName || null,
+      class: element.className && typeof element.className === "string" ? element.className : null,
+      id: element.id || null
+    };
+  }
+  scheduleCursorBatchSend() {
+    if (this.cursorBatchTimer) {
+      clearTimeout(this.cursorBatchTimer);
+    }
+    this.cursorBatchTimer = setTimeout(() => {
+      if (this.movements.length > 0) {
+        this.sendCursorBatch();
+      }
+    }, this.config.batchInterval ?? 5e3);
+  }
+  async sendCursorBatch() {
+    if (this.movements.length === 0) return;
+    const siteUrl = this.movements[0]?.site_url || window.location.origin;
+    const batch = {
+      movements: this.movements,
+      site_url: siteUrl,
+      proposal_id: this.config.proposalId,
+      variant_label: this.config.variantLabel
+    };
+    this.movements = [];
+    if (this.cursorBatchTimer) {
+      clearTimeout(this.cursorBatchTimer);
+      this.cursorBatchTimer = null;
+    }
+    try {
+      console.log("[PROBAT Heatmap] Sending cursor movements batch:", {
+        count: batch.movements.length,
+        site_url: batch.site_url
+      });
+      const response = await fetch(`${this.config.apiBaseUrl}/api/heatmap/cursor-movements`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(batch)
+        // Don't wait for response - fire and forget for performance
+      });
+      if (!response.ok) {
+        console.warn("[PROBAT Heatmap] Failed to send cursor movements:", response.status);
+      } else {
+        console.log("[PROBAT Heatmap] Successfully sent cursor movements batch");
+      }
+    } catch (error) {
+      console.warn("[PROBAT Heatmap] Error sending cursor movements:", error);
+    }
+  }
+  scheduleBatchSend() {
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+    }
+    this.batchTimer = setTimeout(() => {
+      if (this.clicks.length > 0) {
+        this.sendBatch();
+      }
+    }, this.config.batchInterval ?? 5e3);
+  }
+  async sendBatch() {
+    if (this.clicks.length === 0) return;
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    const siteUrl = this.clicks[0]?.site_url || window.location.origin;
+    const batch = {
+      clicks: [...this.clicks],
+      site_url: siteUrl
+    };
+    this.clicks = [];
+    try {
+      const response = await fetch(`${this.config.apiBaseUrl}/api/heatmap/clicks`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(batch)
+      });
+      if (!response.ok) {
+        console.warn("[PROBAT Heatmap] Failed to send clicks:", response.status);
+      }
+    } catch (error) {
+      console.warn("[PROBAT Heatmap] Error sending clicks:", error);
+    }
+  }
+  init() {
+    if (this.isInitialized) {
+      console.warn("[PROBAT Heatmap] Tracker already initialized");
+      return;
+    }
+    if (typeof window === "undefined") {
+      return;
+    }
+    const params = new URLSearchParams(window.location.search);
+    if (params.get("heatmap") === "true") {
+      console.log("[PROBAT Heatmap] Heatmap visualization mode detected");
+      const pageUrl = params.get("page_url");
+      if (pageUrl) {
+        this.config.enabled = false;
+        this.isInitialized = true;
+        this.enableVisualization(pageUrl);
+        return;
+      }
+    }
+    document.addEventListener("click", this.handleClick, true);
+    if (this.config.trackCursor) {
+      document.addEventListener("mousemove", this.handleMouseMove, { passive: true });
+      console.log("[PROBAT Heatmap] Cursor tracking enabled");
+    } else {
+      console.log("[PROBAT Heatmap] Cursor tracking disabled");
+    }
+    this.isInitialized = true;
+    console.log("[PROBAT Heatmap] Tracker initialized");
+    window.addEventListener("beforeunload", () => {
+      if (this.clicks.length > 0) {
+        const siteUrl = this.clicks[0]?.site_url || window.location.origin;
+        const batch = {
+          clicks: this.clicks,
+          site_url: siteUrl
+        };
+        const blob = new Blob([JSON.stringify(batch)], {
+          type: "application/json"
+        });
+        navigator.sendBeacon(
+          `${this.config.apiBaseUrl}/api/heatmap/clicks`,
+          blob
+        );
+      }
+      if (this.movements.length > 0) {
+        const siteUrl = this.movements[0]?.site_url || window.location.origin;
+        const batch = {
+          movements: this.movements,
+          site_url: siteUrl
+        };
+        const blob = new Blob([JSON.stringify(batch)], {
+          type: "application/json"
+        });
+        navigator.sendBeacon(
+          `${this.config.apiBaseUrl}/api/heatmap/cursor-movements`,
+          blob
+        );
+      }
+    });
+  }
+  stop() {
+    if (!this.isInitialized) return;
+    if (this.clicks.length > 0) {
+      this.sendBatch();
+    }
+    if (this.movements.length > 0) {
+      this.sendCursorBatch();
+    }
+    document.removeEventListener("click", this.handleClick, true);
+    if (this.config.trackCursor) {
+      document.removeEventListener("mousemove", this.handleMouseMove);
+    }
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer);
+      this.batchTimer = null;
+    }
+    if (this.cursorBatchTimer) {
+      clearTimeout(this.cursorBatchTimer);
+      this.cursorBatchTimer = null;
+    }
+    this.isInitialized = false;
+  }
+  /**
+   * Enable visualization mode
+   */
+  /**
+   * Enable visualization mode
+   */
+  async enableVisualization(pageUrl) {
+    console.log("[PROBAT Heatmap] Enabling visualization mode for:", pageUrl);
+    this.stop();
+    this.config.enabled = false;
+    try {
+      const url = new URL(`${this.config.apiBaseUrl}/api/heatmap/aggregate`);
+      url.searchParams.append("site_url", window.location.origin);
+      url.searchParams.append("page_url", pageUrl);
+      url.searchParams.append("days", "30");
+      const params = new URLSearchParams(window.location.search);
+      const proposalId = params.get("proposal_id");
+      const variantLabel = params.get("variant_label");
+      if (proposalId) url.searchParams.append("proposal_id", proposalId);
+      if (variantLabel) url.searchParams.append("variant_label", variantLabel);
+      const response = await fetch(url.toString());
+      if (!response.ok) throw new Error("Failed to fetch heatmap data");
+      const data = await response.json();
+      if (data && data.points) {
+        console.log(`[PROBAT Heatmap] Found ${data.points.length} points. Rendering...`);
+        this.renderHeatmapOverlay(data);
+      }
+    } catch (error) {
+      console.error("[PROBAT Heatmap] Visualization error:", error);
+    }
+  }
+  /**
+   * Render heatmap overlay on valid points
+   */
+  renderHeatmapOverlay(data) {
+    const points = data.points;
+    const trackedWidth = data.viewport_width || 0;
+    const existing = document.getElementById("probat-heatmap-overlay");
+    if (existing) existing.remove();
+    const canvas = document.createElement("canvas");
+    canvas.id = "probat-heatmap-overlay";
+    canvas.style.position = "absolute";
+    canvas.style.top = "0";
+    canvas.style.left = "0";
+    canvas.style.zIndex = "999999";
+    canvas.style.pointerEvents = "none";
+    canvas.style.display = "block";
+    canvas.style.margin = "0";
+    canvas.style.padding = "0";
+    document.documentElement.appendChild(canvas);
+    const resize = () => {
+      const dpr = window.devicePixelRatio || 1;
+      const width = document.documentElement.scrollWidth;
+      const height = document.documentElement.scrollHeight;
+      const currentWidth = window.innerWidth;
+      let offsetX = 0;
+      if (trackedWidth > 0 && trackedWidth !== currentWidth) {
+        offsetX = (currentWidth - trackedWidth) / 2;
+        console.log(`[PROBAT Heatmap] Horizontal adjustment: offset=${offsetX}px (Tracked: ${trackedWidth}px, Current: ${currentWidth}px)`);
+      }
+      canvas.style.width = width + "px";
+      canvas.style.height = height + "px";
+      canvas.width = width * dpr;
+      canvas.height = height * dpr;
+      const ctx = canvas.getContext("2d");
+      if (ctx) {
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        this.renderPoints(ctx, points, offsetX);
+      }
+    };
+    window.addEventListener("resize", resize);
+    setTimeout(resize, 300);
+    setTimeout(resize, 1e3);
+    setTimeout(resize, 3e3);
+  }
+  /**
+   * Draw points on canvas
+   */
+  renderPoints(ctx, points, offsetX) {
+    points.forEach((point) => {
+      const x = point.x + offsetX;
+      const y = point.y;
+      const intensity = point.intensity;
+      const radius = 20 + intensity * 12;
+      const color = this.getHeatmapColor(intensity);
+      const gradient = ctx.createRadialGradient(x, y, 0, x, y, radius);
+      gradient.addColorStop(0, this.rgbToRgba(color, 0.8));
+      gradient.addColorStop(1, this.rgbToRgba(color, 0));
+      ctx.beginPath();
+      ctx.arc(x, y, radius, 0, 2 * Math.PI);
+      ctx.fillStyle = gradient;
+      ctx.fill();
+    });
+  }
+  /**
+   * Get heatmap color based on intensity
+   */
+  getHeatmapColor(intensity) {
+    const clamped = Math.max(0, Math.min(1, intensity));
+    if (clamped < 0.25) {
+      const t = clamped / 0.25;
+      const r = Math.floor(0 + t * 0);
+      const g = Math.floor(0 + t * 255);
+      const b = Math.floor(255 + t * (255 - 255));
+      return `rgb(${r}, ${g}, ${b})`;
+    } else if (clamped < 0.5) {
+      const t = (clamped - 0.25) / 0.25;
+      const r = Math.floor(0 + t * 0);
+      const g = 255;
+      const b = Math.floor(255 + t * (0 - 255));
+      return `rgb(${r}, ${g}, ${b})`;
+    } else if (clamped < 0.75) {
+      const t = (clamped - 0.5) / 0.25;
+      const r = Math.floor(0 + t * 255);
+      const g = 255;
+      const b = 0;
+      return `rgb(${r}, ${g}, ${b})`;
+    } else {
+      const t = (clamped - 0.75) / 0.25;
+      const r = 255;
+      const g = Math.floor(255 + t * (0 - 255));
+      const b = 0;
+      return `rgb(${r}, ${g}, ${b})`;
+    }
+  }
+  /**
+   * Convert RGB to RGBA
+   */
+  rgbToRgba(rgb, opacity) {
+    const match = rgb.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
+    if (match) {
+      return `rgba(${match[1]}, ${match[2]}, ${match[3]}, ${opacity})`;
+    }
+    return rgb;
+  }
+};
+var trackerInstance = null;
+function initHeatmapTracking(config) {
+  if (trackerInstance) {
+    trackerInstance.stop();
+  }
+  trackerInstance = new HeatmapTracker(config);
+  trackerInstance.init();
+  return trackerInstance;
+}
+function getHeatmapTracker() {
+  return trackerInstance;
+}
+function stopHeatmapTracking() {
+  if (trackerInstance) {
+    trackerInstance.stop();
+    trackerInstance = null;
+  }
+}
+
 // src/context/ProbatContext.tsx
 var ProbatContext = React4.createContext(null);
 function ProbatProvider({
@@ -28,19 +497,63 @@ function ProbatProvider({
   clientKey,
   environment: explicitEnvironment,
   repoFullName: explicitRepoFullName,
+  proposalId,
+  variantLabel,
   children
 }) {
+  const storedProposalId = typeof window !== "undefined" ? window.localStorage.getItem("probat_active_proposal_id") || void 0 : void 0;
+  const storedVariantLabel = typeof window !== "undefined" ? window.localStorage.getItem("probat_active_variant_label") || void 0 : void 0;
   const contextValue = React4.useMemo(() => {
     const resolvedApiBaseUrl = apiBaseUrl || typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)) }) !== "undefined" && undefined?.VITE_PROBAT_API || typeof globalThis !== "undefined" && globalThis.process?.env?.NEXT_PUBLIC_PROBAT_API || typeof window !== "undefined" && window.__PROBAT_API || "https://gushi.onrender.com";
     const environment = explicitEnvironment || detectEnvironment();
     const resolvedRepoFullName = explicitRepoFullName || typeof globalThis !== "undefined" && globalThis.process?.env?.NEXT_PUBLIC_PROBAT_REPO || typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)) }) !== "undefined" && undefined?.VITE_PROBAT_REPO || typeof window !== "undefined" && window.__PROBAT_REPO || void 0;
+    const params = typeof window !== "undefined" ? new URLSearchParams(window.location.search) : null;
+    const isHeatmapMode = params?.get("heatmap") === "true";
+    let urlProposalId;
+    let urlVariantLabel;
+    if (isHeatmapMode && params) {
+      urlProposalId = params.get("proposal_id") || void 0;
+      urlVariantLabel = params.get("variant_label") || void 0;
+      console.log("[PROBAT] Heatmap mode: Overriding variant from URL", { urlProposalId, urlVariantLabel });
+    }
+    const finalProposalId = urlProposalId || proposalId || (!isHeatmapMode ? storedProposalId : void 0);
+    const finalVariantLabel = urlVariantLabel || variantLabel || (!isHeatmapMode ? storedVariantLabel : void 0);
     return {
       apiBaseUrl: resolvedApiBaseUrl,
       environment,
       clientKey,
-      repoFullName: resolvedRepoFullName
+      repoFullName: resolvedRepoFullName,
+      proposalId: finalProposalId,
+      variantLabel: finalVariantLabel
+    };
+  }, [apiBaseUrl, clientKey, explicitEnvironment, explicitRepoFullName, proposalId, variantLabel, storedProposalId, storedVariantLabel]);
+  React4.useEffect(() => {
+    if (typeof window !== "undefined") {
+      initHeatmapTracking({
+        apiBaseUrl: contextValue.apiBaseUrl,
+        batchSize: 10,
+        batchInterval: 5e3,
+        enabled: true,
+        excludeSelectors: [
+          "[data-heatmap-exclude]",
+          'input[type="password"]',
+          'input[type="email"]',
+          "textarea"
+        ],
+        // Explicitly enable cursor tracking with sensible defaults
+        trackCursor: true,
+        cursorThrottle: 100,
+        // capture every 100ms
+        cursorBatchSize: 50,
+        // send every 50 movements (or after batchInterval)
+        proposalId: contextValue.proposalId,
+        variantLabel: contextValue.variantLabel
+      });
+    }
+    return () => {
+      stopHeatmapTracking();
     };
-  }, [apiBaseUrl, clientKey, explicitEnvironment, explicitRepoFullName]);
+  }, [contextValue.apiBaseUrl, contextValue.proposalId, contextValue.variantLabel]);
   return /* @__PURE__ */ React4__default.default.createElement(ProbatContext.Provider, { value: contextValue }, children);
 }
 function useProbatContext() {
@@ -74,6 +587,14 @@ async function fetchDecision(baseUrl, proposalId) {
       const data = await res.json();
       const experiment_id = (data.experiment_id || `exp_${proposalId}`).toString();
       const label = data.label && data.label.trim() ? data.label : "control";
+      if (typeof window !== "undefined") {
+        try {
+          window.localStorage.setItem("probat_active_proposal_id", proposalId);
+          window.localStorage.setItem("probat_active_variant_label", label);
+        } catch (e) {
+          console.warn("[PROBAT] Failed to set proposal/variant in localStorage:", e);
+        }
+      }
       return { experiment_id, label };
     } finally {
       pendingFetches.delete(proposalId);
@@ -152,6 +673,13 @@ async function fetchComponentExperimentConfig(baseUrl, repoFullName, componentPa
         throw new Error(`HTTP ${res.status}`);
       }
       const data = await res.json();
+      if (typeof window !== "undefined" && data?.proposal_id) {
+        try {
+          window.localStorage.setItem("probat_active_proposal_id", data.proposal_id);
+        } catch (e) {
+          console.warn("[PROBAT] Failed to set proposal_id in localStorage:", e);
+        }
+      }
       return data;
     } catch (e) {
       console.warn(`[PROBAT] Failed to fetch component config: ${e}`);
@@ -607,14 +1135,25 @@ function markTrackedVisit(proposalId, label) {
 
 // src/hooks/useExperiment.ts
 function useExperiment(proposalId, options) {
-  const { apiBaseUrl } = useProbatContext();
+  const context = useProbatContext();
+  const { apiBaseUrl } = context;
   const [choice, setChoice] = React4.useState(null);
   const [isLoading, setIsLoading] = React4.useState(true);
   const [error, setError] = React4.useState(null);
   const autoTrackImpression = options?.autoTrackImpression !== false;
   React4.useEffect(() => {
     let alive = true;
-    const cached = readChoice(proposalId);
+    const isHeatmapMode = typeof window !== "undefined" && new URLSearchParams(window.location.search).get("heatmap") === "true";
+    if (context.proposalId === proposalId && context.variantLabel) {
+      console.log(`[PROBAT] Forced variant from context: ${context.variantLabel}`);
+      setChoice({
+        experiment_id: `forced_${proposalId}`,
+        label: context.variantLabel
+      });
+      setIsLoading(false);
+      return;
+    }
+    const cached = isHeatmapMode ? null : readChoice(proposalId);
     if (cached) {
       setChoice({ experiment_id: cached.experiment_id, label: cached.label });
       setIsLoading(false);
@@ -627,7 +1166,9 @@ function useExperiment(proposalId, options) {
             proposalId
           );
           if (!alive) return;
-          writeChoice(proposalId, experiment_id, label);
+          if (!isHeatmapMode) {
+            writeChoice(proposalId, experiment_id, label);
+          }
           setChoice({ experiment_id, label });
           setError(null);
         } catch (e) {
@@ -648,7 +1189,7 @@ function useExperiment(proposalId, options) {
     return () => {
       alive = false;
     };
-  }, [proposalId, apiBaseUrl]);
+  }, [proposalId, apiBaseUrl, context.proposalId, context.variantLabel]);
   React4.useEffect(() => {
     if (!autoTrackImpression || !choice) return;
     const exp = choice.experiment_id;
@@ -784,32 +1325,70 @@ function withExperiment(Control, options) {
       if (!proposalId) return;
       if (useNewAPI && configLoading) return;
       let alive = true;
-      const cached = readChoice(proposalId);
-      if (cached) {
+      const isHeatmapMode = typeof window !== "undefined" && new URLSearchParams(window.location.search).get("heatmap") === "true";
+      if (context.proposalId === proposalId && context.variantLabel) {
+        console.log(`[PROBAT HOC] Forced variant from context: ${context.variantLabel}`);
         setChoice({
+          experiment_id: `forced_${proposalId}`,
+          label: context.variantLabel
+        });
+        return;
+      }
+      const cached = isHeatmapMode ? null : readChoice(proposalId);
+      if (cached) {
+        const choiceData = {
           experiment_id: cached.experiment_id,
           label: cached.label
-        });
+        };
+        setChoice(choiceData);
+        if (typeof window !== "undefined" && !isHeatmapMode) {
+          try {
+            window.localStorage.setItem("probat_active_proposal_id", proposalId);
+            window.localStorage.setItem("probat_active_variant_label", cached.label);
+          } catch (e) {
+            console.warn("[PROBAT] Failed to set proposal/variant in localStorage:", e);
+          }
+        }
       } else {
         (async () => {
           try {
             const { experiment_id, label: label2 } = await fetchDecision(apiBaseUrl, proposalId);
             if (!alive) return;
-            writeChoice(proposalId, experiment_id, label2);
-            setChoice({ experiment_id, label: label2 });
+            if (!isHeatmapMode) {
+              writeChoice(proposalId, experiment_id, label2);
+              if (typeof window !== "undefined") {
+                try {
+                  window.localStorage.setItem("probat_active_proposal_id", proposalId);
+                  window.localStorage.setItem("probat_active_variant_label", label2);
+                } catch (e) {
+                  console.warn("[PROBAT] Failed to set proposal/variant in localStorage:", e);
+                }
+              }
+            }
+            const choiceData = { experiment_id, label: label2 };
+            setChoice(choiceData);
           } catch (e) {
             if (!alive) return;
-            setChoice({
+            const choiceData = {
               experiment_id: `exp_${proposalId}`,
               label: "control"
-            });
+            };
+            setChoice(choiceData);
+            if (typeof window !== "undefined" && !isHeatmapMode) {
+              try {
+                window.localStorage.setItem("probat_active_proposal_id", proposalId);
+                window.localStorage.setItem("probat_active_variant_label", "control");
+              } catch (err) {
+                console.warn("[PROBAT] Failed to set proposal/variant in localStorage:", err);
+              }
+            }
           }
         })();
       }
       return () => {
         alive = false;
       };
-    }, [proposalId, apiBaseUrl, useNewAPI, configLoading]);
+    }, [proposalId, apiBaseUrl, useNewAPI, configLoading, context.proposalId, context.variantLabel]);
     React4.useEffect(() => {
       if (!proposalId) return;
       const lbl = choice?.label ?? "control";
@@ -865,10 +1444,13 @@ exports.ProbatProviderClient = ProbatProviderClient;
 exports.detectEnvironment = detectEnvironment;
 exports.extractClickMeta = extractClickMeta;
 exports.fetchDecision = fetchDecision;
+exports.getHeatmapTracker = getHeatmapTracker;
 exports.hasTrackedVisit = hasTrackedVisit;
+exports.initHeatmapTracking = initHeatmapTracking;
 exports.markTrackedVisit = markTrackedVisit;
 exports.readChoice = readChoice;
 exports.sendMetric = sendMetric;
+exports.stopHeatmapTracking = stopHeatmapTracking;
 exports.useExperiment = useExperiment;
 exports.useProbatContext = useProbatContext;
 exports.useProbatMetrics = useProbatMetrics;