@gemx-dev/clarity-js 0.8.88 → 0.8.90

package/src/data/upload.ts

@@ -23,6 +23,7 @@ import { signalsEvent } from "@src/data/signal";
 import { snapshot } from "@src/insight/snapshot";
 import * as dynamic from "@src/core/dynamic";
 import * as gemxUpload from "@src/data/gemx-upload";
+import * as gemx from "@src/data/gemx";
 
 let discoverBytes: number = 0;
 let playbackBytes: number = 0;
@@ -33,7 +34,6 @@ let transit: Transit;
 let active: boolean;
 let queuedTime: number = 0;
 let leanLimit = false;
-let hasGemxPayload = false;
 export let track: UploadData;
 
 export function start(): void {
@@ -41,7 +41,6 @@ export function start(): void {
     discoverBytes = 0;
     playbackBytes = 0;
     leanLimit = false;
-    hasGemxPayload = false;
     queuedTime = 0;
     playback = [];
     analysis = [];
@@ -114,27 +113,17 @@ export function queue(tokens: Token[], transmit: boolean = true): void {
     }
 }
 
-export function flush(): void {
+export function flush(type: 'gemx-snapshot' | 'gemx-unload'): void {
     if (!active) { return; }
     clearTimeout(timeout);
     timeout = null;
-    upload(true);
-}
-
-// Trigger an immediate non-beacon upload (used by gemx-discover after inject).
-// Unlike flush(), this does NOT set final=true, so playback data is never stripped.
-export function uploadNow(): void {
-    if (!active) { return; }
-    clearTimeout(timeout);
-    timeout = null;
-    upload(false);
+    upload(false, type);
 }
 
 // Inject pre-buffered tokens directly into playback as discover events.
-// Used by gemx-discover when trigger fires: all buffered Discover tokens are
+// Used by gemx-snapshot when trigger fires: all buffered Discover tokens are
 // counted towards discoverBytes so upload uses MinUploadDelay (fast path).
 export function inject(buffered: Token[][]): void {
-    hasGemxPayload = true;
     for (const tokens of buffered) {
         const e = JSON.stringify(tokens);
         discoverBytes += e.length;
@@ -157,7 +146,7 @@ export function stop(): void {
     active = false;
 }
 
-async function upload(final: boolean = false): Promise<void> {
+async function upload(final: boolean = false, type?: string): Promise<void> {
     if (!active) {
         return;
     }
@@ -167,7 +156,8 @@ async function upload(final: boolean = false): Promise<void> {
     // Check if we can send playback bytes over the wire or not
     // For better instrumentation coverage, we send playback bytes from second sequence onwards
     // And, we only send playback metric when we are able to send the playback bytes back to server
-    let sendPlaybackBytes = (hasGemxPayload || config.lean === false) && playbackBytes > 0 && (playbackBytes < Setting.MaxFirstPayloadBytes || envelope.data.sequence > 0);
+    const isGemxSnapshot = type === "gemx-snapshot";
+    let sendPlaybackBytes = (isGemxSnapshot || config.lean === false) && playbackBytes > 0 && (playbackBytes < Setting.MaxFirstPayloadBytes || envelope.data.sequence > 0);
     if (sendPlaybackBytes) { metric.max(Metric.Playback, BooleanFlag.True); }
 
     // CAUTION: Ensure "transmit" is set to false in the queue function for following events
@@ -184,7 +174,21 @@ async function upload(final: boolean = false): Promise<void> {
     let last = final === true;
     
     // In some cases envelope has null data because it's part of the shutdown process while there's one upload call queued which might introduce runtime error
-    if(!envelope.data) return;
+    if (!envelope.data) return;
+
+    const isDebug = gemx.isDebug();
+    if (!type && isDebug) {
+        const trackedEvents: [number, string][] = [
+            [Event.Click, "click"],
+            [Event.Scroll, "scroll"],
+        ];
+        const eventSet = new Set(analysis.map(item => (JSON.parse(item) as Token[])[1]));
+        const labels: string[] = [];
+        for (const [eventType, label] of trackedEvents) {
+            if (eventSet.has(eventType)) labels.push(label);
+        }
+        type = labels.length > 0 ? labels.join("-") : undefined;
+    }
 
     let e = JSON.stringify(envelope.envelope(last));
     let a = `[${analysis.join()}]`;
@@ -204,7 +208,7 @@ async function upload(final: boolean = false): Promise<void> {
     let payload = stringify(encoded);
     let zipped = last ? null : await compress(payload);
     metric.sum(Metric.TotalBytes, zipped ? zipped.length : payload.length);
-    send(payload, zipped, envelope.data.sequence, last);
+    send(payload, zipped, envelope.data.sequence, last, type);
 
     // Clear out events now that payload has been dispatched
     analysis = [];
@@ -213,7 +217,6 @@ async function upload(final: boolean = false): Promise<void> {
         playbackBytes = 0;
         discoverBytes = 0;
         leanLimit = false;
-        hasGemxPayload = false;
     }
 }
 
@@ -221,7 +224,7 @@ function stringify(encoded: EncodedPayload): string {
     return encoded.p.length > 0 ? `{"e":${encoded.e},"a":${encoded.a},"p":${encoded.p}}` : `{"e":${encoded.e},"a":${encoded.a}}`;
 }
 
-function send(payload: string, zipped: Uint8Array, sequence: number, beacon: boolean = false): void {
+function send(payload: string, zipped: Uint8Array, sequence: number, beacon: boolean = false, type?: string): void {
     // Upload data if a valid URL is defined in the config
     if (typeof config.upload === Constant.String) {
         const url = config.upload as string;
@@ -269,8 +272,7 @@ function send(payload: string, zipped: Uint8Array, sequence: number, beacon: boo
         }
     } else if (config.upload) {
         const callback = config.upload as UploadCallback;
-        const uploadType = hasGemxPayload ? "gemx-discover" : undefined;
-        callback(payload, uploadType);
+        callback(payload, type);
         done(sequence);
     }
 }

package/src/interaction/index.ts

@@ -49,7 +49,7 @@ const ALL_OBSERVE = { allRoots: [scroll], documentOnly: [click, clipboard, point
 let modules: Module[] = ALL;
 
 export function start(): void {
-    modules = config.mode === "gemx" ? GEMX : ALL;
+    modules = config?.mode === "gemx" ? GEMX : ALL;
     modules.forEach(m => m.start());
 }
 
@@ -58,7 +58,7 @@ export function stop(): void {
 }
 
 export function observe(root: Node): void {
-    const observeModules = config.mode === "gemx" ? GEMX_OBSERVE : ALL_OBSERVE;
+    const observeModules = config?.mode === "gemx" ? GEMX_OBSERVE : ALL_OBSERVE;
     observeModules.allRoots.forEach(m => m.observe(root));
     if (root.nodeType === Node.DOCUMENT_NODE) {
         observeModules.documentOnly.forEach(m => m.observe(root));

package/src/interaction/unload.ts

@@ -14,7 +14,7 @@ export function start(): void {
 }
 
 function beforeUnload(): void {
-    upload.flush();
+    upload.flush('gemx-unload');
 }
 
 function recompute(evt: PageTransitionEvent): void {

package/src/layout/{gemx-discover.ts → gemx-snapshot.ts}

@@ -36,30 +36,49 @@ function fire(): void {
     flush();
 }
 
-function schedule(trigger: { scrollDepthPercent?: number; clickCount?: number; activeTimeMs?: number; maxPlaybackBytes?: number }): void {
+function schedule(trigger: { scrollDepthPercent?: number; clickCount?: number; activeTimeMs?: number; delayMs?: number; maxPlaybackBytes?: number }): void {
     triggered = false;
-    let clickCount = 0;
+    let windowExpired = false;
+    let delayScheduled = false;
+
+    const scheduleDelayedFire = (type: 'scroll' | 'click'): void => {
+        if (delayScheduled || windowExpired) return;
+        delayScheduled = true;
+        console.log(`[GemX Snapshot] ${type} triggered:`);
+        setTimeout(fire, trigger.delayMs ?? 0);
+    };
+
+    if (trigger.activeTimeMs) {
+        setTimeout((): void => {
+            windowExpired = true;
+            scroll.onTrustedScroll(null);
+            click.onTrustedClick(null);
+        }, trigger.activeTimeMs);
+    }
 
     if (trigger.scrollDepthPercent) {
         scroll.onTrustedScroll((): void => {
-            const scrolled = window.scrollY + window.innerHeight;
-            const total = document.documentElement.scrollHeight;
-            if ((scrolled / total) * 100 >= trigger.scrollDepthPercent) { fire(); }
+            const docH = document.documentElement.scrollHeight;
+            const vpH = window.innerHeight;
+            const maxScrollY = docH - vpH;
+            if (maxScrollY <= 0) return;
+            
+            const scrollY = "pageYOffset" in window ? Math.round(window.pageYOffset) : Math.round((document.documentElement as HTMLElement).scrollTop);
+            const pct = Math.min(100, Math.round(scrollY / maxScrollY * 100));
+            if (pct >= trigger.scrollDepthPercent) { scheduleDelayedFire('scroll'); }
         });
     }
 
     if (trigger.clickCount) {
+        let clickCount = 0;
         click.onTrustedClick((): void => {
             clickCount++;
-            if (clickCount >= trigger.clickCount) { fire(); }
+            if (clickCount >= trigger.clickCount) { scheduleDelayedFire('click'); }
         });
     }
-
-    if (trigger.activeTimeMs) { setTimeout(fire, trigger.activeTimeMs); }
-    // maxPlaybackBytes trigger is handled via gemxUpload.start() callback above
 }
 
 function flush(): void {
     upload.inject(gemxUpload.drain());
-    upload.uploadNow();
+    upload.flush('gemx-snapshot');
 }

package/src/layout/index.ts

@@ -1,5 +1,5 @@
 import * as discover from "@src/layout/discover";
-import * as gemxDiscover from "@src/layout/gemx-discover";
+import * as gemxSnapshot from "@src/layout/gemx-snapshot";
 import * as doc from "@src/layout/document";
 import * as dom from "@src/layout/dom";
 import * as mutation from "@src/layout/mutation";
@@ -29,7 +29,7 @@ export function start(): void {
     // IMPORTANT: Start custom element detection BEFORE discover
     // This ensures pre-existing custom elements are registered before DOM traversal
     custom.start();
-    gemxDiscover.start(); // activates upload buffer before discover traverses
+    gemxSnapshot.start(); // activates upload buffer before discover traverses
     discover.start();
     style.start();
     animation.start();
@@ -43,5 +43,5 @@ export function stop(): void {
     style.stop();
     animation.stop();
     custom.stop();
-    gemxDiscover.stop();
+    gemxSnapshot.stop();
 }

package/src/layout/mutation.ts

@@ -20,6 +20,8 @@ import traverse from "@src/layout/traverse";
 import processNode from "./node";
 import config from "@src/core/config";
 import * as gemx from "@src/data/gemx";
+import * as gemxUpload from "@src/data/gemx-upload";
+
 
 let observers: Set<MutationObserver> = new Set();
 let mutations: MutationQueue[] = [];
@@ -129,7 +131,9 @@ async function processMutation(timer: Timer, mutation: MutationRecord, instance:
   let target = mutation.target;
 
   const ignoredClasses = gemx.get().ignoreMutationClassNames;
-  if (ignoredClasses.length > 0 && target instanceof Element) {
+  // Before processed snapshot, we need to check if the mutation is ignored
+  const isSnapshotProcessed = gemxUpload.isActive();
+  if (!isSnapshotProcessed && ignoredClasses.length > 0 && target instanceof Element) {
     const el = target as Element;
     if (ignoredClasses.some(cls => el.classList.contains(cls))) { return; }
   }

package/types/data.d.ts

@@ -598,11 +598,13 @@ export interface GCMConsentState {
 export interface DiscoverTrigger {
     scrollDepthPercent?: number; // trigger khi scroll đến X% chiều cao trang
     clickCount?: number;         // trigger sau X lần click
-    activeTimeMs?: number;       // trigger sau X ms kể từ window.load
+    activeTimeMs?: number;       // window tối đa để nhận trigger (ms)
+    delayMs?: number;            // delay thêm sau khi điều kiện thỏa trước khi fire
     maxPlaybackBytes?: number;   // trigger khi buffer đạt X bytes
 }
 
 export interface GemXConfig {
+    debug: boolean;
     excludeClassNames: string[];
     ignoreMutationClassNames: string[];
     discoverTrigger: DiscoverTrigger | null;

package/types/global.d.ts

@@ -2,6 +2,7 @@ declare global {
   interface Window {
       clarityOverrides?: { [key: string]: ((...args: any[]) => any) | undefined };
     GemXHeatmap?: {
+      debug: boolean;
       excludeClassNames: string[];
       ignoreMutationClassNames?: string[];
       discoverTrigger?: {