@probat/react 0.4.1 → 0.4.3

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React$1, { ReactNode } from 'react';
 
 interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
@@ -12,7 +12,7 @@ interface ProbatProviderProps {
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 
 /**
@@ -34,7 +34,7 @@ interface ProbatProviderProps {
  * }
  * ```
  */
-declare function ProbatProviderClient(props: ProbatProviderProps): React.FunctionComponentElement<ProbatProviderProps>;
+declare function ProbatProviderClient(props: ProbatProviderProps): React$1.FunctionComponentElement<ProbatProviderProps>;
 
 interface ExperimentTrackOptions {
     /** Auto-track impressions (default true) */
@@ -50,9 +50,9 @@ interface ExperimentProps {
     /** Experiment key / identifier */
     id: string;
     /** Control variant ReactNode */
-    control: React.ReactNode;
+    control: React$1.ReactNode;
     /** Named variant ReactNodes, keyed by variant key (e.g. { ai_v1: <MyVariant /> }) */
-    variants: Record<string, React.ReactNode>;
+    variants: Record<string, React$1.ReactNode>;
     /** Tracking configuration */
     track?: ExperimentTrackOptions;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
@@ -62,7 +62,91 @@ interface ExperimentProps {
     /** Log decisions + events to console */
     debug?: boolean;
 }
-declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React.JSX.Element;
+declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React$1.JSX.Element;
+
+interface UseTrackBaseOptions {
+    /** Experiment identifier */
+    experimentId: string;
+    /** Stable instance id when multiple instances of the same experiment exist on a page */
+    componentInstanceId?: string;
+    /** Auto-track impressions (default true) */
+    impression?: boolean;
+    /** Auto-track clicks (default true) */
+    click?: boolean;
+    /** Custom impression event name (default "$experiment_exposure") */
+    impressionEventName?: string;
+    /** Custom click event name (default "$experiment_click") */
+    clickEventName?: string;
+    /** Log events to console */
+    debug?: boolean;
+}
+/** Explicit mode: pass the variant key directly */
+interface UseTrackExplicitOptions extends UseTrackBaseOptions {
+    /** The variant key to attach to events */
+    variantKey: string;
+    customerId?: undefined;
+}
+/** Customer mode: backend resolves variant from assignment table */
+interface UseTrackCustomerOptions extends UseTrackBaseOptions {
+    variantKey?: undefined;
+    /** Customer ID to resolve variant server-side. Falls back to provider's customerId. */
+    customerId?: string;
+}
+type UseTrackOptions = UseTrackExplicitOptions | UseTrackCustomerOptions;
+/**
+ * Attaches impression and click tracking to a DOM element via a ref.
+ *
+ * Two modes:
+ * - **Explicit**: pass `variantKey` directly — stamped on every event.
+ * - **Customer**: omit `variantKey` — backend resolves it from the assignment table
+ *   using `(experimentId, customerId)`.
+ *
+ * @example
+ * ```tsx
+ * // Explicit mode
+ * const trackRef = useTrack({ experimentId: "pricing", variantKey: "ai_v1" });
+ *
+ * // Customer mode (backend resolves variant)
+ * const trackRef = useTrack({ experimentId: "pricing", customerId: "user_123" });
+ * ```
+ */
+declare function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement | null>;
+
+type TrackProps = UseTrackOptions & {
+    children: React$1.ReactNode;
+};
+/**
+ * Wrapper component that attaches impression and click tracking to its children.
+ * Alternative to the `useTrack` hook when you prefer a component over a ref.
+ *
+ * @example
+ * ```tsx
+ * <Track experimentId="pricing" variantKey="ai_v1">
+ *   <PricingCard />
+ * </Track>
+ * ```
+ */
+declare function Track({ children, ...trackOptions }: TrackProps): React$1.JSX.Element;
+
+interface UseExperimentOptions {
+    /** Behavior when assignment fetch fails: "control" (default) renders control, "suspend" throws */
+    fallback?: "control" | "suspend";
+    /** Log decisions to console */
+    debug?: boolean;
+}
+interface UseExperimentReturn {
+    /** The resolved variant key (e.g. "control", "ai_v1") */
+    variantKey: string;
+    /** Whether the assignment has been resolved (bootstrap, cache, or fetch) */
+    resolved: boolean;
+}
+/**
+ * Resolves the variant assignment for an experiment.
+ * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
+ *
+ * Priority: bootstrap > localStorage cache > fetchDecision.
+ */
+declare function useExperiment(id: string, options?: UseExperimentOptions): UseExperimentReturn;
 
 interface UseProbatMetricsReturn {
     /**
@@ -102,4 +186,30 @@ declare function fetchDecision(host: string, experimentId: string, distinctId: s
  */
 declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
 
-export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, type UseProbatMetricsReturn, fetchDecision, sendMetric, useProbatMetrics };
+/**
+ * Factory that creates a typed context + hook pair for passing a variantKey
+ * between components in different files without prop-drilling.
+ *
+ * @example
+ * ```tsx
+ * // experiment-context.ts
+ * export const { ExperimentProvider, useVariantKey } = createExperimentContext("pricing-test");
+ *
+ * // Parent.tsx
+ * const { variantKey } = useExperiment("pricing-test");
+ * <ExperimentProvider value={variantKey}><Child /></ExperimentProvider>
+ *
+ * // Child.tsx (different file)
+ * const variantKey = useVariantKey();
+ * const trackRef = useTrack({ experimentId: "pricing-test", variantKey });
+ * ```
+ */
+declare function createExperimentContext(experimentId: string): {
+    ExperimentProvider: ({ value, children, }: {
+        value: string;
+        children: ReactNode;
+    }) => React$1.FunctionComponentElement<React$1.ProviderProps<string | null>>;
+    useVariantKey: () => string;
+};
+
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackCustomerOptions, type UseTrackExplicitOptions, type UseTrackOptions, createExperimentContext, fetchDecision, sendMetric, useExperiment, useProbatMetrics, useTrack };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React$1, { ReactNode } from 'react';
 
 interface ProbatProviderProps {
     /** Your end-user's ID. When provided, used as the distinct_id for variant
@@ -12,7 +12,7 @@ interface ProbatProviderProps {
      * e.g. { "cta-copy-test": "ai_v1" }
      */
     bootstrap?: Record<string, string>;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 }
 
 /**
@@ -34,7 +34,7 @@ interface ProbatProviderProps {
  * }
  * ```
  */
-declare function ProbatProviderClient(props: ProbatProviderProps): React.FunctionComponentElement<ProbatProviderProps>;
+declare function ProbatProviderClient(props: ProbatProviderProps): React$1.FunctionComponentElement<ProbatProviderProps>;
 
 interface ExperimentTrackOptions {
     /** Auto-track impressions (default true) */
@@ -50,9 +50,9 @@ interface ExperimentProps {
     /** Experiment key / identifier */
     id: string;
     /** Control variant ReactNode */
-    control: React.ReactNode;
+    control: React$1.ReactNode;
     /** Named variant ReactNodes, keyed by variant key (e.g. { ai_v1: <MyVariant /> }) */
-    variants: Record<string, React.ReactNode>;
+    variants: Record<string, React$1.ReactNode>;
     /** Tracking configuration */
     track?: ExperimentTrackOptions;
     /** Stable instance id when multiple instances of the same experiment exist on a page */
@@ -62,7 +62,91 @@ interface ExperimentProps {
     /** Log decisions + events to console */
     debug?: boolean;
 }
-declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React.JSX.Element;
+declare function Experiment({ id, control, variants, track, componentInstanceId, fallback, debug, }: ExperimentProps): React$1.JSX.Element;
+
+interface UseTrackBaseOptions {
+    /** Experiment identifier */
+    experimentId: string;
+    /** Stable instance id when multiple instances of the same experiment exist on a page */
+    componentInstanceId?: string;
+    /** Auto-track impressions (default true) */
+    impression?: boolean;
+    /** Auto-track clicks (default true) */
+    click?: boolean;
+    /** Custom impression event name (default "$experiment_exposure") */
+    impressionEventName?: string;
+    /** Custom click event name (default "$experiment_click") */
+    clickEventName?: string;
+    /** Log events to console */
+    debug?: boolean;
+}
+/** Explicit mode: pass the variant key directly */
+interface UseTrackExplicitOptions extends UseTrackBaseOptions {
+    /** The variant key to attach to events */
+    variantKey: string;
+    customerId?: undefined;
+}
+/** Customer mode: backend resolves variant from assignment table */
+interface UseTrackCustomerOptions extends UseTrackBaseOptions {
+    variantKey?: undefined;
+    /** Customer ID to resolve variant server-side. Falls back to provider's customerId. */
+    customerId?: string;
+}
+type UseTrackOptions = UseTrackExplicitOptions | UseTrackCustomerOptions;
+/**
+ * Attaches impression and click tracking to a DOM element via a ref.
+ *
+ * Two modes:
+ * - **Explicit**: pass `variantKey` directly — stamped on every event.
+ * - **Customer**: omit `variantKey` — backend resolves it from the assignment table
+ *   using `(experimentId, customerId)`.
+ *
+ * @example
+ * ```tsx
+ * // Explicit mode
+ * const trackRef = useTrack({ experimentId: "pricing", variantKey: "ai_v1" });
+ *
+ * // Customer mode (backend resolves variant)
+ * const trackRef = useTrack({ experimentId: "pricing", customerId: "user_123" });
+ * ```
+ */
+declare function useTrack(options: UseTrackOptions): React.RefObject<HTMLElement | null>;
+
+type TrackProps = UseTrackOptions & {
+    children: React$1.ReactNode;
+};
+/**
+ * Wrapper component that attaches impression and click tracking to its children.
+ * Alternative to the `useTrack` hook when you prefer a component over a ref.
+ *
+ * @example
+ * ```tsx
+ * <Track experimentId="pricing" variantKey="ai_v1">
+ *   <PricingCard />
+ * </Track>
+ * ```
+ */
+declare function Track({ children, ...trackOptions }: TrackProps): React$1.JSX.Element;
+
+interface UseExperimentOptions {
+    /** Behavior when assignment fetch fails: "control" (default) renders control, "suspend" throws */
+    fallback?: "control" | "suspend";
+    /** Log decisions to console */
+    debug?: boolean;
+}
+interface UseExperimentReturn {
+    /** The resolved variant key (e.g. "control", "ai_v1") */
+    variantKey: string;
+    /** Whether the assignment has been resolved (bootstrap, cache, or fetch) */
+    resolved: boolean;
+}
+/**
+ * Resolves the variant assignment for an experiment.
+ * No tracking — use `useTrack` or `<Track>` to observe impressions/clicks.
+ *
+ * Priority: bootstrap > localStorage cache > fetchDecision.
+ */
+declare function useExperiment(id: string, options?: UseExperimentOptions): UseExperimentReturn;
 
 interface UseProbatMetricsReturn {
     /**
@@ -102,4 +186,30 @@ declare function fetchDecision(host: string, experimentId: string, distinctId: s
  */
 declare function sendMetric(host: string, event: string, properties: Record<string, unknown>): void;
 
-export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, type UseProbatMetricsReturn, fetchDecision, sendMetric, useProbatMetrics };
+/**
+ * Factory that creates a typed context + hook pair for passing a variantKey
+ * between components in different files without prop-drilling.
+ *
+ * @example
+ * ```tsx
+ * // experiment-context.ts
+ * export const { ExperimentProvider, useVariantKey } = createExperimentContext("pricing-test");
+ *
+ * // Parent.tsx
+ * const { variantKey } = useExperiment("pricing-test");
+ * <ExperimentProvider value={variantKey}><Child /></ExperimentProvider>
+ *
+ * // Child.tsx (different file)
+ * const variantKey = useVariantKey();
+ * const trackRef = useTrack({ experimentId: "pricing-test", variantKey });
+ * ```
+ */
+declare function createExperimentContext(experimentId: string): {
+    ExperimentProvider: ({ value, children, }: {
+        value: string;
+        children: ReactNode;
+    }) => React$1.FunctionComponentElement<React$1.ProviderProps<string | null>>;
+    useVariantKey: () => string;
+};
+
+export { type DecisionResponse, Experiment, type ExperimentProps, type ExperimentTrackOptions, type MetricPayload, ProbatProviderClient, type ProbatProviderProps, Track, type TrackProps, type UseExperimentOptions, type UseExperimentReturn, type UseProbatMetricsReturn, type UseTrackCustomerOptions, type UseTrackExplicitOptions, type UseTrackOptions, createExperimentContext, fetchDecision, sendMetric, useExperiment, useProbatMetrics, useTrack };

package/dist/index.js

@@ -204,6 +204,75 @@ function buildMeta(el, isPrimary) {
   return meta;
 }
 
+// src/hooks/useExperiment.ts
+var ASSIGNMENT_PREFIX = "probat:assignment:";
+function readAssignment(id) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = localStorage.getItem(ASSIGNMENT_PREFIX + id);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    return parsed.variantKey ?? null;
+  } catch {
+    return null;
+  }
+}
+function writeAssignment(id, variantKey) {
+  if (typeof window === "undefined") return;
+  try {
+    const entry = { variantKey, ts: Date.now() };
+    localStorage.setItem(ASSIGNMENT_PREFIX + id, JSON.stringify(entry));
+  } catch {
+  }
+}
+function useExperiment(id, options = {}) {
+  const { fallback = "control", debug = false } = options;
+  const { host, bootstrap, customerId } = useProbatContext();
+  const [variantKey, setVariantKey] = React3.useState(() => {
+    if (bootstrap[id]) return bootstrap[id];
+    return "control";
+  });
+  const [resolved, setResolved] = React3.useState(() => {
+    return !!bootstrap[id];
+  });
+  React3.useEffect(() => {
+    if (bootstrap[id] || readAssignment(id)) {
+      const key = bootstrap[id] ?? readAssignment(id) ?? "control";
+      setVariantKey(key);
+      setResolved(true);
+      return;
+    }
+    let cancelled = false;
+    (async () => {
+      try {
+        const distinctId = customerId ?? getDistinctId();
+        const key = await fetchDecision(host, id, distinctId);
+        if (cancelled) return;
+        setVariantKey(key);
+        writeAssignment(id, key);
+      } catch (err) {
+        if (cancelled) return;
+        if (debug) {
+          console.error(`[probat] fetchDecision failed for "${id}":`, err);
+        }
+        if (fallback === "suspend") throw err;
+        setVariantKey("control");
+      } finally {
+        if (!cancelled) setResolved(true);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [id, host]);
+  React3.useEffect(() => {
+    if (debug && resolved) {
+      console.log(`[probat] Experiment "${id}" -> variant "${variantKey}"`);
+    }
+  }, [debug, id, variantKey, resolved]);
+  return { variantKey, resolved };
+}
+
 // src/utils/dedupeStorage.ts
 var PREFIX = "probat:seen:";
 var memorySet = /* @__PURE__ */ new Set();
@@ -291,113 +360,48 @@ function useStableInstanceIdFallback(experimentId) {
 }
 var useStableInstanceId = typeof React3__default.default.useId === "function" ? useStableInstanceIdV18 : useStableInstanceIdFallback;
 
-// src/components/Experiment.tsx
-var ASSIGNMENT_PREFIX = "probat:assignment:";
-function readAssignment(id) {
-  if (typeof window === "undefined") return null;
-  try {
-    const raw = localStorage.getItem(ASSIGNMENT_PREFIX + id);
-    if (!raw) return null;
-    const parsed = JSON.parse(raw);
-    return parsed.variantKey ?? null;
-  } catch {
-    return null;
-  }
-}
-function writeAssignment(id, variantKey) {
-  if (typeof window === "undefined") return;
-  try {
-    const entry = { variantKey, ts: Date.now() };
-    localStorage.setItem(ASSIGNMENT_PREFIX + id, JSON.stringify(entry));
-  } catch {
-  }
-}
-function Experiment({
-  id,
-  control,
-  variants,
-  track,
-  componentInstanceId,
-  fallback = "control",
-  debug = false
-}) {
-  const { host, bootstrap, customerId } = useProbatContext();
-  const autoInstanceId = useStableInstanceId(id);
+// src/hooks/useTrack.ts
+function useTrack(options) {
+  const {
+    experimentId,
+    componentInstanceId,
+    impression: trackImpression = true,
+    click: trackClick = true,
+    impressionEventName = "$experiment_exposure",
+    clickEventName = "$experiment_click",
+    debug = false
+  } = options;
+  const variantKey = options.variantKey ?? void 0;
+  const explicitCustomerId = "customerId" in options ? options.customerId : void 0;
+  const { host, customerId: providerCustomerId } = useProbatContext();
+  const resolvedCustomerId = explicitCustomerId ?? providerCustomerId;
+  const isCustomerMode = !variantKey;
+  const autoInstanceId = useStableInstanceId(experimentId);
   const instanceId = componentInstanceId ?? autoInstanceId;
-  const trackImpression = track?.impression !== false;
-  const trackClick = track?.primaryClick !== false;
-  const impressionEvent = track?.impressionEventName ?? "$experiment_exposure";
-  const clickEvent = track?.clickEventName ?? "$experiment_click";
-  const [variantKey, setVariantKey] = React3.useState(() => {
-    if (bootstrap[id]) return bootstrap[id];
-    return "control";
-  });
-  const [resolved, setResolved] = React3.useState(() => {
-    return !!bootstrap[id];
-  });
-  React3.useEffect(() => {
-    if (bootstrap[id] || readAssignment(id)) {
-      const key = bootstrap[id] ?? readAssignment(id) ?? "control";
-      setVariantKey(key);
-      setResolved(true);
-      return;
-    }
-    let cancelled = false;
-    (async () => {
-      try {
-        const distinctId = customerId ?? getDistinctId();
-        const key = await fetchDecision(host, id, distinctId);
-        if (cancelled) return;
-        if (key !== "control" && !(key in variants)) {
-          if (debug) {
-            console.warn(
-              `[probat] Unknown variant "${key}" for experiment "${id}", falling back to control`
-            );
-          }
-          setVariantKey("control");
-        } else {
-          setVariantKey(key);
-          writeAssignment(id, key);
-        }
-      } catch (err) {
-        if (cancelled) return;
-        if (debug) {
-          console.error(`[probat] fetchDecision failed for "${id}":`, err);
-        }
-        if (fallback === "suspend") throw err;
-        setVariantKey("control");
-      } finally {
-        if (!cancelled) setResolved(true);
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [id, host]);
+  const containerRef = React3.useRef(null);
+  const impressionSent = React3.useRef(false);
   React3.useEffect(() => {
-    if (debug && resolved) {
-      console.log(`[probat] Experiment "${id}" \u2192 variant "${variantKey}"`, {
-        instanceId,
-        pageKey: getPageKey()
-      });
+    if (isCustomerMode && !resolvedCustomerId && debug) {
+      console.warn(
+        `[probat] useTrack called without variantKey and no customerId available for "${experimentId}". Events will have no variant attribution.`
+      );
     }
-  }, [debug, id, variantKey, resolved, instanceId]);
+  }, [isCustomerMode, resolvedCustomerId, experimentId, debug]);
   const eventProps = React3.useMemo(
     () => ({
-      experiment_id: id,
-      variant_key: variantKey,
+      experiment_id: experimentId,
+      ...variantKey ? { variant_key: variantKey } : {},
       component_instance_id: instanceId,
-      ...customerId ? { distinct_id: customerId } : {}
+      ...resolvedCustomerId ? { distinct_id: resolvedCustomerId } : {}
     }),
-    [id, variantKey, instanceId, customerId]
+    [experimentId, variantKey, instanceId, resolvedCustomerId]
   );
-  const containerRef = React3.useRef(null);
-  const impressionSent = React3.useRef(false);
+  const dedupeVariant = variantKey ?? resolvedCustomerId ?? "__anon__";
   React3.useEffect(() => {
-    if (!trackImpression || !resolved) return;
+    if (!trackImpression) return;
     impressionSent.current = false;
     const pageKey = getPageKey();
-    const dedupeKey = makeDedupeKey(id, variantKey, instanceId, pageKey);
+    const dedupeKey = makeDedupeKey(experimentId, dedupeVariant, instanceId, pageKey);
     if (hasSeen(dedupeKey)) {
       impressionSent.current = true;
       return;
@@ -408,8 +412,8 @@ function Experiment({
       if (!impressionSent.current) {
         impressionSent.current = true;
         markSeen(dedupeKey);
-        sendMetric(host, impressionEvent, eventProps);
-        if (debug) console.log(`[probat] Impression sent (no IO) for "${id}"`);
+        sendMetric(host, impressionEventName, eventProps);
+        if (debug) console.log(`[probat] Impression sent (no IO) for "${experimentId}"`);
       }
       return;
     }
@@ -422,8 +426,8 @@ function Experiment({
             if (impressionSent.current) return;
             impressionSent.current = true;
             markSeen(dedupeKey);
-            sendMetric(host, impressionEvent, eventProps);
-            if (debug) console.log(`[probat] Impression sent for "${id}"`);
+            sendMetric(host, impressionEventName, eventProps);
+            if (debug) console.log(`[probat] Impression sent for "${experimentId}"`);
             observer.disconnect();
           }, 250);
         } else if (timer) {
@@ -440,12 +444,11 @@ function Experiment({
     };
   }, [
     trackImpression,
-    resolved,
-    id,
-    variantKey,
+    experimentId,
+    dedupeVariant,
     instanceId,
     host,
-    impressionEvent,
+    impressionEventName,
     eventProps,
     debug
   ]);
@@ -454,22 +457,59 @@ function Experiment({
       if (!trackClick) return;
       const meta = extractClickMeta(e.target);
       if (!meta) return;
-      sendMetric(host, clickEvent, {
+      sendMetric(host, clickEventName, {
         ...eventProps,
         ...meta
       });
       if (debug) {
-        console.log(`[probat] Click tracked for "${id}"`, meta);
+        console.log(`[probat] Click tracked for "${experimentId}"`, meta);
       }
     },
-    [trackClick, host, clickEvent, eventProps, id, debug]
+    [trackClick, host, clickEventName, eventProps, experimentId, debug]
   );
+  React3.useEffect(() => {
+    const el = containerRef.current;
+    if (!el || !trackClick) return;
+    el.addEventListener("click", handleClick);
+    return () => {
+      el.removeEventListener("click", handleClick);
+    };
+  }, [handleClick, trackClick]);
+  return containerRef;
+}
+
+// src/components/Experiment.tsx
+function Experiment({
+  id,
+  control,
+  variants,
+  track,
+  componentInstanceId,
+  fallback = "control",
+  debug = false
+}) {
+  const { variantKey: rawKey, resolved } = useExperiment(id, { fallback, debug });
+  const variantKey = rawKey === "control" || rawKey in variants ? rawKey : "control";
+  if (debug && rawKey !== variantKey) {
+    console.warn(
+      `[probat] Unknown variant "${rawKey}" for experiment "${id}", falling back to control`
+    );
+  }
+  const trackRef = useTrack({
+    experimentId: id,
+    variantKey,
+    componentInstanceId,
+    impression: resolved ? track?.impression !== false : false,
+    click: track?.primaryClick !== false,
+    impressionEventName: track?.impressionEventName,
+    clickEventName: track?.clickEventName,
+    debug
+  });
   const content = variantKey === "control" || !(variantKey in variants) ? control : variants[variantKey];
   return /* @__PURE__ */ React3__default.default.createElement(
     "div",
     {
-      ref: containerRef,
-      onClick: handleClick,
+      ref: trackRef,
       "data-probat-experiment": id,
       "data-probat-variant": variantKey,
       style: {
@@ -483,6 +523,19 @@ function Experiment({
     content
   );
 }
+function Track({ children, ...trackOptions }) {
+  const trackRef = useTrack(trackOptions);
+  return /* @__PURE__ */ React3__default.default.createElement(
+    "div",
+    {
+      ref: trackRef,
+      "data-probat-track": trackOptions.experimentId,
+      "data-probat-variant": trackOptions.variantKey ?? "server-resolved",
+      style: { display: "contents" }
+    },
+    children
+  );
+}
 function useProbatMetrics() {
   const { host, customerId } = useProbatContext();
   const capture = React3.useCallback(
@@ -496,11 +549,34 @@ function useProbatMetrics() {
   );
   return { capture };
 }
+function createExperimentContext(experimentId) {
+  const Ctx = React3.createContext(null);
+  function ExperimentProvider({
+    value,
+    children
+  }) {
+    return React3__default.default.createElement(Ctx.Provider, { value }, children);
+  }
+  function useVariantKey() {
+    const v = React3.useContext(Ctx);
+    if (v === null) {
+      throw new Error(
+        `useVariantKey() must be used inside <ExperimentProvider> for "${experimentId}"`
+      );
+    }
+    return v;
+  }
+  return { ExperimentProvider, useVariantKey };
+}
 
 exports.Experiment = Experiment;
 exports.ProbatProviderClient = ProbatProviderClient;
+exports.Track = Track;
+exports.createExperimentContext = createExperimentContext;
 exports.fetchDecision = fetchDecision;
 exports.sendMetric = sendMetric;
+exports.useExperiment = useExperiment;
 exports.useProbatMetrics = useProbatMetrics;
+exports.useTrack = useTrack;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map