@probat/react 0.2.1 → 0.3.1

package/src/utils/dedupeStorage.ts

@@ -0,0 +1,40 @@
+/**
+ * Dedupe storage for experiment exposures.
+ * Uses sessionStorage + in-memory Set fallback.
+ * Key format: probat:seen:{id}:{variantKey}:{instanceId}:{pageKey}
+ */
+
+const PREFIX = "probat:seen:";
+const memorySet = new Set<string>();
+
+export function makeDedupeKey(
+    experimentId: string,
+    variantKey: string,
+    instanceId: string,
+    pageKey: string
+): string {
+    return `${PREFIX}${experimentId}:${variantKey}:${instanceId}:${pageKey}`;
+}
+
+export function hasSeen(key: string): boolean {
+    if (memorySet.has(key)) return true;
+    if (typeof window === "undefined") return false;
+    try {
+        return sessionStorage.getItem(key) === "1";
+    } catch {
+        return false;
+    }
+}
+
+export function markSeen(key: string): void {
+    memorySet.add(key);
+    if (typeof window === "undefined") return;
+    try {
+        sessionStorage.setItem(key, "1");
+    } catch {}
+}
+
+/** Reset all dedupe state — useful for testing. */
+export function resetDedupe(): void {
+    memorySet.clear();
+}

package/src/utils/eventContext.ts

