@gemx-dev/clarity-js 0.8.67 → 0.8.69

package/src/layout/dom.ts

@@ -1,6 +1,6 @@
 import { Privacy } from "@clarity-types/core";
 import { Code, Setting, Severity } from "@clarity-types/data";
-import { Constant, Mask, NodeInfo, NodeMeta, NodeValue, Selector, SelectorInput, Source } from "@clarity-types/layout";
+import { Constant, NodeInfo, NodeMeta, NodeValue, Selector, SelectorInput, Source } from "@clarity-types/layout";
 import config from "@src/core/config";
 import { bind } from "@src/core/event";
 import hash from "@src/core/hash";
@@ -9,6 +9,7 @@ import * as internal from "@src/diagnostic/internal";
 import { removeObserver } from "@src/layout/node";
 import * as region from "@src/layout/region";
 import * as selector from "@src/layout/selector";
+import { MaskTextList, MaskDisableList, MaskExcludeList, MaskTagsList } from "./constants";
 let index: number = 1;
 let nodesMap: Map<Number, Node> = null; // Maps id => node to retrieve further node details using id.
 let values: NodeValue[] = [];
@@ -16,10 +17,10 @@ let updateMap: number[] = [];
 let hashMap: { [hash: string]: number } = {};
 let override = [];
 let unmask = [];
-let maskText = [];
-let maskExclude = [];
-let maskDisable = [];
-let maskTags = [];
+let maskText: string[] = [];
+let maskExclude: string[] = [];
+let maskDisable: string[] = [];
+let maskTags: string[] = [];
 
 // The WeakMap object is a collection of key/value pairs in which the keys are weakly referenced
 let idMap: WeakMap<Node, number> = null; // Maps node => id.
