@aranova/tracking-react 0.17.2 → 0.17.3

package/dist/index.d.mts

@@ -349,6 +349,7 @@ type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
 declare const pageExitMetadataSchema: z.ZodObject<{
     dwell_ms: z.ZodNumber;
     max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+    scroll_baseline_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     page: z.ZodObject<{
         path: z.ZodString;
     }, "strict", z.ZodTypeAny, {
@@ -362,12 +363,14 @@ declare const pageExitMetadataSchema: z.ZodObject<{
     };
     dwell_ms: number;
     max_scroll_percent: number | null;
+    scroll_baseline_percent?: number | null | undefined;
 }, {
     page: {
         path: string;
     };
     dwell_ms: number;
     max_scroll_percent: number | null;
+    scroll_baseline_percent?: number | null | undefined;
 }>;
 type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
 /**
@@ -934,6 +937,7 @@ declare const EVENT_REGISTRY: {
         readonly metadataSchema: z.ZodObject<{
             dwell_ms: z.ZodNumber;
             max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+            scroll_baseline_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             page: z.ZodObject<{
                 path: z.ZodString;
             }, "strict", z.ZodTypeAny, {
@@ -947,12 +951,14 @@ declare const EVENT_REGISTRY: {
             };
             dwell_ms: number;
             max_scroll_percent: number | null;
+            scroll_baseline_percent?: number | null | undefined;
         }, {
             page: {
                 path: string;
             };
             dwell_ms: number;
             max_scroll_percent: number | null;
+            scroll_baseline_percent?: number | null | undefined;
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };

package/dist/index.d.ts

@@ -349,6 +349,7 @@ type MultiPageSessionConfig = z.infer<typeof multiPageSessionConfigSchema>;
 declare const pageExitMetadataSchema: z.ZodObject<{
     dwell_ms: z.ZodNumber;
     max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+    scroll_baseline_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     page: z.ZodObject<{
         path: z.ZodString;
     }, "strict", z.ZodTypeAny, {
@@ -362,12 +363,14 @@ declare const pageExitMetadataSchema: z.ZodObject<{
     };
     dwell_ms: number;
     max_scroll_percent: number | null;
+    scroll_baseline_percent?: number | null | undefined;
 }, {
     page: {
         path: string;
     };
     dwell_ms: number;
     max_scroll_percent: number | null;
+    scroll_baseline_percent?: number | null | undefined;
 }>;
 type PageExitMetadata = z.infer<typeof pageExitMetadataSchema>;
 /**
@@ -934,6 +937,7 @@ declare const EVENT_REGISTRY: {
         readonly metadataSchema: z.ZodObject<{
             dwell_ms: z.ZodNumber;
             max_scroll_percent: z.ZodNullable<z.ZodNumber>;
+            scroll_baseline_percent: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
             page: z.ZodObject<{
                 path: z.ZodString;
             }, "strict", z.ZodTypeAny, {
@@ -947,12 +951,14 @@ declare const EVENT_REGISTRY: {
             };
             dwell_ms: number;
             max_scroll_percent: number | null;
+            scroll_baseline_percent?: number | null | undefined;
         }, {
             page: {
                 path: string;
             };
             dwell_ms: number;
             max_scroll_percent: number | null;
+            scroll_baseline_percent?: number | null | undefined;
         }>;
         readonly configSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     };

package/dist/index.js

@@ -726,9 +726,9 @@ function resolveConversionConfig(options) {
     }
   }
   function notifyResolved() {
-    const listeners = [...resolveListeners];
+    const listeners2 = [...resolveListeners];
     resolveListeners.clear();
-    for (const listener of listeners) {
+    for (const listener of listeners2) {
       try {
         listener();
       } catch {
@@ -1496,6 +1496,14 @@ var pageExitMetadataSchema = import_zod7.z.object({
   // null = left without any scroll signal; floor is 0 so a valid 0% is never
   // rejected (a single bad field 422s the whole keepalive beacon batch).
   max_scroll_percent: import_zod7.z.number().int().min(0).max(100).nullable(),
+  // The gating baseline: the fraction of the page visible at load with
+  // zero scrolling — or, for pages that grew after the post-paint snapshot
+  // (skeleton/streaming renders), the first-scroll position that
+  // established it. null = page had no scrollable range, or the segment
+  // ended before the snapshot. `.optional()` is load-bearing: SDK builds
+  // predating this field keep POSTing page_exit without the key —
+  // requiring it would 422 whole keepalive beacon batches.
+  scroll_baseline_percent: import_zod7.z.number().int().min(0).max(100).nullable().optional(),
   page: import_zod7.z.object({
     path: import_zod7.z.string()
   }).strict()
@@ -1765,6 +1773,97 @@ function attachSpecificPageVisit(client, config) {
   };
 }
 
+// ../tracking-core/src/triggers/navigation.ts
+var listeners = /* @__PURE__ */ new Set();
+var restorePatch = null;
+function notify() {
+  for (const listener of listeners) listener();
+}
+function notifyDeferred() {
+  setTimeout(notify, 0);
+}
+function installPatch() {
+  const originalPushState = history.pushState;
+  const originalReplaceState = history.replaceState;
+  function patchedPushState(...args) {
+    originalPushState.apply(this, args);
+    notifyDeferred();
+  }
+  function patchedReplaceState(...args) {
+    originalReplaceState.apply(this, args);
+    notifyDeferred();
+  }
+  history.pushState = patchedPushState;
+  history.replaceState = patchedReplaceState;
+  window.addEventListener("popstate", notify);
+  restorePatch = () => {
+    history.pushState = originalPushState;
+    history.replaceState = originalReplaceState;
+    window.removeEventListener("popstate", notify);
+    restorePatch = null;
+  };
+}
+function onHistoryChange(listener) {
+  if (listeners.size === 0) installPatch();
+  listeners.add(listener);
+  return () => {
+    if (!listeners.delete(listener)) return;
+    if (listeners.size === 0) restorePatch?.();
+  };
+}
+
+// ../tracking-core/src/triggers/scroll-measurement.ts
+var BOTTOM_EPSILON_PX = 2;
+function measureScrollPercent() {
+  const root = document.scrollingElement ?? document.documentElement;
+  const scrollHeight = root.scrollHeight;
+  const clientHeight = root.clientHeight;
+  if (scrollHeight <= 0 || clientHeight <= 0) return null;
+  if (scrollHeight <= clientHeight + BOTTOM_EPSILON_PX) return null;
+  const maxTop = scrollHeight - clientHeight;
+  const scrollTop = Math.min(Math.max(root.scrollTop, 0), maxTop);
+  if (scrollTop + clientHeight >= scrollHeight - BOTTOM_EPSILON_PX) return 100;
+  return Math.max(1, Math.min(100, Math.round((scrollTop + clientHeight) / scrollHeight * 100)));
+}
+function scheduleBaselineSnapshot(onSnapshot) {
+  let rafId = requestAnimationFrame(() => {
+    rafId = requestAnimationFrame(() => {
+      onSnapshot(measureScrollPercent());
+    });
+  });
+  return () => cancelAnimationFrame(rafId);
+}
+function createBaselineGate() {
+  let baselinePercent = null;
+  let ready = false;
+  let cancelSnapshot = null;
+  return {
+    rebaseline() {
+      cancelSnapshot?.();
+      ready = false;
+      baselinePercent = null;
+      cancelSnapshot = scheduleBaselineSnapshot((b) => {
+        baselinePercent = b;
+        ready = true;
+      });
+    },
+    cancel() {
+      cancelSnapshot?.();
+    },
+    baseline() {
+      return ready ? baselinePercent : null;
+    },
+    sample() {
+      if (!ready) return null;
+      if (baselinePercent === null) {
+        baselinePercent = measureScrollPercent();
+        return null;
+      }
+      return measureScrollPercent();
+    }
+  };
+}
+
 // ../tracking-core/src/triggers/scroll-depth.ts
 function attachScrollDepth(client, config) {
   if (typeof window === "undefined" || typeof document === "undefined") {
@@ -1775,17 +1874,14 @@ function attachScrollDepth(client, config) {
   let firedForPath = /* @__PURE__ */ new Set();
   let currentPath2 = window.location.pathname;
   let rafId = null;
-  function getScrollPercent() {
-    const doc = document.documentElement;
-    const scrollTop = window.scrollY || doc.scrollTop;
-    const scrollHeight = doc.scrollHeight;
-    const clientHeight = doc.clientHeight;
-    if (scrollHeight <= clientHeight) return 100;
-    return Math.round((scrollTop + clientHeight) / scrollHeight * 100);
-  }
+  const gate = createBaselineGate();
   function checkThresholds() {
-    const percent = getScrollPercent();
+    const percent = gate.sample();
+    if (percent === null) return;
+    const baseline = gate.baseline();
+    if (baseline === null) return;
     for (const threshold of thresholds) {
+      if (threshold <= baseline) continue;
       if (percent >= threshold && !firedForPath.has(threshold)) {
         firedForPath.add(threshold);
         client.trackEvent({
@@ -1812,28 +1908,15 @@ function attachScrollDepth(client, config) {
     if (newPath === currentPath2) return;
     currentPath2 = newPath;
     firedForPath = /* @__PURE__ */ new Set();
-    setTimeout(checkThresholds, 0);
+    gate.rebaseline();
   }
-  const originalPushState = history.pushState.bind(history);
-  const originalReplaceState = history.replaceState.bind(history);
-  function patchedPushState(...args) {
-    originalPushState(...args);
-    setTimeout(resetIfPathChanged, 0);
-  }
-  function patchedReplaceState(...args) {
-    originalReplaceState(...args);
-    setTimeout(resetIfPathChanged, 0);
-  }
-  history.pushState = patchedPushState;
-  history.replaceState = patchedReplaceState;
-  window.addEventListener("popstate", resetIfPathChanged);
+  const unsubscribeNav = onHistoryChange(resetIfPathChanged);
   window.addEventListener("scroll", onScroll, { passive: true });
-  setTimeout(checkThresholds, 0);
+  gate.rebaseline();
   return () => {
     if (rafId !== null) cancelAnimationFrame(rafId);
-    history.pushState = originalPushState;
-    history.replaceState = originalReplaceState;
-    window.removeEventListener("popstate", resetIfPathChanged);
+    gate.cancel();
+    unsubscribeNav();
     window.removeEventListener("scroll", onScroll);
   };
 }
@@ -2005,21 +2088,14 @@ function attachPageExit(client) {
   let accumulatedMs = 0;
   let maxScrollPercent = null;
   let rafId = null;
-  function getScrollPercent() {
-    const doc = document.documentElement;
-    const scrollTop = window.scrollY || doc.scrollTop;
-    const scrollHeight = doc.scrollHeight;
-    const clientHeight = doc.clientHeight;
-    if (scrollHeight <= clientHeight) return 100;
-    return Math.round((scrollTop + clientHeight) / scrollHeight * 100);
-  }
+  const gate = createBaselineGate();
   function onScroll() {
     if (rafId !== null) return;
     rafId = requestAnimationFrame(() => {
       rafId = null;
-      const percent = getScrollPercent();
-      if (percent >= 1 && (maxScrollPercent === null || percent > maxScrollPercent)) {
-        maxScrollPercent = Math.min(percent, 100);
+      const percent = gate.sample();
+      if (percent !== null && (maxScrollPercent === null || percent > maxScrollPercent)) {
+        maxScrollPercent = percent;
       }
     });
   }
@@ -2038,6 +2114,12 @@ function attachPageExit(client) {
       metadata: {
         dwell_ms: dwell,
         max_scroll_percent: maxScrollPercent,
+        // Lets the backend tell "scrolled to the bottom" apart from "the page
+        // was barely scrollable". null = unscrollable page or the segment
+        // ended before the post-paint snapshot landed. For pages that grew
+        // after the snapshot this is the first-scroll position, not the
+        // at-load fraction (see BaselineGate.baseline).
+        scroll_baseline_percent: gate.baseline(),
         page: { path }
       },
       pageUrl: window.location.href,
@@ -2055,6 +2137,7 @@ function attachPageExit(client) {
     emitSegment(currentPath2, false);
     currentPath2 = newPath;
     maxScrollPercent = null;
+    gate.rebaseline();
     accumulatedMs = 0;
     activeSince = document.visibilityState === "visible" ? Date.now() : null;
   }
@@ -2068,27 +2151,15 @@ function attachPageExit(client) {
   function onPageHide() {
     emitSegment(currentPath2, true);
   }
-  const originalPushState = history.pushState.bind(history);
-  const originalReplaceState = history.replaceState.bind(history);
-  function patchedPushState(...args) {
-    originalPushState(...args);
-    setTimeout(onNavigate, 0);
-  }
-  function patchedReplaceState(...args) {
-    originalReplaceState(...args);
-    setTimeout(onNavigate, 0);
-  }
-  history.pushState = patchedPushState;
-  history.replaceState = patchedReplaceState;
-  window.addEventListener("popstate", onNavigate);
+  const unsubscribeNav = onHistoryChange(onNavigate);
   window.addEventListener("scroll", onScroll, { passive: true });
   document.addEventListener("visibilitychange", onVisibilityChange);
   window.addEventListener("pagehide", onPageHide);
+  gate.rebaseline();
   return () => {
     if (rafId !== null) cancelAnimationFrame(rafId);
-    history.pushState = originalPushState;
-    history.replaceState = originalReplaceState;
-    window.removeEventListener("popstate", onNavigate);
+    gate.cancel();
+    unsubscribeNav();
     window.removeEventListener("scroll", onScroll);
     document.removeEventListener("visibilitychange", onVisibilityChange);
     window.removeEventListener("pagehide", onPageHide);
@@ -2893,7 +2964,7 @@ function GoogleAdsTracking(props) {
 var import_react6 = require("react");
 
 // package.json
-var version = "0.17.2";
+var version = "0.17.3";
 
 // ../tracking-core/src/phone-react.tsx
 var import_react5 = require("react");