@appfunnel-dev/sdk 2.0.0-canary.4 → 2.0.0-canary.5

package/dist/index.js

@@ -1,7 +1,9 @@
-import { isRtl, formatProduct, bucketingSeed, resolveExperiments, entryGuard, evaluateGate, expectedPathLength, nextPage, outgoingKeys, buildCatalog, resolveLocale } from './chunk-AKO6XKXP.js';
-export { assignVariant, bucketingSeed, buildCatalog, compileManifest, currencyExponent, defineFunnel, definePage, entryGuard, evaluateCondition, evaluateGate, expectedPathLength, fnv1a, formatMoney, formatProduct, hashToUnit, isRtl, isVariantKey, nextPage, outgoingKeys, pageMeta, parseSlotKey, pickByWeight, resolveExperiments, resolveLocale, resolveProduct, resolveRoute, validateExperiments } from './chunk-AKO6XKXP.js';
-import { checkoutError, isInlineSurface, PROVIDER_PROFILES } from './chunk-YY375F2B.js';
-export { INLINE_SURFACES, PROVIDER_PROFILES, checkoutError, isInlineSurface, isMerchantOfRecord, isOrchestrator, surfacesFor, validateCheckout, validateUpsell } from './chunk-YY375F2B.js';
+import { isRtl, formatProduct, bucketingSeed, resolveExperiments, entryGuard, evaluateGate, expectedPathLength, nextPage, outgoingKeys, buildCatalog, resolveLocale } from './chunk-AXXG3ODP.js';
+export { assignVariant, bucketingSeed, buildCatalog, compileManifest, currencyExponent, defineFunnel, definePage, entryGuard, evaluateCondition, evaluateGate, expectedPathLength, fnv1a, formatMoney, formatProduct, hashToUnit, isRtl, isVariantKey, nextPage, outgoingKeys, pageMeta, parseSlotKey, pickByWeight, resolveExperiments, resolveLocale, resolveProduct, resolveRoute, validateExperiments } from './chunk-AXXG3ODP.js';
+import { AF_PROTOCOL } from './chunk-ZZJG4EYL.js';
+import { checkoutError, isInlineSurface, PROVIDER_PROFILES } from './chunk-TNLRQPVY.js';
+export { INLINE_SURFACES, PROVIDER_PROFILES, checkoutError, isInlineSurface, isMerchantOfRecord, isOrchestrator, surfacesFor, validateCheckout, validateUpsell } from './chunk-TNLRQPVY.js';
+import './chunk-G3PMV62Z.js';
 import React, { createContext, createElement, useCallback, useContext, useMemo, lazy, useRef, useState, useEffect, useTransition, Suspense, Fragment, isValidElement, cloneElement, useReducer, useSyncExternalStore } from 'react';
 import ReactDOM, { createPortal } from 'react-dom';
 import { jsx } from 'react/jsx-runtime';
@@ -380,7 +382,27 @@ function createBus(accessors, now2 = () => Date.now()) {
       }
     }
   };
