@preprio/toolkit 0.6.0-alpha.2 → 0.6.0-alpha.4

package/dist/nextjs/components.cjs

@@ -22,6 +22,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var components_exports = {};
 __export(components_exports, {
   PreprAbSwitch: () => PreprAbSwitch,
+  PreprPersonalizationSwitch: () => PreprPersonalizationSwitch,
   PreprToolbar: () => PreprToolbar,
   PreprTrackingPixel: () => PreprTrackingPixel,
   PreprVariantTracking: () => PreprVariantTracking
@@ -2315,6 +2316,131 @@ function isReactHydrated(text) {
   return true;
 }
 
+// src/core/refresh.ts
+var PREPR_REFRESH_COOKIE = "prepr_refresh";
+var PREPR_REFRESH_HEADER = "Prepr-Refresh";
+var REFRESH_MAX_PATHS = 5;
+var SAFE_PATH = /^\/(?![/\\])[\w\-./%]{0,200}$/;
+function safePath(path) {
+  return SAFE_PATH.test(path) ? path : void 0;
+}
+function isFresh(at, freshFor, now = Date.now()) {
+  const age = now - at;
+  return at > 0 && age >= 0 && age < freshFor;
+}
+function cleanEntries(entries) {
+  const out = [];
+  for (const entry of entries) {
+    if (out.length === REFRESH_MAX_PATHS) break;
+    if (safePath(entry.path) && !out.some((e2) => e2.path === entry.path)) {
+      out.push(entry);
+    }
+  }
+  return out;
+}
+function parseRefresh(raw) {
+  return cleanEntries(
+    (raw ?? "").split("|").map((pair) => {
+      const split = pair.lastIndexOf("~");
+      const at = Number(split < 0 ? "" : pair.slice(split + 1));
+      return {
+        path: split < 0 ? pair : pair.slice(0, split),
+        at: Number.isFinite(at) && at > 0 ? Math.floor(at) : 0
+      };
+    })
+  );
+}
+
+// src/core/refresh-scheduler.ts
+var VIEW_DELAYS_MS = [3e3, 1e4];
+var INTENT_MIN_AGE_MS = 2e3;
+var INTENT_EVENTS = ["pointerover", "focusin", "touchstart"];
+var LISTENER = { capture: true, passive: true };
+var COOKIE_PATTERN = new RegExp(`(?:^|; )${PREPR_REFRESH_COOKIE}=([^;]*)`);
+var UNSUPPORTED_KEY = "prepr_refresh_unsupported";
+function readEntries() {
+  const match = document.cookie.match(COOKIE_PATTERN);
+  try {
+    return parseRefresh(match ? decodeURIComponent(match[1]) : void 0);
+  } catch {
+    return [];
+  }
+}
+function unsupported() {
+  try {
+    return sessionStorage.getItem(UNSUPPORTED_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+function createPreprRefreshScheduler(options = {}) {
+  const freshFor = options.freshFor ?? 1e4;
+  let timers = [];
+  let inFlight = false;
+  let stopped = unsupported();
+  function refresh() {
+    if (inFlight || stopped) return;
+    const paths = readEntries().map((entry) => entry.path);
+    if (paths.length === 0) return;
+    inFlight = true;
+    const controller = new AbortController();
+    fetch(location.pathname, {
+      headers: { [PREPR_REFRESH_HEADER]: paths.join("|") },
+      cache: "no-store",
+      credentials: "same-origin",
+      signal: controller.signal
+    }).then((response) => {
+      if (response.status === 204) return;
+      stopped = true;
+      controller.abort();
+      try {
+        sessionStorage.setItem(UNSUPPORTED_KEY, "1");
+      } catch {
+      }
+    }).catch(() => void 0).finally(() => {
+      inFlight = false;
+    });
+  }
+  function onIntent(event) {
+    const anchor = event.target?.closest?.("a[href]");
+    if (!(anchor instanceof HTMLAnchorElement)) return;
+    let url;
+    try {
+      url = new URL(anchor.href, location.href);
+    } catch {
+      return;
+    }
+    if (url.origin !== location.origin) return;
+    const entry = readEntries().find((e2) => e2.path === url.pathname);
+    if (entry && !isFresh(entry.at, INTENT_MIN_AGE_MS)) refresh();
+  }
+  function onVisibility() {
+    if (document.visibilityState === "visible" && readEntries().some((entry) => !isFresh(entry.at, freshFor))) {
+      refresh();
+    }
+  }
+  for (const type of INTENT_EVENTS) {
+    document.addEventListener(type, onIntent, LISTENER);
+  }
+  document.addEventListener("visibilitychange", onVisibility, {
+    passive: true
+  });
+  return {
+    view() {
+      timers.forEach(clearTimeout);
+      timers = VIEW_DELAYS_MS.map((delay) => setTimeout(refresh, delay));
+    },
+    stop() {
+      timers.forEach(clearTimeout);
+      timers = [];
+      for (const type of INTENT_EVENTS) {
+        document.removeEventListener(type, onIntent, LISTENER);
+      }
+      document.removeEventListener("visibilitychange", onVisibility);
+    }
+  };
+}
+
 // src/nextjs/ab-switch.ts
 function applyPreprAbBucket() {
   const match = document.cookie.match(/(?:^|; )prepr_ab_bucket=([AB])(?:;|$)/);
@@ -2338,7 +2464,11 @@ function applyPreprAbBucket() {
     state.__preprAbSheet.textContent = css;
   }
 }
-function applyPreprDecisions() {
+function applyPreprDecisions(view) {
+  const viewState = window;
+  const current = view === void 0 ? location.pathname + location.search : view;
+  if (viewState.__preprDecisionsView === current) return;
+  viewState.__preprDecisionsView = current;
   const match = document.cookie.match(/(?:^|; )prepr_decisions=([^;]*)/);
   let raw;
   try {
@@ -2383,7 +2513,7 @@ function applyPreprDecisions() {
 var import_react = require("react");
 
 // src/version.ts
-var VERSION = "0.6.0-alpha.2";
+var VERSION = "0.6.0-alpha.4";
 
 // src/core/pixel.ts
 var PIXEL_SCRIPT_URL = "https://cdn.tracking.prepr.io/js/prepr.min.js";
@@ -2461,8 +2591,41 @@ function PreprToolbar({
 function PreprAbSwitch() {
   (0, import_react2.useLayoutEffect)(() => {
     applyPreprAbBucket();
+  });
+  return null;
+}
+function PreprPersonalizationSwitch({
+  refresh = true,
+  freshFor
+}) {
+  const [scheduler, setScheduler] = (0, import_react2.useState)(
+    null
+  );
+  (0, import_react2.useLayoutEffect)(() => {
     applyPreprDecisions();
   });
+  (0, import_react2.useEffect)(() => {
+    if (!refresh) return;
+    const started = createPreprRefreshScheduler({ freshFor });
+    setScheduler(started);
+    return () => {
+      started.stop();
+      setScheduler(null);
+    };
+  }, [refresh, freshFor]);
+  return scheduler ? (0, import_react2.createElement)(
+    import_react2.Suspense,
+    { fallback: null },
+    (0, import_react2.createElement)(ViewCounter, { scheduler })
+  ) : null;
+}
+function ViewCounter({
+  scheduler
+}) {
+  const pathname = (0, import_navigation.usePathname)();
+  (0, import_react2.useEffect)(() => {
+    scheduler.view();
+  }, [pathname, scheduler]);
   return null;
 }
 var VARIANT_KEY_ATTRIBUTE = "data-prepr-variant-key";
@@ -2501,6 +2664,7 @@ function PreprVariantTracking({
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PreprAbSwitch,
+  PreprPersonalizationSwitch,
   PreprToolbar,
   PreprTrackingPixel,
   PreprVariantTracking

package/dist/nextjs/components.d.cts

@@ -1,4 +1,4 @@
-import { ReactNode, ReactElement } from 'react';
+import { ReactElement, ReactNode } from 'react';
 import { k as PreprToolbarComponentProps } from '../types-BYH9XqmN.cjs';
 import { P as PreprPixelConfig } from '../pixel-DwW7cXJm.cjs';
 
@@ -23,14 +23,42 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
 /**
- * Applies the visitor's A/B bucket, and the segment variants decided in the
- * proxy, after client-side navigation. A full page
+ * Applies the visitor's A/B bucket after client-side navigation. A full page
  * load is covered by the inline script `PreprStack` renders, but React does
  * not run inline scripts that arrive with a client-side navigation; a layout
  * effect still runs before the browser paints the new page. Rendered by
  * `PreprStack`; you do not need it yourself.
  */
 declare function PreprAbSwitch(): null;
+interface PreprPersonalizationSwitchProps {
+    /**
+     * Keep segment decisions fresh in the background. Default `true`. Leave it
+     * on for the instance in your root layout; `PreprStack` renders its own
+     * with `false`.
+     */
+    refresh?: boolean;
+    /** Same as `createPreprProxy`'s `freshFor`. Default 10 000 ms. */
+    freshFor?: number;
+}
+/**
+ * Shows the segment variants decided in the proxy for the groups above the
+ * fold, before the page paints, and keeps those decisions fresh while the
+ * visitor browses: a short while after each page view, when the visitor
+ * points at a link to a personalized page, and when the tab comes back.
+ * Because the next page's decision is already in place when it opens, a
+ * visitor who joins a segment mid-visit sees it on their next page view,
+ * without anything on screen changing.
+ *
+ * Mount it once in the root layout. The background refreshes are answered by
+ * `createPreprProxy`; with a proxy that calls `resolveDecisions` itself, the
+ * first refresh gets a page back and refreshing stops for the browser
+ * session. The decisions themselves come from `createPreprProxy` or
+ * `resolveDecisions` in `proxy.ts`.
+ *
+ * @example
+ * <PreprPersonalizationSwitch />
+ */
+declare function PreprPersonalizationSwitch({ refresh, freshFor, }: PreprPersonalizationSwitchProps): ReactElement | null;
 /**
  * Wraps one rendered variant and, once hydrated, puts the variant keys on the
  * elements inside, where Prepr's tracking pixel counts impressions and the
@@ -52,4 +80,4 @@ declare function PreprVariantTracking({ variantKeys, ab, children, }: {
     children?: ReactNode;
 }): ReactElement;
 
-export { PreprAbSwitch, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, PreprVariantTracking };
+export { PreprAbSwitch, PreprPersonalizationSwitch, type PreprPersonalizationSwitchProps, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, PreprVariantTracking };

package/dist/nextjs/components.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode, ReactElement } from 'react';
+import { ReactElement, ReactNode } from 'react';
 import { k as PreprToolbarComponentProps } from '../types-BYH9XqmN.js';
 import { P as PreprPixelConfig } from '../pixel-DwW7cXJm.js';
 
@@ -23,14 +23,42 @@ declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): n
  */
 declare function PreprToolbar({ options, ...props }: PreprToolbarComponentProps): null;
 /**
- * Applies the visitor's A/B bucket, and the segment variants decided in the
- * proxy, after client-side navigation. A full page
+ * Applies the visitor's A/B bucket after client-side navigation. A full page
  * load is covered by the inline script `PreprStack` renders, but React does
  * not run inline scripts that arrive with a client-side navigation; a layout
  * effect still runs before the browser paints the new page. Rendered by
  * `PreprStack`; you do not need it yourself.
  */
 declare function PreprAbSwitch(): null;
+interface PreprPersonalizationSwitchProps {
+    /**
+     * Keep segment decisions fresh in the background. Default `true`. Leave it
+     * on for the instance in your root layout; `PreprStack` renders its own
+     * with `false`.
+     */
+    refresh?: boolean;
+    /** Same as `createPreprProxy`'s `freshFor`. Default 10 000 ms. */
+    freshFor?: number;
+}
+/**
+ * Shows the segment variants decided in the proxy for the groups above the
+ * fold, before the page paints, and keeps those decisions fresh while the
+ * visitor browses: a short while after each page view, when the visitor
+ * points at a link to a personalized page, and when the tab comes back.
+ * Because the next page's decision is already in place when it opens, a
+ * visitor who joins a segment mid-visit sees it on their next page view,
+ * without anything on screen changing.
+ *
+ * Mount it once in the root layout. The background refreshes are answered by
+ * `createPreprProxy`; with a proxy that calls `resolveDecisions` itself, the
+ * first refresh gets a page back and refreshing stops for the browser
+ * session. The decisions themselves come from `createPreprProxy` or
+ * `resolveDecisions` in `proxy.ts`.
+ *
+ * @example
+ * <PreprPersonalizationSwitch />
+ */
+declare function PreprPersonalizationSwitch({ refresh, freshFor, }: PreprPersonalizationSwitchProps): ReactElement | null;
 /**
  * Wraps one rendered variant and, once hydrated, puts the variant keys on the
  * elements inside, where Prepr's tracking pixel counts impressions and the
@@ -52,4 +80,4 @@ declare function PreprVariantTracking({ variantKeys, ab, children, }: {
     children?: ReactNode;
 }): ReactElement;
 
-export { PreprAbSwitch, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, PreprVariantTracking };
+export { PreprAbSwitch, PreprPersonalizationSwitch, type PreprPersonalizationSwitchProps, PreprToolbar, PreprTrackingPixel, type PreprTrackingPixelProps, PreprVariantTracking };

package/dist/nextjs/components.js

@@ -2,9 +2,9 @@
 import {
   createPreprPreview,
   loadTrackingPixel
-} from "../chunk-DS3QA3HF.js";
+} from "../chunk-YNZUYENT.js";
 import "../chunk-S5RWVMDJ.js";
-import "../chunk-VV4PRH7W.js";
+import "../chunk-EE3GXKCF.js";
 
 // src/nextjs/components.ts
 import { usePathname, useRouter } from "next/navigation";
@@ -12,7 +12,9 @@ import {
   createElement,
   useEffect as useEffect2,
   useLayoutEffect,
-  useRef
+  useRef,
+  useState,
+  Suspense
 } from "react";
 
 // src/react/hydration.ts
@@ -34,6 +36,131 @@ function isReactHydrated(text) {
   return true;
 }
 
+// src/core/refresh.ts
+var PREPR_REFRESH_COOKIE = "prepr_refresh";
+var PREPR_REFRESH_HEADER = "Prepr-Refresh";
+var REFRESH_MAX_PATHS = 5;
+var SAFE_PATH = /^\/(?![/\\])[\w\-./%]{0,200}$/;
+function safePath(path) {
+  return SAFE_PATH.test(path) ? path : void 0;
+}
+function isFresh(at, freshFor, now = Date.now()) {
+  const age = now - at;
+  return at > 0 && age >= 0 && age < freshFor;
+}
+function cleanEntries(entries) {
+  const out = [];
+  for (const entry of entries) {
+    if (out.length === REFRESH_MAX_PATHS) break;
+    if (safePath(entry.path) && !out.some((e) => e.path === entry.path)) {
+      out.push(entry);
+    }
+  }
+  return out;
+}
+function parseRefresh(raw) {
+  return cleanEntries(
+    (raw ?? "").split("|").map((pair) => {
+      const split = pair.lastIndexOf("~");
+      const at = Number(split < 0 ? "" : pair.slice(split + 1));
+      return {
+        path: split < 0 ? pair : pair.slice(0, split),
+        at: Number.isFinite(at) && at > 0 ? Math.floor(at) : 0
+      };
+    })
+  );
+}
+
+// src/core/refresh-scheduler.ts
+var VIEW_DELAYS_MS = [3e3, 1e4];
+var INTENT_MIN_AGE_MS = 2e3;
+var INTENT_EVENTS = ["pointerover", "focusin", "touchstart"];
+var LISTENER = { capture: true, passive: true };
+var COOKIE_PATTERN = new RegExp(`(?:^|; )${PREPR_REFRESH_COOKIE}=([^;]*)`);
+var UNSUPPORTED_KEY = "prepr_refresh_unsupported";
+function readEntries() {
+  const match = document.cookie.match(COOKIE_PATTERN);
+  try {
+    return parseRefresh(match ? decodeURIComponent(match[1]) : void 0);
+  } catch {
+    return [];
+  }
+}
+function unsupported() {
+  try {
+    return sessionStorage.getItem(UNSUPPORTED_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+function createPreprRefreshScheduler(options = {}) {
+  const freshFor = options.freshFor ?? 1e4;
+  let timers = [];
+  let inFlight = false;
+  let stopped = unsupported();
+  function refresh() {
+    if (inFlight || stopped) return;
+    const paths = readEntries().map((entry) => entry.path);
+    if (paths.length === 0) return;
+    inFlight = true;
+    const controller = new AbortController();
+    fetch(location.pathname, {
+      headers: { [PREPR_REFRESH_HEADER]: paths.join("|") },
+      cache: "no-store",
+      credentials: "same-origin",
+      signal: controller.signal
+    }).then((response) => {
+      if (response.status === 204) return;
+      stopped = true;
+      controller.abort();
+      try {
+        sessionStorage.setItem(UNSUPPORTED_KEY, "1");
+      } catch {
+      }
+    }).catch(() => void 0).finally(() => {
+      inFlight = false;
+    });
+  }
+  function onIntent(event) {
+    const anchor = event.target?.closest?.("a[href]");
+    if (!(anchor instanceof HTMLAnchorElement)) return;
+    let url;
+    try {
+      url = new URL(anchor.href, location.href);
+    } catch {
+      return;
+    }
+    if (url.origin !== location.origin) return;
+    const entry = readEntries().find((e) => e.path === url.pathname);
+    if (entry && !isFresh(entry.at, INTENT_MIN_AGE_MS)) refresh();
+  }
+  function onVisibility() {
+    if (document.visibilityState === "visible" && readEntries().some((entry) => !isFresh(entry.at, freshFor))) {
+      refresh();
+    }
+  }
+  for (const type of INTENT_EVENTS) {
+    document.addEventListener(type, onIntent, LISTENER);
+  }
+  document.addEventListener("visibilitychange", onVisibility, {
+    passive: true
+  });
+  return {
+    view() {
+      timers.forEach(clearTimeout);
+      timers = VIEW_DELAYS_MS.map((delay) => setTimeout(refresh, delay));
+    },
+    stop() {
+      timers.forEach(clearTimeout);
+      timers = [];
+      for (const type of INTENT_EVENTS) {
+        document.removeEventListener(type, onIntent, LISTENER);
+      }
+      document.removeEventListener("visibilitychange", onVisibility);
+    }
+  };
+}
+
 // src/nextjs/ab-switch.ts
 function applyPreprAbBucket() {
   const match = document.cookie.match(/(?:^|; )prepr_ab_bucket=([AB])(?:;|$)/);
@@ -57,7 +184,11 @@ function applyPreprAbBucket() {
     state.__preprAbSheet.textContent = css;
   }
 }
-function applyPreprDecisions() {
+function applyPreprDecisions(view) {
+  const viewState = window;
+  const current = view === void 0 ? location.pathname + location.search : view;
+  if (viewState.__preprDecisionsView === current) return;
+  viewState.__preprDecisionsView = current;
   const match = document.cookie.match(/(?:^|; )prepr_decisions=([^;]*)/);
   let raw;
   try {
@@ -136,8 +267,41 @@ function PreprToolbar({
 function PreprAbSwitch() {
   useLayoutEffect(() => {
     applyPreprAbBucket();
+  });
+  return null;
+}
+function PreprPersonalizationSwitch({
+  refresh = true,
+  freshFor
+}) {
+  const [scheduler, setScheduler] = useState(
+    null
+  );
+  useLayoutEffect(() => {
     applyPreprDecisions();
   });
+  useEffect2(() => {
+    if (!refresh) return;
+    const started = createPreprRefreshScheduler({ freshFor });
+    setScheduler(started);
+    return () => {
+      started.stop();
+      setScheduler(null);
+    };
+  }, [refresh, freshFor]);
+  return scheduler ? createElement(
+    Suspense,
+    { fallback: null },
+    createElement(ViewCounter, { scheduler })
+  ) : null;
+}
+function ViewCounter({
+  scheduler
+}) {
+  const pathname = usePathname();
+  useEffect2(() => {
+    scheduler.view();
+  }, [pathname, scheduler]);
   return null;
 }
 var VARIANT_KEY_ATTRIBUTE = "data-prepr-variant-key";
@@ -175,6 +339,7 @@ function PreprVariantTracking({
 }
 export {
   PreprAbSwitch,
+  PreprPersonalizationSwitch,
   PreprToolbar,
   PreprTrackingPixel,
   PreprVariantTracking