@preprio/toolkit 0.6.0-alpha.1 → 0.6.0-alpha.3

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.1";
+var VERSION = "0.6.0-alpha.3";
 
 // src/core/pixel.ts
 var PIXEL_SCRIPT_URL = "https://cdn.tracking.prepr.io/js/prepr.min.js";
@@ -2461,8 +2591,30 @@ function PreprToolbar({
 function PreprAbSwitch() {
   (0, import_react2.useLayoutEffect)(() => {
     applyPreprAbBucket();
+  });
+  return null;
+}
+function PreprPersonalizationSwitch({
+  refresh = true,
+  freshFor
+}) {
+  const pathname = (0, import_navigation.usePathname)();
+  const scheduler = (0, import_react2.useRef)(null);
+  (0, import_react2.useLayoutEffect)(() => {
     applyPreprDecisions();
   });
+  (0, import_react2.useEffect)(() => {
+    if (!refresh) return;
+    const started = createPreprRefreshScheduler({ freshFor });
+    scheduler.current = started;
+    return () => {
+      started.stop();
+      scheduler.current = null;
+    };
+  }, [refresh, freshFor]);
+  (0, import_react2.useEffect)(() => {
+    scheduler.current?.view();
+  }, [pathname, refresh, freshFor]);
   return null;
 }
 var VARIANT_KEY_ATTRIBUTE = "data-prepr-variant-key";
@@ -2474,15 +2626,19 @@ function PreprVariantTracking({
   const ref = (0, import_react2.useRef)(null);
   const keys = variantKeys.join(" ");
   (0, import_react2.useLayoutEffect)(() => {
-    const elements = [...ref.current?.children ?? []];
-    const list = keys.split(" ");
-    const pairs = elements.length === list.length ? elements.map((element, i2) => [element, list[i2]]) : elements.slice(0, 1).map((element) => [element, list[0]]);
-    const tagged = pairs.filter(([element, key]) => {
-      if (element.hasAttribute(VARIANT_KEY_ATTRIBUTE)) return false;
-      element.setAttribute(VARIANT_KEY_ATTRIBUTE, key);
-      return true;
+    let tagged = [];
+    const timer = setTimeout(() => {
+      const elements = [...ref.current?.children ?? []];
+      const list = keys.split(" ");
+      const pairs = elements.length === list.length ? elements.map((element, i2) => [element, list[i2]]) : elements.slice(0, 1).map((element) => [element, list[0]]);
+      tagged = pairs.filter(([element, key]) => {
+        if (element.hasAttribute(VARIANT_KEY_ATTRIBUTE)) return false;
+        element.setAttribute(VARIANT_KEY_ATTRIBUTE, key);
+        return true;
+      });
     });
     return () => {
+      clearTimeout(timer);
       for (const [element] of tagged) {
         element.removeAttribute(VARIANT_KEY_ATTRIBUTE);
       }
@@ -2497,6 +2653,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

@@ -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): 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

@@ -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): 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-VI6QZTBM.js";
+} from "../chunk-3YZANSVY.js";
 import "../chunk-S5RWVMDJ.js";
-import "../chunk-YWIKKWBR.js";
+import "../chunk-VY5D3IED.js";
 
 // src/nextjs/components.ts
 import { usePathname, useRouter } from "next/navigation";
@@ -34,6 +34,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 +182,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 +265,30 @@ function PreprToolbar({
 function PreprAbSwitch() {
   useLayoutEffect(() => {
     applyPreprAbBucket();
+  });
+  return null;
+}
+function PreprPersonalizationSwitch({
+  refresh = true,
+  freshFor
+}) {
+  const pathname = usePathname();
+  const scheduler = useRef(null);
+  useLayoutEffect(() => {
     applyPreprDecisions();
   });
+  useEffect2(() => {
+    if (!refresh) return;
+    const started = createPreprRefreshScheduler({ freshFor });
+    scheduler.current = started;
+    return () => {
+      started.stop();
+      scheduler.current = null;
+    };
+  }, [refresh, freshFor]);
+  useEffect2(() => {
+    scheduler.current?.view();
+  }, [pathname, refresh, freshFor]);
   return null;
 }
 var VARIANT_KEY_ATTRIBUTE = "data-prepr-variant-key";
@@ -149,15 +300,19 @@ function PreprVariantTracking({
   const ref = useRef(null);
   const keys = variantKeys.join(" ");
   useLayoutEffect(() => {
-    const elements = [...ref.current?.children ?? []];
-    const list = keys.split(" ");
-    const pairs = elements.length === list.length ? elements.map((element, i) => [element, list[i]]) : elements.slice(0, 1).map((element) => [element, list[0]]);
-    const tagged = pairs.filter(([element, key]) => {
-      if (element.hasAttribute(VARIANT_KEY_ATTRIBUTE)) return false;
-      element.setAttribute(VARIANT_KEY_ATTRIBUTE, key);
-      return true;
+    let tagged = [];
+    const timer = setTimeout(() => {
+      const elements = [...ref.current?.children ?? []];
+      const list = keys.split(" ");
+      const pairs = elements.length === list.length ? elements.map((element, i) => [element, list[i]]) : elements.slice(0, 1).map((element) => [element, list[0]]);
+      tagged = pairs.filter(([element, key]) => {
+        if (element.hasAttribute(VARIANT_KEY_ATTRIBUTE)) return false;
+        element.setAttribute(VARIANT_KEY_ATTRIBUTE, key);
+        return true;
+      });
     });
     return () => {
+      clearTimeout(timer);
       for (const [element] of tagged) {
         element.removeAttribute(VARIANT_KEY_ATTRIBUTE);
       }
@@ -171,6 +326,7 @@ function PreprVariantTracking({
 }
 export {
   PreprAbSwitch,
+  PreprPersonalizationSwitch,
   PreprToolbar,
   PreprTrackingPixel,
   PreprVariantTracking