@gemx-dev/clarity-js 0.8.39

package/src/layout/style.ts

@@ -0,0 +1,160 @@
+import { Event } from "@clarity-types/data";
+import { StyleSheetOperation, StyleSheetState } from "@clarity-types/layout";
+import { time } from "@src/core/time";
+import { shortid } from "@src/data/metadata";
+import encode from "@src/layout/encode";
+import { getId } from "@src/layout/dom";
+import * as core from "@src/core";
+import config from "@src/core/config";
+import { getCssRules } from "./node";
+
+export let sheetUpdateState: StyleSheetState[] = [];
+export let sheetAdoptionState: StyleSheetState[] = [];
+const styleSheetId = 'claritySheetId';
+let styleSheetMap = {};
+let styleTimeMap: {[key: string]: number} = {};
+let documentNodes = [];
+let createdSheetIds = [];
+
+function proxyStyleRules(win: any) {
+    if ((config.lean && config.lite) || win === null || win === undefined) {
+        return;
+    }
+    
+    win.clarityOverrides = win.clarityOverrides || {};
+
+    if (win['CSSStyleSheet'] && win.CSSStyleSheet.prototype) {
+        if (win.clarityOverrides.replace === undefined) { 
+            win.clarityOverrides.replace = win.CSSStyleSheet.prototype.replace; 
+            win.CSSStyleSheet.prototype.replace = function(): Promise<CSSStyleSheet> {
+                if (core.active()) {
+                    // if we haven't seen this stylesheet on this page yet, wait until the checkDocumentStyles has found it
+                    // and attached the sheet to a document. This way the timestamp of the style sheet creation will align
+                    // to when it is used in the document rather than potentially being misaligned during the traverse process.
+                    if (createdSheetIds.indexOf(this[styleSheetId]) > -1) {
+                        trackStyleChange(time(), this[styleSheetId], StyleSheetOperation.Replace, arguments[0]);
+                    }
+                }
+                return win.clarityOverrides.replace.apply(this, arguments);
+            };
+        }
+
+        if (win.clarityOverrides.replaceSync === undefined) { 
+            win.clarityOverrides.replaceSync = win.CSSStyleSheet.prototype.replaceSync; 
+            win.CSSStyleSheet.prototype.replaceSync = function(): void {
+                if (core.active()) {
+                    // if we haven't seen this stylesheet on this page yet, wait until the checkDocumentStyles has found it
+                    // and attached the sheet to a document. This way the timestamp of the style sheet creation will align
+                    // to when it is used in the document rather than potentially being misaligned during the traverse process.
+                    if (createdSheetIds.indexOf(this[styleSheetId]) > -1) {
+                        trackStyleChange(time(), this[styleSheetId], StyleSheetOperation.ReplaceSync, arguments[0]);
+                    }                
+                }
+                return win.clarityOverrides.replaceSync.apply(this, arguments);
+            };
+        }
+    }   
+}
+
+export function start(): void {
+    proxyStyleRules(window);
+}
+
+export function checkDocumentStyles(documentNode: Document, timestamp: number): void {
+    if (config.lean && config.lite) { return; }
+
+    if (documentNodes.indexOf(documentNode) === -1) {
+        documentNodes.push(documentNode);
+        if (documentNode.defaultView) {
+            proxyStyleRules(documentNode.defaultView);
+        }
+    }
+    timestamp = timestamp || time();
+    if (!documentNode?.adoptedStyleSheets) {
+        // if we don't have adoptedStyledSheets on the Node passed to us, we can short circuit.
+        return;
+    }
+    let currentStyleSheets: string[] = [];
+    for (var styleSheet of documentNode.adoptedStyleSheets) {
+        // If we haven't seen this style sheet on this page yet, we create a reference to it for the visualizer.
+        // For SPA or times in which Clarity restarts on a given page, our visualizer would lose context
+        // on the previously created style sheet for page N-1.
+        // Then we synthetically call replaceSync with its contents to bootstrap it
+        if (!styleSheet[styleSheetId] || createdSheetIds.indexOf(styleSheet[styleSheetId]) === -1) {
+            styleSheet[styleSheetId] = shortid();
+            createdSheetIds.push(styleSheet[styleSheetId]);
+            trackStyleChange(timestamp, styleSheet[styleSheetId], StyleSheetOperation.Create);
+            trackStyleChange(timestamp, styleSheet[styleSheetId], StyleSheetOperation.ReplaceSync, getCssRules(styleSheet));
+        }
+
+        currentStyleSheets.push(styleSheet[styleSheetId]);
+    }
+
+    let documentId = getId(documentNode, true);
+    if (!styleSheetMap[documentId]) {
+        styleSheetMap[documentId] = [];
+    }
+    if (!arraysEqual(currentStyleSheets, styleSheetMap[documentId])) {
+        // Using -1 to signify the root document node as we don't track that as part of our nodeMap
+        trackStyleAdoption(timestamp, documentNode == document ? -1 : getId(documentNode), StyleSheetOperation.SetAdoptedStyles, currentStyleSheets);
+        styleSheetMap[documentId] = currentStyleSheets;
+        styleTimeMap[documentId] = timestamp;
+    }
+}
+
+export function compute(): void {
+    for (var documentNode of documentNodes) {
+        var docId = documentNode == document ? -1 : getId(documentNode);
+        let ts = docId in styleTimeMap ? styleTimeMap[docId] : null;
+        checkDocumentStyles(documentNode, ts);
+    }
+}
+
+export function reset(): void {
+    sheetAdoptionState = [];
+    sheetUpdateState = [];
+}
+
+export function stop(): void {
+    styleSheetMap = {};
+    styleTimeMap = {};
+    documentNodes = [];
+    createdSheetIds = [];
+    reset();
+}
+
+function trackStyleChange(time: number, id: string, operation: StyleSheetOperation, cssRules?: string): void {
+    sheetUpdateState.push({
+        time,
+        event: Event.StyleSheetUpdate,
+        data: {
+            id,
+            operation,
+            cssRules
+        }
+    });
+
+    encode(Event.StyleSheetUpdate);
+}
+
+function trackStyleAdoption(time: number, id: number, operation: StyleSheetOperation, newIds: string[]): void {
+    sheetAdoptionState.push({
+        time,
+        event: Event.StyleSheetAdoption,
+        data: {
+            id,
+            operation,
+            newIds
+        }
+    });
+
+    encode(Event.StyleSheetAdoption);
+}
+
+function arraysEqual(a: string[], b: string[]): boolean {
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    return a.every((value, index) => value === b[index]);
+}

