@mrrocket/sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this package. It follows semantic versioning; before 1.0 a minor version may change an API.
 
+## 0.2.0
+
+- **Session recordings** (rrweb 2.1.6 via `@rrweb/record`, pinned): recorded only with the visitor's own replay consent, separate from analytics and off by default: new `replay` prop and `setConsent({ replay })` (`setConsent` now also takes `{ analytics?, replay? }`; `useCockpit()` returns `replay`). The recorder is a dynamic import, loaded only when a visit records (about 26 KB gzip); pages without recording load about 1.9 KB more than 0.1.0.
+- Privacy defaults: all inputs masked; password, hidden and card fields and payment iframes never recorded; `data-ck-mask` masks text, `data-ck-block` leaves elements out; no canvas, video, fonts, inlined images or network bodies; console only at error level, clipped.
+- Sampling from the product's config (`replay.sampleRate`, default 0.1); other visits keep the last minute in memory and upload it on a JS error, a rage click or a `purchase…` / `checkout…` event. Chunks every 5 s or 64 KB, gzip'd, to `POST /api/sdk/replay`, `sendBeacon` on page hide, 30 minutes at most.
+- **Heatmaps:** `$click`, `$rageclick` and `$scroll` events under the normal analytics consent (`heatmaps` prop, default true). Labels only for links and buttons, never typed text.
+- New types `ReplayConfig`, `ConsentChoice`; `CockpitConfig.replay`.
+
 ## 0.1.0
 
 First public release on npm as `@mrrocket/sdk`, MIT licensed. Next.js lives under `@mrrocket/sdk/next`

package/README.md

@@ -2,7 +2,7 @@
 
 The MRRocket SDK. This release covers Next.js (App Router), imported from `@mrrocket/sdk/next`; other frameworks get their own entry in the same package (`@mrrocket/sdk/react` is next). One provider in your layout gives MRRocket page views, your events and A/B tests that the agents can run. MRRocket shows every variant of your real pages, because the SDK can render any variant on request.
 
-Status: 0.1.0, MIT licensed, compiled to ESM JavaScript with type declarations (no `transpilePackages`). Works with Next.js 15 and 16, React 19, on Node and on Cloudflare Workers (OpenNext). The source lives in the MRRocket repo (`prototype/web/packages/cockpit-next`).
+Status: 0.2.0, MIT licensed, compiled to ESM JavaScript with type declarations (no `transpilePackages`). Works with Next.js 15 and 16, React 19, on Node and on Cloudflare Workers (OpenNext). The source lives in the MRRocket repo (`prototype/web/packages/cockpit-next`).
 
 ## Install
 
@@ -202,6 +202,36 @@ Apps with RevenueCat: set the subscriber attribute `$mrr_ref` (and `$mrr_click`)
 
 The referral cookie is a marketing cookie: where the law asks for consent (EU, UK), it needs it. Withdrawing consent (leaving `"cookies"`) deletes it.
 
