@particle-academy/fancy-pixel 0.1.0 → 0.2.1

package/dist/index.cjs

@@ -31,6 +31,533 @@ function sendPixelBeacon(endpoint, payload) {
   return false;
 }
 
+// node_modules/@particle-academy/fancy-heuristics-js/dist/chunk-3RKEJJ4Y.js
+function base(kind, actor, path, ts) {
+  return { kind, actor, path, ts };
+}
+function buildPageview(path, ts, actor = "human") {
+  return base("pageview", actor, path, ts);
+}
+function buildClick(args) {
+  const e = base("click", args.actor ?? "human", args.path, args.ts);
+  e.x = args.x;
+  e.y = args.y;
+  e.vw = args.vw;
+  e.vh = args.vh;
+  if (args.targetId !== void 0) e.targetId = args.targetId;
+  if (args.label !== void 0) e.label = args.label;
+  if (args.meta !== void 0) e.meta = args.meta;
+  return e;
+}
+function buildScroll(args) {
+  const e = base("scroll", args.actor ?? "human", args.path, args.ts);
+  e.scrollPct = args.scrollPct;
+  return e;
+}
+function buildPointer(args) {
+  const e = base("pointer", args.actor ?? "human", args.path, args.ts);
+  e.x = args.x;
+  e.y = args.y;
+  e.vw = args.vw;
+  e.vh = args.vh;
+  return e;
+}
+function buildDwell(args) {
+  const e = base("dwell", args.actor ?? "human", args.path, args.ts);
+  e.dwellMs = args.dwellMs;
+  return e;
+}
+function scrollPercent(scrollTop, scrollable) {
+  if (scrollable <= 0) return 100;
+  const pct = scrollTop / scrollable * 100;
+  if (pct <= 0) return 0;
+  if (pct >= 100) return 100;
+  return Math.round(pct);
+}
+function mapActivityToEvent(e, path) {
+  const source = e.source ?? "agent";
+  if (source !== "agent" && source !== "flow") return void 0;
+  const targetId = e.target?.elementId;
+  const label = e.target?.label;
+  const dwellMs = numericMeta(e.meta, "dwellMs");
+  if (dwellMs !== void 0) {
+    const ev2 = buildDwell({ path, ts: e.timestamp, dwellMs, actor: "agent" });
+    if (targetId !== void 0) ev2.targetId = targetId;
+    if (label !== void 0) ev2.label = label;
+    ev2.meta = { action: e.action, agentId: e.agentId, source };
+    return ev2;
+  }
+  const ev = buildClick({
+    path,
+    ts: e.timestamp,
+    x: numericMeta(e.meta, "x") ?? 0,
+    y: numericMeta(e.meta, "y") ?? 0,
+    vw: numericMeta(e.meta, "vw") ?? 0,
+    vh: numericMeta(e.meta, "vh") ?? 0,
+    actor: "agent",
+    targetId,
+    label,
+    meta: { action: e.action, agentId: e.agentId, source }
+  });
+  return ev;
+}
+function numericMeta(meta, key) {
+  const v = meta?.[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+async function tapAgentActivity(opts) {
+  const load = opts.loadModule ?? defaultLoad;
+  let mod;
+  try {
+    mod = await load();
+  } catch {
+    mod = void 0;
+  }
+  if (!mod || typeof mod.onActivity !== "function") return () => {
+  };
+  try {
+    return mod.onActivity((e) => {
+      const ev = mapActivityToEvent(e, opts.path());
+      if (ev) opts.emit(ev);
+    });
+  } catch {
+    return () => {
+    };
+  }
+}
+async function defaultLoad() {
+  const spec = "@particle-academy/fancy-auto-common";
+  try {
+    const mod = await import(
+      /* @vite-ignore */
+      spec
+    );
+    if (mod && typeof mod.onActivity === "function") {
+      return mod;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+var EventBuffer = class {
+  constructor(opts) {
+    this.events = [];
+    this.siteKey = opts.siteKey;
+    this.url = joinCollect(opts.endpoint);
+    this.sessionId = opts.sessionId;
+    this.context = opts.context;
+    this.send = opts.send ?? defaultSend;
+  }
+  /** Queue one event for the next flush. */
+  add(event) {
+    this.events.push(event);
+  }
+  /** Number of buffered (un-flushed) events. */
+  get size() {
+    return this.events.length;
+  }
+  /** The collect URL this buffer ships to. */
+  get collectUrl() {
+    return this.url;
+  }
+  /**
+   * Ship the buffered events as one batch. No-op when empty. On a failed
+   * handoff the events are kept so the next flush retries them.
+   */
+  flush() {
+    if (this.events.length === 0) return;
+    const batch = {
+      siteKey: this.siteKey,
+      sessionId: this.sessionId,
+      events: this.events
+    };
+    if (this.context !== void 0) batch.context = this.context;
+    const body = JSON.stringify(batch);
+    const ok = this.send(this.url, body);
+    if (ok) {
+      this.events = [];
+      this.context = void 0;
+    }
+  }
+};
+function joinCollect(endpoint) {
+  return endpoint.replace(/\/+$/, "") + "/collect";
+}
+var defaultSend = (url, body) => {
+  const nav = typeof navigator !== "undefined" ? navigator : void 0;
+  if (nav && typeof nav.sendBeacon === "function") {
+    try {
+      const blob = typeof Blob !== "undefined" ? new Blob([body], { type: "application/json" }) : body;
+      if (nav.sendBeacon(url, blob)) return true;
+    } catch {
+    }
+  }
+  if (typeof fetch === "function") {
+    try {
+      void fetch(url, {
+        method: "POST",
+        body,
+        headers: { "Content-Type": "application/json" },
+        keepalive: true,
+        // Cross-origin ingestion: the PHP routes are CSRF-exempt; we don't read
+        // the response, so an opaque mode is fine.
+        mode: "cors",
+        credentials: "omit"
+      }).catch(() => {
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+};
+var UTM_KEYS = [
+  ["utm_source", "source"],
+  ["utm_medium", "medium"],
+  ["utm_campaign", "campaign"],
+  ["utm_term", "term"],
+  ["utm_content", "content"]
+];
+function buildContext() {
+  if (typeof document === "undefined" || !document) return void 0;
+  const ctx = {};
+  if (typeof document.referrer === "string") {
+    ctx.referrer = document.referrer;
+  }
+  const utm = parseUtm(
+    typeof location !== "undefined" && location ? location.search : void 0
+  );
+  if (utm) ctx.utm = utm;
+  const nav = typeof navigator !== "undefined" ? navigator : void 0;
+  if (nav && typeof nav.language === "string" && nav.language) {
+    ctx.lang = nav.language;
+  }
+  const tz = resolveTimeZone();
+  if (tz) ctx.tz = tz;
+  const scr = typeof screen !== "undefined" ? screen : void 0;
+  if (scr) {
+    if (typeof scr.width === "number") ctx.screenW = scr.width;
+    if (typeof scr.height === "number") ctx.screenH = scr.height;
+  }
+  if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+    ctx.dpr = window.devicePixelRatio;
+  }
+  return ctx;
+}
+function parseUtm(search) {
+  if (!search || typeof URLSearchParams === "undefined") return void 0;
+  let params;
+  try {
+    params = new URLSearchParams(search);
+  } catch {
+    return void 0;
+  }
+  const utm = {};
+  let found = false;
+  for (const [param, field] of UTM_KEYS) {
+    const raw = params.get(param);
+    if (raw) {
+      utm[field] = raw;
+      found = true;
+    }
+  }
+  return found ? utm : void 0;
+}
+function resolveTimeZone() {
+  try {
+    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat !== "function") {
+      return void 0;
+    }
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return tz || void 0;
+  } catch {
+    return void 0;
+  }
+}
+var SESSION_KEY = "fancy-heuristics:sid";
+var fallbackCounter = 0;
+function generateSessionId() {
+  const c = typeof globalThis !== "undefined" ? globalThis.crypto : void 0;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  if (c && typeof c.getRandomValues === "function") {
+    const bytes = new Uint8Array(16);
+    c.getRandomValues(bytes);
+    bytes[6] = bytes[6] & 15 | 64;
+    bytes[8] = bytes[8] & 63 | 128;
+    const hex = [];
+    for (let i = 0; i < 16; i++) hex.push(bytes[i].toString(16).padStart(2, "0"));
+    return hex.slice(0, 4).join("") + "-" + hex.slice(4, 6).join("") + "-" + hex.slice(6, 8).join("") + "-" + hex.slice(8, 10).join("") + "-" + hex.slice(10, 16).join("");
+  }
+  fallbackCounter = fallbackCounter + 1 >>> 0;
+  return `fh-${Date.now().toString(36)}-${fallbackCounter.toString(36)}`;
+}
+function resolveSessionId(store) {
+  const s = safeSessionStorage();
+  if (!s) return generateSessionId();
+  try {
+    const existing = s.getItem(SESSION_KEY);
+    if (existing) return existing;
+    const fresh = generateSessionId();
+    s.setItem(SESSION_KEY, fresh);
+    return fresh;
+  } catch {
+    return generateSessionId();
+  }
+}
+function safeSessionStorage() {
+  try {
+    const ss = globalThis.sessionStorage;
+    if (!ss) return void 0;
+    ss.getItem(SESSION_KEY);
+    return ss;
+  } catch {
+    return void 0;
+  }
+}
+var DEFAULT_FLUSH_MS = 1500;
+var DEFAULT_POINTER_THROTTLE_MS = 120;
+var DEFAULT_SCROLL_THROTTLE_MS = 200;
+function resolveTrack(track) {
+  return {
+    pageview: track?.pageview ?? true,
+    dwell: track?.dwell ?? true,
+    click: track?.click ?? true,
+    scroll: track?.scroll ?? true,
+    pointer: track?.pointer ?? true,
+    agent: track?.agent ?? true
+  };
+}
+function createCollector(opts) {
+  if (!opts || !opts.siteKey || !opts.endpoint) {
+    throw new Error("createCollector: { siteKey, endpoint } are required");
+  }
+  const track = resolveTrack(opts.track);
+  const flushMs = opts.flushMs ?? DEFAULT_FLUSH_MS;
+  const pointerThrottleMs = opts.pointerThrottleMs ?? DEFAULT_POINTER_THROTTLE_MS;
+  const scrollThrottleMs = opts.scrollThrottleMs ?? DEFAULT_SCROLL_THROTTLE_MS;
+  const sessionId = resolveSessionId();
+  const context = buildContext();
+  const buffer = new EventBuffer({
+    siteKey: opts.siteKey,
+    endpoint: opts.endpoint,
+    sessionId,
+    ...context !== void 0 ? { context } : {}
+  });
+  let started = false;
+  let flushTimer;
+  let agentUnsub;
+  const teardown = [];
+  let visibleSince = 0;
+  let accumulatedDwell = 0;
+  let maxScrollPct = 0;
+  let lastScrollAt = 0;
+  let lastPointerAt = 0;
+  const path = () => typeof location !== "undefined" && location ? location.pathname : "/";
+  const now = opts.now ?? (() => Date.now());
+  const vw = () => typeof window !== "undefined" ? window.innerWidth || 0 : 0;
+  const vh = () => typeof window !== "undefined" ? window.innerHeight || 0 : 0;
+  const emit = (e) => buffer.add(e);
+  const onClick = (ev) => {
+    const me = ev;
+    const targetEl = ev.target;
+    const { id, label } = describeTarget(targetEl);
+    emit(
+      buildClick({
+        path: path(),
+        ts: now(),
+        x: Math.round(me.clientX ?? 0),
+        y: Math.round(me.clientY ?? 0),
+        vw: vw(),
+        vh: vh(),
+        targetId: id,
+        label
+      })
+    );
+  };
+  const onScroll = () => {
+    const t = now();
+    if (t - lastScrollAt < scrollThrottleMs) return;
+    lastScrollAt = t;
+    const doc = typeof document !== "undefined" ? document.documentElement : void 0;
+    if (!doc) return;
+    const scrollTop = (typeof window !== "undefined" ? window.scrollY : 0) || doc.scrollTop || 0;
+    const scrollable = doc.scrollHeight - doc.clientHeight;
+    const pct = scrollPercent(scrollTop, scrollable);
+    if (pct > maxScrollPct) {
+      maxScrollPct = pct;
+      emit(buildScroll({ path: path(), ts: t, scrollPct: maxScrollPct }));
+    }
+  };
+  const onPointerMove = (ev) => {
+    const t = now();
+    if (t - lastPointerAt < pointerThrottleMs) return;
+    lastPointerAt = t;
+    const pe = ev;
+    emit(
+      buildPointer({
+        path: path(),
+        ts: t,
+        x: Math.round(pe.clientX ?? 0),
+        y: Math.round(pe.clientY ?? 0),
+        vw: vw(),
+        vh: vh()
+      })
+    );
+  };
+  const isVisible = () => typeof document === "undefined" || document.visibilityState !== "hidden";
+  const openDwellWindow = () => {
+    if (visibleSince === 0) visibleSince = now();
+  };
+  const closeDwellWindow = () => {
+    if (visibleSince !== 0) {
+      accumulatedDwell += now() - visibleSince;
+      visibleSince = 0;
+    }
+  };
+  const onVisibilityChange = () => {
+    if (isVisible()) openDwellWindow();
+    else closeDwellWindow();
+  };
+  const emitDwell = () => {
+    closeDwellWindow();
+    if (accumulatedDwell > 0) {
+      emit(buildDwell({ path: path(), ts: now(), dwellMs: accumulatedDwell }));
+      accumulatedDwell = 0;
+    }
+    if (isVisible()) openDwellWindow();
+  };
+  const onPageHide = () => {
+    if (track.dwell) {
+      closeDwellWindow();
+      if (accumulatedDwell > 0) {
+        emit(buildDwell({ path: path(), ts: now(), dwellMs: accumulatedDwell }));
+        accumulatedDwell = 0;
+      }
+    }
+    buffer.flush();
+  };
+  const addListener = (target, type, handler, options) => {
+    if (!target || typeof target.addEventListener !== "function") return;
+    target.addEventListener(type, handler, options);
+    teardown.push(() => target.removeEventListener(type, handler, options));
+  };
+  return {
+    start() {
+      if (started) return;
+      started = true;
+      const doc = typeof document !== "undefined" ? document : void 0;
+      const win = typeof window !== "undefined" ? window : void 0;
+      if (track.pageview) {
+        emit(buildPageview(path(), now()));
+      }
+      if (track.dwell) {
+        openDwellWindow();
+        addListener(doc, "visibilitychange", onVisibilityChange);
+      }
+      if (track.click) {
+        addListener(doc, "click", onClick, { capture: true, passive: true });
+      }
+      if (track.scroll) {
+        addListener(win, "scroll", onScroll, { passive: true });
+      }
+      if (track.pointer) {
+        addListener(win, "pointermove", onPointerMove, { passive: true });
+      }
+      addListener(win, "pagehide", onPageHide);
+      if (track.agent) {
+        void tapAgentActivity({ path, emit }).then((unsub) => {
+          if (started) agentUnsub = unsub;
+          else unsub();
+        });
+      }
+      if (typeof setInterval === "function") {
+        flushTimer = setInterval(() => {
+          if (track.dwell) emitDwell();
+          buffer.flush();
+        }, flushMs);
+      }
+    },
+    stop() {
+      if (!started) return;
+      started = false;
+      if (flushTimer !== void 0) {
+        clearInterval(flushTimer);
+        flushTimer = void 0;
+      }
+      for (const fn of teardown.splice(0)) {
+        try {
+          fn();
+        } catch {
+        }
+      }
+      if (agentUnsub) {
+        try {
+          agentUnsub();
+        } catch {
+        }
+        agentUnsub = void 0;
+      }
+      if (track.dwell) {
+        closeDwellWindow();
+        if (accumulatedDwell > 0) {
+          emit(buildDwell({ path: path(), ts: now(), dwellMs: accumulatedDwell }));
+          accumulatedDwell = 0;
+        }
+      }
+      buffer.flush();
+    },
+    flush() {
+      buffer.flush();
+    }
+  };
+}
+function describeTarget(el) {
+  if (!el) return {};
+  let node = el;
+  let id;
+  for (let depth = 0; node && depth < 5; depth++) {
+    const candidate = node.getAttribute?.("data-fancy-id") ?? node.getAttribute?.("data-testid") ?? (node.id || void 0);
+    if (candidate) {
+      id = candidate;
+      break;
+    }
+    node = node.parentElement;
+  }
+  const labelSource = node ?? el;
+  const label = readLabel(labelSource);
+  const out = {};
+  if (id !== void 0) out.id = id;
+  if (label !== void 0) out.label = label;
+  return out;
+}
+function readLabel(el) {
+  const aria = el.getAttribute?.("aria-label");
+  if (aria) return trim(aria);
+  const text = el.textContent;
+  if (text) {
+    const t = trim(text);
+    if (t) return t;
+  }
+  const tag = el.tagName ? el.tagName.toLowerCase() : void 0;
+  return tag;
+}
+function trim(s) {
+  return s.replace(/\s+/g, " ").trim().slice(0, 120);
+}
+
+// src/collector.ts
+var factory = (opts) => createCollector({ siteKey: opts.siteKey, endpoint: opts.endpoint });
+function createPixelCollector(opts) {
+  return factory(opts);
+}
+function __setCollectorFactory(next) {
+  factory = next ?? ((opts) => createCollector({ siteKey: opts.siteKey, endpoint: opts.endpoint }));
+}
+
 // src/render.ts
 function logoGlyph(size) {
   return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" aria-hidden="true" focusable="false" style="display:block;flex:0 0 auto;">
@@ -191,6 +718,7 @@ function mountPixel(opts = {}) {
   const mode = MODES.includes(opts.mode) ? opts.mode : "floating";
   const siteKey = opts.siteKey ?? "";
   const endpoint = opts.endpoint ?? "";
+  const collect = opts.collect !== false;
   const href = opts.href ?? DEFAULT_HREF;
   const target = opts.target ?? null;
   const host = createPixelHost(style, mode, href);
@@ -244,11 +772,21 @@ function mountPixel(opts = {}) {
     setVisible(true);
   }
   beacon();
+  let collector = null;
+  if (endpoint && collect) {
+    try {
+      collector = createPixelCollector({ siteKey, endpoint });
+      collector.start();
+    } catch {
+      collector = null;
+    }
+  }
   const resolved = {
     style,
     mode,
     siteKey,
     endpoint,
+    collect,
     href,
     target
   };
@@ -257,12 +795,22 @@ function mountPixel(opts = {}) {
     get visible() {
       return visible;
     },
+    get collector() {
+      return collector;
+    },
     options: resolved,
     destroy() {
       if (destroyed) return;
       destroyed = true;
       observer?.disconnect();
       observer = null;
+      if (collector) {
+        try {
+          collector.stop();
+        } catch {
+        }
+        collector = null;
+      }
       host.remove();
     }
   };
@@ -280,14 +828,16 @@ function readScriptConfig() {
   }
   if (!el) return null;
   const ds = el.dataset;
-  if (ds.style === void 0 && ds.mode === void 0 && ds.site === void 0 && ds.endpoint === void 0 && ds.fancyPixel === void 0) {
+  if (ds.style === void 0 && ds.mode === void 0 && ds.site === void 0 && ds.endpoint === void 0 && ds.collect === void 0 && ds.fancyPixel === void 0) {
     return null;
   }
+  const collect = ds.collect !== void 0 ? ds.collect !== "false" : void 0;
   return {
     style: ds.style,
     mode: ds.mode,
     siteKey: ds.site,
     endpoint: ds.endpoint,
+    collect,
     target: ds.target ?? null,
     href: ds.href
   };
@@ -310,7 +860,9 @@ function autoInit() {
   return run();
 }
 
+exports.__setCollectorFactory = __setCollectorFactory;
 exports.autoInit = autoInit;
+exports.createPixelCollector = createPixelCollector;
 exports.createPixelHost = createPixelHost;
 exports.hostStyleFor = hostStyleFor;
 exports.mountPixel = mountPixel;