-  return { on, off, events, emit, ...accessors };
+  let nav = null;
+  let warnedNoNav = false;
+  const currentNav = () => {
+    if (!nav && !warnedNoNav) {
+      warnedNoNav = true;
+      console.warn("[appfunnel] window.appfunnel navigation called before the funnel flow mounted \u2014 ignored");
+    }
+    return nav;
+  };
+  const registerNavigation = (n) => {
+    nav = n;
+    warnedNoNav = false;
+    return () => {
+      if (nav === n) nav = null;
+    };
+  };
+  const goTo = (pageKey) => currentNav()?.goTo(pageKey) ?? false;
+  const goNext = () => currentNav()?.goNext();
+  const goPrevious = () => currentNav()?.goPrevious();
+  const navigation = () => nav?.snapshot() ?? null;
+  return { on, off, events, emit, registerNavigation, goTo, goNext, goPrevious, navigation, ...accessors };
 }
 function withBus(tracker, bus) {
   return {
@@ -402,7 +424,19 @@ function withBus(tracker, bus) {
 function attachBus(bus) {
   if (typeof window === "undefined") return () => {
   };
-  const { on, off, getVariable, getVariables, getCurrentPageId, getCustomerId, getVisitorId } = bus;
+  const {
+    on,
+    off,
+    getVariable,
+    getVariables,
+    getCurrentPageId,
+    getCustomerId,
+    getVisitorId,
+    goTo,
+    goNext,
+    goPrevious,
+    navigation
+  } = bus;
   const api = {
     on,
     off,
@@ -411,6 +445,11 @@ function attachBus(bus) {
     getCurrentPageId,
     getCustomerId,
     getVisitorId,
+    // Flow control (bound closures over the bus's live nav registration).
+    goTo,
+    goNext,
+    goPrevious,
+    navigation,
     get events() {
       return bus.events;
     }
@@ -552,6 +591,102 @@ function useProducts() {
     [catalog, locale]
   );
 }
+
+// src/flow/screenshot.ts
+var MIME = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+var ScreenshotError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+};
+function resolveTarget(t) {
+  if (!t || t.kind === "page") return document.getElementById("root") ?? document.body;
+  if (t.kind === "viewport") return document.body;
+  return document.querySelector(t.selector);
+}
+var delay = (ms) => new Promise((r) => setTimeout(r, ms));
+function hideAll(selectors) {
+  const touched = [];
+  for (const sel of selectors) {
+    document.querySelectorAll(sel).forEach((el) => {
+      touched.push([el, el.style.visibility]);
+      el.style.visibility = "hidden";
+    });
+  }
+  return () => touched.forEach(([el, v]) => el.style.visibility = v);
+}
+async function scrollThrough(el) {
+  const prev = el.scrollTop;
+  const step = el.clientHeight || window.innerHeight;
+  for (let y = 0; y < el.scrollHeight; y += step) {
+    el.scrollTop = y;
+    await delay(16);
+  }
+  el.scrollTop = prev;
+  await delay(16);
+}
+function blobToDataURL(blob) {
+  return new Promise((resolve, reject) => {
+    const fr = new FileReader();
+    fr.onload = () => resolve(String(fr.result));
+    fr.onerror = () => reject(fr.error);
+    fr.readAsDataURL(blob);
+  });
+}
+async function captureScreenshot(params = {}) {
+  const el = resolveTarget(params.target);
+  if (!el) throw new ScreenshotError("bad_params", "screenshot target not found");
+  const restore = params.hideSelectors?.length ? hideAll(params.hideSelectors) : null;
+  const scale = Math.min(params.scale ?? 2, params.maxScale ?? 3);
+  const format = params.format ?? "png";
+  const timeout = params.timeout ?? 1e4;
+  try {
+    if (params.waitForFonts !== false && document.fonts?.ready) {
+      await Promise.race([document.fonts.ready, delay(timeout)]);
+    }
+    if (params.triggerLazyLoad) await scrollThrough(el);
+    if (params.waitForImages !== false) {
+      await Promise.all(
+        Array.from(el.querySelectorAll("img")).map(
+          (img) => typeof img.decode === "function" ? img.decode().catch(() => {
+          }) : Promise.resolve()
+        )
+      );
+    }
+    const { domToBlob } = await import('modern-screenshot');
+    let blob;
+    try {
+      blob = await domToBlob(el, {
+        type: MIME[format],
+        quality: params.quality ?? 0.92,
+        scale,
+        width: params.width,
+        height: params.height,
+        // `null` = transparent (png/webp); only fall back to white when the caller omitted it. `??`
+        // would wrongly collapse an explicit `null` to white.
+        backgroundColor: params.backgroundColor === void 0 ? "#ffffff" : params.backgroundColor,
+        timeout
+      });
+    } catch (e) {
+      throw new ScreenshotError("failed", `capture failed (an image/font may be served without CORS '*'): ${String(e?.message || e)}`);
+    }
+    const result = {
+      mime: MIME[format],
+      width: Math.round((params.width ?? el.clientWidth) * scale),
+      height: Math.round((params.height ?? el.scrollHeight) * scale),
+      scale,
+      bytesApprox: blob.size
+    };
+    if ((params.encoding ?? "blob") === "dataURL") result.dataURL = await blobToDataURL(blob);
+    else result.blob = blob;
+    return result;
+  } finally {
+    restore?.();
+  }
+}
+
+// src/flow/flow.tsx
 var NavContext = createContext(null);
 var ExperimentContext = createContext({});
 function useExperiment(id) {
@@ -604,6 +739,7 @@ function usePageExitTimer(tracker, currentKey) {
 function FunnelView({
   pages,
   initialKey,
+  trustInitialKey = false,
   layout,
   fallback,
   prefetch: prefetchMode = "auto",
@@ -651,6 +787,7 @@ function FunnelView({
     if (!initialKey || initialKey === start) return start ? [start] : [];
     const target = toSlot(initialKey);
     const page2 = flowPages.find((p) => p.key === target);
+    if (trustInitialKey) return page2 ? [target] : start ? [start] : [];
     const guard = entryGuard(page2?.meta);
     const ok = page2 && (!guard || evaluateGate(guard, funnel.snapshot()));
     const first = ok ? target : start;
@@ -736,6 +873,44 @@ function FunnelView({
     canGoBack: history.length > 1,
     isNavigating
   };
+  const bus = useBusInternal();
+  const navRef = useRef(value);
+  navRef.current = value;
+  useEffect(() => {
+    if (!bus) return;
+    const control = {
+      goTo: (key) => {
+        if (!components.has(toRenderKey(key))) return false;
+        navRef.current.go(key);
+        return true;
+      },
+      goNext: () => navRef.current.next(),
+      goPrevious: () => navRef.current.back(),
+      snapshot: () => {
+        const v = navRef.current;
+        return {
+          key: v.page.key,
+          index: v.page.index,
+          total: v.page.total,
+          progressPercentage: v.page.progressPercentage,
+          canGoBack: v.canGoBack,
+          nextCandidates: v.nextCandidates
+        };
+      }
+    };
+    return bus.registerNavigation(control);
+  }, [bus]);
+  useEffect(() => {
+    const v = navRef.current;
+    bus?.emit("navigation", {
+      key: v.page.key,
+      index: v.page.index,
+      total: v.page.total,
+      progressPercentage: v.page.progressPercentage,
+      canGoBack: v.canGoBack,
+      nextCandidates: v.nextCandidates
+    });
+  }, [bus, currentKey]);
   const renderKey = toRenderKey(currentKey);
   const Current = components.get(renderKey);
   const pageEl = createElement(Suspense, { fallback: fallback ?? null }, Current ? createElement(Current) : null);
@@ -751,6 +926,81 @@ function useNavigation() {
   if (!ctx) throw new Error("useNavigation must be used inside <FunnelView>");
   return ctx;
 }
+var EMBED_CAPABILITIES = {
+  methods: ["nav.snapshot", "nav.goTo", "nav.goNext", "nav.goPrevious", "screenshot"],
+  events: ["navigation"]
+};
+function EmbedBridge() {
+  const bus = useBusInternal();
+  useEffect(() => {
+    if (!bus || typeof window === "undefined" || window.parent === window) return;
+    const parent = window.parent;
+    let disposed = false;
+    const send = (msg) => {
+      try {
+        parent.postMessage({ af: AF_PROTOCOL, source: "af-preview", ...msg }, "*");
+      } catch {
+      }
+    };
+    const hello = () => send({ kind: "hello", role: "funnel", protocol: AF_PROTOCOL, capabilities: EMBED_CAPABILITIES });
+    const sendSnapshot = () => {
+      const s = bus.navigation();
+      if (s) send({ kind: "event", event: "navigation", data: s });
+    };
+    async function invoke(method, params) {
+      switch (method) {
+        case "nav.snapshot":
+          return bus.navigation();
+        case "nav.goTo": {
+          const key = params?.key;
+          if (typeof key !== "string" || !bus.goTo(key)) throw { code: "bad_params", message: `unknown page key: ${String(key)}` };
+          return void 0;
+        }
+        case "nav.goNext":
+          bus.goNext();
+          return void 0;
+        case "nav.goPrevious":
+          bus.goPrevious();
+          return void 0;
+        case "screenshot":
+          return await captureScreenshot(params ?? {});
+        default:
+          throw { code: "unknown_method", message: `unknown method: ${method}` };
+      }
+    }
+    async function onMsg(e) {
+      if (e.source !== parent) return;
+      const d = e.data;
+      if (!d || typeof d !== "object" || d.af !== AF_PROTOCOL || d.source !== "af-host") return;
+      if (d.kind === "hello") {
+        hello();
+        sendSnapshot();
+        return;
+      }
+      if (d.kind !== "request" || typeof d.id !== "string") return;
+      try {
+        const result = await invoke(d.method, d.params);
+        if (!disposed) send({ kind: "response", id: d.id, ok: true, result });
+      } catch (err) {
+        const e2 = err;
+        const error = e2 && typeof e2.code === "string" ? { code: e2.code, message: String(e2.message ?? e2.code) } : { code: "failed", message: String(e2?.message ?? err) };
+        if (!disposed) send({ kind: "response", id: d.id, ok: false, error });
+      }
+    }
+    window.addEventListener("message", onMsg);
+    const offNav = bus.on("navigation", (data) => {
+      if (!disposed) send({ kind: "event", event: "navigation", data });
+    });
+    hello();
+    sendSnapshot();
+    return () => {
+      disposed = true;
+      offNav();
+      window.removeEventListener("message", onMsg);
+    };
+  }, [bus]);
+  return null;
+}
 function usePage() {
   return useNavigation().page;
 }
@@ -2568,6 +2818,7 @@ var FunnelCtx = createContext(null);
 function FunnelProvider({
   config,
   sessionValues,
+  deferSessionValues = false,
   tracker,
   context: contextOpts,
   products,
@@ -2583,7 +2834,12 @@ function FunnelProvider({
   const [value] = useState(() => {
     const s = store ?? createFunnelStore(
       { responses: config?.responses, data: config?.data },
-      sessionValues
+      // FLASH-FREE HYDRATION: with deferSessionValues the initial render is seeded with
+      // DEFAULTS ONLY, so the client's first render is byte-identical to the build-time
+      // DEFAULT-state prerender it hydrates against (clean match). The visitor's saved
+      // answers arrive as a post-hydration setMany below. Without the flag, sessionValues
+      // seed the store at construction (SSR + non-prerendered paths).
+      deferSessionValues ? void 0 : sessionValues
     );
     const ctx = buildContext({
       funnelId: config?.id,
@@ -2615,6 +2871,12 @@ function FunnelProvider({
     };
   });
   useEffect(() => attachBus(value.bus), [value.bus]);
+  useEffect(() => {
+    if (!deferSessionValues || !sessionValues) return;
+    const updates = {};
+    for (const [key, v] of Object.entries(sessionValues)) if (v !== void 0) updates[key] = v;
+    if (Object.keys(updates).length > 0) value.store.setMany(updates);
+  }, []);
   useEffect(() => {
     value.tracker.setAcquisition?.(buildAcquisition(value.context));
   }, [value]);
@@ -2650,6 +2912,9 @@ function useFunnelCtx() {
 function useFunnel() {
   return useFunnelCtx().funnel;
 }
+function useBusInternal() {
+  return useContext(FunnelCtx)?.bus ?? null;
+}
 function useStoreKey(store, key) {
   const subscribe = useCallback(
     (cb) => store.subscribe(cb, { keys: [key] }),
@@ -2713,6 +2978,152 @@ function useContextValue(path) {
   );
 }
 
+// src/tracking/snapshotPersistence.ts
+function createSnapshotPersistence(opts) {
+  const baseDelay = opts.baseDelayMs ?? 1e3;
+  const maxDelay = opts.maxDelayMs ?? 3e4;
+  const setT = opts.timers?.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearT = opts.timers?.clearTimeout ?? ((h) => clearTimeout(h));
+  const rand = opts.random ?? Math.random;
+  let pending = null;
+  let seq = 0;
+  let pendingSeq = 0;
+  let inFlight = false;
+  let attempt = 0;
+  let retryTimer = null;
+  let disposed = false;
+  let fatalSeq = -1;
+  const clearRetry = () => {
+    if (retryTimer !== null) {
+      clearT(retryTimer);
+      retryTimer = null;
+    }
+  };
+  const buildBody = (snapshot, s) => JSON.stringify({ sessionId: opts.getSessionId(), userData: snapshot, seq: s });
+  const trySend = () => {
+    if (disposed || inFlight || pending === null) return;
+    if (retryTimer !== null) return;
+    const sessionId = opts.getSessionId();
+    if (!sessionId) return;
+    if (typeof navigator !== "undefined" && navigator.onLine === false) return;
+    if (pendingSeq === fatalSeq) return;
+    const snapshot = pending;
+    const sentSeq = pendingSeq;
+    const body = buildBody(snapshot, sentSeq);
+    inFlight = true;
+    void fetch(opts.url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+      keepalive: true
+    }).then((res) => {
+      inFlight = false;
+      if (disposed) return;
+      if (res.ok) {
+        attempt = 0;
+        if (pendingSeq === sentSeq) pending = null;
+        else trySend();
+        return;
+      }
+      if (res.status >= 400 && res.status < 500) {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(
+            `[appfunnel] snapshot persist rejected ${res.status} (dropping snapshot; check session/payload)`
+          );
+        }
+        fatalSeq = sentSeq;
+        if (pendingSeq === sentSeq) pending = null;
+        else trySend();
+        return;
+      }
+      scheduleRetry();
+    }).catch(() => {
+      inFlight = false;
+      if (disposed) return;
+      scheduleRetry();
+    });
+  };
+  const scheduleRetry = () => {
+    if (disposed || pending === null) return;
+    const exp = Math.min(maxDelay, baseDelay * 2 ** attempt);
+    const delay2 = Math.round(exp * (0.5 + rand() * 0.5));
+    attempt++;
+    clearRetry();
+    retryTimer = setT(() => {
+      retryTimer = null;
+      trySend();
+    }, delay2);
+  };
+  const push = (snapshot) => {
+    if (disposed) return;
+    pending = snapshot;
+    pendingSeq = ++seq;
+    if (fatalSeq !== -1 && pendingSeq !== fatalSeq) fatalSeq = -1;
+    if (retryTimer === null) trySend();
+  };
+  const flushBeacon = () => {
+    if (disposed || pending === null) return;
+    const sessionId = opts.getSessionId();
+    if (!sessionId) return;
+    const body = buildBody(pending, pendingSeq);
+    let delivered = false;
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      try {
+        delivered = navigator.sendBeacon(
+          opts.url,
+          new Blob([body], { type: "application/json" })
+        );
+      } catch {
+        delivered = false;
+      }
+    }
+    if (!delivered) {
+      try {
+        void fetch(opts.url, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body,
+          keepalive: true
+        }).catch(() => {
+        });
+        delivered = true;
+      } catch {
+        delivered = false;
+      }
+    }
+    if (delivered) pending = null;
+  };
+  const onHidden = () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      flushBeacon();
+    }
+  };
+  const onPageHide = () => flushBeacon();
+  const onOnline = () => trySend();
+  if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    try {
+      document.addEventListener("visibilitychange", onHidden);
+      window.addEventListener("pagehide", onPageHide);
+      window.addEventListener("online", onOnline);
+    } catch {
+    }
+  }
+  const dispose = () => {
+    disposed = true;
+    clearRetry();
+    pending = null;
+    if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+      try {
+        document.removeEventListener("visibilitychange", onHidden);
+        window.removeEventListener("pagehide", onPageHide);
+        window.removeEventListener("online", onOnline);
+      } catch {
+      }
+    }
+  };
+  return { push, flushBeacon, dispose };
+}
+
 // src/tracking/platformTracker.ts
 function validClickIds(acq) {
   return Object.entries(acq.clickIds ?? {}).filter(
@@ -2818,32 +3229,35 @@ function createPlatformTracker(cfg) {
     }
   };
   const VARS_DEBOUNCE_MS = 800;
+  const dataUrl = `${base}/campaign/${encodeURIComponent(cfg.campaignId)}/event/session/data`;
   let pendingVars = null;
   let varsTimer = null;
+  const persistence = createSnapshotPersistence({
+    url: dataUrl,
+    getSessionId: () => sessionId
+  });
   const flushVars = () => {
     if (varsTimer) {
       clearTimeout(varsTimer);
       varsTimer = null;
     }
     if (!pendingVars) return;
-    const doPost = () => {
-      if (!pendingVars || !sessionId) return;
-      const userData = pendingVars;
-      pendingVars = null;
-      void fetch(`${base}/campaign/${encodeURIComponent(cfg.campaignId)}/event/session/data`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ sessionId, userData }),
-        keepalive: true
-      }).catch((e) => {
-        if (process.env.NODE_ENV !== "production") console.warn("[appfunnel] variable persist failed:", e);
-      });
-    };
-    if (sessionId) doPost();
-    else chain = chain.then(doPost);
+    const snapshot = pendingVars;
+    pendingVars = null;
+    persistence.push(snapshot);
+    if (!sessionId) chain = chain.then(() => {
+      persistence.push(snapshot);
+    });
+  };
+  const drainOnExit = () => {
+    if (pendingVars) {
+      flushVars();
+      persistence.flushBeacon();
+    }
   };
   try {
-    window.addEventListener("pagehide", flushVars);
+    window.addEventListener("visibilitychange", drainOnExit);
+    window.addEventListener("pagehide", drainOnExit);
   } catch {
   }
   if (cfg.experiment?.id && cfg.experiment.variant) {
@@ -2886,6 +3300,7 @@ function createFunnelTree({
 }) {
   return function tree(opts) {
     const mode = opts.mode ?? "live";
+    const embedEnabled = opts.embed ?? false;
     const tracker = opts.tracking ? createPlatformTracker({
       ...opts.tracking,
       visitorId: opts.visitorId,
@@ -2907,6 +3322,7 @@ function createFunnelTree({
         Fragment,
         null,
         createElement(CheckoutResume, null),
+        embedEnabled ? createElement(EmbedBridge, null) : null,
         layout ? createElement(layout, null, children) : children
       );
     };
@@ -2920,6 +3336,7 @@ function createFunnelTree({
         tracker,
         checkout,
         sessionValues: opts.sessionValues,
+        deferSessionValues: opts.deferSessionValues,
         experiments: opts.experiments,
         context: {
           mode,
@@ -2931,6 +3348,13 @@ function createFunnelTree({
           pages,
           layout: layoutWithResume,
           initialKey: opts.initialKey,
+          // FLASH-FREE HYDRATION (Option B, FIX 1): trust the SERVER-resolved initialKey instead of
+          // re-running the entry guard. The CLIENT sets this via deferSessionValues (its deferred
+          // snapshot is empty, so re-running the guard would bounce a qualified deep-link and
+          // mismatch the markup). The build-time PRERENDER sets `trustInitialKey` explicitly so a
+          // guarded page prerenders its OWN default-state markup (the renderer picks target-vs-bounce
+          // at serve time). Live SSR fallback leaves both off → the guard runs against real values.
+          trustInitialKey: opts.trustInitialKey ?? opts.deferSessionValues,
           prefetch: "off"
           // renderer background-modulepreloads all chunks
         })