@@ -44,10 +45,10 @@ function reset(): void {
     hashMap = {};
     override = [];
     unmask = [];
-    maskText = Mask.Text.split(Constant.Comma);
-    maskExclude = Mask.Exclude.split(Constant.Comma);
-    maskDisable = Mask.Disable.split(Constant.Comma);
-    maskTags = Mask.Tags.split(Constant.Comma);
+    maskText = MaskTextList;
+    maskExclude = MaskExcludeList;
+    maskDisable = MaskDisableList;
+    maskTags = MaskTagsList;
     nodesMap = new Map();
     idMap = new WeakMap();
     iframeMap = new WeakMap();

package/src/layout/encode.ts

@@ -105,7 +105,7 @@ export default async function (type: Event, timer: Timer = null, ts: number = nu
                                 case "attributes":
                                     for (let attr in data[key]) {
                                         if (data[key][attr] !== undefined) {
-                                            tokens.push(attribute(attr, data[key][attr], privacy));
+                                            tokens.push(attribute(attr, data[key][attr], privacy, data.tag));
                                         }
                                     }
                                     break;
@@ -149,6 +149,9 @@ function str(input: number): string {
     return input.toString(36);
 }
 
-function attribute(key: string, value: string, privacy: Privacy): string {
+function attribute(key: string, value: string, privacy: Privacy, tag: string): string {
+    if (key === Constant.Href && tag === Constant.LinkTag) {
+        return `${key}=${value}`;
+    }
     return `${key}=${scrub.text(value, key.indexOf(Constant.DataAttribute) === 0 ? Constant.DataAttribute : key, privacy)}`;
 }

package/src/layout/index.ts

@@ -20,17 +20,19 @@ export function start(): void {
     region.start();
     dom.start();
     if (config.delayDom) {
-        // Lazy load layout module as part of page load time performance improvements experiment 
+        // Lazy load layout module as part of page load time performance improvements experiment
         bind(window, 'load', () => {
             mutation.start();
         });
     } else {
         mutation.start();
     }
+    // IMPORTANT: Start custom element detection BEFORE discover
+    // This ensures pre-existing custom elements are registered before DOM traversal
+    custom.start();
     discover.start();
     style.start();
     animation.start();
-    custom.start();
 }
 
 export function stop(): void {

package/src/layout/mutation.ts

@@ -352,7 +352,7 @@ function proxyStyleRules(win: any): void {
   // by injecting CSS using insertRule API vs. appending text node. A side effect of
   // using javascript API is that it doesn't trigger DOM mutation and therefore we
   // need to override the insertRule API and listen for changes manually.
-  if (win.clarityOverrides.InsertRule === undefined) {
+  if ("CSSStyleSheet" in win && win.CSSStyleSheet && win.CSSStyleSheet.prototype && win.clarityOverrides.InsertRule === undefined) {
     win.clarityOverrides.InsertRule = win.CSSStyleSheet.prototype.insertRule;
     win.CSSStyleSheet.prototype.insertRule = function (): number {
       if (core.active()) {
@@ -362,7 +362,7 @@ function proxyStyleRules(win: any): void {
     };
   }
 
-  if ("CSSMediaRule" in win && win.clarityOverrides.MediaInsertRule === undefined) {
+  if ("CSSMediaRule" in win && win.CSSMediaRule && win.CSSMediaRule.prototype && win.clarityOverrides.MediaInsertRule === undefined) {
     win.clarityOverrides.MediaInsertRule = win.CSSMediaRule.prototype.insertRule;
     win.CSSMediaRule.prototype.insertRule = function (): number {
       if (core.active()) {
@@ -372,7 +372,7 @@ function proxyStyleRules(win: any): void {
     };
   }
 
-  if (win.clarityOverrides.DeleteRule === undefined) {
+  if ("CSSStyleSheet" in win && win.CSSStyleSheet && win.CSSStyleSheet.prototype && win.clarityOverrides.DeleteRule === undefined) {
     win.clarityOverrides.DeleteRule = win.CSSStyleSheet.prototype.deleteRule;
     win.CSSStyleSheet.prototype.deleteRule = function (): void {
       if (core.active()) {
@@ -382,7 +382,7 @@ function proxyStyleRules(win: any): void {
     };
   }
 
-  if ("CSSMediaRule" in win && win.clarityOverrides.MediaDeleteRule === undefined) {
+  if ("CSSMediaRule" in win && win.CSSMediaRule && win.CSSMediaRule.prototype && win.clarityOverrides.MediaDeleteRule === undefined) {
     win.clarityOverrides.MediaDeleteRule = win.CSSMediaRule.prototype.deleteRule;
     win.CSSMediaRule.prototype.deleteRule = function (): void {
       if (core.active()) {
@@ -395,7 +395,7 @@ function proxyStyleRules(win: any): void {
   // Add a hook to attachShadow API calls
   // In case we are unable to add a hook and browser throws an exception,
   // reset attachShadow variable and resume processing like before
-  if (win.clarityOverrides.AttachShadow === undefined) {
+  if ("Element" in win && win.Element && win.Element.prototype && win.clarityOverrides.AttachShadow === undefined) {
     win.clarityOverrides.AttachShadow = win.Element.prototype.attachShadow;
     try {
       win.Element.prototype.attachShadow = function (): ShadowRoot {

package/src/layout/selector.ts

@@ -1,7 +1,8 @@
 import { Character } from "../../types/data";
 import { Constant, Selector, SelectorInput } from "../../types/layout";
+import { ExcludeClassNamesList } from "./constants";
 
-const excludeClassNames = Constant.ExcludeClassNames.split(Constant.Comma);
+const excludeClassNames = ExcludeClassNamesList;
 
 let extraExcludeClassNames: string[] = [];
 let selectorMap: { [selector: string]: number[] } = {};

package/test/consentv2.test.ts

@@ -57,9 +57,10 @@ const clarityJsPath = join(__dirname, "../build/clarity.min.js");
 /**
  * Sets up a cookie mock for data: URLs which don't support cookies natively.
  * Handles both cookie setting and deletion (via max-age or empty values).
+ * @param initialCookieValue - Optional initial cookie value (e.g., "marketing_id=abc123")
  */
-function setupCookieMock() {
-    let cookieStore = "";
+function setupCookieMock(initialCookieValue?: string): void {
+    let cookieStore = initialCookieValue || "";
     Object.defineProperty(document, "cookie", {
         get: () => cookieStore,
         set: (value: string) => {
@@ -101,7 +102,7 @@ test.describe("consentv2 - Production API", () => {
     // ========================
 
     test("implicit denied: track=false results in denied consent", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state (before Clarity starts) - no cookies should exist
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -263,7 +264,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 explicit denial: track=false → denied/denied remains without cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -333,7 +334,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 mixed consent: track=false → denied analytics, granted ads no cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -400,7 +401,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 mixed consent: track=false → granted analytics, denied ads sets cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -468,7 +469,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 grants consent: track=false → granted/granted sets cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -573,7 +574,7 @@ test.describe("consentv2 - Production API", () => {
     // ========================
 
     test("implicit granted: track=true results in granted consent", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -648,7 +649,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 revokes consent: track=true → denied/denied deletes cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -750,7 +751,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 mixed consent: track=true → granted analytics, denied ads keeps cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -817,7 +818,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 mixed consent: track=true → denied analytics, granted ads deletes cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -887,7 +888,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consentv2 maintains consent: track=true → granted/granted keeps cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -998,7 +999,7 @@ test.describe("consentv2 - Production API", () => {
     // ========================
 
     test("consent v1: track=false → consent(true) grants consent and sets cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -1064,7 +1065,7 @@ test.describe("consentv2 - Production API", () => {
     });
 
     test("consent v1: track=true → consent(false) revokes consent and deletes cookies", async ({ page }) => {
-        await page.evaluate(setupCookieMock);
+        await page.evaluate(setupCookieMock as () => void);
 
         // Verify initial state - no cookies before Clarity starts
         const initialState = await page.evaluate(({ sessionKey, cookieKey }) => {
@@ -1160,5 +1161,149 @@ test.describe("consentv2 - Production API", () => {
         expect(consentResult.clskCookieValue).toBe("");
         expect(consentResult.clckCookieValue).toBe("");
     });
-});
 
+    // ========================
+    // Config cookies tests
+    // ========================
+
+    interface ConfigCookieTestOptions {
+        track: boolean;
+        grantConsentAfterStart?: boolean;
+        denyConsentAfterStart?: boolean;
+    }
+
+    interface ConfigCookieTestResult {
+        containsCookieValue: boolean;
+        beforeChangeContainsCookie?: boolean;
+        afterChangeContainsCookie?: boolean;
+    }
+
+    /**
+     * Helper to run config cookie tests with consistent setup.
+     * Sets up cookie mock with marketing_id=abc123 and returns whether the cookie value appears in payloads.
+     */
+    async function runConfigCookieTest(page: any, options: ConfigCookieTestOptions): Promise<ConfigCookieTestResult> {
+        // Set up cookie mock with initial marketing cookie before evaluating test logic
+        await page.evaluate(setupCookieMock as (initialValue: string) => void, "marketing_id=abc123");
+
+        const result = await page.evaluate((opts: ConfigCookieTestOptions) => {
+
+            return new Promise((resolve) => {
+                const payloadsBefore: string[] = [];
+                const payloadsAfter: string[] = [];
+                let phase = "before";
+
+                (window as any).clarity("start", {
+                    projectId: "test",
+                    track: opts.track,
+                    cookies: ["marketing_id"],
+                    upload: (payload: string) => {
+                        if (phase === "before") {
+                            payloadsBefore.push(payload);
+                        } else {
+                            payloadsAfter.push(payload);
+                        }
+                    }
+                });
+
+                const hasConsentChange = opts.grantConsentAfterStart || opts.denyConsentAfterStart;
+                // For denial tests, use longer delay to ensure initial upload completes before denial
+                const consentChangeDelay = opts.denyConsentAfterStart
+                    ? (window as any).CONSENT_CALLBACK_TIMEOUT / 2
+                    : (window as any).COOKIE_SETUP_DELAY;
+
+                if (hasConsentChange) {
+                    setTimeout(() => {
+                        phase = "after";
+                        const adStorage = opts.grantConsentAfterStart ? "granted" : "denied";
+                        const analyticsStorage = opts.grantConsentAfterStart ? "granted" : "denied";
+                        (window as any).clarity("consentv2", { ad_Storage: adStorage, analytics_Storage: analyticsStorage });
+                    }, consentChangeDelay);
+                }
+
+                // For denial tests, wait longer to allow for restart
+                const totalTimeout = opts.denyConsentAfterStart
+                    ? consentChangeDelay + (window as any).CONSENT_CALLBACK_TIMEOUT
+                    : (window as any).CONSENT_CALLBACK_TIMEOUT;
+
+                setTimeout(() => {
+                    const allPayloads = [...payloadsBefore, ...payloadsAfter].join("");
+                    resolve({
+                        containsCookieValue: allPayloads.includes("abc123"),
+                        beforeChangeContainsCookie: payloadsBefore.join("").includes("abc123"),
+                        afterChangeContainsCookie: payloadsAfter.join("").includes("abc123")
+                    });
+                }, totalTimeout);
+            });
+        }, options);
+
+        return result as ConfigCookieTestResult;
+    }
+
+    test("config cookies: track=true logs config cookies as variables", async ({ page }) => {
+        const result = await runConfigCookieTest(page, { track: true });
+        expect(result.containsCookieValue).toBe(true);
+    });
+
+    test("config cookies: track=false does not log config cookies", async ({ page }) => {
+        const result = await runConfigCookieTest(page, { track: false });
+        expect(result.containsCookieValue).toBe(false);
+    });
+
+    test("config cookies: track=false then consentv2 grants consent logs config cookies", async ({ page }) => {
+        const result = await runConfigCookieTest(page, { track: false, grantConsentAfterStart: true });
+        expect(result.containsCookieValue).toBe(true);
+    });
+
+    test("config cookies: track=true then consentv2 denies consent does not log cookies after restart", async ({ page }) => {
+        const result = await runConfigCookieTest(page, { track: true, denyConsentAfterStart: true });
+        // Before denial, cookies should be logged (track=true, implicit granted)
+        expect(result.beforeChangeContainsCookie).toBe(true);
+        // After restart with denied consent, cookies should NOT be logged
+        expect(result.afterChangeContainsCookie).toBe(false);
+    });
+
+    test("GCM error handling: handles misconfigured GTM gracefully", async ({ page }) => {
+        await page.evaluate(setupCookieMock as () => void);
+
+        const result = await page.evaluate(({ clarityJs }) => {
+            return new Promise<{ errorWasThrown: boolean }>((resolve) => {
+                let errorWasThrown = false;
+
+                // Mock GTM with misconfigured consent state
+                (window as any).google_tag_data = {
+                    ics: {
+                        addListener: function(_events: string[], callback: () => void) {
+                            setTimeout(() => callback(), 100);
+                        },
+                        // getConsentState throws error due to uninitialized internal state
+                        getConsentState: function() {
+                            errorWasThrown = true;
+                            throw new TypeError("Cannot read properties of undefined (reading 'usedContainerScopedDefaults')");
+                        }
+                    }
+                };
+
+                // Load and execute Clarity
+                eval(clarityJs);
+
+                // Start Clarity with track=true
+                (window as any).clarity("start", {
+                    projectId: "test",
+                    track: true,
+                    upload: false
+                });
+
+                // Wait for callback to be triggered and error to be thrown
+                setTimeout(() => {
+                    resolve({
+                        errorWasThrown
+                    });
+                }, 500);
+            });
+        }, { clarityJs: readFileSync(clarityJsPath, "utf-8") });
+
+        // Verify error was thrown and handled gracefully (test success proves it was caught)
+        expect(result.errorWasThrown).toBe(true);
+    });
+});

package/types/core.d.ts

@@ -141,6 +141,7 @@ export interface Config {
     conversions?: boolean;
     includeSubdomains?: boolean;
     modules?: string[];
+    diagnostics?: boolean;
     excludeClassNames?: string[];
     externalSession?: boolean;
     userId?: string;

package/types/data.d.ts

@@ -264,6 +264,7 @@ export const enum Setting {
     PlaybackBytesLimit = 10 * 1024 * 1024, // 10MB
     CollectionLimit = 128, // Number of unique entries for dimensions
     ClickPrecision = 32767, // 2^15 - 1
+    ClickParentTraversal = 10, // Maximum number of parent elements to traverse when computing relative click coordinates
     BoxPrecision = 100, // Up to 2 decimal points (e.g. 34.56)
     ScriptErrorLimit = 5, // Do not send the same script error more than 5 times per page
     DimensionLimit = 256, // Do not extract dimensions which are over 256 characters

package/types/interaction.d.ts

@@ -11,6 +11,14 @@ export const enum BrowsingContext {
     Top = 3
 }
 
+export const enum ClickSource {
+    Undefined = 0,
+    FirstParty = 1,
+    ThirdParty = 2,
+    Eval = 3,
+    Unknown = 4
+}
+
 export const enum Setting {
     LookAhead = 500, // 500ms
     InputLookAhead = 1000, // 1s
@@ -131,6 +139,7 @@ export interface ClickData {
     tag: string;
     class: string;
     id: string;
+    source: ClickSource;
 }
 
 export interface TextInfo {

package/types/layout.d.ts

@@ -56,13 +56,6 @@ export const enum RegionVisibility {
     ScrolledToEnd = 13
 }
 
-export const enum Mask {
-    Text = "address,password,contact",
-    Disable = "radio,checkbox,range,button,reset,submit",
-    Exclude = "password,secret,pass,social,ssn,code,hidden",
-    Tags = "INPUT,SELECT,TEXTAREA"
-}
-
 export const enum Constant {
     Empty = "",
     SvgPrefix = "svg:",
@@ -95,6 +88,7 @@ export const enum Constant {
     Object = "object",
     Function = "function",
     StyleTag = "STYLE",
+    LinkTag = "LINK",
     InputTag = "INPUT",
     IFrameTag = "IFRAME",
     ImageTag = "IMG",
@@ -128,7 +122,6 @@ export const enum Constant {
     ogType = "og:type",
     ogTitle = "og:title",
     SvgStyle = "svg:style",
-    ExcludeClassNames = "load,active,fixed,visible,focus,show,collaps,animat",
     StyleSheet = "stylesheet"
 }
 

package/types/performance.d.ts

@@ -1,5 +1,8 @@
 /* Helper Interface */
 
+export const enum FunctionNames {
+    ClickSource = 1,
+}
 
 // Reference: https://wicg.github.io/netinfo/#networkinformation-interface
 export interface NavigatorConnection extends EventTarget {