package/src/layout/target.ts

@@ -0,0 +1,32 @@
+import { Privacy } from "@clarity-types/core";
+import { Event } from "@clarity-types/data";
+import { TargetMetadata } from "@clarity-types/layout";
+import * as fraud from "@src/diagnostic/fraud";
+import * as region from "@src/layout/region";
+import * as dom from "@src/layout/dom";
+import * as mutation from "@src/layout/mutation";
+
+export function target(evt: UIEvent): Node {
+    let path = evt.composed && evt.composedPath ? evt.composedPath() : null;
+    let node = (path && path.length > 0 ? path[0] : evt.target) as Node;
+    mutation.active(); // Mark active periods of time so mutations can continue uninterrupted
+    return node && node.nodeType === Node.DOCUMENT_NODE ? (node as Document).documentElement : node;
+}
+
+export function metadata(node: Node, event: Event, text: string = null): TargetMetadata {
+    // If the node is null, we return a reserved value for id: 0. Valid assignment of id begins from 1+.
+    let output: TargetMetadata = { id: 0, hash: null, privacy: Privacy.Text };
+    if (node) {
+        let value = dom.get(node);
+        if (value !== null) {
+            let metadata = value.metadata;
+            output.id = value.id;
+            output.hash = value.hash;
+            output.privacy = metadata.privacy;
+            if (value.region) { region.track(value.region, event); }
+            if (metadata.fraud) { fraud.check(metadata.fraud, value.id, text || value.data.value); }
+        }
+    }
+
+    return output;
+}

