@particle-academy/agent-integrations 0.17.0 → 0.19.0

package/dist/heuristics/sink.d.cts

@@ -0,0 +1,78 @@
+import { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
+
+/**
+ * In-browser heuristics analytics sink for agent traffic.
+ *
+ * Agent bridge mutations emit `AutoActivityEvent`s into the in-page
+ * `@particle-academy/fancy-auto-common` activity bus (presence / cursors).
+ * This sink — living in THIS package so it shares the SAME bundled
+ * `fancy-auto-common` module instance the bridges emit into — subscribes to
+ * that bus and POSTs each event to the `fancy-heuristics` `/collect` endpoint
+ * as `actor:"agent"`, so agent traffic shows up in the heuristics dashboard.
+ *
+ * It does NOT depend on `fancy-heuristics` / `fancy-heuristics-js`: it only
+ * emits the frozen wire shape over HTTP. The mapping mirrors
+ * `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent` — keep parity.
+ */
+
+/** What kind of interaction an event captures (mirrors fancy-heuristics-js). */
+type HeuristicsEventKind = "pageview" | "click" | "scroll" | "pointer" | "dwell";
+/** Who produced the interaction. */
+type HeuristicsActor = "human" | "agent";
+/**
+ * A single interaction event — mirrors `fancy-heuristics-js` `HeuristicsEvent`.
+ * Optional fields are omitted (never `null`) when not relevant to the `kind`.
+ */
+interface HeuristicsEvent {
+    kind: HeuristicsEventKind;
+    actor: HeuristicsActor;
+    /** location.pathname at capture time. */
+    path: string;
+    /** ms epoch. */
+    ts: number;
+    x?: number;
+    y?: number;
+    vw?: number;
+    vh?: number;
+    scrollPct?: number;
+    dwellMs?: number;
+    targetId?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+/** The batched POST body sent to `${endpoint}/collect`. */
+interface CollectBatch {
+    siteKey: string;
+    sessionId: string;
+    events: HeuristicsEvent[];
+}
+interface AttachHeuristicsSinkOptions {
+    /** Base URL, e.g. "/heuristics". POSTs to `${endpoint}/collect`. */
+    endpoint: string;
+    /** Identifies the site to the ingestion endpoint. */
+    siteKey: string;
+    /** Stable session id. Default: a generated "agent-<rand>" per attach. */
+    sessionId?: string;
+    /** Resolves the current path. Default: `() => location.pathname`. */
+    path?: () => string;
+    /** Which activity sources to record. Default "all". */
+    source?: "agent" | "flow" | "all";
+    /** Flush interval in ms. Default 2000. */
+    batchMs?: number;
+}
+/**
+ * Map one activity event to an `actor:"agent"` HeuristicsEvent. Activities
+ * carrying a finite `meta.dwellMs` become `kind:"dwell"`; everything else is a
+ * discrete `kind:"click"` with x/y/vw/vh pulled from numeric meta (default 0).
+ * Mirrors `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent`.
+ */
+declare function mapActivityToEvent(e: AutoActivityEvent, path: string): HeuristicsEvent;
+/**
+ * Subscribe to the in-page agent activity bus and forward each matching event
+ * to the heuristics `/collect` endpoint as `actor:"agent"`. SSR-safe (returns a
+ * no-op when there is no `window`). Returns an unsubscribe that flushes the
+ * buffer and detaches all listeners/timers.
+ */
+declare function attachHeuristicsSink(opts: AttachHeuristicsSinkOptions): () => void;
+
+export { type AttachHeuristicsSinkOptions, type CollectBatch, type HeuristicsEvent, attachHeuristicsSink, mapActivityToEvent };

package/dist/heuristics/sink.d.ts

@@ -0,0 +1,78 @@
+import { AutoActivityEvent } from '@particle-academy/fancy-auto-common';
+
+/**
+ * In-browser heuristics analytics sink for agent traffic.
+ *
+ * Agent bridge mutations emit `AutoActivityEvent`s into the in-page
+ * `@particle-academy/fancy-auto-common` activity bus (presence / cursors).
+ * This sink — living in THIS package so it shares the SAME bundled
+ * `fancy-auto-common` module instance the bridges emit into — subscribes to
+ * that bus and POSTs each event to the `fancy-heuristics` `/collect` endpoint
+ * as `actor:"agent"`, so agent traffic shows up in the heuristics dashboard.
+ *
+ * It does NOT depend on `fancy-heuristics` / `fancy-heuristics-js`: it only
+ * emits the frozen wire shape over HTTP. The mapping mirrors
+ * `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent` — keep parity.
+ */
+
+/** What kind of interaction an event captures (mirrors fancy-heuristics-js). */
+type HeuristicsEventKind = "pageview" | "click" | "scroll" | "pointer" | "dwell";
+/** Who produced the interaction. */
+type HeuristicsActor = "human" | "agent";
+/**
+ * A single interaction event — mirrors `fancy-heuristics-js` `HeuristicsEvent`.
+ * Optional fields are omitted (never `null`) when not relevant to the `kind`.
+ */
+interface HeuristicsEvent {
+    kind: HeuristicsEventKind;
+    actor: HeuristicsActor;
+    /** location.pathname at capture time. */
+    path: string;
+    /** ms epoch. */
+    ts: number;
+    x?: number;
+    y?: number;
+    vw?: number;
+    vh?: number;
+    scrollPct?: number;
+    dwellMs?: number;
+    targetId?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+/** The batched POST body sent to `${endpoint}/collect`. */
+interface CollectBatch {
+    siteKey: string;
+    sessionId: string;
+    events: HeuristicsEvent[];
+}
+interface AttachHeuristicsSinkOptions {
+    /** Base URL, e.g. "/heuristics". POSTs to `${endpoint}/collect`. */
+    endpoint: string;
+    /** Identifies the site to the ingestion endpoint. */
+    siteKey: string;
+    /** Stable session id. Default: a generated "agent-<rand>" per attach. */
+    sessionId?: string;
+    /** Resolves the current path. Default: `() => location.pathname`. */
+    path?: () => string;
+    /** Which activity sources to record. Default "all". */
+    source?: "agent" | "flow" | "all";
+    /** Flush interval in ms. Default 2000. */
+    batchMs?: number;
+}
+/**
+ * Map one activity event to an `actor:"agent"` HeuristicsEvent. Activities
+ * carrying a finite `meta.dwellMs` become `kind:"dwell"`; everything else is a
+ * discrete `kind:"click"` with x/y/vw/vh pulled from numeric meta (default 0).
+ * Mirrors `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent`.
+ */
+declare function mapActivityToEvent(e: AutoActivityEvent, path: string): HeuristicsEvent;
+/**
+ * Subscribe to the in-page agent activity bus and forward each matching event
+ * to the heuristics `/collect` endpoint as `actor:"agent"`. SSR-safe (returns a
+ * no-op when there is no `window`). Returns an unsubscribe that flushes the
+ * buffer and detaches all listeners/timers.
+ */
+declare function attachHeuristicsSink(opts: AttachHeuristicsSinkOptions): () => void;
+
+export { type AttachHeuristicsSinkOptions, type CollectBatch, type HeuristicsEvent, attachHeuristicsSink, mapActivityToEvent };

package/dist/heuristics.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+var fancyAutoCommon = require('@particle-academy/fancy-auto-common');
+
+// src/presence/registry.ts
+
+// src/heuristics/sink.ts
+function numericMeta(meta, key) {
+  const v = meta?.[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function mapActivityToEvent(e, path) {
+  const source = e.source ?? "agent";
+  const targetId = e.target?.elementId;
+  const label = e.target?.label;
+  const meta = {
+    action: e.action,
+    agentId: e.agentId,
+    source,
+    kind: e.target?.kind
+  };
+  const dwellMs = numericMeta(e.meta, "dwellMs");
+  if (dwellMs !== void 0) {
+    const ev2 = {
+      kind: "dwell",
+      actor: "agent",
+      path,
+      ts: e.timestamp,
+      dwellMs,
+      meta
+    };
+    if (targetId !== void 0) ev2.targetId = targetId;
+    if (label !== void 0) ev2.label = label;
+    return ev2;
+  }
+  const ev = {
+    kind: "click",
+    actor: "agent",
+    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,
+    meta
+  };
+  if (targetId !== void 0) ev.targetId = targetId;
+  if (label !== void 0) ev.label = label;
+  return ev;
+}
+function randomId() {
+  return Math.random().toString(36).slice(2, 10);
+}
+function attachHeuristicsSink(opts) {
+  if (typeof window === "undefined") return () => {
+  };
+  const endpoint = opts.endpoint.replace(/\/$/, "");
+  const url = `${endpoint}/collect`;
+  const siteKey = opts.siteKey;
+  const sessionId = opts.sessionId ?? `agent-${randomId()}`;
+  const getPath = opts.path ?? (() => location.pathname);
+  const source = opts.source ?? "all";
+  const batchMs = opts.batchMs ?? 2e3;
+  const filter = source === "all" ? void 0 : { source };
+  let buffer = [];
+  function flush() {
+    if (buffer.length === 0) return;
+    const events = buffer;
+    buffer = [];
+    const batch = { siteKey, sessionId, events };
+    const body = JSON.stringify(batch);
+    try {
+      if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+        const blob = new Blob([body], { type: "application/json" });
+        navigator.sendBeacon(url, blob);
+        return;
+      }
+    } catch {
+    }
+    try {
+      void fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true
+      });
+    } catch {
+    }
+  }
+  const unsubscribeActivity = fancyAutoCommon.onActivity((e) => {
+    try {
+      buffer.push(mapActivityToEvent(e, getPath()));
+    } catch {
+    }
+  }, filter);
+  const timer = setInterval(flush, batchMs);
+  const onPageHide = () => flush();
+  const onVisibility = () => {
+    if (document.visibilityState === "hidden") flush();
+  };
+  window.addEventListener("pagehide", onPageHide);
+  document.addEventListener("visibilitychange", onVisibility);
+  return () => {
+    unsubscribeActivity();
+    window.removeEventListener("pagehide", onPageHide);
+    document.removeEventListener("visibilitychange", onVisibility);
+    clearInterval(timer);
+    flush();
+  };
+}
+
+exports.attachHeuristicsSink = attachHeuristicsSink;
+exports.mapActivityToEvent = mapActivityToEvent;
+//# sourceMappingURL=heuristics.cjs.map
+//# sourceMappingURL=heuristics.cjs.map

package/dist/heuristics.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/heuristics/sink.ts"],"names":["ev","onActivity"],"mappings":"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","file":"heuristics.cjs","sourcesContent":["/**\n * In-browser heuristics analytics sink for agent traffic.\n *\n * Agent bridge mutations emit `AutoActivityEvent`s into the in-page\n * `@particle-academy/fancy-auto-common` activity bus (presence / cursors).\n * This sink — living in THIS package so it shares the SAME bundled\n * `fancy-auto-common` module instance the bridges emit into — subscribes to\n * that bus and POSTs each event to the `fancy-heuristics` `/collect` endpoint\n * as `actor:\"agent\"`, so agent traffic shows up in the heuristics dashboard.\n *\n * It does NOT depend on `fancy-heuristics` / `fancy-heuristics-js`: it only\n * emits the frozen wire shape over HTTP. The mapping mirrors\n * `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent` — keep parity.\n */\nimport { onActivity, type AgentActivityEvent } from \"../presence\";\n\n/** What kind of interaction an event captures (mirrors fancy-heuristics-js). */\ntype HeuristicsEventKind = \"pageview\" | \"click\" | \"scroll\" | \"pointer\" | \"dwell\";\n\n/** Who produced the interaction. */\ntype HeuristicsActor = \"human\" | \"agent\";\n\n/**\n * A single interaction event — mirrors `fancy-heuristics-js` `HeuristicsEvent`.\n * Optional fields are omitted (never `null`) when not relevant to the `kind`.\n */\nexport interface HeuristicsEvent {\n  kind: HeuristicsEventKind;\n  actor: HeuristicsActor;\n  /** location.pathname at capture time. */\n  path: string;\n  /** ms epoch. */\n  ts: number;\n  x?: number;\n  y?: number;\n  vw?: number;\n  vh?: number;\n  scrollPct?: number;\n  dwellMs?: number;\n  targetId?: string;\n  label?: string;\n  meta?: Record<string, unknown>;\n}\n\n/** The batched POST body sent to `${endpoint}/collect`. */\nexport interface CollectBatch {\n  siteKey: string;\n  sessionId: string;\n  events: HeuristicsEvent[];\n}\n\nexport interface AttachHeuristicsSinkOptions {\n  /** Base URL, e.g. \"/heuristics\". POSTs to `${endpoint}/collect`. */\n  endpoint: string;\n  /** Identifies the site to the ingestion endpoint. */\n  siteKey: string;\n  /** Stable session id. Default: a generated \"agent-<rand>\" per attach. */\n  sessionId?: string;\n  /** Resolves the current path. Default: `() => location.pathname`. */\n  path?: () => string;\n  /** Which activity sources to record. Default \"all\". */\n  source?: \"agent\" | \"flow\" | \"all\";\n  /** Flush interval in ms. Default 2000. */\n  batchMs?: number;\n}\n\nfunction numericMeta(\n  meta: Record<string, unknown> | undefined,\n  key: string,\n): number | undefined {\n  const v = meta?.[key];\n  return typeof v === \"number\" && Number.isFinite(v) ? v : undefined;\n}\n\n/**\n * Map one activity event to an `actor:\"agent\"` HeuristicsEvent. Activities\n * carrying a finite `meta.dwellMs` become `kind:\"dwell\"`; everything else is a\n * discrete `kind:\"click\"` with x/y/vw/vh pulled from numeric meta (default 0).\n * Mirrors `fancy-heuristics-js/src/agent.ts` `mapActivityToEvent`.\n */\nexport function mapActivityToEvent(\n  e: AgentActivityEvent,\n  path: string,\n): HeuristicsEvent {\n  const source = e.source ?? \"agent\";\n  const targetId = e.target?.elementId;\n  const label = e.target?.label;\n  const meta: Record<string, unknown> = {\n    action: e.action,\n    agentId: e.agentId,\n    source,\n    kind: e.target?.kind,\n  };\n  const dwellMs = numericMeta(e.meta, \"dwellMs\");\n\n  if (dwellMs !== undefined) {\n    const ev: HeuristicsEvent = {\n      kind: \"dwell\",\n      actor: \"agent\",\n      path,\n      ts: e.timestamp,\n      dwellMs,\n      meta,\n    };\n    if (targetId !== undefined) ev.targetId = targetId;\n    if (label !== undefined) ev.label = label;\n    return ev;\n  }\n\n  const ev: HeuristicsEvent = {\n    kind: \"click\",\n    actor: \"agent\",\n    path,\n    ts: e.timestamp,\n    x: numericMeta(e.meta, \"x\") ?? 0,\n    y: numericMeta(e.meta, \"y\") ?? 0,\n    vw: numericMeta(e.meta, \"vw\") ?? 0,\n    vh: numericMeta(e.meta, \"vh\") ?? 0,\n    meta,\n  };\n  if (targetId !== undefined) ev.targetId = targetId;\n  if (label !== undefined) ev.label = label;\n  return ev;\n}\n\nfunction randomId(): string {\n  return Math.random().toString(36).slice(2, 10);\n}\n\n/**\n * Subscribe to the in-page agent activity bus and forward each matching event\n * to the heuristics `/collect` endpoint as `actor:\"agent\"`. SSR-safe (returns a\n * no-op when there is no `window`). Returns an unsubscribe that flushes the\n * buffer and detaches all listeners/timers.\n */\nexport function attachHeuristicsSink(\n  opts: AttachHeuristicsSinkOptions,\n): () => void {\n  // Browser guard — SSR-safe no-op.\n  if (typeof window === \"undefined\") return () => {};\n\n  const endpoint = opts.endpoint.replace(/\\/$/, \"\");\n  const url = `${endpoint}/collect`;\n  const siteKey = opts.siteKey;\n  const sessionId = opts.sessionId ?? `agent-${randomId()}`;\n  const getPath = opts.path ?? (() => location.pathname);\n  const source = opts.source ?? \"all\";\n  const batchMs = opts.batchMs ?? 2000;\n\n  // onActivity's `source` filter is strict-equality; only set it when we want a\n  // single source. \"all\" subscribes unfiltered.\n  const filter = source === \"all\" ? undefined : { source };\n\n  let buffer: HeuristicsEvent[] = [];\n\n  function flush(): void {\n    if (buffer.length === 0) return;\n    const events = buffer;\n    buffer = [];\n    const batch: CollectBatch = { siteKey, sessionId, events };\n    const body = JSON.stringify(batch);\n    try {\n      if (\n        typeof navigator !== \"undefined\" &&\n        typeof navigator.sendBeacon === \"function\"\n      ) {\n        const blob = new Blob([body], { type: \"application/json\" });\n        navigator.sendBeacon(url, blob);\n        return;\n      }\n    } catch {\n      // fall through to fetch\n    }\n    try {\n      void fetch(url, {\n        method: \"POST\",\n        headers: { \"content-type\": \"application/json\" },\n        body,\n        keepalive: true,\n      });\n    } catch {\n      // never throw from a flush\n    }\n  }\n\n  const unsubscribeActivity = onActivity((e) => {\n    try {\n      buffer.push(mapActivityToEvent(e, getPath()));\n    } catch {\n      // never let a malformed event break the bus\n    }\n  }, filter);\n\n  const timer: ReturnType<typeof setInterval> = setInterval(flush, batchMs);\n\n  const onPageHide = () => flush();\n  const onVisibility = () => {\n    if (document.visibilityState === \"hidden\") flush();\n  };\n  window.addEventListener(\"pagehide\", onPageHide);\n  document.addEventListener(\"visibilitychange\", onVisibility);\n\n  return () => {\n    unsubscribeActivity();\n    window.removeEventListener(\"pagehide\", onPageHide);\n    document.removeEventListener(\"visibilitychange\", onVisibility);\n    clearInterval(timer);\n    flush();\n  };\n}\n"]}