@@ -0,0 +1,94 @@
+/**
+ * Event context helpers: distinct_id, session_id, page info.
+ * All browser-safe — no-ops when window is unavailable.
+ */
+
+const DISTINCT_ID_KEY = "probat:distinct_id";
+const SESSION_ID_KEY = "probat:session_id";
+
+let cachedDistinctId: string | null = null;
+let cachedSessionId: string | null = null;
+
+function generateId(): string {
+    // crypto.randomUUID where available, else fallback
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // fallback: random hex
+    const bytes = new Uint8Array(16);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        crypto.getRandomValues(bytes);
+    } else {
+        for (let i = 0; i < 16; i++) bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+export function getDistinctId(): string {
+    if (cachedDistinctId) return cachedDistinctId;
+    if (typeof window === "undefined") return "server";
+    try {
+        const stored = localStorage.getItem(DISTINCT_ID_KEY);
+        if (stored) {
+            cachedDistinctId = stored;
+            return stored;
+        }
+    } catch {}
+    const id = `anon_${generateId()}`;
+    cachedDistinctId = id;
+    try {
+        localStorage.setItem(DISTINCT_ID_KEY, id);
+    } catch {}
+    return id;
+}
+
+export function getSessionId(): string {
+    if (cachedSessionId) return cachedSessionId;
+    if (typeof window === "undefined") return "server";
+    try {
+        const stored = sessionStorage.getItem(SESSION_ID_KEY);
+        if (stored) {
+            cachedSessionId = stored;
+            return stored;
+        }
+    } catch {}
+    const id = `sess_${generateId()}`;
+    cachedSessionId = id;
+    try {
+        sessionStorage.setItem(SESSION_ID_KEY, id);
+    } catch {}
+    return id;
+}
+
+export function getPageKey(): string {
+    if (typeof window === "undefined") return "";
+    return window.location.pathname + window.location.search;
+}
+
+export function getPageUrl(): string {
+    if (typeof window === "undefined") return "";
+    return window.location.href;
+}
+
+export function getReferrer(): string {
+    if (typeof document === "undefined") return "";
+    return document.referrer;
+}
+
+export interface EventContext {
+    distinct_id: string;
+    session_id: string;
+    $page_url: string;
+    $pathname: string;
+    $referrer: string;
+}
+
+export function buildEventContext(): EventContext {
+    return {
+        distinct_id: getDistinctId(),
+        session_id: getSessionId(),
+        $page_url: getPageUrl(),
+        $pathname: typeof window !== "undefined" ? window.location.pathname : "",
+        $referrer: getReferrer(),
+    };
+}

package/src/utils/stableInstanceId.ts

@@ -0,0 +1,113 @@
+/**
+ * Stable auto-generated instance IDs for <Experiment />.
+ *
+ * Problem: a naïve useRef + module counter gives a different ID on every mount,
+ * so StrictMode double-mount or unmount/remount changes the dedupe key.
+ *
+ * Solution:
+ *   1. React 18+  → useId() is stable per fiber position.
+ *   2. Fallback   → sessionStorage-backed slot counter per (experimentId, pageKey).
+ *   3. Both paths persist a mapping in sessionStorage:
+ *        probat:instance:{experimentId}:{pageKey}:{positionKey} → stableId
+ *      so the same position resolves to the same ID across mounts.
+ */
+
+import React, { useRef } from "react";
+import { getPageKey } from "./eventContext";
+
+const INSTANCE_PREFIX = "probat:instance:";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function shortId(): string {
+    const bytes = new Uint8Array(4);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        crypto.getRandomValues(bytes);
+    } else {
+        for (let i = 0; i < 4; i++) bytes[i] = Math.floor(Math.random() * 256);
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Look up or create a stable instance ID in sessionStorage.
+ */
+function resolveStableId(storageKey: string): string {
+    if (typeof window !== "undefined") {
+        try {
+            const stored = sessionStorage.getItem(storageKey);
+            if (stored) return stored;
+        } catch {}
+    }
+    const id = `inst_${shortId()}`;
+    if (typeof window !== "undefined") {
+        try {
+            sessionStorage.setItem(storageKey, id);
+        } catch {}
+    }
+    return id;
+}
+
+// ── Fallback: render-wave slot counter ─────────────────────────────────────
+// Each synchronous render batch claims sequential slots per (experimentId,
+// pageKey). A microtask resets the counters so the next batch starts at 0,
+// giving the same component position the same slot across mounts.
+
+const slotCounters = new Map<string, number>();
+let resetScheduled = false;
+
+function claimSlot(groupKey: string): number {
+    const idx = slotCounters.get(groupKey) ?? 0;
+    slotCounters.set(groupKey, idx + 1);
+    if (!resetScheduled) {
+        resetScheduled = true;
+        Promise.resolve().then(() => {
+            slotCounters.clear();
+            resetScheduled = false;
+        });
+    }
+    return idx;
+}
+
+// ── Hook: React 18+ path (useId available) ─────────────────────────────────
+
+function useStableInstanceIdV18(experimentId: string): string {
+    const reactId = (React as any).useId() as string;
+    const ref = useRef("");
+    if (!ref.current) {
+        const key = `${INSTANCE_PREFIX}${experimentId}:${getPageKey()}:${reactId}`;
+        ref.current = resolveStableId(key);
+    }
+    return ref.current;
+}
+
+// ── Hook: fallback path (no useId) ─────────────────────────────────────────
+
+function useStableInstanceIdFallback(experimentId: string): string {
+    const slotRef = useRef(-1);
+    const ref = useRef("");
+    if (slotRef.current === -1) {
+        slotRef.current = claimSlot(`${experimentId}:${getPageKey()}`);
+    }
+    if (!ref.current) {
+        const key = `${INSTANCE_PREFIX}${experimentId}:${getPageKey()}:${slotRef.current}`;
+        ref.current = resolveStableId(key);
+    }
+    return ref.current;
+}
+
+// ── Exported hook ──────────────────────────────────────────────────────────
+// Selection is a module-level constant so the hook-call count never changes
+// between renders — safe for the rules of hooks.
+
+export const useStableInstanceId: (experimentId: string) => string =
+    typeof (React as any).useId === "function"
+        ? useStableInstanceIdV18
+        : useStableInstanceIdFallback;
+
+// ── Test utility ───────────────────────────────────────────────────────────
+
+export function resetInstanceIdState(): void {
+    slotCounters.clear();
+    resetScheduled = false;
+}

package/src/utils/storage.ts

@@ -1,77 +1,35 @@
-const TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
+/**
+ * Safe localStorage/sessionStorage helpers.
+ */
 
-export type Choice = {
-    experiment_id: string;
-    label: string;
-    ts: number;
-};
-
-export function safeGet(k: string): any | null {
+export function safeGetLocal(key: string): string | null {
+    if (typeof window === "undefined") return null;
     try {
-        const raw = localStorage.getItem(k);
-        return raw ? JSON.parse(raw) : null;
+        return localStorage.getItem(key);
     } catch {
         return null;
     }
 }
 
-export function safeSet(k: string, v: any) {
+export function safeSetLocal(key: string, value: string): void {
+    if (typeof window === "undefined") return;
     try {
-        localStorage.setItem(k, JSON.stringify(v));
-    } catch { }
-}
-
-export function now() {
-    return Date.now();
+        localStorage.setItem(key, value);
+    } catch {}
 }
 
-export function fresh(ts: number) {
-    return now() - ts <= TTL_MS;
-}
-
-export const KEY = (proposalId: string) => `probat_choice_v3:${proposalId}`;
-export const VISIT_KEY = (proposalId: string, label: string) =>
-    `probat_visit_v1:${proposalId}:${label}`;
-
-export function readChoice(proposalId: string): Choice | null {
-    const c = safeGet(KEY(proposalId)) as Choice | null;
-    return c && fresh(c.ts) ? c : null;
-}
-
-export function writeChoice(
-    proposalId: string,
-    experiment_id: string,
-    label: string
-) {
-    safeSet(KEY(proposalId), { experiment_id, label, ts: now() } as Choice);
-}
-
-const visitMemo = new Set<string>();
-
-export function hasTrackedVisit(proposalId: string, label: string): boolean {
-    const key = VISIT_KEY(proposalId, label);
-    if (visitMemo.has(key)) return true;
+export function safeGetSession(key: string): string | null {
+    if (typeof window === "undefined") return null;
     try {
-        const raw = localStorage.getItem(key);
-        if (!raw) return false;
-        const ts = Number(raw);
-        if (!Number.isFinite(ts) || ts <= 0) return false;
-        if (now() - ts > TTL_MS) {
-            localStorage.removeItem(key);
-            return false;
-        }
-        visitMemo.add(key);
-        return true;
+        return sessionStorage.getItem(key);
     } catch {
-        return false;
+        return null;
     }
 }
 
-export function markTrackedVisit(proposalId: string, label: string) {
-    const key = VISIT_KEY(proposalId, label);
-    visitMemo.add(key);
+export function safeSetSession(key: string, value: string): void {
+    if (typeof window === "undefined") return;
     try {
-        localStorage.setItem(key, now().toString());
-    } catch { }
+        sessionStorage.setItem(key, value);
+    } catch {}
 }
-

package/src/hoc/itrt-frontend.code-workspace

@@ -1,10 +0,0 @@
-{
-    "folders": [
-        {
-            "path": "../../../.."
-        },
-        {
-            "path": "../../../../../itrt-frontend"
-        }
-    ]
-}

package/src/hoc/withExperiment.tsx

@@ -1,311 +0,0 @@
-"use client";
-
-import React, { useState, useEffect, useCallback } from "react";
-import type { MouseEvent } from "react";
-import { useProbatContext } from "../context/ProbatContext";
-import {
-    fetchDecision,
-    fetchComponentExperimentConfig,
-    loadVariantComponent,
-    sendMetric,
-    extractClickMeta,
-} from "../utils/api";
-import {
-    readChoice,
-    writeChoice,
-    hasTrackedVisit,
-    markTrackedVisit,
-} from "../utils/storage";
-
-// Support both old and new API for backward compatibility
-export interface WithExperimentOptions {
-    // New API: component-based
-    componentPath?: string;
-    repoFullName?: string;
-
-    // Old API: direct proposal/registry (for backward compatibility)
-    proposalId?: string;
-    registry?: Record<string, React.ComponentType<any>>;
-}
-
-/**
- * Higher-Order Component for wrapping components with experiment variants
- */
-export function withExperiment<P = any>(
-    Control: React.ComponentType<P>,
-    options: WithExperimentOptions
-): React.ComponentType<P & { probat?: { trackClick: () => void } }> {
-    // Validate inputs at HOC level (not in component)
-    if (!Control) {
-        console.error("[PROBAT] withExperiment: Control component is required");
-        return ((props: P) => null) as any;
-    }
-
-    if (!options || typeof options !== 'object') {
-        console.error("[PROBAT] withExperiment: options is required");
-        return Control as any;
-    }
-
-    const useNewAPI = !!options.componentPath;
-    const useOldAPI = !!(options.proposalId && options.registry);
-
-    if (!useNewAPI && !useOldAPI) {
-        console.warn("[PROBAT] withExperiment: Invalid config, returning Control");
-        return Control as any;
-    }
-
-    const ControlComponent = Control;
-
-    function Wrapped(props: P) {
-        // ============================================================
-        // ALL HOOKS MUST BE AT THE TOP - BEFORE ANY CONDITIONAL RETURNS
-        // ============================================================
-
-        // 1. Context hook - always called first
-        const context = useProbatContext();
-        const apiBaseUrl = context?.apiBaseUrl || "https://gushi.onrender.com";
-        const contextRepoFullName = context?.repoFullName;
-
-        // 2. State hooks - always called in same order
-        const [config, setConfig] = useState<{
-            proposalId: string;
-            variants: Record<string, React.ComponentType<any>>;
-        } | null>(null);
-        const [configLoading, setConfigLoading] = useState(useNewAPI);
-        const [choice, setChoice] = useState<{
-            experiment_id: string;
-            label: string;
-        } | null>(null);
-
-        // Derived values
-        const repoFullName = options.repoFullName || contextRepoFullName;
-        const proposalId = useNewAPI ? config?.proposalId : options.proposalId;
-
-        // 3. Effect hooks - always called
-        // Load component config (new API)
-        useEffect(() => {
-            if (!useNewAPI) return;
-            if (!repoFullName) {
-                console.warn("[PROBAT] componentPath provided but repoFullName not found");
-                setConfigLoading(false);
-                return;
-            }
-
-            let alive = true;
-            setConfigLoading(true);
-
-            (async () => {
-                try {
-                    const componentConfig = await fetchComponentExperimentConfig(
-                        apiBaseUrl,
-                        repoFullName,
-                        options.componentPath!
-                    );
-
-                    if (!alive) return;
-
-                    if (!componentConfig) {
-                        setConfig(null);
-                        setConfigLoading(false);
-                        return;
-                    }
-
-                    const variantComponents: Record<string, React.ComponentType<any>> = {
-                        control: ControlComponent,
-                    };
-
-                    for (const [label, variantInfo] of Object.entries(componentConfig.variants)) {
-                        if (label === "control") continue;
-                        if (variantInfo?.file_path) {
-                            try {
-                                const VariantComp = await loadVariantComponent(
-                                    apiBaseUrl,
-                                    componentConfig.proposal_id,
-                                    variantInfo.experiment_id,
-                                    variantInfo.file_path,
-                                    componentConfig.repo_full_name,
-                                    componentConfig.base_ref
-                                );
-                                if (VariantComp && typeof VariantComp === 'function' && alive) {
-                                    variantComponents[label] = VariantComp;
-                                }
-                            } catch (e) {
-                                console.warn(`[PROBAT] Failed to load variant ${label}:`, e);
-                            }
-                        }
-                    }
-
-                    if (alive) {
-                        setConfig({
-                            proposalId: componentConfig.proposal_id,
-                            variants: variantComponents,
-                        });
-                        setConfigLoading(false);
-                    }
-                } catch (e) {
-                    console.warn("[PROBAT] Failed to load component config:", e);
-                    if (alive) {
-                        setConfig(null);
-                        setConfigLoading(false);
-                    }
-                }
-            })();
-
-            return () => { alive = false; };
-        }, [useNewAPI, options.componentPath, repoFullName, apiBaseUrl]);
-
-        // Fetch experiment decision
-        useEffect(() => {
-            if (!proposalId) return;
-            if (useNewAPI && configLoading) return;
-
-            let alive = true;
-
-            // Detect if we are in heatmap mode
-            const isHeatmapMode = typeof window !== 'undefined' &&
-                new URLSearchParams(window.location.search).get('heatmap') === 'true';
-
-            // HIGH PRIORITY: Check if context is already forcing a specific variant for this proposal
-            // (This happens during Live Heatmap visualization)
-            if (context.proposalId === proposalId && context.variantLabel) {
-                console.log(`[PROBAT HOC] Forced variant from context: ${context.variantLabel}`);
-                setChoice({
-                    experiment_id: `forced_${proposalId}`,
-                    label: context.variantLabel
-                });
-                return;
-            }
-
-            // If we are in heatmap mode, bypass the cache to avoid showing stale variants
-            const cached = isHeatmapMode ? null : readChoice(proposalId);
-
-            if (cached) {
-                const choiceData = {
-                    experiment_id: cached.experiment_id,
-                    label: cached.label,
-                };
-                setChoice(choiceData);
-                // Set localStorage for heatmap tracking
-                if (typeof window !== 'undefined' && !isHeatmapMode) {
-                    try {
-                        window.localStorage.setItem('probat_active_proposal_id', proposalId);
-                        window.localStorage.setItem('probat_active_variant_label', cached.label);
-                    } catch (e) {
-                        console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
-                    }
-                }
-            } else {
-                (async () => {
-                    try {
-                        const { experiment_id, label } = await fetchDecision(apiBaseUrl, proposalId);
-                        if (!alive) return;
-
-                        // Only write to choice cache and localStorage if NOT in heatmap mode
-                        if (!isHeatmapMode) {
-                            writeChoice(proposalId, experiment_id, label);
-                            if (typeof window !== 'undefined') {
-                                try {
-                                    window.localStorage.setItem('probat_active_proposal_id', proposalId);
-                                    window.localStorage.setItem('probat_active_variant_label', label);
-                                } catch (e) {
-                                    console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
-                                }
-                            }
-                        }
-
-                        const choiceData = { experiment_id, label };
-                        setChoice(choiceData);
-                    } catch (e) {
-                        if (!alive) return;
-                        const choiceData = {
-                            experiment_id: `exp_${proposalId}`,
-                            label: "control",
-                        };
-                        setChoice(choiceData);
-
-                        if (typeof window !== 'undefined' && !isHeatmapMode) {
-                            try {
-                                window.localStorage.setItem('probat_active_proposal_id', proposalId);
-                                window.localStorage.setItem('probat_active_variant_label', 'control');
-                            } catch (err) {
-                                console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', err);
-                            }
-                        }
-                    }
-                })();
-            }
-
-            return () => { alive = false; };
-        }, [proposalId, apiBaseUrl, useNewAPI, configLoading, context.proposalId, context.variantLabel]);
-
-        // Track visit
-        useEffect(() => {
-            if (!proposalId) return;
-            const lbl = choice?.label ?? "control";
-            if (!lbl || hasTrackedVisit(proposalId, lbl)) return;
-            markTrackedVisit(proposalId, lbl);
-            void sendMetric(apiBaseUrl, proposalId, "visit", lbl, choice?.experiment_id);
-        }, [proposalId, choice?.experiment_id, choice?.label, apiBaseUrl]);
-
-        // 4. Callback hooks - always called
-        const trackClick = useCallback(
-            (event?: MouseEvent | null, opts?: { force?: boolean }) => {
-                if (!proposalId) return false;
-                const lbl = choice?.label ?? "control";
-                const meta = extractClickMeta(event ?? undefined);
-                if (!opts?.force && event && !meta) return false;
-                void sendMetric(apiBaseUrl, proposalId, "click", lbl, undefined, meta);
-                return true;
-            },
-            [proposalId, choice?.experiment_id, choice?.label, apiBaseUrl]
-        );
-
-        // ============================================================
-        // NOW WE CAN DO CONDITIONAL RETURNS - AFTER ALL HOOKS
-        // ============================================================
-
-        // Loading state - return control
-        if (useNewAPI && (configLoading || !config || !proposalId)) {
-            return React.createElement(ControlComponent as any, props as any);
-        }
-
-        // No proposalId - return control
-        if (!proposalId) {
-            return React.createElement(ControlComponent as any, props as any);
-        }
-
-        // Build registry - always has control
-        const registry: Record<string, React.ComponentType<any>> = { control: ControlComponent };
-
-        if (useNewAPI && config?.variants) {
-            for (const [key, value] of Object.entries(config.variants)) {
-                if (key !== 'control' && value && typeof value === 'function') {
-                    registry[key] = value;
-                }
-            }
-        } else if (!useNewAPI && options.registry) {
-            for (const [key, value] of Object.entries(options.registry)) {
-                if (key !== 'control' && value && typeof value === 'function') {
-                    registry[key] = value;
-                }
-            }
-        }
-
-        // Select variant
-        const label = choice?.label ?? "control";
-        const Variant = registry[label] || registry.control || ControlComponent;
-
-        return (
-            <div onClick={(event) => trackClick(event)} data-probat-proposal={proposalId}>
-                {React.createElement(Variant, {
-                    key: `${proposalId}:${label}`,
-                    ...(props as any),
-                    probat: { trackClick: () => trackClick(null, { force: true }) },
-                })}
-            </div>
-        );
-    }
-
-    Wrapped.displayName = `withExperiment(${Control.displayName || Control.name || "Component"})`;
-    return Wrapped as any;
-}