package/src/layout/traverse.ts

@@ -0,0 +1,28 @@
+import { Task, Timer } from "@clarity-types/core";
+import { Source } from "@clarity-types/layout";
+import * as task from "@src/core/task";
+import node from "@src/layout/node";
+
+export default async function(root: Node, timer: Timer, source: Source, timestamp: number): Promise<void> {
+    let queue = [root];
+    while (queue.length > 0) {
+        let entry = queue.shift();
+        let next = entry.firstChild;
+
+        while (next) {
+            queue.push(next);
+            next = next.nextSibling;
+        }
+      
+        // Check the status of current task to see if we should yield before continuing
+        let state = task.state(timer);
+        if (state === Task.Wait) { state = await task.suspend(timer); }
+        if (state === Task.Stop) { break; }
+
+        // Check if processing a node gives us a pointer to one of its sub nodes for traversal
+        // E.g. an element node may give us a pointer to traverse shadowDom if shadowRoot property is set
+        // Or, an iframe from the same origin could give a pointer to it's document for traversing contents of iframe.
+        let subnode = node(entry, source, timestamp);
+        if (subnode) { queue.push(subnode); }
+    }
+}

package/src/performance/blank.ts

@@ -0,0 +1,10 @@
+export * from "@src/insight/blank";
+
+export let keys = [];
+
+/* Intentionally blank module with empty code */
+export function hashText(): void {}
+export function trigger(): void {}
+export function track(): void {}
+export function event(): void {}
+export function register(): void {}

package/src/performance/encode.ts

@@ -0,0 +1,31 @@
+import {Event, Token} from "@clarity-types/data";
+import { time } from "@src/core/time";
+import { queue } from "@src/data/upload";
+import * as navigation from "@src/performance/navigation";
+
+export default async function(type: Event): Promise<void> {
+    let t = time();
+    let tokens: Token[] = [t, type];
+    switch (type) {
+        case Event.Navigation:
+            tokens.push(navigation.data.fetchStart);
+            tokens.push(navigation.data.connectStart);
+            tokens.push(navigation.data.connectEnd);
+            tokens.push(navigation.data.requestStart);
+            tokens.push(navigation.data.responseStart);
+            tokens.push(navigation.data.responseEnd);
+            tokens.push(navigation.data.domInteractive);
+            tokens.push(navigation.data.domComplete);
+            tokens.push(navigation.data.loadEventStart);
+            tokens.push(navigation.data.loadEventEnd);
+            tokens.push(navigation.data.redirectCount);
+            tokens.push(navigation.data.size);
+            tokens.push(navigation.data.type);
+            tokens.push(navigation.data.protocol);
+            tokens.push(navigation.data.encodedSize);
+            tokens.push(navigation.data.decodedSize);
+            navigation.reset();
+            queue(tokens);
+            break;
+    }
+}

package/src/performance/index.ts

@@ -0,0 +1,12 @@
+import * as navigation from "@src/performance/navigation";
+import * as observer from "@src/performance/observer";
+
+export function start(): void {
+    navigation.reset();
+    observer.start();
+}
+
+export function stop(): void {
+    observer.stop();
+    navigation.reset();
+}

package/src/performance/interaction.ts