package/dist/heuristics.js

@@ -0,0 +1,6 @@
+export { attachHeuristicsSink, mapActivityToEvent } from './chunk-7R6RMROL.js';
+import './chunk-UCKJAUBY.js';
+import './chunk-ULJL53DL.js';
+import './chunk-C3TYI5TJ.js';
+//# sourceMappingURL=heuristics.js.map
+//# sourceMappingURL=heuristics.js.map

package/dist/heuristics.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"heuristics.js"}

package/dist/index.cjs

@@ -8,8 +8,13 @@ var reactDom = require('react-dom');
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -3479,9 +3484,184 @@ function CoBrowseCursorLayer({ active = true, zIndex = 2147483e3 }) {
   );
 }
 CoBrowseCursorLayer.displayName = "CoBrowseCursorLayer";
+function resolveCsrf(explicit) {
+  if (explicit) return explicit;
+  if (typeof document === "undefined") return void 0;
+  return document.querySelector('meta[name="csrf-token"]')?.content;
+}
+function SimulateUsersButton({
+  endpoint = "/active-users/simulate",
+  count = 10,
+  label,
+  csrfToken,
+  onTriggered,
+  onError,
+  className,
+  style
+}) {
+  const [busy, setBusy] = react.useState(false);
+  async function trigger() {
+    if (busy) return;
+    setBusy(true);
+    try {
+      const token = resolveCsrf(csrfToken);
+      const res = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Requested-With": "XMLHttpRequest",
+          ...token ? { "X-CSRF-TOKEN": token } : {}
+        },
+        credentials: "same-origin",
+        body: JSON.stringify({ count })
+      });
+      if (!res.ok) throw new Error(`Simulate request failed: ${res.status}`);
+      onTriggered?.();
+    } catch (err) {
+      onError?.(err);
+    } finally {
+      setBusy(false);
+    }
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "button",
+    {
+      type: "button",
+      "data-fai-simulate-users": "",
+      className: ["fai-simulate-users", className ?? ""].filter(Boolean).join(" "),
+      onClick: trigger,
+      disabled: busy,
+      style: {
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 8,
+        padding: "8px 14px",
+        borderRadius: 8,
+        border: "1px solid rgba(139,92,246,0.4)",
+        background: busy ? "rgba(139,92,246,0.15)" : "rgba(139,92,246,0.1)",
+        color: "#7c3aed",
+        font: "inherit",
+        fontSize: 13,
+        fontWeight: 500,
+        cursor: busy ? "progress" : "pointer",
+        opacity: busy ? 0.7 : 1,
+        ...style
+      },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": true, children: busy ? "\u23F3" : "\u2728" }),
+        label ?? `Simulate ${count} active users`
+      ]
+    }
+  );
+}
 
 // src/presence/index.ts
 init_registry();