+## 11. Heatmaps
+
+Every click and the scroll depth of every page feed MRRocket › Heatmaps: `$click` (where it landed, the viewport and page size, a short CSS selector, a link's or button's label of at most 40 characters, and whether it hit anything clickable), `$rageclick` (the third quick click on one spot) and `$scroll` (the deepest point seen, sent when the page changes or hides). They go with your other events under the normal analytics consent, never contain typed text, and nothing inside `data-ck-mask` or `data-ck-block` gets a label. No replay consent needed: MRRocket shows them only as per-page aggregates.
+
+```tsx
+<CockpitProvider heatmaps={false}>{children}</CockpitProvider> // no click or scroll events
+```
+
+## 12. Session recordings
+
+Recordings of real visits (rrweb 2.1.6), for products whose recordings are on in MRRocket › Sessions. They need the **visitor's own consent**, separate from analytics and off by default:
+
+```tsx
+<CockpitProvider replay={allowedByBanner}>{children}</CockpitProvider>
+
+// or later, from your consent banner:
+const { setConsent } = useCockpit();
+setConsent({ replay: true });  // the visitor allowed "Session recordings"
+setConsent({ replay: false }); // declined or withdrew: stops and drops what was not sent
+```
+
+The recorder (about 26 KB gzip with rrweb) loads only when a visit records: product on, replay consent given, analytics not `"off"`, not a MRRocket preview. Pages without recording load nothing extra.
+
+- **Masked by default:** every input value becomes `*`. Never recorded: password, hidden and card fields (`autocomplete="cc-…"`, names with card/cvc/cvv), Stripe and PayPal iframes. No canvas, video, fonts or inlined images, no network bodies; console lines only at error level, clipped.
+- **Your markers:** `data-ck-mask` masks the text inside an element (a name, an email), `data-ck-block` leaves an element out entirely (a payment form).
+- **What uploads:** the product's sample rate (default 10 %) of sessions from their start. Every other recording visit keeps about the last minute in memory and uploads it only when something happens: a JS error, a rage click (3 clicks within 1 s on one spot), or a `track()` event whose name starts with `purchase` or `checkout`.
+- **How:** chunks every 5 s or 64 KB, gzip'd (`CompressionStream`), to `POST {host}/api/sdk/replay`; the last one with `sendBeacon` when the page hides. A recording ends after 30 minutes. It carries the SDK's session id and, after `identify()`, the user id, so MRRocket can delete a person's recordings.
+
+MRRocket keeps recordings 30 days by default (at most 90), in the EU. Add the recording paragraph to your privacy policy; Sessions' "Copy for AI" prompt adds the banner choice, the wiring and the paragraph for you.
+
 ## Privacy and consent
 
 ```tsx
@@ -220,6 +250,8 @@ The referral cookie is a marketing cookie: where the law asks for consent (EU, U
 - **`respectDnt`** (default false): when the browser sends Do Not Track or Global Privacy Control, nothing is sent or stored, whatever the consent.
 - **Sessions** end after 30 minutes without an event: in the `ck_sid` cookie with `"cookies"`, in memory otherwise (a reload starts a new session id).
 - Previews inside MRRocket (`ck_embed=1`) track nothing.
+- **Session recordings** need `replay` consent on top (see 12); `consent` alone never records.
+- **Heatmap clicks and scroll depth** follow `consent` like page views (see 11).
 
 ## What it sends
 
@@ -248,4 +280,6 @@ The referral cookie is a marketing cookie: where the law asks for consent (EU, U
 
 Answers `202 { ok: true, received, dropped }`; `400` bad body, `404` unknown key, `413` too large, `429` over 600 requests a minute per key. The server adds the country (from `x-vercel-ip-country` or `cf-ipcountry`) and browser, OS and device (from the user agent); the IP only feeds the daily hash. Bot user agents are not stored. `signup`, `checkout` and `purchase` feed Web analytics, `$identify` creates a person in People. Raw events are kept 90 days.
 
-`GET {host}/api/sdk/config?key=…` returns the experiments for the key.
+`GET {host}/api/sdk/config?key=…` returns the experiments for the key, and `replay: { sampleRate }` while the product records sessions.
+
+`POST {host}/api/sdk/replay` takes recording chunks: `{ key, sessionId, distinctId?, identified?, start, seq, consent: { replay: true }, trigger, enc: "gzip" | "json", data, meta }`, at most 1 MB per request. `403` without the consent flag or while the product's recordings are off; `409` once a recording passed 30 minutes or 20 MB (the SDK stops).

package/dist/capture.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Clicks and scroll depth for heatmaps, and the rage-click detector session recordings share. Small on purpose: it is
+ * part of every page that uses the provider. Runs under the normal analytics consent; it never reads what anyone typed.
+ *
+ * A click is described by where it landed (x in CSS pixels with the viewport width, y in page pixels with the page
+ * height), a short CSS selector and, for links and buttons only, a label of at most 40 characters. Nothing inside
+ * `data-ck-mask` or `data-ck-block` gets a label, form fields never do.
+ */
+/** Elements a click is meant for. A click on anything else is a dead click. */
+export declare const INTERACTIVE = "a[href],button,input,select,textarea,label,summary,[role=\"button\"],[role=\"link\"],[role=\"tab\"],[role=\"menuitem\"],[role=\"checkbox\"],[role=\"switch\"],[onclick],[data-ck-goal]";
+/** Text inside is masked in recordings and never becomes a click label. */
+export declare const MASK_SELECTOR = "[data-ck-mask]";
+/** Left out of recordings entirely (a placeholder of the same size) and never labelled. */
+export declare const BLOCK_ATTR_SELECTOR = "[data-ck-block]";
+export interface ClickInfo {
+    /** Pointer position: x in CSS pixels from the left of the viewport, y in page pixels from the top of the document. */
+    x: number;
+    y: number;
+    /** Viewport width and height, and the page height, in CSS pixels. */
+    vw: number;
+    vh: number;
+    docH: number;
+    /** A short CSS path, like `main > section.pricing > button`. Ids and classes only, never text. */
+    selector: string;
+    /** For links and buttons: what they say (aria-label, title or text), at most 40 characters; else "". */
+    label: string;
+    /** On a link, button or field; false is a dead click. */
+    interactive: boolean;
+}
+/** A selector for the element, three levels at most; stops early at an id. */
+export declare const selectorOf: (el: Element) => string;
+/** What a link or button says, never a field's value; "" inside masked or blocked parts. */
+export declare const labelOf: (el: Element) => string;
+/** The click's description, or null when it did not land on an element. */
+export declare const clickInfo: (e: MouseEvent) => ClickInfo | null;
+/**
+ * Three or more clicks within one second on the same spot (30 pixels) are a rage click. `push` answers true once per
+ * burst, on the third click.
+ */
+export declare class RageDetector {
+    private readonly windowMs;
+    private readonly radius;
+    private readonly count;
+    private clicks;
+    private fired;
+    constructor(windowMs?: number, radius?: number, count?: number);
+    push(x: number, y: number, t: number): boolean;
+}
+/** How far down the page the visitor has seen, 0 to 100. */
+export declare const seenDepth: () => number;

package/dist/capture.js

@@ -0,0 +1,91 @@
+// src/capture.ts
+var INTERACTIVE = 'a[href],button,input,select,textarea,label,summary,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"],[role="switch"],[onclick],[data-ck-goal]';
+var MASK_SELECTOR = "[data-ck-mask]";
+var BLOCK_ATTR_SELECTOR = "[data-ck-block]";
+var generated = /\d{4,}|^[a-z]{1,3}-[a-z0-9]{5,}$|^_|__|css-|^sc-|^jsx-/i;
+var part = (el) => {
+  const tag = el.tagName.toLowerCase();
+  if (el.id && !generated.test(el.id) && el.id.length <= 40) return `${tag}#${el.id}`;
+  const cls = typeof el.className === "string" ? el.className.split(/\s+/).filter((c) => c && !generated.test(c) && c.length <= 30 && !c.includes(":")) : [];
+  const base = cls.length ? `${tag}.${cls.slice(0, 2).join(".")}` : tag;
+  const same = el.parentElement ? [...el.parentElement.children].filter((c) => c.tagName === el.tagName) : [];
+  return same.length > 1 ? `${base}:nth-of-type(${same.indexOf(el) + 1})` : base;
+};
+var selectorOf = (el) => {
+  const out = [];
+  let cur = el;
+  while (cur && out.length < 3 && cur.tagName && cur.tagName !== "BODY" && cur.tagName !== "HTML") {
+    const p = part(cur);
+    out.unshift(p);
+    if (p.includes("#")) break;
+    cur = cur.parentElement;
+  }
+  return out.join(" > ").slice(0, 160);
+};
+var clean = (s) => (s ?? "").replace(/\s+/g, " ").trim().slice(0, 40);
+var labelOf = (el) => {
+  if (el.closest(`${MASK_SELECTOR},${BLOCK_ATTR_SELECTOR}`)) return "";
+  const tag = el.tagName.toLowerCase();
+  if (tag === "input") {
+    const type = (el.getAttribute("type") ?? "text").toLowerCase();
+    return type === "submit" || type === "button" ? clean(el.getAttribute("aria-label") ?? el.value) : clean(el.getAttribute("aria-label"));
+  }
+  if (tag === "select" || tag === "textarea") return clean(el.getAttribute("aria-label"));
+  return clean(el.getAttribute("aria-label") ?? el.getAttribute("title") ?? el.innerText ?? el.textContent);
+};
+var clickInfo = (e) => {
+  const target = e.target instanceof Element ? e.target : null;
+  if (!target) return null;
+  const hit = target.closest(INTERACTIVE);
+  const el = hit ?? target;
+  const doc = document.documentElement;
+  return {
+    x: Math.round(e.clientX),
+    y: Math.round(e.clientY + window.scrollY),
+    vw: window.innerWidth,
+    vh: window.innerHeight,
+    docH: Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0),
+    selector: selectorOf(el),
+    label: hit ? labelOf(hit) : "",
+    interactive: !!hit
+  };
+};
+var RageDetector = class {
+  constructor(windowMs = 1e3, radius = 30, count = 3) {
+    this.windowMs = windowMs;
+    this.radius = radius;
+    this.count = count;
+  }
+  windowMs;
+  radius;
+  count;
+  clicks = [];
+  fired = false;
+  push(x, y, t) {
+    const near = this.clicks.filter((c) => t - c.t <= this.windowMs && Math.hypot(c.x - x, c.y - y) <= this.radius);
+    if (near.length !== this.clicks.length) this.fired = false;
+    this.clicks = [...near, { x, y, t }];
+    if (this.clicks.length >= this.count && !this.fired) {
+      this.fired = true;
+      return true;
+    }
+    return false;
+  }
+};
+var seenDepth = () => {
+  const doc = document.documentElement;
+  const h = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);
+  if (!h) return 0;
+  return Math.min(100, Math.round((window.scrollY + window.innerHeight) / h * 100));
+};
+export {
+  BLOCK_ATTR_SELECTOR,
+  INTERACTIVE,
+  MASK_SELECTOR,
+  RageDetector,
+  clickInfo,
+  labelOf,
+  seenDepth,
+  selectorOf
+};
+//# sourceMappingURL=capture.js.map

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/capture.ts"],"sourcesContent":["/**\n * Clicks and scroll depth for heatmaps, and the rage-click detector session recordings share. Small on purpose: it is\n * part of every page that uses the provider. Runs under the normal analytics consent; it never reads what anyone typed.\n *\n * A click is described by where it landed (x in CSS pixels with the viewport width, y in page pixels with the page\n * height), a short CSS selector and, for links and buttons only, a label of at most 40 characters. Nothing inside\n * `data-ck-mask` or `data-ck-block` gets a label, form fields never do.\n */\n\n/** Elements a click is meant for. A click on anything else is a dead click. */\nexport const INTERACTIVE =\n    'a[href],button,input,select,textarea,label,summary,[role=\"button\"],[role=\"link\"],[role=\"tab\"],[role=\"menuitem\"],[role=\"checkbox\"],[role=\"switch\"],[onclick],[data-ck-goal]';\n/** Text inside is masked in recordings and never becomes a click label. */\nexport const MASK_SELECTOR = \"[data-ck-mask]\";\n/** Left out of recordings entirely (a placeholder of the same size) and never labelled. */\nexport const BLOCK_ATTR_SELECTOR = \"[data-ck-block]\";\n\nexport interface ClickInfo {\n    /** Pointer position: x in CSS pixels from the left of the viewport, y in page pixels from the top of the document. */\n    x: number;\n    y: number;\n    /** Viewport width and height, and the page height, in CSS pixels. */\n    vw: number;\n    vh: number;\n    docH: number;\n    /** A short CSS path, like `main > section.pricing > button`. Ids and classes only, never text. */\n    selector: string;\n    /** For links and buttons: what they say (aria-label, title or text), at most 40 characters; else \"\". */\n    label: string;\n    /** On a link, button or field; false is a dead click. */\n    interactive: boolean;\n}\n\n/** Ids and classes that look generated (hashes, long numbers) say nothing across builds. */\nconst generated = /\\d{4,}|^[a-z]{1,3}-[a-z0-9]{5,}$|^_|__|css-|^sc-|^jsx-/i;\n\nconst part = (el: Element) => {\n    const tag = el.tagName.toLowerCase();\n    if (el.id && !generated.test(el.id) && el.id.length <= 40) return `${tag}#${el.id}`;\n    const cls = typeof el.className === \"string\" ? el.className.split(/\\s+/).filter((c) => c && !generated.test(c) && c.length <= 30 && !c.includes(\":\")) : [];\n    const base = cls.length ? `${tag}.${cls.slice(0, 2).join(\".\")}` : tag;\n    // Siblings of the same kind (two plain buttons side by side) are told apart by their place.\n    const same = el.parentElement ? [...el.parentElement.children].filter((c) => c.tagName === el.tagName) : [];\n    return same.length > 1 ? `${base}:nth-of-type(${same.indexOf(el) + 1})` : base;\n};\n\n/** A selector for the element, three levels at most; stops early at an id. */\nexport const selectorOf = (el: Element) => {\n    const out: string[] = [];\n    let cur: Element | null = el;\n    while (cur && out.length < 3 && cur.tagName && cur.tagName !== \"BODY\" && cur.tagName !== \"HTML\") {\n        const p = part(cur);\n        out.unshift(p);\n        if (p.includes(\"#\")) break;\n        cur = cur.parentElement;\n    }\n    return out.join(\" > \").slice(0, 160);\n};\n\nconst clean = (s: string | null | undefined) => (s ?? \"\").replace(/\\s+/g, \" \").trim().slice(0, 40);\n\n/** What a link or button says, never a field's value; \"\" inside masked or blocked parts. */\nexport const labelOf = (el: Element) => {\n    if (el.closest(`${MASK_SELECTOR},${BLOCK_ATTR_SELECTOR}`)) return \"\";\n    const tag = el.tagName.toLowerCase();\n    if (tag === \"input\") {\n        const type = (el.getAttribute(\"type\") ?? \"text\").toLowerCase();\n        return type === \"submit\" || type === \"button\" ? clean(el.getAttribute(\"aria-label\") ?? (el as HTMLInputElement).value) : clean(el.getAttribute(\"aria-label\"));\n    }\n    if (tag === \"select\" || tag === \"textarea\") return clean(el.getAttribute(\"aria-label\"));\n    return clean(el.getAttribute(\"aria-label\") ?? el.getAttribute(\"title\") ?? (el as HTMLElement).innerText ?? el.textContent);\n};\n\n/** The click's description, or null when it did not land on an element. */\nexport const clickInfo = (e: MouseEvent): ClickInfo | null => {\n    const target = e.target instanceof Element ? e.target : null;\n    if (!target) return null;\n    const hit = target.closest(INTERACTIVE);\n    const el = hit ?? target;\n    const doc = document.documentElement;\n    return {\n        x: Math.round(e.clientX),\n        y: Math.round(e.clientY + window.scrollY),\n        vw: window.innerWidth,\n        vh: window.innerHeight,\n        docH: Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0),\n        selector: selectorOf(el),\n        label: hit ? labelOf(hit) : \"\",\n        interactive: !!hit,\n    };\n};\n\n/**\n * Three or more clicks within one second on the same spot (30 pixels) are a rage click. `push` answers true once per\n * burst, on the third click.\n */\nexport class RageDetector {\n    private clicks: { x: number; y: number; t: number }[] = [];\n    private fired = false;\n    constructor(\n        private readonly windowMs = 1000,\n        private readonly radius = 30,\n        private readonly count = 3,\n    ) {}\n    push(x: number, y: number, t: number) {\n        const near = this.clicks.filter((c) => t - c.t <= this.windowMs && Math.hypot(c.x - x, c.y - y) <= this.radius);\n        if (near.length !== this.clicks.length) this.fired = false;\n        this.clicks = [...near, { x, y, t }];\n        if (this.clicks.length >= this.count && !this.fired) {\n            this.fired = true;\n            return true;\n        }\n        return false;\n    }\n}\n\n/** How far down the page the visitor has seen, 0 to 100. */\nexport const seenDepth = () => {\n    const doc = document.documentElement;\n    const h = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);\n    if (!h) return 0;\n    return Math.min(100, Math.round(((window.scrollY + window.innerHeight) / h) * 100));\n};\n"],"mappings":"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","names":[]}

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 import { type AttributionMode } from "./referral.js";
-import { type CockpitConfig, type ConsentMode, type VariantId } from "./core.js";
+import { type CockpitConfig, type ConsentChoice, type ConsentMode, type VariantId } from "./core.js";
 export interface CockpitProviderProps {
     /** The product's public key from Cockpit › Settings › SDK. Safe in the browser. Default: `NEXT_PUBLIC_MRROCKET_KEY`. */
     apiKey?: string;
@@ -19,6 +19,17 @@ export interface CockpitProviderProps {
     consent?: ConsentMode;
     /** Send nothing when the browser asks not to be tracked (Do Not Track or Global Privacy Control). */
     respectDnt?: boolean;
+    /**
+     * The visitor's consent to session recordings, separate from analytics (default false). Recording also needs the
+     * product to record (Cockpit › Sessions) and analytics not "off". Without it nothing is recorded or buffered.
+     * Change it later with `setConsent({ replay })`.
+     */
+    replay?: boolean;
+    /**
+     * Clicks and scroll depth for Heatmaps (default true): where a click landed, a short selector and a link's or
+     * button's label, never typed text. Sent under the normal analytics consent as `$click`, `$rageclick` and `$scroll`.
+     */
+    heatmaps?: boolean;
     /** Ask visitors the surveys you run in Cockpit. Set false to switch them off. */
     surveys?: boolean;
     /**
@@ -38,8 +49,11 @@ export interface CockpitProviderProps {
  * `preview` forces variants for this render, for example from the `ck_preview` search param on the server,
  * so a Cockpit preview never flickers. Without it the provider reads the param itself after the first render.
  */
-export declare const CockpitProvider: ({ apiKey: apiKeyProp, host: hostProp, preview: forced, embedded: embeddedProp, config: bootstrapConfig, distinctId: bootstrapId, consent: consentProp, respectDnt, surveys, attribution, referralParam, children, }: CockpitProviderProps) => import("react").JSX.Element;
-/** `track`, `identify`, the consent mode and its setter, the visitor id and whether the experiments have loaded. */
+export declare const CockpitProvider: ({ apiKey: apiKeyProp, host: hostProp, preview: forced, embedded: embeddedProp, config: bootstrapConfig, distinctId: bootstrapId, consent: consentProp, respectDnt, replay: replayProp, heatmaps, surveys, attribution, referralParam, children, }: CockpitProviderProps) => import("react").JSX.Element;
+/**
+ * `track`, `identify`, the consent mode, the replay consent and their setter, the visitor id and whether the
+ * experiments have loaded. `setConsent("cookies")` sets the mode, `setConsent({ replay: true })` the replay consent.
+ */
 export declare const useCockpit: () => {
     track: (event: string, props?: Record<string, unknown>) => void;
     identify: (id: string, props?: Record<string, unknown>) => void;
@@ -47,7 +61,8 @@ export declare const useCockpit: () => {
     ready: boolean;
     embedded: boolean;
     consent: ConsentMode;
-    setConsent: (mode: ConsentMode) => void;
+    replay: boolean;
+    setConsent: (choice: ConsentChoice) => void;
 };
 /** The variant this visitor sees, for example `"control"` or `"a"`. Records the exposure. */
 export declare const useVariant: (key: string) => VariantId;

package/dist/client.js

@@ -5,6 +5,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { usePathname } from "next/navigation";
 import { Ctx, useCtx } from "./context.js";
 import { Survey, forgetStoredDismissals } from "./survey.js";
+import { RageDetector, clickInfo, seenDepth } from "./capture.js";
 import {
   DEFAULT_REFERRAL_DAYS,
   captureReferral,
@@ -118,6 +119,8 @@ var CockpitProvider = ({
   distinctId: bootstrapId,
   consent: consentProp = "cookieless",
   respectDnt = false,
+  replay: replayProp = false,
+  heatmaps = true,
   surveys = true,
   attribution = "consent",
   referralParam = "ref",
@@ -128,6 +131,7 @@ var CockpitProvider = ({
   const host = resolveHost(hostProp);
   const [config, setConfig] = useState(bootstrapConfig ?? null);
   const [consent, setConsentState] = useState(consentProp);
+  const [replayConsent, setReplayConsent] = useState(replayProp);
   const [mounted, setMounted] = useState(false);
   const [dnt, setDnt] = useState(false);
   const [visitor, setVisitor] = useState(null);
@@ -154,9 +158,11 @@ var CockpitProvider = ({
     setDnt(privacySignal());
     setMounted(true);
   }, []);
-  const setConsent = useCallback((mode) => {
+  const setConsent = useCallback((choice) => {
+    const { analytics: mode, replay } = typeof choice === "string" ? { analytics: choice, replay: void 0 } : choice;
     if (mode === "off") queue.current.length = 0;
-    setConsentState(mode);
+    if (mode) setConsentState(mode);
+    if (typeof replay === "boolean") setReplayConsent(replay);
   }, []);
   const lastProp = useRef(consentProp);
   useEffect(() => {
@@ -164,6 +170,12 @@ var CockpitProvider = ({
     lastProp.current = consentProp;
     setConsent(consentProp);
   }, [consentProp, setConsent]);
+  const lastReplayProp = useRef(replayProp);
+  useEffect(() => {
+    if (lastReplayProp.current === replayProp) return;
+    lastReplayProp.current = replayProp;
+    setConsent({ replay: replayProp });
+  }, [replayProp, setConsent]);
   const storedFor = useRef(null);
   useEffect(() => {
     if (!mounted) return;
@@ -230,12 +242,12 @@ var CockpitProvider = ({
       flush(true);
     };
   }, [flush]);
-  const live = useRef({ resolved: false, tracking, distinctId, sendId, persist: false });
-  live.current = { resolved: visitor !== null, tracking, distinctId, sendId, persist: visitor?.mode === "cookies" };
-  const record = useCallback((event, props, ts = Date.now()) => {
+  const live = useRef({ resolved: false, tracking, distinctId, sendId, persist: false, identified: false });
+  live.current = { resolved: visitor !== null, tracking, distinctId, sendId, persist: visitor?.mode === "cookies", identified: !!identified };
+  const record = useCallback((event, props, ts = Date.now(), url) => {
     const now = live.current;
     if (!now.resolved) {
-      early.current.push(() => record(event, props, ts));
+      early.current.push(() => record(event, props, ts, url));
       return;
     }
     if (!now.tracking) return;
@@ -246,13 +258,20 @@ var CockpitProvider = ({
       distinctId: now.sendId,
       sessionId: touchSession(now.persist),
       ts,
-      url: window.location.href,
+      url: url ?? window.location.href,
       referrer: page.referrer,
       ...page.utm,
       screen: { w: window.screen.width, h: window.screen.height }
     });
   }, []);
-  const track = useCallback((event, props) => record(event, props), [record]);
+  const replayer = useRef(null);
+  const track = useCallback(
+    (event, props) => {
+      record(event, props);
+      if (live.current.tracking) replayer.current?.event(event);
+    },
+    [record]
+  );
   const identify = useCallback(
     (id, props) => {
       const now = live.current;
@@ -261,8 +280,9 @@ var CockpitProvider = ({
         return;
       }
       const previous = now.sendId;
-      live.current = { ...now, distinctId: id, sendId: id };
+      live.current = { ...now, distinctId: id, sendId: id, identified: true };
       record("$identify", { ...props, id, ...previous && previous !== id ? { previousId: previous } : {} });
+      replayer.current?.identify(id);
       if (now.persist) writeCookie(ID_COOKIE, id, YEAR_S);
       setIdentified(id);
       setUser({ id, ...props });
@@ -319,24 +339,99 @@ var CockpitProvider = ({
   );
   useEffect(() => {
     enterPage();
+    replayer.current?.page(pathname);
   }, [pathname]);
   useEffect(() => {
     if (!tracking || lastPage.current === pathname) return;
     lastPage.current = pathname;
     track("$pageview", { path: pathname });
   }, [pathname, tracking, track]);
+  const rage = useRef(new RageDetector());
   useEffect(() => {
     const onClick = (e) => {
       const el = e.target?.closest("[data-ck-goal]");
       if (el?.dataset.ckGoal) track(el.dataset.ckGoal, { text: el.textContent?.trim().slice(0, 80) });
+      if (!live.current.tracking) return;
+      const c = clickInfo(e);
+      if (!c) return;
+      const raged = rage.current.push(c.x, c.y, Date.now());
+      replayer.current?.click(c, raged);
+      if (!heatmaps) return;
+      const props = { x: c.x, y: c.y, vw: c.vw, vh: c.vh, docH: c.docH, selector: c.selector, label: c.label, dead: !c.interactive };
+      record("$click", props);
+      if (raged) record("$rageclick", props);
     };
     document.addEventListener("click", onClick);
     return () => document.removeEventListener("click", onClick);
-  }, [track]);
+  }, [track, record, heatmaps]);
+  const depth = useRef(null);
+  useEffect(() => {
+    if (!heatmaps || !tracking || embedded) return;
+    const send = () => {
+      const d = depth.current;
+      if (d && d.max > 0) record("$scroll", { depth: d.max, docH: d.docH, vw: window.innerWidth, vh: window.innerHeight }, Date.now(), d.url);
+      depth.current = null;
+    };
+    const measure = () => {
+      const doc = document.documentElement;
+      const docH = Math.max(doc.scrollHeight, document.body?.scrollHeight ?? 0);
+      const max = seenDepth();
+      const href = window.location.href;
+      if (depth.current?.url !== href) depth.current = { url: href, max, docH };
+      else if (max > depth.current.max) depth.current = { url: href, max, docH };
+    };
+    measure();
+    let frame = 0;
+    const onScroll = () => {
+      if (frame) return;
+      frame = window.requestAnimationFrame(() => {
+        frame = 0;
+        measure();
+      });
+    };
+    const onHide = () => {
+      send();
+      flush(true);
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("pagehide", onHide);
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("pagehide", onHide);
+      window.cancelAnimationFrame(frame);
+      send();
+    };
+  }, [heatmaps, tracking, embedded, pathname, record, flush]);
+  const replayConfig = config?.replay;
+  const recording = tracking && replayConsent && !!replayConfig && !!apiKey;
+  useEffect(() => {
+    if (!recording || !replayConfig) return;
+    let active = true;
+    let handle = null;
+    void (typeof window === "undefined" ? Promise.resolve(null) : import("./replay.js")).then(
+      (m) => m?.startReplay({
+        host,
+        apiKey,
+        sessionId: touchSession(live.current.persist),
+        distinctId: live.current.sendId,
+        identified: live.current.identified,
+        sampleRate: replayConfig.sampleRate,
+        warn: warnOnce
+      })
+    ).then((h) => {
+      if (!active) h?.stop(true);
+      else replayer.current = handle = h ?? null;
+    }).catch(() => warnOnce("Session recording could not start (the recorder did not load)."));
+    return () => {
+      active = false;
+      handle?.stop(true);
+      if (replayer.current === handle) replayer.current = null;
+    };
+  }, [recording, replayConfig, host, apiKey]);
   const texts = useMemo(() => textChanges(config, distinctId, preview), [config, distinctId, preview]);
   const value = useMemo(
-    () => ({ apiKey, host, user, ready, distinctId, config, preview, embedded, consent, effectiveConsent, setConsent, texts, track, identify, expose }),
-    [apiKey, host, user, ready, distinctId, config, preview, embedded, consent, effectiveConsent, setConsent, texts, track, identify, expose]
+    () => ({ apiKey, host, user, ready, distinctId, config, preview, embedded, consent, effectiveConsent, replayConsent, setConsent, texts, track, identify, expose }),
+    [apiKey, host, user, ready, distinctId, config, preview, embedded, consent, effectiveConsent, replayConsent, setConsent, texts, track, identify, expose]
   );
   return /* @__PURE__ */ jsxs(Ctx.Provider, { value, children: [
     children,
@@ -344,8 +439,8 @@ var CockpitProvider = ({
   ] });
 };
 var useCockpit = () => {
-  const { track, identify, distinctId, ready, embedded, consent, setConsent } = useCtx();
-  return { track, identify, distinctId, ready, embedded, consent, setConsent };
+  const { track, identify, distinctId, ready, embedded, consent, replayConsent, setConsent } = useCtx();
+  return { track, identify, distinctId, ready, embedded, consent, replay: replayConsent, setConsent };
 };
 var useVariant = (key) => {
   const { config, distinctId, preview, expose } = useCtx();