@@ -0,0 +1,125 @@
+import { PerformanceEventTiming, Interaction } from '@clarity-types/data';
+
+// Estimate variables to keep track of interactions
+let interactionCountEstimate = 0;
+let minKnownInteractionId = Infinity;
+let maxKnownInteractionId = 0;
+
+let prevInteractionCount = 0; // Used to track interaction count between pages
+
+const MAX_INTERACTIONS_TO_CONSIDER = 10; // Maximum number of interactions we consider for INP
+const DEFAULT_DURATION_THRESHOLD = 40; // Threshold to ignore very short interactions
+
+// List to store the longest interaction events
+const longestInteractionList: Interaction[] = [];
+// Map to track interactions by their ID, ensuring we handle duplicates
+const longestInteractionMap: Map<number, Interaction> = new Map();
+
+/**
+ * Update the approx number of interactions estimate count if the interactionCount is not supported.
+ * The difference between `maxKnownInteractionId` and `minKnownInteractionId` gives us a rough range of how many interactions have occurred.
+ * Dividing by 7 helps approximate the interaction count more accurately, since interaction IDs are spread out across a large range.
+ */
+const countInteractions = (entry: PerformanceEventTiming) => {
+  if ('interactionCount' in performance) {
+    interactionCountEstimate = performance.interactionCount as number;
+    return;
+  }
+
+  if (entry.interactionId) {
+    minKnownInteractionId = Math.min(
+      minKnownInteractionId,
+      entry.interactionId
+    );
+    maxKnownInteractionId = Math.max(
+      maxKnownInteractionId,
+      entry.interactionId
+    );
+
+    interactionCountEstimate = maxKnownInteractionId
+      ? (maxKnownInteractionId - minKnownInteractionId) / 7 + 1
+      : 0;
+  }
+};
+
+const getInteractionCount = () => {
+  return interactionCountEstimate || 0;
+};
+
+const getInteractionCountForNavigation = () => {
+  return getInteractionCount() - prevInteractionCount;
+};
+
+/**
+ * Estimates the 98th percentile (P98) of the longest interactions by selecting
+ * the candidate interaction based on the current interaction count.
+ * Dividing by 50 is a heuristic to estimate the 98th percentile (P98) interaction.
+ * This assumes one out of every 50 interactions represents the P98 interaction.
+ * By dividing the total interaction count by 50, we get an index to approximate 
+ * the slowest 2% of interactions, helping identify a likely P98 candidate.
+ */
+export const estimateP98LongestInteraction = () => {
+  if(!longestInteractionList.length){
+    return -1;
+  }
+
+  const candidateInteractionIndex = Math.min(
+    longestInteractionList.length - 1,
+    Math.floor(getInteractionCountForNavigation() / 50)
+  );
+
+  return longestInteractionList[candidateInteractionIndex].latency;
+};
+
+/**
+ * Resets the interaction tracking, usually called after navigation to a new page.
+ */
+export const resetInteractions = () => {
+  prevInteractionCount = getInteractionCount();
+  longestInteractionList.length = 0;
+  longestInteractionMap.clear();
+};
+
+/**
+ * Processes a PerformanceEventTiming entry by updating the longest interaction list.
+ */
+export const processInteractionEntry = (entry: PerformanceEventTiming) => {
+  // Ignore entries with 0 interactionId or very short durations
+  if (!entry.interactionId || entry.duration < DEFAULT_DURATION_THRESHOLD) {
+    return;
+  }
+
+  countInteractions(entry);
+
+  const minLongestInteraction =
+    longestInteractionList[longestInteractionList.length - 1];
+
+  const existingInteraction = longestInteractionMap.get(entry.interactionId!);
+
+  // Either update existing, add new, or replace shortest interaction if necessary
+  if (
+    existingInteraction ||
+    longestInteractionList.length < MAX_INTERACTIONS_TO_CONSIDER ||
+    entry.duration > minLongestInteraction?.latency
+  ) {
+    if (!existingInteraction) {
+      const interaction = {
+        id: entry.interactionId,
+        latency: entry.duration,
+      };
+      longestInteractionMap.set(interaction.id, interaction);
+      longestInteractionList.push(interaction);
+    } else if (entry.duration > existingInteraction.latency) {
+      existingInteraction.latency = entry.duration;
+    }
+
+    longestInteractionList.sort((a, b) => b.latency - a.latency);
+
+    // Trim the list to the maximum number of interactions to consider
+    if (longestInteractionList.length > MAX_INTERACTIONS_TO_CONSIDER) {
+      longestInteractionList
+        .splice(MAX_INTERACTIONS_TO_CONSIDER)
+        .forEach((i) => longestInteractionMap.delete(i.id));
+    }
+  }
+};

