@aranova/tracking-next 0.17.1 → 0.17.3

package/dist/index.d.mts

@@ -302,6 +302,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, {
@@ -315,12 +316,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>;
 /**
@@ -887,6 +890,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, {
@@ -900,12 +904,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

@@ -302,6 +302,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, {
@@ -315,12 +316,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>;
 /**
@@ -887,6 +890,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, {
@@ -900,12 +904,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

@@ -680,9 +680,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 {
@@ -1122,6 +1122,27 @@ function getOrCreateTrackingClient(config) {
   globalClientKey = key;
   return globalClient;
 }
+var clientCaptureRegistry = /* @__PURE__ */ new WeakMap();
+function attachClientCapturesOnce(client, build) {
+  let entry = clientCaptureRegistry.get(client);
+  if (entry === void 0) {
+    entry = { detach: build(), refCount: 0 };
+    clientCaptureRegistry.set(client, entry);
+  }
+  entry.refCount += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const current = clientCaptureRegistry.get(client);
+    if (current === void 0) return;
+    current.refCount -= 1;
+    if (current.refCount <= 0) {
+      current.detach();
+      clientCaptureRegistry.delete(client);
+    }
+  };
+}
 function createTrackingClient(config) {
   const flushIntervalMs = config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
   const maxQueueSize = Math.min(config.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE, HARD_MAX_BATCH);
@@ -1391,6 +1412,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()
@@ -1615,6 +1644,97 @@ function attachTimeOnSite(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") {
@@ -1625,17 +1745,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({
@@ -1662,28 +1779,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);
   };
 }
@@ -1765,21 +1869,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;
       }
     });
   }
@@ -1798,6 +1895,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,
@@ -1815,6 +1918,7 @@ function attachPageExit(client) {
     emitSegment(currentPath2, false);
     currentPath2 = newPath;
     maxScrollPercent = null;
+    gate.rebaseline();
     accumulatedMs = 0;
     activeSince = document.visibilityState === "visible" ? Date.now() : null;
   }
@@ -1828,27 +1932,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);
@@ -2664,10 +2756,10 @@ function GoogleAdsTracking(props) {
 }
 
 // src/factory.tsx
-var import_navigation = require("next/navigation");
+var import_navigation3 = require("next/navigation");
 
 // package.json
-var version = "0.17.1";
+var version = "0.17.3";
 
 // src/factory.tsx
 var import_react4 = require("react");
@@ -2761,8 +2853,8 @@ var PhoneField = (0, import_react3.forwardRef)(function PhoneField2({ country, v
 // src/factory.tsx
 var import_jsx_runtime5 = require("react/jsx-runtime");
 function PageViewTracker({ fire }) {
-  const pathname = (0, import_navigation.usePathname)();
-  const searchParams = (0, import_navigation.useSearchParams)();
+  const pathname = (0, import_navigation3.usePathname)();
+  const searchParams = (0, import_navigation3.useSearchParams)();
   (0, import_react4.useEffect)(() => {
     fire();
   }, [pathname, searchParams, fire]);
@@ -2793,7 +2885,7 @@ function createTracking(options) {
   const specificPageVisitConfig = triggers.automatic.specific_page_visit ?? null;
   const timeOnSiteConfig = triggers.automatic.time_on_site ?? null;
   function TrackingProvider({ children }) {
-    const pathname = (0, import_navigation.usePathname)();
+    const pathname = (0, import_navigation3.usePathname)();
     const client = (0, import_react4.useMemo)(
       () => createTypedClient(
         getOrCreateTrackingClient({
@@ -2866,33 +2958,6 @@ function createTracking(options) {
         });
       }
     }, [pathname]);
-    (0, import_react4.useEffect)(() => {
-      const rawClient = getOrCreateTrackingClient({
-        apiKey,
-        endpoint,
-        surface: "next",
-        packageName: "@aranova/tracking-next",
-        triggers,
-        environment,
-        activeGtagIds: gtagIds,
-        debug
-      });
-      return attachBfcacheRestore(wrapClient(rawClient));
-    }, []);
-    (0, import_react4.useEffect)(() => {
-      if (!timeOnSiteConfig) return;
-      const rawClient = getOrCreateTrackingClient({
-        apiKey,
-        endpoint,
-        surface: "next",
-        packageName: "@aranova/tracking-next",
-        triggers,
-        environment,
-        activeGtagIds: gtagIds,
-        debug
-      });
-      return attachTimeOnSite(wrapClient(rawClient), timeOnSiteConfig);
-    }, []);
     const multiPageSessionConfig = triggers.automatic.multi_page_session ?? null;
     const mpsLastPathRef = (0, import_react4.useRef)(null);
     (0, import_react4.useEffect)(() => {
@@ -2943,7 +3008,6 @@ function createTracking(options) {
       }
     }, [pathname]);
     (0, import_react4.useEffect)(() => {
-      const detachers = [];
       const rawClient = getOrCreateTrackingClient({
         apiKey,
         endpoint,
@@ -2954,29 +3018,36 @@ function createTracking(options) {
         activeGtagIds: gtagIds,
         debug
       });
-      const detectorClient = wrapClient(rawClient);
-      detachers.push(attachPageExit(detectorClient));
-      const scrollDepth = triggers.automatic.scroll_depth;
-      if (scrollDepth) {
-        detachers.push(attachScrollDepth(detectorClient, scrollDepth));
-      }
-      const formStart = triggers.automatic.form_start;
-      if (formStart) {
-        detachers.push(attachFormStart(detectorClient, formStart));
-      }
-      const ctaClick = triggers.manual?.cta_click;
-      if (ctaClick) {
-        detachers.push(attachCtaClickCapture(detectorClient, ctaClick));
-      }
-      const phoneClick = triggers.manual?.phone_click;
-      if (phoneClick) {
-        detachers.push(attachPhoneClickCapture(detectorClient, phoneClick));
-      }
-      return () => {
-        for (let i = detachers.length - 1; i >= 0; i--) {
-          detachers[i]();
+      return attachClientCapturesOnce(rawClient, () => {
+        const detachers = [];
+        const detectorClient = wrapClient(rawClient);
+        detachers.push(attachPageExit(detectorClient));
+        detachers.push(attachBfcacheRestore(detectorClient));
+        if (timeOnSiteConfig) {
+          detachers.push(attachTimeOnSite(detectorClient, timeOnSiteConfig));
+        }
+        const scrollDepth = triggers.automatic.scroll_depth;
+        if (scrollDepth) {
+          detachers.push(attachScrollDepth(detectorClient, scrollDepth));
         }
-      };
+        const formStart = triggers.automatic.form_start;
+        if (formStart) {
+          detachers.push(attachFormStart(detectorClient, formStart));
+        }
+        const ctaClick = triggers.manual?.cta_click;
+        if (ctaClick) {
+          detachers.push(attachCtaClickCapture(detectorClient, ctaClick));
+        }
+        const phoneClick = triggers.manual?.phone_click;
+        if (phoneClick) {
+          detachers.push(attachPhoneClickCapture(detectorClient, phoneClick));
+        }
+        return () => {
+          for (let i = detachers.length - 1; i >= 0; i--) {
+            detachers[i]();
+          }
+        };
+      });
     }, []);
     return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)(TrackingContext.Provider, { value: client, children: [
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_react4.Suspense, { fallback: null, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(PageViewTracker, { fire: firePageView }) }),