+
+// src/heuristics/sink.ts
+function numericMeta(meta, key) {
+  const v = meta?.[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function mapActivityToEvent(e, path) {
+  const source = e.source ?? "agent";
+  const targetId = e.target?.elementId;
+  const label = e.target?.label;
+  const meta = {
+    action: e.action,
+    agentId: e.agentId,
+    source,
+    kind: e.target?.kind
+  };
+  const dwellMs = numericMeta(e.meta, "dwellMs");
+  if (dwellMs !== void 0) {
+    const ev2 = {
+      kind: "dwell",
+      actor: "agent",
+      path,
+      ts: e.timestamp,
+      dwellMs,
+      meta
+    };
+    if (targetId !== void 0) ev2.targetId = targetId;
+    if (label !== void 0) ev2.label = label;
+    return ev2;
+  }
+  const ev = {
+    kind: "click",
+    actor: "agent",
+    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,
+    meta
+  };
+  if (targetId !== void 0) ev.targetId = targetId;
+  if (label !== void 0) ev.label = label;
+  return ev;
+}
+function randomId2() {
+  return Math.random().toString(36).slice(2, 10);
+}
+function attachHeuristicsSink(opts) {
+  if (typeof window === "undefined") return () => {
+  };
+  const endpoint = opts.endpoint.replace(/\/$/, "");
+  const url = `${endpoint}/collect`;
+  const siteKey = opts.siteKey;
+  const sessionId = opts.sessionId ?? `agent-${randomId2()}`;
+  const getPath = opts.path ?? (() => location.pathname);
+  const source = opts.source ?? "all";
+  const batchMs = opts.batchMs ?? 2e3;
+  const filter = source === "all" ? void 0 : { source };
+  let buffer = [];
+  function flush() {
+    if (buffer.length === 0) return;
+    const events = buffer;
+    buffer = [];
+    const batch = { siteKey, sessionId, events };
+    const body = JSON.stringify(batch);
+    try {
+      if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+        const blob = new Blob([body], { type: "application/json" });
+        navigator.sendBeacon(url, blob);
+        return;
+      }
+    } catch {
+    }
+    try {
+      void fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true
+      });
+    } catch {
+    }
+  }
+  const unsubscribeActivity = fancyAutoCommon.onActivity((e) => {
+    try {
+      buffer.push(mapActivityToEvent(e, getPath()));
+    } catch {
+    }
+  }, filter);
+  const timer = setInterval(flush, batchMs);
+  const onPageHide = () => flush();
+  const onVisibility = () => {
+    if (document.visibilityState === "hidden") flush();
+  };
+  window.addEventListener("pagehide", onPageHide);
+  document.addEventListener("visibilitychange", onVisibility);
+  return () => {
+    unsubscribeActivity();
+    window.removeEventListener("pagehide", onPageHide);
+    document.removeEventListener("visibilitychange", onVisibility);
+    clearInterval(timer);
+    flush();
+  };
+}
 function useUndoStack(agentId, intervalMs = 500) {
   const [history, setHistory] = react.useState(() => fancyAutoCommon.readHistory(agentId));
   react.useEffect(() => {
@@ -3622,10 +3802,12 @@ exports.MicroMcpServer = MicroMcpServer;
 exports.RelayTransport = RelayTransport;
 exports.ScreensActivityBridge = ScreensActivityBridge;
 exports.ShareControls = ShareControls;
+exports.SimulateUsersButton = SimulateUsersButton;
 exports.SseRelayTransport = SseRelayTransport;
 exports.ToolRegistry = ToolRegistry;
 exports.VscodeMark = VscodeMark;
 exports.WrenchMark = WrenchMark;
+exports.attachHeuristicsSink = attachHeuristicsSink;
 exports.attachInProcess = attachInProcess;
 exports.attachRelay = attachRelay;
 exports.attachSseRelay = attachSseRelay;
@@ -3644,6 +3826,7 @@ exports.describeSession = describeSession;
 exports.encodeBase64Json = encodeBase64Json;
 exports.ensureUndoToolsRegistered = ensureUndoToolsRegistered;
 exports.errorResult = errorResult;
+exports.mapActivityToHeuristicsEvent = mapActivityToEvent;
 exports.readSessionFromUrl = readSessionFromUrl;
 exports.registerChartsBridge = registerChartsBridge;
 exports.registerCodeBridge = registerCodeBridge;