package/src/performance/navigation.ts

@@ -0,0 +1,31 @@
+import { Event } from "@clarity-types/data";
+import { NavigationData } from "@clarity-types/performance";
+import encode from "./encode";
+
+export let data: NavigationData = null;
+
+export function reset(): void {
+    data = null;
+}
+
+export function compute(entry: PerformanceNavigationTiming): void {
+    data = {
+        fetchStart: Math.round(entry.fetchStart),
+        connectStart: Math.round(entry.connectStart),
+        connectEnd: Math.round(entry.connectEnd),
+        requestStart: Math.round(entry.requestStart),
+        responseStart: Math.round(entry.responseStart),
+        responseEnd: Math.round(entry.responseEnd),
+        domInteractive: Math.round(entry.domInteractive),
+        domComplete: Math.round(entry.domComplete),
+        loadEventStart: Math.round(entry.loadEventStart),
+        loadEventEnd: Math.round(entry.loadEventEnd),
+        redirectCount: Math.round(entry.redirectCount),
+        size: entry.transferSize ? entry.transferSize : 0,
+        type: entry.type,
+        protocol: entry.nextHopProtocol,
+        encodedSize: entry.encodedBodySize ? entry.encodedBodySize : 0,
+        decodedSize: entry.decodedBodySize ? entry.decodedBodySize : 0
+    };
+    encode(Event.Navigation);
+}

package/src/performance/observer.ts

@@ -0,0 +1,112 @@
+import { Code, Constant, Dimension, Metric, Severity, PerformanceEventTiming } from "@clarity-types/data";
+import config from "@src/core/config";
+import { bind } from "@src/core/event";
+import measure from "@src/core/measure";
+import { setTimeout } from "@src/core/timeout";
+import * as dimension from "@src/data/dimension";
+import * as metric from "@src/data/metric";
+import * as internal from "@src/diagnostic/internal";
+import * as navigation from "@src/performance/navigation";
+import * as interaction from "@src/performance/interaction";
+
+let observer: PerformanceObserver;
+const types: string[] = [Constant.Navigation, Constant.Resource, Constant.LongTask, Constant.FID, Constant.CLS, Constant.LCP, Constant.PerformanceEventTiming];
+
+export function start(): void {
+    // Capture connection properties, if available
+    if (navigator && navigator["connection"]) {
+        dimension.log(Dimension.ConnectionType, navigator["connection"]["effectiveType"]);
+    }
+
+    // Check the browser support performance observer as a pre-requisite for any performance measurement
+    if (window["PerformanceObserver"] && PerformanceObserver.supportedEntryTypes) {
+        // Start monitoring performance data after page has finished loading.
+        // If the document.readyState is not yet complete, we intentionally call observe using a setTimeout.
+        // This allows us to capture loadEventEnd on navigation timeline.
+        if (document.readyState !== "complete") {
+            bind(window, "load", setTimeout.bind(this, observe, 0));
+        } else { observe(); }
+    } else { internal.log(Code.PerformanceObserver, Severity.Info); }
+}
+
+function observe(): void {
+    // Some browsers will throw an error for unsupported entryType, e.g. "layout-shift"
+    // In those cases, we log it as a warning and continue with rest of the Clarity processing
+    try {
+        if (observer) { observer.disconnect(); }
+        observer = new PerformanceObserver(measure(handle) as PerformanceObserverCallback);
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe
+        // "buffered" flag indicates whether buffered entries should be queued into the observer's buffer.
+        // It must only be used only with the "type" option, and cannot be used with entryTypes.
+        // This is why we need to individually "observe" each supported type
+        for (let x of types) {
+            if (PerformanceObserver.supportedEntryTypes.indexOf(x) >= 0) {
+                // Initialize CLS with a value of zero. It's possible (and recommended) for sites to not have any cumulative layout shift.
+                // In those cases, we want to still initialize the metric in Clarity
+                if (x === Constant.CLS) { metric.sum(Metric.CumulativeLayoutShift, 0); }
+                observer.observe({type: x, buffered: true});
+            }
+        }
+    } catch { internal.log(Code.PerformanceObserver, Severity.Warning); }
+}
+
+function handle(entries: PerformanceObserverEntryList): void {
+    process(entries.getEntries());
+}
+
+function process(entries: PerformanceEntryList): void {
+    let visible = "visibilityState" in document ? document.visibilityState === "visible" : true;
+    for (let i = 0; i < entries.length; i++) {
+        let entry = entries[i];
+        switch (entry.entryType) {
+            case Constant.Navigation:
+                navigation.compute(entry as PerformanceNavigationTiming);
+                break;
+            case Constant.Resource:
+                let name = entry.name;
+                dimension.log(Dimension.NetworkHosts, host(name));
+                if (name === config.upload || name === config.fallback) { metric.max(Metric.UploadTime, entry.duration); }
+                break;
+            case Constant.LongTask:
+                metric.count(Metric.LongTaskCount);
+                break;
+            case Constant.FID:
+                if (visible) { metric.max(Metric.FirstInputDelay, entry["processingStart"] - entry.startTime); }
+                break;
+            case Constant.PerformanceEventTiming:
+                if (visible && 'PerformanceEventTiming' in window &&  'interactionId' in PerformanceEventTiming.prototype)
+                {
+                    interaction.processInteractionEntry(entry as PerformanceEventTiming); 
+                    // Logging it as dimension because we're always looking for the last value.
+                    dimension.log(Dimension.InteractionNextPaint, interaction.estimateP98LongestInteraction().toString()); 
+                }
+                break;
+            case Constant.CLS:
+                // Scale the value to avoid sending back floating point number
+                if (visible && !entry["hadRecentInput"]) { metric.sum(Metric.CumulativeLayoutShift, entry["value"] * 1000); }
+                break;
+            case Constant.LCP:
+                if (visible) { metric.max(Metric.LargestPaint, entry.startTime); }
+                break;
+        }
+    }
+}
+
+export function stop(): void {
+    if (observer) { observer.disconnect(); }
+    observer = null;
+    interaction.resetInteractions();
+    anchorCache = null;
+}
+
+// Cached anchor element for optimal performance & memory management
+let anchorCache: HTMLAnchorElement | null = null;
+
+function host(url: string): string {
+    if (!anchorCache) {
+        anchorCache = document.createElement("a");
+    }
+
+    anchorCache.href = url;
+    return anchorCache.host;
+}

