From 680f6a841378406ee8efe2792e3454c980258821 Mon Sep 17 00:00:00 2001
From: Bill Yang <billyang@umich.edu>
Date: Wed, 21 Jan 2026 19:05:25 -0800
Subject: [PATCH] heatmaps

---
 client/src/api/analytics/endpoints/heatmap.ts |  83 +++++++++
 client/src/api/analytics/endpoints/index.ts   |  13 ++
 .../hooks/heatmap/useGetClickHeatmap.ts       |  35 ++++
 .../hooks/heatmap/useGetHeatmapPages.ts       |  26 +++
 .../app/[site]/[privateKey]/heatmaps/page.tsx |   2 +
 .../app/[site]/components/Sidebar/Sidebar.tsx |  11 ++
 .../heatmaps/components/HeatmapControls.tsx   |  42 +++++
 .../heatmaps/components/HeatmapPageList.tsx   |  63 +++++++
 .../heatmaps/components/HeatmapViewer.tsx     | 139 ++++++++++++++
 client/src/app/[site]/heatmaps/page.tsx       |  92 ++++++++++
 .../src/components/heatmap/HeatmapCanvas.tsx  | 132 ++++++++++++++
 client/src/components/heatmap/PagePreview.tsx |  99 ++++++++++
 server/src/api/heatmap/getClickHeatmap.ts     |  39 ++++
 server/src/api/heatmap/getHeatmapPages.ts     |  31 ++++
 server/src/api/heatmap/index.ts               |   2 +
 server/src/db/clickhouse/clickhouse.ts        |  24 +++
 server/src/index.ts                           |   9 +-
 .../services/heatmap/clickHeatmapService.ts   | 172 ++++++++++++++++++
 .../replay/sessionReplayIngestService.ts      |  85 +++++++++
 19 files changed, 1098 insertions(+), 1 deletion(-)
 create mode 100644 client/src/api/analytics/endpoints/heatmap.ts
 create mode 100644 client/src/api/analytics/hooks/heatmap/useGetClickHeatmap.ts
 create mode 100644 client/src/api/analytics/hooks/heatmap/useGetHeatmapPages.ts
 create mode 100644 client/src/app/[site]/[privateKey]/heatmaps/page.tsx
 create mode 100644 client/src/app/[site]/heatmaps/components/HeatmapControls.tsx
 create mode 100644 client/src/app/[site]/heatmaps/components/HeatmapPageList.tsx
 create mode 100644 client/src/app/[site]/heatmaps/components/HeatmapViewer.tsx
 create mode 100644 client/src/app/[site]/heatmaps/page.tsx
 create mode 100644 client/src/components/heatmap/HeatmapCanvas.tsx
 create mode 100644 client/src/components/heatmap/PagePreview.tsx
 create mode 100644 server/src/api/heatmap/getClickHeatmap.ts
 create mode 100644 server/src/api/heatmap/getHeatmapPages.ts
 create mode 100644 server/src/api/heatmap/index.ts
 create mode 100644 server/src/services/heatmap/clickHeatmapService.ts

