@funnelsgrove/runtime 0.1.0 → 0.1.1

package/dist/runtime/use-funnel-flow-controller.js

@@ -1,25 +1,69 @@
 'use client';
 import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
-import { writeStepChoice } from '../sdk/userAnswers';
-import { apiService } from '../services/api.service';
-import { logger } from '../services/logger';
-import { buildHostedStepLocation, dispatchWindowCustomEvent, readWindowStorageValue, writeWindowStorageValue, } from './browser-helpers';
-import { getAssignedVariantId, getRequestedEntryPointId, getRuntimeFunnelIdentity, isPreviewStepLockRequested, resolveNextStepFromContext, } from './funnel-flow';
-import { usePreviewBridge } from './preview-bridge';
-import { getExperimentAssignmentAttributeKey, getExperimentAssignmentStorageKey } from './experiment-assignment';
-import { isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service';
-import { isPreviewFrameRuntime } from '../services/preview-frame.service';
+import { writeStepChoice } from '../sdk/userAnswers.js';
+import { apiService } from '../services/api.service.js';
+import { logger } from '../services/logger.js';
+import { FUNNEL_ID, FUNNEL_VERSION_ID, POSTHOG_API_HOST, POSTHOG_PROJECT_API_KEY, PROJECT_ID, } from '../services/runtime-api.config.js';
+import { buildHostedStepLocation, dispatchWindowCustomEvent, } from './browser-helpers.js';
+import { isPreviewStepLockRequested, resolveNextStepFromContext, shouldRunAutoAdvanceTimer, } from './funnel-flow.js';
+import { usePreviewBridge } from './preview-bridge.js';
+import { resolveExperimentAssignment } from './experiment-assignment.js';
+import { collectCurrentFunnelAttribution } from './funnel-attribution.js';
+import { bootstrapPostHog, getPostHog, identifyPostHog, isPostHogReady, resolveExperimentVariant, } from './posthog-flags.js';
+import { isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service.js';
+import { isPreviewFrameRuntime } from '../services/preview-frame.service.js';
+const buildFeatureFlagProperties = (featureFlags) => {
+    return Object.fromEntries(Object.entries(featureFlags).map(([key, value]) => [`$feature/${key}`, value]));
+};
+const capturePostHogStepEvent = (event, properties) => {
+    if (!getPostHog() || !POSTHOG_API_HOST || !POSTHOG_PROJECT_API_KEY || !PROJECT_ID) {
+        return;
+    }
+    const payload = JSON.stringify({
+        api_key: POSTHOG_PROJECT_API_KEY,
+        batch: [
+            {
+                event,
+                properties: Object.assign({ $groups: {
+                        project: PROJECT_ID,
+                    }, $insert_id: typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+                        ? crypto.randomUUID()
+                        : `${event}_${Date.now()}_${Math.random().toString(16).slice(2)}`, event_source: 'client' }, properties),
+                timestamp: new Date().toISOString(),
+            },
+        ],
+    });
+    const endpoint = `${POSTHOG_API_HOST}/batch/`;
+    if (typeof navigator !== 'undefined' && typeof navigator.sendBeacon === 'function') {
+        const accepted = navigator.sendBeacon(endpoint, new Blob([payload], { type: 'application/json' }));
+        if (accepted) {
+            return;
+        }
+    }
+    void fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: payload,
+        keepalive: true,
+    }).catch(() => {
+        // Analytics delivery must never block funnel interaction.
+    });
+};
+export function computeRenderSuspended(input) {
+    if (input.isPreviewRuntime || input.postHogReady) {
+        return false;
+    }
+    return input.experiments.some((experiment) => experiment.stepId === input.activeStepId);
+}
 export function useFunnelFlowController({ initialStepId, lockToInitialStep = false, defaultStepId, stepSequence, stepById, stepComponentById, funnelExperiments, getPathForStep, getStepIdFromPath, getSequentialNextStepId, getChoiceTargetsForStep, isFunnelStepId, resolveConfiguredNextStep, resolveRuntimeInitialStepId, }) {
     var _a, _b;
     const [runtimeMode, setRuntimeMode] = useRuntimeMode();
     const [editorModeEnabled, setEditorModeEnabled] = useState(false);
     const [editorPanelExpanded, setEditorPanelExpanded] = useState(false);
+    const [postHogReady, setPostHogReady] = useState(() => isPostHogReady());
+    const [editorVariantOverrides, setEditorVariantOverrides] = useState({});
     const shouldLockToInitialStep = lockToInitialStep || isPreviewStepLockRequested();
     const isPreviewRuntime = useMemo(() => isPreviewFrameRuntime(), []);
-    const experimentAssignmentStorage = useMemo(() => ({
-        read: readWindowStorageValue,
-        write: writeWindowStorageValue,
-    }), []);
     const resolveRenderableStepId = useCallback((stepId) => {
         if (!stepId || !isFunnelStepId(stepId)) {
             return null;
@@ -46,7 +90,6 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
     const safeInitialStepId = useMemo(() => {
         const requestedStepId = resolveRuntimeInitialStepId({
             requestedStepId: initialStepId,
-            entryPointId: getRequestedEntryPointId(),
         });
         return resolveFallbackStepId(requestedStepId);
     }, [initialStepId, resolveFallbackStepId, resolveRuntimeInitialStepId]);
@@ -57,30 +100,69 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         name: '',
         email: '',
         attributes: {},
+        document: {},
         completedSteps: [],
     }));
     const attributesAtStepStart = useRef({});
     const attributesRef = useRef(attributes);
+    const postHogFeatureFlagsRef = useRef({});
     const prevStepIdRef = useRef(null);
     const stepStartedAtByIdRef = useRef({});
     const currentUserIdRef = useRef(user.id);
     const safeActiveStepId = useMemo(() => { var _a; return (_a = resolveRenderableStepId(activeStepId)) !== null && _a !== void 0 ? _a : safeInitialStepId; }, [activeStepId, resolveRenderableStepId, safeInitialStepId]);
     const activeStepMeta = stepById[safeActiveStepId];
+    const renderSuspended = useMemo(() => computeRenderSuspended({
+        activeStepId: safeActiveStepId,
+        postHogReady,
+        experiments: funnelExperiments,
+        isPreviewRuntime,
+    }), [funnelExperiments, isPreviewRuntime, postHogReady, safeActiveStepId]);
+    const resolveExperimentVariantKey = useCallback((experiment) => {
+        var _a;
+        const override = editorVariantOverrides[experiment.experimentId];
+        if (override) {
+            return override;
+        }
+        if (!postHogReady) {
+            return null;
+        }
+        return (_a = resolveExperimentVariant(experiment.experimentId)) !== null && _a !== void 0 ? _a : null;
+    }, [editorVariantOverrides, postHogReady]);
     const renderedStepId = useMemo(() => {
-        const activeExperiment = funnelExperiments.find((experiment) => experiment.status === 'active' && experiment.stepId === safeActiveStepId);
-        if (!activeExperiment) {
+        const experiment = funnelExperiments.find((candidate) => candidate.stepId === safeActiveStepId);
+        if (!experiment) {
             return safeActiveStepId;
         }
-        const assignedVariantId = getAssignedVariantId(activeExperiment, user.id, experimentAssignmentStorage);
-        if (!assignedVariantId) {
+        const override = editorVariantOverrides[experiment.experimentId];
+        if (override) {
+            const matchedVariant = experiment.variants.find((variant) => variant.variantKey === override);
+            const variantStepId = resolveRenderableStepId((matchedVariant === null || matchedVariant === void 0 ? void 0 : matchedVariant.routeToStepId) || null);
+            return variantStepId !== null && variantStepId !== void 0 ? variantStepId : safeActiveStepId;
+        }
+        if (!postHogReady) {
             return safeActiveStepId;
         }
-        const assignedVariant = activeExperiment.variants.find((variant) => variant.id === assignedVariantId);
-        const variantStepId = resolveRenderableStepId((assignedVariant === null || assignedVariant === void 0 ? void 0 : assignedVariant.routeToStepId) || null);
+        const assignment = resolveExperimentAssignment({
+            experimentId: experiment.experimentId,
+            variants: experiment.variants,
+        });
+        if (!assignment) {
+            return safeActiveStepId;
+        }
+        const variantStepId = resolveRenderableStepId(assignment.routeToStepId);
         return variantStepId !== null && variantStepId !== void 0 ? variantStepId : safeActiveStepId;
-    }, [experimentAssignmentStorage, funnelExperiments, resolveRenderableStepId, safeActiveStepId, user.id]);
+    }, [editorVariantOverrides, funnelExperiments, postHogReady, resolveRenderableStepId, safeActiveStepId]);
     const renderedStepMeta = stepById[renderedStepId];
     const activeStepComponent = stepComponentById[renderedStepId];
+    const postHogFeatureFlags = useMemo(() => {
+        if (!postHogReady || isPreviewRuntime) {
+            return {};
+        }
+        return Object.fromEntries(funnelExperiments.flatMap((experiment) => {
+            const variantKey = resolveExperimentVariant(experiment.experimentId);
+            return variantKey ? [[experiment.experimentId, variantKey]] : [];
+        }));
+    }, [funnelExperiments, isPreviewRuntime, postHogReady]);
     const goToStep = useCallback((stepId) => {
         var _a;
         if (shouldLockToInitialStep) {
@@ -119,38 +201,67 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
     useEffect(() => {
         attributesRef.current = attributes;
     }, [attributes]);
+    useEffect(() => {
+        postHogFeatureFlagsRef.current = postHogFeatureFlags;
+    }, [postHogFeatureFlags]);
+    useEffect(() => {
+        if (postHogReady) {
+            return;
+        }
+        if (isPostHogReady()) {
+            setPostHogReady(true);
+            return;
+        }
+        const intervalId = window.setInterval(() => {
+            if (isPostHogReady()) {
+                setPostHogReady(true);
+                window.clearInterval(intervalId);
+            }
+        }, 100);
+        return () => window.clearInterval(intervalId);
+    }, [postHogReady]);
     const resolveNextStepId = useCallback((stepId) => {
-        const activeUserId = currentUserIdRef.current || user.id;
         return resolveNextStepFromContext({
             stepId,
             attributes: attributesRef.current,
-            userId: activeUserId,
             safeInitialStepId,
             resolveRenderableStepId,
             getConfiguredNextStepId: (currentStepId, context) => resolveConfiguredNextStep(currentStepId, context),
             getSequentialNextStepId,
-            getAssignedVariantId: (experiment, currentUserId) => getAssignedVariantId(experiment, currentUserId, experimentAssignmentStorage),
+            resolveExperimentVariantKey,
         });
     }, [
-        experimentAssignmentStorage,
         getSequentialNextStepId,
         resolveConfiguredNextStep,
+        resolveExperimentVariantKey,
         resolveRenderableStepId,
         safeInitialStepId,
-        user.id,
     ]);
     const goNext = useCallback(() => {
         goToStep(resolveNextStepId(safeActiveStepId));
     }, [goToStep, resolveNextStepId, safeActiveStepId]);
     useEffect(() => {
         const localUserId = apiService.getOrCreateClientUserId();
+        const bootstrapCandidateUserId = apiService.getBootstrapCandidateUserId(localUserId);
+        const initialAttribution = collectCurrentFunnelAttribution();
         setUser((prev) => (Object.assign(Object.assign({}, prev), { id: localUserId })));
         if (isPreviewRuntime) {
             return;
         }
-        apiService
+        const postHogBootstrap = bootstrapPostHog({
+            apiKey: POSTHOG_PROJECT_API_KEY,
+            apiHost: POSTHOG_API_HOST,
+            distinctId: localUserId,
+        })
+            .then(() => setPostHogReady(true))
+            .catch((error) => {
+            logger.error('Failed to bootstrap PostHog feature flags:', error);
+            setPostHogReady(true);
+        });
+        const sessionBootstrap = apiService
             .bootstrapSession({
-            userId: localUserId,
+            userId: bootstrapCandidateUserId || localUserId,
+            attribution: initialAttribution,
         })
             .then((sessionUser) => {
             const sessionAttributes = Object.keys(sessionUser.attributes || {}).length > 0
@@ -159,70 +270,23 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
             if (sessionAttributes) {
                 setAttributes((prev) => (Object.assign(Object.assign({}, sessionAttributes), prev)));
             }
-            setUser((prev) => (Object.assign(Object.assign({}, prev), { id: sessionUser.id || prev.id, name: sessionUser.name || prev.name, email: sessionUser.email || prev.email, attributes: sessionAttributes ? Object.assign(Object.assign({}, sessionAttributes), prev.attributes) : prev.attributes })));
+            setUser((prev) => (Object.assign(Object.assign({}, prev), { id: sessionUser.id || prev.id, name: sessionUser.name || prev.name, email: sessionUser.email || prev.email, document: sessionUser.document, attributes: sessionAttributes ? Object.assign(Object.assign({}, sessionAttributes), prev.attributes) : prev.attributes })));
+            return sessionUser;
         })
             .catch((error) => {
             logger.error('Failed to bootstrap user session:', error);
+            return null;
         });
-    }, [isPreviewRuntime]);
-    useEffect(() => {
-        if (!currentUserIdRef.current) {
-            return;
-        }
-        const assignmentUpdates = {};
-        const assignmentEvents = [];
-        for (const experiment of funnelExperiments) {
-            if (experiment.status !== 'active') {
-                continue;
-            }
-            const assignedVariantId = getAssignedVariantId(experiment, currentUserIdRef.current, experimentAssignmentStorage);
-            if (!assignedVariantId) {
-                continue;
+        Promise.all([postHogBootstrap, sessionBootstrap])
+            .then(([, sessionUser]) => {
+            if (sessionUser === null || sessionUser === void 0 ? void 0 : sessionUser.id) {
+                identifyPostHog(sessionUser.id, localUserId);
             }
-            const assignmentKey = getExperimentAssignmentAttributeKey(experiment.experimentId);
-            if (attributesRef.current[assignmentKey] === assignedVariantId) {
-                continue;
-            }
-            assignmentUpdates[assignmentKey] = assignedVariantId;
-            const assignedVariant = experiment.variants.find((variant) => variant.id === assignedVariantId);
-            assignmentEvents.push({
-                experiment,
-                variantId: assignedVariantId,
-                variantLabel: (assignedVariant === null || assignedVariant === void 0 ? void 0 : assignedVariant.label) || assignedVariantId,
-            });
-        }
-        const entries = Object.entries(assignmentUpdates);
-        if (entries.length === 0) {
-            return;
-        }
-        setAttributes((prev) => {
-            let changed = false;
-            const next = Object.assign({}, prev);
-            for (const [key, value] of entries) {
-                if (next[key] !== value) {
-                    next[key] = value;
-                    changed = true;
-                }
-            }
-            return changed ? next : prev;
+        })
+            .catch((error) => {
+            logger.error('Failed to identify PostHog user:', error);
         });
-        if (!isPreviewRuntime) {
-            assignmentEvents.forEach(({ experiment, variantId, variantLabel }) => {
-                const stepMeta = stepById[experiment.stepId];
-                apiService.trackFunnelEvent({
-                    userId: currentUserIdRef.current,
-                    eventType: 'experiment_variant_assigned',
-                    stepId: experiment.stepId,
-                    stepName: (stepMeta === null || stepMeta === void 0 ? void 0 : stepMeta.name) || (stepMeta === null || stepMeta === void 0 ? void 0 : stepMeta.title) || experiment.stepId,
-                    selected: {
-                        experimentId: experiment.experimentId,
-                        variantId,
-                        variantLabel,
-                    },
-                });
-            });
-        }
-    }, [experimentAssignmentStorage, funnelExperiments, isPreviewRuntime, stepById]);
+    }, [isPreviewRuntime]);
     const recordStepCompletion = useCallback((stepId, explicitChoices) => {
         const meta = stepById[stepId];
         if (!meta) {
@@ -258,11 +322,12 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
                 endedAt: record.completedAt,
                 selected: record.choices,
             });
+            capturePostHogStepEvent('step_completed', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: record.stepId, step_name: record.stepName, started_at: startedAt, ended_at: record.completedAt, selected: record.choices }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
         }
         setUser((prev) => {
-            var _a;
+            var _a, _b;
             const updatedSteps = [...((_a = prev.completedSteps) !== null && _a !== void 0 ? _a : []), record];
-            const updatedUser = Object.assign(Object.assign({}, prev), { attributes: Object.assign(Object.assign({}, prev.attributes), attributesRef.current), completedSteps: updatedSteps });
+            const updatedUser = Object.assign(Object.assign({}, prev), { attributes: Object.assign(Object.assign({}, prev.attributes), attributesRef.current), document: prev.document, completedSteps: updatedSteps });
             if (!isPreviewRuntime) {
                 apiService
                     .updateUser({
@@ -270,6 +335,9 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
                     name: updatedUser.name,
                     email: updatedUser.email,
                     attributes: Object.assign(Object.assign({}, updatedUser.attributes), { completedSteps: updatedSteps }),
+                    document: (_b = updatedUser.document) !== null && _b !== void 0 ? _b : {},
+                }, {
+                    attribution: collectCurrentFunnelAttribution(),
                 })
                     .catch((error) => {
                     logger.error('Failed to persist step completion:', error);
@@ -287,6 +355,9 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
             setActiveStepId(safeActiveStepId);
             return;
         }
+        if (renderSuspended) {
+            return;
+        }
         const prevId = prevStepIdRef.current;
         if (prevId && prevId !== safeActiveStepId) {
             recordStepCompletion(prevId);
@@ -300,28 +371,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
                 stepName: (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name) || (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title) || safeActiveStepId,
                 startedAt,
             });
-        }
-        const stepExperiments = funnelExperiments.filter((experiment) => experiment.status === 'active' && experiment.stepId === safeActiveStepId);
-        for (const experiment of stepExperiments) {
-            const assignedVariantId = getAssignedVariantId(experiment, currentUserIdRef.current, experimentAssignmentStorage);
-            if (!assignedVariantId) {
-                continue;
-            }
-            const assignedVariant = experiment.variants.find((variant) => variant.id === assignedVariantId);
-            if (!isPreviewRuntime) {
-                apiService.trackFunnelEvent({
-                    userId: currentUserIdRef.current,
-                    eventType: 'experiment_step_exposed',
-                    stepId: safeActiveStepId,
-                    stepName: (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name) || (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title) || safeActiveStepId,
-                    startedAt,
-                    selected: {
-                        experimentId: experiment.experimentId,
-                        variantId: assignedVariantId,
-                        variantLabel: (assignedVariant === null || assignedVariant === void 0 ? void 0 : assignedVariant.label) || assignedVariantId,
-                    },
-                });
-            }
+            capturePostHogStepEvent('step_started', Object.assign({ distinct_id: currentUserIdRef.current, funnel_id: FUNNEL_ID || undefined, funnel_version_id: FUNNEL_VERSION_ID || undefined, project_id: PROJECT_ID || undefined, step_id: safeActiveStepId, step_name: (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name) || (activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title) || safeActiveStepId, started_at: startedAt }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
         }
         attributesAtStepStart.current = Object.assign({}, attributesRef.current);
         prevStepIdRef.current = safeActiveStepId;
@@ -329,10 +379,9 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         activeStepId,
         activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name,
         activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title,
-        experimentAssignmentStorage,
-        funnelExperiments,
         isPreviewRuntime,
         recordStepCompletion,
+        renderSuspended,
         safeActiveStepId,
     ]);
     useEffect(() => {
@@ -363,21 +412,19 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
     const nextStepId = useMemo(() => resolveNextStepFromContext({
         stepId: safeActiveStepId,
         attributes,
-        userId: user.id,
         safeInitialStepId,
         resolveRenderableStepId,
         getConfiguredNextStepId: (currentStepId, context) => resolveConfiguredNextStep(currentStepId, context),
         getSequentialNextStepId,
-        getAssignedVariantId: (experiment, currentUserId) => getAssignedVariantId(experiment, currentUserId, experimentAssignmentStorage),
+        resolveExperimentVariantKey,
     }), [
         attributes,
-        experimentAssignmentStorage,
         getSequentialNextStepId,
         resolveConfiguredNextStep,
+        resolveExperimentVariantKey,
         resolveRenderableStepId,
         safeActiveStepId,
         safeInitialStepId,
-        user.id,
     ]);
     const choiceTargets = getChoiceTargetsForStep(safeActiveStepId);
     const actionBar = (_a = renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.actionBar) !== null && _a !== void 0 ? _a : activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.actionBar;
@@ -387,10 +434,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
     const buttonText = (actionBar === null || actionBar === void 0 ? void 0 : actionBar.buttonText) || 'Continue';
     const hideActionBar = (actionBar === null || actionBar === void 0 ? void 0 : actionBar.hidden) === true;
     useEffect(() => {
-        if (shouldLockToInitialStep) {
-            return;
-        }
-        if (!autoAdvanceMs) {
+        if (!shouldRunAutoAdvanceTimer({ autoAdvanceMs, isPreviewRuntime, shouldLockToInitialStep })) {
             return;
         }
         const autoAdvanceTarget = resolveNextStepId(safeActiveStepId);
@@ -398,7 +442,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
             goToStep(autoAdvanceTarget);
         }, autoAdvanceMs);
         return () => window.clearTimeout(timer);
-    }, [autoAdvanceMs, goToStep, resolveNextStepId, safeActiveStepId, shouldLockToInitialStep]);
+    }, [autoAdvanceMs, goToStep, isPreviewRuntime, resolveNextStepId, safeActiveStepId, shouldLockToInitialStep]);
     const handleContinue = useCallback(() => {
         goToStep(nextStepId);
     }, [goToStep, nextStepId]);
@@ -423,53 +467,37 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         setRuntimeMode,
         shouldLockToInitialStep,
     });
-    const setEditorVariantSelection = useCallback((experiment, variantId) => {
-        const nextVariantId = variantId.trim();
-        if (!nextVariantId) {
+    const setEditorVariantSelection = useCallback((experiment, variantKey) => {
+        const nextVariantKey = variantKey.trim();
+        if (!nextVariantKey) {
             return;
         }
-        const selectedVariant = experiment.variants.find((variant) => variant.id === nextVariantId);
+        const selectedVariant = experiment.variants.find((variant) => variant.variantKey === nextVariantKey);
         if (!selectedVariant) {
             return;
         }
-        const userId = currentUserIdRef.current || user.id;
-        if (!userId) {
-            return;
-        }
-        try {
-            const storageKey = getExperimentAssignmentStorageKey(getRuntimeFunnelIdentity(), userId, experiment.experimentId);
-            writeWindowStorageValue(storageKey, selectedVariant.id);
-        }
-        catch (_a) {
-            // ignore storage access failures
-        }
-        const assignmentKey = getExperimentAssignmentAttributeKey(experiment.experimentId);
-        setAttributes((prev) => prev[assignmentKey] === selectedVariant.id
-            ? prev
-            : Object.assign(Object.assign({}, prev), { [assignmentKey]: selectedVariant.id }));
-        if (!isPreviewRuntime) {
-            const stepMeta = stepById[experiment.stepId];
-            apiService.trackFunnelEvent({
-                userId,
-                eventType: 'experiment_variant_selected_editor',
-                stepId: experiment.stepId,
-                stepName: (stepMeta === null || stepMeta === void 0 ? void 0 : stepMeta.name) || (stepMeta === null || stepMeta === void 0 ? void 0 : stepMeta.title) || experiment.stepId,
-                selected: {
-                    experimentId: experiment.experimentId,
-                    variantId: selectedVariant.id,
-                    variantLabel: selectedVariant.label,
-                },
-            });
-        }
-    }, [isPreviewRuntime, stepById, user.id]);
+        setEditorVariantOverrides((prev) => (Object.assign(Object.assign({}, prev), { [experiment.experimentId]: selectedVariant.variantKey })));
+    }, []);
     const experimentAssignmentForEditor = useCallback((experiment) => {
         var _a;
-        return (getAssignedVariantId(experiment, user.id, experimentAssignmentStorage) ||
-            ((_a = experiment.variants[0]) === null || _a === void 0 ? void 0 : _a.id) ||
-            '');
-    }, [experimentAssignmentStorage, user.id]);
+        const override = editorVariantOverrides[experiment.experimentId];
+        if (override) {
+            return override;
+        }
+        if (postHogReady) {
+            const assignment = resolveExperimentAssignment({
+                experimentId: experiment.experimentId,
+                variants: experiment.variants,
+            });
+            if (assignment) {
+                return assignment.variantKey;
+            }
+        }
+        return ((_a = experiment.variants[0]) === null || _a === void 0 ? void 0 : _a.variantKey) || '';
+    }, [editorVariantOverrides, postHogReady]);
     const contextValue = useMemo(() => ({
         activeStepId: safeActiveStepId,
+        isBuilder: isPreviewRuntime,
         goToStep: goToStepFromContext,
         goNext,
         goChoice,
@@ -494,6 +522,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         goChoice,
         goNext,
         goToStepFromContext,
+        isPreviewRuntime,
         resolveRenderableStepId,
         safeActiveStepId,
         setAnswer,
@@ -512,6 +541,8 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         experimentAssignmentForEditor,
         funnelExperiments,
         handleContinue,
+        postHogReady,
+        renderSuspended,
         renderedStepId,
         renderedStepMeta,
         runtimeMode,

package/dist/sdk/userAnswers.d.ts

@@ -1,4 +1,4 @@
-import type { FunnelStepId } from '../runtime/funnel-runtime';
+import type { FunnelStepId } from '../runtime/funnel-runtime.js';
 export type FunnelBinaryChoice = 'yes' | 'no';
 export type FunnelBirthDate = {
     year: number;
@@ -14,7 +14,7 @@ export type FunnelTempUpload = {
 };
 /**
  * Typed SDK-facing answers object shared across all steps.
- * Keep this shape in sync with SDK_USER_OBJECT.md so future funnels can extend it safely.
+ * Keep this shape in sync with docs/references/funnel-sdk-user-answers.md so future funnels can extend it safely.
  */
 export type FunnelUserAnswers = Record<string, unknown> & {
     /** Generic branching answers by step id for yes/no splits. */

package/dist/services/api.service.d.ts

@@ -1,9 +1,11 @@
-import type { FunnelUserAnswers } from '../sdk/userAnswers';
+import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
+import { type FunnelUserAttribution } from '../runtime/funnel-attribution.js';
 export type AppUser = {
     id: string;
     name: string;
     email: string;
     attributes: FunnelUserAnswers;
+    document: Record<string, unknown>;
 };
 export type FunnelEvent = {
     userId: string;
@@ -26,7 +28,7 @@ export type StepCompletionEvent = {
 export type ManageSubscriptionsResponse = {
     user: {
         id: string;
-        externalUserId: string;
+        user_id: string;
         email: string | null;
         fullName: string | null;
         subscriptionStatus: string | null;
@@ -35,8 +37,15 @@ export type ManageSubscriptionsResponse = {
         id: string;
         status: string;
         providerSubscriptionId: string;
+        providerPlanId: string | null;
         cancelAtPeriodEnd: boolean;
+        currentPeriodStart: string | null;
         currentPeriodEnd: string | null;
+        createdAt: string | null;
+        amountCents?: number | null;
+        currency?: string | null;
+        billingInterval?: string | null;
+        billingIntervalCount?: number | null;
         environment: 'test' | 'live';
     }>;
     eventsCount: number;
@@ -51,15 +60,23 @@ export type TempPhotoUploadResult = {
 declare class ApiService {
     private readFileAsDataUrl;
     getOrCreateClientUserId(): string;
+    getSubscriptionManagementUserId(): string | null;
+    getSubscriptionManagementStripeCustomerId(): string | null;
+    getBootstrapCandidateUserId(fallbackUserId?: string | null): string | null;
+    private fetchCurrentUserState;
+    private resolveBootstrapUserId;
     bootstrapSession(input?: {
         userId?: string;
         email?: string;
         name?: string;
+        attribution?: FunnelUserAttribution;
+    }): Promise<AppUser>;
+    updateUser(user: AppUser, options?: {
+        attribution?: FunnelUserAttribution;
     }): Promise<AppUser>;
-    updateUser(user: AppUser): Promise<AppUser>;
     uploadTempPhoto(input: {
         file: File;
-        externalUserId?: string;
+        userId?: string;
         source?: 'camera' | 'upload';
     }): Promise<TempPhotoUploadResult>;
     private sendEventAsync;