package/src/queue.ts

@@ -0,0 +1,33 @@
+import { Constant } from "@clarity-types/data";
+import * as clarity from "@src/clarity";
+
+const w = window; 
+const c = Constant.Clarity;
+
+export function setup() {
+    // Start queuing up calls while Clarity is inactive and we are in a browser enviornment    
+    if (typeof w !== "undefined") {
+        w[c] = function() {
+            (w[c].q = w[c].q || []).push(arguments);
+            // if the start function was called, don't queue it and instead process the queue
+            arguments[0] === "start" && w[c].q.unshift(w[c].q.pop()) && process();
+        };
+    }
+}
+
+export function process() {
+    if (typeof w !== "undefined") {
+        // Do not execute or reset global "clarity" variable if a version of Clarity is already running on the page
+        if (w[c] && w[c].v) { return console.warn("Error CL001: Multiple Clarity tags detected."); }
+
+        // Expose clarity in a browser environment
+        // To be efficient about queuing up operations while Clarity is wiring up, we expose clarity.*(args) => clarity(*, args);
+        // This allows us to reprocess any calls that we missed once Clarity is available on the page
+        // Once Clarity script bundle is loaded on the page, we also initialize a "v" property that holds current version
+        // We use the presence or absence of "v" to determine if we are attempting to run a duplicate instance
+        let queue = w[c] ? (w[c].q || []) : [];
+        w[c] = function(method: string, ...args: any[]): void { return clarity[method](...args); }
+        w[c].v = clarity.version;
+        while (queue.length > 0) { w[c](...queue.shift()); }
+    }
+}