diff --git a/client/src/api/analytics/endpoints/heatmap.ts b/client/src/api/analytics/endpoints/heatmap.ts
new file mode 100644
index 000000000..1bd95e543
--- /dev/null
+++ b/client/src/api/analytics/endpoints/heatmap.ts
@@ -0,0 +1,83 @@
+import { authedFetch } from "../../utils";
+import { CommonApiParams, toQueryParams } from "./types";
+
+// Heatmap data point type
+export interface HeatmapDataPoint {
+  x: number; // 0-100 percentage
+  y: number; // 0-100 percentage
+  value: number; // click count
+}
+
+// Click heatmap result type
+export interface ClickHeatmapResult {
+  points: HeatmapDataPoint[];
+  totalClicks: number;
+  uniqueSessions: number;
+}
+
+// Click heatmap response type
+export interface ClickHeatmapResponse {
+  data: ClickHeatmapResult;
+  pathname: string;
+}
+
+// Heatmap page type
+export interface HeatmapPage {
+  pathname: string;
+  clickCount: number;
+  sessionCount: number;
+}
+
+// Heatmap pages response type
+export interface HeatmapPagesResponse {
+  data: HeatmapPage[];
+}
+
+// Viewport breakpoint type
+export type ViewportBreakpoint = "mobile" | "tablet" | "desktop" | "all";
+
+// Click heatmap params
+export interface ClickHeatmapParams extends CommonApiParams {
+  pathname: string;
+  viewportBreakpoint?: ViewportBreakpoint;
+  gridResolution?: number;
+}
+
+// Heatmap pages params
+export interface HeatmapPagesParams extends CommonApiParams {
+  limit?: number;
+}
+
+/**
+ * Fetch click heatmap data for a specific page
+ * GET /api/sites/:siteId/heatmap/clicks
+ */
+export async function fetchClickHeatmap(
+  site: string | number,
+  params: ClickHeatmapParams
+): Promise<ClickHeatmapResponse> {
+  const queryParams = {
+    ...toQueryParams(params),
+    pathname: params.pathname,
+    viewportBreakpoint: params.viewportBreakpoint,
+    gridResolution: params.gridResolution,
+  };
+
+  return authedFetch<ClickHeatmapResponse>(`/sites/${site}/heatmap/clicks`, queryParams);
+}
+
+/**
+ * Fetch list of pages with click data for heatmaps
+ * GET /api/sites/:siteId/heatmap/pages
+ */
+export async function fetchHeatmapPages(
+  site: string | number,
+  params: HeatmapPagesParams
+): Promise<HeatmapPagesResponse> {
+  const queryParams = {
+    ...toQueryParams(params),
+    limit: params.limit,
+  };
+
+  return authedFetch<HeatmapPagesResponse>(`/sites/${site}/heatmap/pages`, queryParams);
+}
diff --git a/client/src/api/analytics/endpoints/index.ts b/client/src/api/analytics/endpoints/index.ts
index f171400d2..e31e5000b 100644
--- a/client/src/api/analytics/endpoints/index.ts
+++ b/client/src/api/analytics/endpoints/index.ts
@@ -135,3 +135,16 @@ export type {
 // Export endpoints
 export { exportPdfReport } from "./export";
 export type { ExportPdfParams } from "./export";
+
+// Heatmap endpoints
+export { fetchClickHeatmap, fetchHeatmapPages } from "./heatmap";
+export type {
+  HeatmapDataPoint,
+  ClickHeatmapResult,
+  ClickHeatmapResponse,
+  HeatmapPage,
+  HeatmapPagesResponse,
+  ViewportBreakpoint,
+  ClickHeatmapParams,
+  HeatmapPagesParams,
+} from "./heatmap";
diff --git a/client/src/api/analytics/hooks/heatmap/useGetClickHeatmap.ts b/client/src/api/analytics/hooks/heatmap/useGetClickHeatmap.ts
new file mode 100644
index 000000000..b45aa8919
--- /dev/null
+++ b/client/src/api/analytics/hooks/heatmap/useGetClickHeatmap.ts
@@ -0,0 +1,35 @@
+import { useQuery } from "@tanstack/react-query";
+import { useStore } from "../../../../lib/store";
+import { buildApiParams } from "../../../utils";
+import { fetchClickHeatmap, ViewportBreakpoint } from "../../endpoints/heatmap";
+
+interface UseGetClickHeatmapOptions {
+  pathname: string;
+  viewportBreakpoint?: ViewportBreakpoint;
+  gridResolution?: number;
+  enabled?: boolean;
+}
+
+export function useGetClickHeatmap({
+  pathname,
+  viewportBreakpoint = "all",
+  gridResolution = 100,
+  enabled = true,
+}: UseGetClickHeatmapOptions) {
+  const { time, site, filters, timezone } = useStore();
+  const params = buildApiParams(time, { filters });
+
+  return useQuery({
+    queryKey: ["click-heatmap", site, pathname, viewportBreakpoint, gridResolution, time, filters, timezone],
+    queryFn: () =>
+      fetchClickHeatmap(site, {
+        ...params,
+        pathname,
+        viewportBreakpoint,
+        gridResolution,
+      }),
+    staleTime: 1000 * 60 * 5, // 5 minutes
+    refetchOnWindowFocus: false,
+    enabled: !!site && !!pathname && enabled,
+  });
+}
diff --git a/client/src/api/analytics/hooks/heatmap/useGetHeatmapPages.ts b/client/src/api/analytics/hooks/heatmap/useGetHeatmapPages.ts
new file mode 100644
index 000000000..7d8aa80b7
--- /dev/null
+++ b/client/src/api/analytics/hooks/heatmap/useGetHeatmapPages.ts
@@ -0,0 +1,26 @@
+import { useQuery } from "@tanstack/react-query";
+import { useStore } from "../../../../lib/store";
+import { buildApiParams } from "../../../utils";
+import { fetchHeatmapPages } from "../../endpoints/heatmap";
+
+interface UseGetHeatmapPagesOptions {
+  limit?: number;
+  enabled?: boolean;
+}
+
+export function useGetHeatmapPages({ limit = 100, enabled = true }: UseGetHeatmapPagesOptions = {}) {
+  const { time, site, filters, timezone } = useStore();
+  const params = buildApiParams(time, { filters });
+
+  return useQuery({
+    queryKey: ["heatmap-pages", site, limit, time, filters, timezone],
+    queryFn: () =>
+      fetchHeatmapPages(site, {
+        ...params,
+        limit,
+      }),
+    staleTime: 1000 * 60 * 5, // 5 minutes
+    refetchOnWindowFocus: false,
+    enabled: !!site && enabled,
+  });
+}
diff --git a/client/src/app/[site]/[privateKey]/heatmaps/page.tsx b/client/src/app/[site]/[privateKey]/heatmaps/page.tsx
new file mode 100644
index 000000000..7c16bedce
--- /dev/null
+++ b/client/src/app/[site]/[privateKey]/heatmaps/page.tsx
@@ -0,0 +1,2 @@
+// Re-export the heatmaps page for private link routes
+export { default } from "../../heatmaps/page";
diff --git a/client/src/app/[site]/components/Sidebar/Sidebar.tsx b/client/src/app/[site]/components/Sidebar/Sidebar.tsx
index e9ad72330..0d8e41afe 100644
--- a/client/src/app/[site]/components/Sidebar/Sidebar.tsx
+++ b/client/src/app/[site]/components/Sidebar/Sidebar.tsx
@@ -4,6 +4,7 @@ import {
   ChartColumnDecreasing,
   Code,
   File,
+  Flame,
   Funnel,
   Gauge,
   Globe2,
@@ -124,6 +125,16 @@ function SidebarContent() {
             />
           )}
         </div>
+        <div className="hidden md:block">
+          {!subscription?.planName?.startsWith("appsumo") && !isSubscriptionLoading && (
+            <SidebarComponents.Item
+              label="Heatmaps"
+              active={isActiveTab("heatmaps")}
+              href={getTabPath("heatmaps")}
+              icon={<Flame className="w-4 h-4" />}
+            />
+          )}
+        </div>
         <SidebarComponents.Item
           label="Funnels"
           active={isActiveTab("funnels")}
diff --git a/client/src/app/[site]/heatmaps/components/HeatmapControls.tsx b/client/src/app/[site]/heatmaps/components/HeatmapControls.tsx
new file mode 100644
index 000000000..7790e1520
--- /dev/null
+++ b/client/src/app/[site]/heatmaps/components/HeatmapControls.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import { Monitor, Smartphone, Tablet } from "lucide-react";
+import { ViewportBreakpoint } from "../../../../api/analytics/endpoints/heatmap";
+import { cn } from "../../../../lib/utils";
+
+interface HeatmapControlsProps {
+  viewportBreakpoint: ViewportBreakpoint;
+  onViewportChange: (breakpoint: ViewportBreakpoint) => void;
+}
+
+const VIEWPORT_OPTIONS: { value: ViewportBreakpoint; label: string; icon: React.ReactNode }[] = [
+  { value: "all", label: "All", icon: null },
+  { value: "desktop", label: "Desktop", icon: <Monitor className="w-4 h-4" /> },
+  { value: "tablet", label: "Tablet", icon: <Tablet className="w-4 h-4" /> },
+  { value: "mobile", label: "Mobile", icon: <Smartphone className="w-4 h-4" /> },
+];
+
+export function HeatmapControls({ viewportBreakpoint, onViewportChange }: HeatmapControlsProps) {
+  return (
+    <div className="flex items-center gap-2">
+      <span className="text-sm text-neutral-500 dark:text-neutral-400">Viewport:</span>
+      <div className="flex items-center bg-neutral-100 dark:bg-neutral-800 rounded-lg p-0.5">
+        {VIEWPORT_OPTIONS.map((option) => (
+          <button
+            key={option.value}
+            onClick={() => onViewportChange(option.value)}
+            className={cn(
+              "flex items-center gap-1.5 px-3 py-1.5 text-sm rounded-md transition-colors",
+              viewportBreakpoint === option.value
+                ? "bg-white dark:bg-neutral-700 text-neutral-900 dark:text-neutral-100 shadow-sm"
+                : "text-neutral-600 dark:text-neutral-400 hover:text-neutral-900 dark:hover:text-neutral-200"
+            )}
+          >
+            {option.icon}
+            {option.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/client/src/app/[site]/heatmaps/components/HeatmapPageList.tsx b/client/src/app/[site]/heatmaps/components/HeatmapPageList.tsx
new file mode 100644
index 000000000..21876e78a
--- /dev/null
+++ b/client/src/app/[site]/heatmaps/components/HeatmapPageList.tsx
@@ -0,0 +1,63 @@
+"use client";
+
+import { FileText, Loader2 } from "lucide-react";
+import { HeatmapPage } from "../../../../api/analytics/endpoints/heatmap";
+import { cn } from "../../../../lib/utils";
+
+interface HeatmapPageListProps {
+  pages: HeatmapPage[];
+  selectedPathname: string | null;
+  onSelectPage: (pathname: string) => void;
+  isLoading: boolean;
+}
+
+export function HeatmapPageList({ pages, selectedPathname, onSelectPage, isLoading }: HeatmapPageListProps) {
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center h-full">
+        <Loader2 className="w-6 h-6 animate-spin text-neutral-400" />
+      </div>
+    );
+  }
+
+  if (pages.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full text-center px-4">
+        <FileText className="w-8 h-8 text-neutral-400 mb-2" />
+        <p className="text-sm text-neutral-500 dark:text-neutral-400">No pages with click data found</p>
+        <p className="text-xs text-neutral-400 dark:text-neutral-500 mt-1">
+          Click data will appear once session replay captures user interactions
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-1 overflow-y-auto h-full">
+      <div className="text-xs font-medium text-neutral-500 dark:text-neutral-400 px-2 py-1 uppercase tracking-wide">
+        Pages ({pages.length})
+      </div>
+      {pages.map((page) => (
+        <button
+          key={page.pathname}
+          onClick={() => onSelectPage(page.pathname)}
+          className={cn(
+            "flex items-center justify-between px-3 py-2 rounded-lg text-left transition-colors",
+            "hover:bg-neutral-100 dark:hover:bg-neutral-800",
+            selectedPathname === page.pathname && "bg-neutral-100 dark:bg-neutral-800 ring-1 ring-neutral-200 dark:ring-neutral-700"
+          )}
+        >
+          <div className="flex-1 min-w-0">
+            <div className="text-sm font-medium text-neutral-900 dark:text-neutral-100 truncate">{page.pathname}</div>
+            <div className="text-xs text-neutral-500 dark:text-neutral-400">
+              {page.sessionCount.toLocaleString()} sessions
+            </div>
+          </div>
+          <div className="ml-2 px-2 py-0.5 bg-neutral-200 dark:bg-neutral-700 rounded text-xs font-medium text-neutral-700 dark:text-neutral-300">
+            {page.clickCount.toLocaleString()}
+          </div>
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/client/src/app/[site]/heatmaps/components/HeatmapViewer.tsx b/client/src/app/[site]/heatmaps/components/HeatmapViewer.tsx
new file mode 100644
index 000000000..94ae50da4
--- /dev/null
+++ b/client/src/app/[site]/heatmaps/components/HeatmapViewer.tsx
@@ -0,0 +1,139 @@
+"use client";
+
+import { Loader2, MousePointerClick } from "lucide-react";
+import { useMemo, useState } from "react";
+import { useGetClickHeatmap } from "../../../../api/analytics/hooks/heatmap/useGetClickHeatmap";
+import { HeatmapCanvas } from "../../../../components/heatmap/HeatmapCanvas";
+import { ViewportBreakpoint } from "../../../../api/analytics/endpoints/heatmap";
+
+interface HeatmapViewerProps {
+  pathname: string;
+  baseUrl: string;
+  viewportBreakpoint: ViewportBreakpoint;
+  width: number;
+  height: number;
+}
+
+export function HeatmapViewer({ pathname, baseUrl, viewportBreakpoint, width, height }: HeatmapViewerProps) {
+  const { data, isLoading, error } = useGetClickHeatmap({
+    pathname,
+    viewportBreakpoint,
+    gridResolution: 100,
+  });
+
+  const [iframeLoaded, setIframeLoaded] = useState(false);
+  const [iframeError, setIframeError] = useState(false);
+
+  // Construct full page URL
+  const pageUrl = useMemo(() => {
+    try {
+      const url = new URL(pathname, baseUrl);
+      return url.toString();
+    } catch {
+      return `${baseUrl}${pathname}`;
+    }
+  }, [pathname, baseUrl]);
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center h-full bg-neutral-50 dark:bg-neutral-900 rounded-lg">
+        <Loader2 className="w-8 h-8 animate-spin text-neutral-400" />
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full bg-neutral-50 dark:bg-neutral-900 rounded-lg">
+        <p className="text-sm text-red-500">Failed to load heatmap data</p>
+        <p className="text-xs text-neutral-400 mt-1">{error.message}</p>
+      </div>
+    );
+  }
+
+  const points = data?.data.points ?? [];
+  const totalClicks = data?.data.totalClicks ?? 0;
+  const uniqueSessions = data?.data.uniqueSessions ?? 0;
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Stats bar */}
+      <div className="flex items-center gap-4 px-4 py-2 bg-neutral-100 dark:bg-neutral-800 rounded-t-lg border-b border-neutral-200 dark:border-neutral-700">
+        <div className="flex items-center gap-2 text-sm">
+          <MousePointerClick className="w-4 h-4 text-neutral-500" />
+          <span className="font-medium text-neutral-900 dark:text-neutral-100">
+            {totalClicks.toLocaleString()}
+          </span>
+          <span className="text-neutral-500 dark:text-neutral-400">clicks</span>
+        </div>
+        <div className="text-sm text-neutral-500 dark:text-neutral-400">
+          from <span className="font-medium text-neutral-700 dark:text-neutral-300">{uniqueSessions.toLocaleString()}</span> sessions
+        </div>
+      </div>
+
+      {/* Heatmap visualization */}
+      <div className="flex-1 relative bg-white dark:bg-neutral-950 rounded-b-lg overflow-hidden">
+        {/* Iframe with page preview */}
+        <iframe
+          src={pageUrl}
+          width={width}
+          height={height - 48}
+          className="w-full h-full"
+          style={{
+            pointerEvents: "none",
+            opacity: iframeLoaded && !iframeError ? 1 : 0.3,
+          }}
+          sandbox="allow-same-origin"
+          onLoad={() => setIframeLoaded(true)}
+          onError={() => setIframeError(true)}
+          title="Page Preview"
+        />
+
+        {/* Heatmap overlay */}
+        {points.length > 0 && (
+          <HeatmapCanvas points={points} width={width} height={height - 48} gridResolution={100} />
+        )}
+
+        {/* No data overlay */}
+        {points.length === 0 && !isLoading && (
+          <div className="absolute inset-0 flex items-center justify-center bg-neutral-900/50">
+            <div className="bg-white dark:bg-neutral-800 rounded-lg p-4 text-center shadow-lg">
+              <MousePointerClick className="w-8 h-8 text-neutral-400 mx-auto mb-2" />
+              <p className="text-sm font-medium text-neutral-900 dark:text-neutral-100">No click data for this page</p>
+              <p className="text-xs text-neutral-500 dark:text-neutral-400 mt-1">
+                Click data will appear once users interact with this page
+              </p>
+            </div>
+          </div>
+        )}
+
+        {/* Loading overlay for iframe */}
+        {!iframeLoaded && !iframeError && (
+          <div className="absolute inset-0 flex items-center justify-center bg-neutral-100 dark:bg-neutral-900">
+            <Loader2 className="w-8 h-8 animate-spin text-neutral-400" />
+          </div>
+        )}
+
+        {/* Error overlay for iframe */}
+        {iframeError && (
+          <div className="absolute inset-0 flex items-center justify-center bg-neutral-100 dark:bg-neutral-900">
+            <div className="text-center">
+              <p className="text-sm text-neutral-500 dark:text-neutral-400">
+                Unable to preview page
+              </p>
+              <p className="text-xs text-neutral-400 dark:text-neutral-500 mt-1">
+                The page may block iframe embedding
+              </p>
+              {/* Still show heatmap data even without page preview */}
+              {points.length > 0 && (
+                <div className="mt-4">
+                  <HeatmapCanvas points={points} width={width} height={height - 48} gridResolution={100} />
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/client/src/app/[site]/heatmaps/page.tsx b/client/src/app/[site]/heatmaps/page.tsx
new file mode 100644
index 000000000..7ad1d5c65
--- /dev/null
+++ b/client/src/app/[site]/heatmaps/page.tsx
@@ -0,0 +1,92 @@
+"use client";
+
+import { useMeasure, useWindowSize } from "@uidotdev/usehooks";
+import { Flame } from "lucide-react";
+import { useState } from "react";
+import { useGetSite } from "../../../api/admin/hooks/useSites";
+import { useGetHeatmapPages } from "../../../api/analytics/hooks/heatmap/useGetHeatmapPages";
+import { ViewportBreakpoint } from "../../../api/analytics/endpoints/heatmap";
+import { NothingFound } from "../../../components/NothingFound";
+import { useSetPageTitle } from "../../../hooks/useSetPageTitle";
+import { useStore } from "../../../lib/store";
+import { SubHeader } from "../components/SubHeader/SubHeader";
+import { HeatmapControls } from "./components/HeatmapControls";
+import { HeatmapPageList } from "./components/HeatmapPageList";
+import { HeatmapViewer } from "./components/HeatmapViewer";
+
+export default function HeatmapsPage() {
+  useSetPageTitle("Rybbit · Heatmaps");
+
+  const { site } = useStore();
+  const { data: siteData } = useGetSite(site);
+  const { data: pagesData, isLoading: isPagesLoading } = useGetHeatmapPages();
+
+  console.info(pagesData);
+
+  const [selectedPathname, setSelectedPathname] = useState<string | null>(null);
+  const [viewportBreakpoint, setViewportBreakpoint] = useState<ViewportBreakpoint>("all");
+
+  const [ref, { width: containerWidth }] = useMeasure();
+  const { height: windowHeight } = useWindowSize();
+
+  const pages = pagesData?.data ?? [];
+  const hasNoPages = !isPagesLoading && pages.length === 0;
+
+  // Use first page as default if none selected
+  const activePathname = selectedPathname ?? pages[0]?.pathname ?? null;
+
+  // Build base URL from site domain
+  const baseUrl = siteData?.domain ? `https://${siteData.domain}` : "";
+
+  return (
+    <div className="p-2 md:p-4 max-w-[2000px] mx-auto flex flex-col gap-2 h-dvh overflow-hidden">
+      <SubHeader />
+
+      {/* Controls bar */}
+      <div className="flex items-center justify-between">
+        <h1 className="text-lg font-semibold text-neutral-900 dark:text-neutral-100">Click Heatmaps</h1>
+        <HeatmapControls viewportBreakpoint={viewportBreakpoint} onViewportChange={setViewportBreakpoint} />
+      </div>
+
+      {hasNoPages ? (
+        <NothingFound
+          icon={<Flame className="w-10 h-10" />}
+          title="No heatmap data found"
+          description="Click data will appear here once session replay captures user interactions."
+        />
+      ) : (
+        <div className="grid grid-cols-[250px_1fr] gap-4 flex-1 min-h-0">
+          {/* Page list sidebar */}
+          <div className="bg-white dark:bg-neutral-900 rounded-lg border border-neutral-200 dark:border-neutral-800 p-2 overflow-hidden">
+            <HeatmapPageList
+              pages={pages}
+              selectedPathname={activePathname}
+              onSelectPage={setSelectedPathname}
+              isLoading={isPagesLoading}
+            />
+          </div>
+
+          {/* Heatmap viewer */}
+          <div
+            ref={ref}
+            className="bg-white dark:bg-neutral-900 rounded-lg border border-neutral-200 dark:border-neutral-800 overflow-hidden"
+          >
+            {activePathname && containerWidth && windowHeight && baseUrl ? (
+              <HeatmapViewer
+                pathname={activePathname}
+                baseUrl={baseUrl}
+                viewportBreakpoint={viewportBreakpoint}
+                width={containerWidth}
+                height={windowHeight - 180}
+              />
+            ) : (
+              <div className="flex items-center justify-center h-full text-neutral-500 dark:text-neutral-400">
+                {!baseUrl ? "Loading site data..." : "Select a page to view heatmap"}
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/client/src/components/heatmap/HeatmapCanvas.tsx b/client/src/components/heatmap/HeatmapCanvas.tsx
new file mode 100644
index 000000000..668fda0fa
--- /dev/null
+++ b/client/src/components/heatmap/HeatmapCanvas.tsx
@@ -0,0 +1,132 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { HeatmapDataPoint } from "../../api/analytics/endpoints/heatmap";
+
+interface HeatmapCanvasProps {
+  points: HeatmapDataPoint[];
+  width: number;
+  height: number;
+  radius?: number;
+  maxOpacity?: number;
+  blur?: number;
+  gridResolution?: number;
+}
+
+// Color gradient for heatmap (blue -> cyan -> green -> yellow -> red)
+const GRADIENT_COLORS = [
+  { stop: 0, color: "rgba(0, 0, 255, 0)" },
+  { stop: 0.25, color: "rgba(0, 255, 255, 0.5)" },
+  { stop: 0.5, color: "rgba(0, 255, 0, 0.6)" },
+  { stop: 0.75, color: "rgba(255, 255, 0, 0.7)" },
+  { stop: 1, color: "rgba(255, 0, 0, 0.8)" },
+];
+
+export function HeatmapCanvas({
+  points,
+  width,
+  height,
+  radius = 25,
+  maxOpacity = 0.8,
+  blur = 15,
+  gridResolution = 100,
+}: HeatmapCanvasProps) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas || points.length === 0) return;
+
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    // Clear canvas
+    ctx.clearRect(0, 0, width, height);
+
+    // Find max value for normalization
+    const maxValue = Math.max(...points.map((p) => p.value), 1);
+
+    // Create offscreen canvas for the alpha mask
+    const alphaCanvas = document.createElement("canvas");
+    alphaCanvas.width = width;
+    alphaCanvas.height = height;
+    const alphaCtx = alphaCanvas.getContext("2d");
+    if (!alphaCtx) return;
+
+    // Draw circles for each point on alpha canvas
+    points.forEach((point) => {
+      // Convert percentage coordinates to pixel coordinates
+      const x = (point.x / gridResolution) * width;
+      const y = (point.y / gridResolution) * height;
+      const intensity = point.value / maxValue;
+
+      // Create radial gradient for each point
+      const gradient = alphaCtx.createRadialGradient(x, y, 0, x, y, radius);
+      gradient.addColorStop(0, `rgba(0, 0, 0, ${intensity})`);
+      gradient.addColorStop(1, "rgba(0, 0, 0, 0)");
+
+      alphaCtx.beginPath();
+      alphaCtx.fillStyle = gradient;
+      alphaCtx.arc(x, y, radius, 0, Math.PI * 2);
+      alphaCtx.fill();
+    });
+
+    // Apply blur to alpha canvas
+    alphaCtx.filter = `blur(${blur}px)`;
+    const tempCanvas = document.createElement("canvas");
+    tempCanvas.width = width;
+    tempCanvas.height = height;
+    const tempCtx = tempCanvas.getContext("2d");
+    if (tempCtx) {
+      tempCtx.filter = `blur(${blur}px)`;
+      tempCtx.drawImage(alphaCanvas, 0, 0);
+    }
+
+    // Get alpha data
+    const alphaData = (tempCtx || alphaCtx).getImageData(0, 0, width, height);
+
+    // Create gradient image
+    const gradientCanvas = document.createElement("canvas");
+    gradientCanvas.width = 256;
+    gradientCanvas.height = 1;
+    const gradientCtx = gradientCanvas.getContext("2d");
+    if (!gradientCtx) return;
+
+    const linearGradient = gradientCtx.createLinearGradient(0, 0, 256, 0);
+    GRADIENT_COLORS.forEach(({ stop, color }) => {
+      linearGradient.addColorStop(stop, color);
+    });
+    gradientCtx.fillStyle = linearGradient;
+    gradientCtx.fillRect(0, 0, 256, 1);
+    const gradientData = gradientCtx.getImageData(0, 0, 256, 1).data;
+
+    // Apply colorization
+    const outputData = ctx.createImageData(width, height);
+    for (let i = 0; i < alphaData.data.length; i += 4) {
+      const alpha = alphaData.data[i + 3];
+      if (alpha > 0) {
+        const gradientIndex = Math.min(255, Math.floor((alpha / 255) * 255)) * 4;
+        outputData.data[i] = gradientData[gradientIndex]; // R
+        outputData.data[i + 1] = gradientData[gradientIndex + 1]; // G
+        outputData.data[i + 2] = gradientData[gradientIndex + 2]; // B
+        outputData.data[i + 3] = Math.floor(alpha * maxOpacity); // A
+      }
+    }
+
+    ctx.putImageData(outputData, 0, 0);
+  }, [points, width, height, radius, maxOpacity, blur, gridResolution]);
+
+  if (points.length === 0) {
+    return null;
+  }
+
+  return (
+    <canvas
+      ref={canvasRef}
+      width={width}
+      height={height}
+      className="absolute inset-0 pointer-events-none"
+      style={{ width, height }}
+    />
+  );
+}
diff --git a/client/src/components/heatmap/PagePreview.tsx b/client/src/components/heatmap/PagePreview.tsx
new file mode 100644
index 000000000..a5e1fc424
--- /dev/null
+++ b/client/src/components/heatmap/PagePreview.tsx
@@ -0,0 +1,99 @@
+"use client";
+
+import { AlertCircle, ExternalLink, Loader2 } from "lucide-react";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+interface PagePreviewProps {
+  pageUrl: string;
+  width: number;
+  height: number;
+  onLoad?: () => void;
+  onError?: (error: string) => void;
+}
+
+export function PagePreview({ pageUrl, width, height, onLoad, onError }: PagePreviewProps) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  const handleLoad = useCallback(() => {
+    setIsLoading(false);
+    setLoadError(null);
+    onLoad?.();
+  }, [onLoad]);
+
+  const handleError = useCallback(() => {
+    const errorMessage = "Unable to load page preview. The page may block embedding or require authentication.";
+    setIsLoading(false);
+    setLoadError(errorMessage);
+    onError?.(errorMessage);
+  }, [onError]);
+
+  useEffect(() => {
+    setIsLoading(true);
+    setLoadError(null);
+  }, [pageUrl]);
+
+  // Set a timeout to detect if iframe fails to load
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      if (isLoading) {
+        // If still loading after 10 seconds, assume it failed
+        setIsLoading(false);
+        // Don't set error - the page might still be loading slowly
+      }
+    }, 10000);
+
+    return () => clearTimeout(timer);
+  }, [pageUrl, isLoading]);
+
+  if (loadError) {
+    return (
+      <div
+        className="flex flex-col items-center justify-center bg-neutral-100 dark:bg-neutral-800 rounded-lg border border-neutral-200 dark:border-neutral-700"
+        style={{ width, height }}
+      >
+        <AlertCircle className="w-12 h-12 text-neutral-400 mb-4" />
+        <p className="text-sm text-neutral-500 dark:text-neutral-400 text-center max-w-md px-4">{loadError}</p>
+        <a
+          href={pageUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="mt-4 flex items-center gap-2 text-sm text-blue-500 hover:text-blue-600"
+        >
+          Open page in new tab
+          <ExternalLink className="w-4 h-4" />
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <div className="relative" style={{ width, height }}>
+      {isLoading && (
+        <div
+          className="absolute inset-0 flex items-center justify-center bg-neutral-100 dark:bg-neutral-800 rounded-lg"
+          style={{ width, height }}
+        >
+          <Loader2 className="w-8 h-8 animate-spin text-neutral-400" />
+        </div>
+      )}
+      <iframe
+        ref={iframeRef}
+        src={pageUrl}
+        width={width}
+        height={height}
+        className="rounded-lg border border-neutral-200 dark:border-neutral-700"
+        style={{
+          pointerEvents: "none",
+          opacity: isLoading ? 0 : 1,
+          transition: "opacity 0.2s ease-in-out",
+        }}
+        sandbox="allow-same-origin"
+        onLoad={handleLoad}
+        onError={handleError}
+        title="Page Preview"
+      />
+    </div>
+  );
+}
diff --git a/server/src/api/heatmap/getClickHeatmap.ts b/server/src/api/heatmap/getClickHeatmap.ts
new file mode 100644
index 000000000..05cbe7564
--- /dev/null
+++ b/server/src/api/heatmap/getClickHeatmap.ts
@@ -0,0 +1,39 @@
+import { FilterParams } from "@rybbit/shared";
+import { FastifyReply, FastifyRequest } from "fastify";
+import { clickHeatmapService } from "../../services/heatmap/clickHeatmapService.js";
+
+export interface GetClickHeatmapRequest {
+  Params: {
+    siteId: string;
+  };
+  Querystring: FilterParams<{
+    pathname: string;
+    viewportBreakpoint?: "mobile" | "tablet" | "desktop" | "all";
+    gridResolution?: string;
+  }>;
+}
+
+export async function getClickHeatmap(req: FastifyRequest<GetClickHeatmapRequest>, res: FastifyReply) {
+  const { pathname, viewportBreakpoint, gridResolution, ...filterParams } = req.query;
+  const siteId = Number(req.params.siteId);
+
+  if (!pathname) {
+    return res.status(400).send({ error: "pathname is required" });
+  }
+
+  try {
+    const result = await clickHeatmapService.getClickHeatmap(siteId, pathname, {
+      ...filterParams,
+      viewportBreakpoint: viewportBreakpoint || "all",
+      gridResolution: gridResolution ? Number(gridResolution) : 100,
+    });
+
+    return res.send({
+      data: result,
+      pathname,
+    });
+  } catch (error) {
+    console.error("Error fetching click heatmap:", error);
+    return res.status(500).send({ error: "Failed to fetch click heatmap data" });
+  }
+}
diff --git a/server/src/api/heatmap/getHeatmapPages.ts b/server/src/api/heatmap/getHeatmapPages.ts
new file mode 100644
index 000000000..e7f45c499
--- /dev/null
+++ b/server/src/api/heatmap/getHeatmapPages.ts
@@ -0,0 +1,31 @@
+import { FilterParams } from "@rybbit/shared";
+import { FastifyReply, FastifyRequest } from "fastify";
+import { clickHeatmapService } from "../../services/heatmap/clickHeatmapService.js";
+
+export interface GetHeatmapPagesRequest {
+  Params: {
+    siteId: string;
+  };
+  Querystring: FilterParams<{
+    limit?: string;
+  }>;
+}
+
+export async function getHeatmapPages(req: FastifyRequest<GetHeatmapPagesRequest>, res: FastifyReply) {
+  const { limit, ...filterParams } = req.query;
+  const siteId = Number(req.params.siteId);
+
+  try {
+    const pages = await clickHeatmapService.getHeatmapPages(siteId, {
+      ...filterParams,
+      limit: limit ? Number(limit) : 100,
+    });
+
+    return res.send({
+      data: pages,
+    });
+  } catch (error) {
+    console.error("Error fetching heatmap pages:", error);
+    return res.status(500).send({ error: "Failed to fetch heatmap pages" });
+  }
+}
diff --git a/server/src/api/heatmap/index.ts b/server/src/api/heatmap/index.ts
new file mode 100644
index 000000000..f4fc25e6f
--- /dev/null
+++ b/server/src/api/heatmap/index.ts
@@ -0,0 +1,2 @@
+export { getClickHeatmap } from "./getClickHeatmap.js";
+export { getHeatmapPages } from "./getHeatmapPages.js";
diff --git a/server/src/db/clickhouse/clickhouse.ts b/server/src/db/clickhouse/clickhouse.ts
index 4e53bb45f..0139356b0 100644
--- a/server/src/db/clickhouse/clickhouse.ts
+++ b/server/src/db/clickhouse/clickhouse.ts
@@ -168,6 +168,30 @@ export const initializeClickhouse = async () => {
       `,
   });
 
+  // Create session replay clicks table for heatmap data
+  // This stores click coordinates extracted during ingestion for efficient heatmap queries
+  await clickhouse.exec({
+    query: `
+      CREATE TABLE IF NOT EXISTS session_replay_clicks (
+        site_id UInt16,
+        session_id String,
+        timestamp DateTime64(3),
+        -- Click coordinates (viewport-relative)
+        x Float32,
+        y Float32,
+        -- Viewport dimensions for normalization
+        viewport_width UInt16,
+        viewport_height UInt16,
+        -- Click type: 2=Click, 4=DblClick
+        click_type UInt8
+      )
+      ENGINE = MergeTree()
+      PARTITION BY toYYYYMM(timestamp)
+      ORDER BY (site_id, timestamp)
+      TTL toDateTime(timestamp) + INTERVAL 30 DAY
+      `,
+  });
+
   // Create uptime monitor events table
   await clickhouse.exec({
     query: `
diff --git a/server/src/index.ts b/server/src/index.ts
index d3e80fe3c..c7efab59a 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -23,7 +23,6 @@ import {
   getEventNames,
   getEventProperties,
   getEvents,
-
   getFunnel,
   getFunnelStepSessions,
   getFunnels,
@@ -65,6 +64,7 @@ import {
   getSessionReplays,
   recordSessionReplay,
 } from "./api/sessionReplay/index.js";
+import { getClickHeatmap, getHeatmapPages } from "./api/heatmap/index.js";
 import {
   addSite,
   batchImportEvents,
@@ -274,6 +274,12 @@ async function sessionReplayRoutes(fastify: FastifyInstance) {
   fastify.delete("/sites/:siteId/session-replay/:sessionId", authSite, deleteSessionReplay);
 }
 
+async function heatmapRoutes(fastify: FastifyInstance) {
+  // Heatmaps
+  fastify.get("/sites/:siteId/heatmap/clicks", publicSite, getClickHeatmap);
+  fastify.get("/sites/:siteId/heatmap/pages", publicSite, getHeatmapPages);
+}
+
 async function sitesRoutes(fastify: FastifyInstance) {
   // Sites
   fastify.get("/sites/:siteId", publicSite, getSite);
@@ -363,6 +369,7 @@ async function stripeAdminRoutes(fastify: FastifyInstance) {
 async function apiRoutes(fastify: FastifyInstance) {
   await fastify.register(analyticsRoutes);
   await fastify.register(sessionReplayRoutes);
+  await fastify.register(heatmapRoutes);
   await fastify.register(sitesRoutes);
   await fastify.register(organizationsRoutes);
   await fastify.register(userRoutes);
diff --git a/server/src/services/heatmap/clickHeatmapService.ts b/server/src/services/heatmap/clickHeatmapService.ts
new file mode 100644
index 000000000..2b1bcb03f
--- /dev/null
+++ b/server/src/services/heatmap/clickHeatmapService.ts
@@ -0,0 +1,172 @@
+import { FilterParams } from "@rybbit/shared";
+import { clickhouse } from "../../db/clickhouse/clickhouse.js";
+import { getTimeStatement, processResults } from "../../api/analytics/utils/utils.js";
+
+export interface HeatmapDataPoint {
+  x: number; // 0-100 percentage
+  y: number; // 0-100 percentage
+  value: number; // click count
+}
+
+export interface ClickHeatmapResult {
+  points: HeatmapDataPoint[];
+  totalClicks: number;
+  uniqueSessions: number;
+}
+
+export interface HeatmapPage {
+  pathname: string;
+  clickCount: number;
+  sessionCount: number;
+}
+
+type ViewportBreakpoint = "mobile" | "tablet" | "desktop" | "all";
+
+const VIEWPORT_BREAKPOINTS = {
+  mobile: { max: 768 },
+  tablet: { min: 769, max: 1024 },
+  desktop: { min: 1025 },
+} as const;
+
+function getViewportCondition(breakpoint: ViewportBreakpoint): string {
+  if (breakpoint === "all") return "";
+
+  const bp = VIEWPORT_BREAKPOINTS[breakpoint];
+  if ("max" in bp && !("min" in bp)) {
+    return `AND viewport_width <= ${bp.max}`;
+  }
+  if ("min" in bp && "max" in bp) {
+    return `AND viewport_width >= ${bp.min} AND viewport_width <= ${bp.max}`;
+  }
+  if ("min" in bp && !("max" in bp)) {
+    return `AND viewport_width >= ${bp.min}`;
+  }
+  return "";
+}
+
+export class ClickHeatmapService {
+  /**
+   * Get aggregated click data for heatmap visualization
+   * Queries the session_replay_clicks table and normalizes coordinates to percentages
+   */
+  async getClickHeatmap(
+    siteId: number,
+    pathname: string,
+    options: FilterParams<{
+      viewportBreakpoint?: ViewportBreakpoint;
+      gridResolution?: number; // Number of grid cells (default 100 = 1% resolution)
+    }>
+  ): Promise<ClickHeatmapResult> {
+    const { viewportBreakpoint = "all", gridResolution = 100 } = options;
+
+    // Build time statement for filtering
+    const timeStatement = getTimeStatement(options).replace(/timestamp/g, "src.timestamp");
+    const viewportCondition = getViewportCondition(viewportBreakpoint).replace(/viewport_width/g, "src.viewport_width");
+
+    // Build pathname pattern for LIKE query
+    // Remove trailing slashes and handle exact match
+    const cleanPathname = pathname.replace(/\/+$/, "") || "/";
+    const pathnamePattern = cleanPathname === "/" ? "/" : `%${cleanPathname}%`;
+
+    const query = `
+      SELECT
+        ROUND(src.x / src.viewport_width * {gridResolution:UInt16}, 0) as x,
+        ROUND(src.y / src.viewport_height * {gridResolution:UInt16}, 0) as y,
+        COUNT(*) as value
+      FROM session_replay_clicks src
+      INNER JOIN session_replay_metadata srm ON src.session_id = srm.session_id AND src.site_id = srm.site_id
+      WHERE src.site_id = {siteId:UInt16}
+        AND src.viewport_width > 0
+        AND src.viewport_height > 0
+        AND src.x >= 0 AND src.y >= 0
+        AND src.x <= src.viewport_width
+        AND src.y <= src.viewport_height
+        AND srm.page_url LIKE {pathnamePattern:String}
+        ${viewportCondition}
+        ${timeStatement}
+      GROUP BY x, y
+      HAVING value >= 1
+      ORDER BY value DESC
+      LIMIT 10000
+    `;
+
+    const statsQuery = `
+      SELECT
+        COUNT(*) as totalClicks,
+        COUNT(DISTINCT src.session_id) as uniqueSessions
+      FROM session_replay_clicks src
+      INNER JOIN session_replay_metadata srm ON src.session_id = srm.session_id AND src.site_id = srm.site_id
+      WHERE src.site_id = {siteId:UInt16}
+        AND src.viewport_width > 0
+        AND src.viewport_height > 0
+        AND srm.page_url LIKE {pathnamePattern:String}
+        ${viewportCondition}
+        ${timeStatement}
+    `;
+
+    const [pointsResult, statsResult] = await Promise.all([
+      clickhouse.query({
+        query,
+        query_params: { siteId, pathnamePattern, gridResolution },
+        format: "JSONEachRow",
+      }),
+      clickhouse.query({
+        query: statsQuery,
+        query_params: { siteId, pathnamePattern },
+        format: "JSONEachRow",
+      }),
+    ]);
+
+    const points = await processResults<HeatmapDataPoint>(pointsResult);
+    const stats = await processResults<{ totalClicks: number; uniqueSessions: number }>(statsResult);
+
+    return {
+      points,
+      totalClicks: stats[0]?.totalClicks ?? 0,
+      uniqueSessions: stats[0]?.uniqueSessions ?? 0,
+    };
+  }
+
+  /**
+   * Get list of pages that have click data for heatmaps
+   * Returns pages sorted by click count
+   */
+  async getHeatmapPages(
+    siteId: number,
+    options: FilterParams<{
+      limit?: number;
+    }>
+  ): Promise<HeatmapPage[]> {
+    const { limit = 100 } = options;
+
+    const timeStatement = getTimeStatement(options).replace(/timestamp/g, "sre.timestamp");
+
+    // Query the dedicated session_replay_clicks table
+    // This table is populated during ingestion with click coordinates extracted from rrweb events
+    const query = `
+      SELECT
+        path(srm.page_url) as pathname,
+        COUNT(*) as clickCount,
+        COUNT(DISTINCT src.session_id) as sessionCount
+      FROM session_replay_clicks src
+      INNER JOIN session_replay_metadata srm ON src.session_id = srm.session_id AND src.site_id = srm.site_id
+      WHERE src.site_id = {siteId:UInt16}
+        ${timeStatement}
+      GROUP BY pathname
+      ORDER BY clickCount DESC
+      LIMIT {limit:UInt32}
+    `;
+
+    const result = await clickhouse.query({
+      query,
+      query_params: { siteId, limit },
+      format: "JSONEachRow",
+    });
+
+    const pages = await processResults<HeatmapPage>(result);
+
+    return pages;
+  }
+}
+
+export const clickHeatmapService = new ClickHeatmapService();
diff --git a/server/src/services/replay/sessionReplayIngestService.ts b/server/src/services/replay/sessionReplayIngestService.ts
index a2acc71aa..071d36889 100644
--- a/server/src/services/replay/sessionReplayIngestService.ts
+++ b/server/src/services/replay/sessionReplayIngestService.ts
@@ -117,12 +117,97 @@ export class SessionReplayIngestService {
       });
     }
 
+    // Extract and store click events for heatmap functionality
+    const clicksToInsert = this.extractClickEvents(
+      events,
+      siteId,
+      sessionId,
+      metadata?.viewportWidth || 0,
+      metadata?.viewportHeight || 0
+    );
+
+    if (clicksToInsert.length > 0) {
+      await clickhouse.insert({
+        table: "session_replay_clicks",
+        values: clicksToInsert,
+        format: "JSONEachRow",
+      });
+    }
+
     // Update or insert metadata
     if (metadata) {
       await this.updateSessionMetadata(siteId, sessionId, userId, identifiedUserId, metadata, requestMeta);
     }
   }
 
+  /**
+   * Extract click events from rrweb events for heatmap storage
+   * rrweb IncrementalSnapshot (type 3) with source 2 (MouseInteraction) and type 2 (Click) or 4 (DblClick)
+   */
+  private extractClickEvents(
+    events: Array<{ type: number | string; data: any; timestamp: number }>,
+    siteId: number,
+    sessionId: string,
+    viewportWidth: number,
+    viewportHeight: number
+  ): Array<{
+    site_id: number;
+    session_id: string;
+    timestamp: number;
+    x: number;
+    y: number;
+    viewport_width: number;
+    viewport_height: number;
+    click_type: number;
+  }> {
+    const clicks: Array<{
+      site_id: number;
+      session_id: string;
+      timestamp: number;
+      x: number;
+      y: number;
+      viewport_width: number;
+      viewport_height: number;
+      click_type: number;
+    }> = [];
+
+    for (const event of events) {
+      // Check if this is an IncrementalSnapshot (type 3)
+      if (event.type !== 3 && event.type !== "3") continue;
+
+      const data = event.data;
+      if (!data) continue;
+
+      // Check if this is a MouseInteraction (source 2)
+      if (data.source !== 2) continue;
+
+      // Check if this is a Click (type 2) or DblClick (type 4)
+      // rrweb MouseInteractions enum: MouseUp=0, MouseDown=1, Click=2, ContextMenu=3, DblClick=4, Focus=5, Blur=6, TouchStart=7, etc.
+      if (data.type !== 2 && data.type !== 4) continue;
+
+      // Extract coordinates
+      const x = data.x;
+      const y = data.y;
+
+      // Validate coordinates
+      if (typeof x !== "number" || typeof y !== "number") continue;
+      if (x < 0 || y < 0) continue;
+
+      clicks.push({
+        site_id: siteId,
+        session_id: sessionId,
+        timestamp: event.timestamp,
+        x,
+        y,
+        viewport_width: viewportWidth,
+        viewport_height: viewportHeight,
+        click_type: data.type,
+      });
+    }
+
+    return clicks;
+  }
+
   private async updateSessionMetadata(
     siteId: number,
     sessionId: string,