@funnelsgrove/runtime 0.1.55 → 0.1.59

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

@@ -8,14 +8,218 @@ import { buildHostedStepLocation, dispatchWindowCustomEvent, } from './browser-h
 import { isPreviewStepLockRequested, resolveNextStepFromContext, shouldRunAutoAdvanceTimer, } from './funnel-flow.js';
 import { usePreviewBridge } from './preview-bridge.js';
 import { resolveExperimentAssignment, resolveForcedExperimentAssignment, } from './experiment-assignment.js';
-import { collectCurrentFunnelAttribution } from './funnel-attribution.js';
+import { buildFunnelAttributionEventMetadata, collectCurrentFunnelAttribution, getFunnelUserAttribution, } from './funnel-attribution.js';
 import { resolveUrlUserAttributes } from './url-user-attributes.js';
 import { bootstrapPostHog, identifyPostHog, isPostHogReady, resolveExperimentVariant, } from './posthog-flags.js';
 import { getRuntimeMode, isEditorEnabled, useRuntimeMode } from '../services/runtime-mode.service.js';
 import { isPreviewFrameRuntime } from '../services/preview-frame.service.js';
+import { FUNNEL_STEP_CONTRACTS, LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION, } from '../steps/step-contract.js';
+import { isDevelopmentRuntime } from '../config/env.config.js';
+import { consumeChoiceCompletionMarker, enforceChoiceBypassGuard, registerInternalChoiceCommit, runAtomicChoiceCommit, } from './use-step-choices.js';
+import { createFunnelStepLifecycleState, finishVisit, startVisit, } from './funnel-step-lifecycle.js';
+import { createEmailCaptureSingleFlight, submitEmailCapture as submitEmailCapturePrimitive, } from './submit-email-capture.js';
+const isTerminalCompletion = (stepMeta, outcome) => {
+    var _a;
+    return (outcome.type === 'complete'
+        && Boolean(stepMeta && ((_a = FUNNEL_STEP_CONTRACTS[stepMeta.type]) === null || _a === void 0 ? void 0 : _a.terminal) === true));
+};
+export function resolveFunnelEventAttribution(document, provisionalAttribution) {
+    var _a;
+    return (_a = getFunnelUserAttribution(document)) !== null && _a !== void 0 ? _a : provisionalAttribution;
+}
+export function buildReadyFunnelAttributionEventMetadata(attributionReady, attribution) {
+    return attributionReady ? buildFunnelAttributionEventMetadata(attribution) : null;
+}
+export function scheduleAttributionFailOpen(onReady, timeoutMs) {
+    const timeoutId = setTimeout(onReady, timeoutMs);
+    return () => clearTimeout(timeoutId);
+}
+export function takeInitialFunnelAttributionMetadata(tracked, attributionReady, attribution) {
+    if (tracked) {
+        return { tracked, metadata: null };
+    }
+    const metadata = buildReadyFunnelAttributionEventMetadata(attributionReady, attribution);
+    return { tracked: metadata !== null, metadata };
+}
+const EXIT_REASONS = new Set(['back', 'replace', 'cancel', 'abandon']);
+const MAX_NAVIGATION_SELECTED_KEYS = 128;
+const MAX_NAVIGATION_SELECTED_KEY_LENGTH = 128;
+const MAX_NAVIGATION_SELECTED_STRING_LENGTH = 4096;
+const MAX_NAVIGATION_SELECTED_DEPTH = 16;
+const MAX_NAVIGATION_SELECTED_NODES = 512;
+const INVALID_SELECTED_VALUE = Symbol('invalid-selected-value');
+const copyOwnDataProperties = (input, maxKeys) => {
+    try {
+        const keys = Reflect.ownKeys(input);
+        if (keys.length > maxKeys || keys.some((key) => typeof key !== 'string')) {
+            return null;
+        }
+        const copy = Object.create(null);
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+                return null;
+            }
+            Object.defineProperty(copy, key, {
+                configurable: false,
+                enumerable: true,
+                value: descriptor.value,
+                writable: false,
+            });
+        }
+        return Object.freeze(copy);
+    }
+    catch (_a) {
+        return null;
+    }
+};
+const canonicalizeSelected = (input) => {
+    let nodes = 0;
+    const ancestors = new WeakSet();
+    const visit = (value, depth) => {
+        nodes += 1;
+        if (nodes > MAX_NAVIGATION_SELECTED_NODES || depth > MAX_NAVIGATION_SELECTED_DEPTH) {
+            return INVALID_SELECTED_VALUE;
+        }
+        if (value === null || typeof value === 'boolean') {
+            return value;
+        }
+        if (typeof value === 'number') {
+            return Number.isFinite(value) ? value : INVALID_SELECTED_VALUE;
+        }
+        if (typeof value === 'string') {
+            return value.length <= MAX_NAVIGATION_SELECTED_STRING_LENGTH
+                ? value
+                : INVALID_SELECTED_VALUE;
+        }
+        if (typeof value !== 'object' || ancestors.has(value)) {
+            return INVALID_SELECTED_VALUE;
+        }
+        const isArray = Array.isArray(value);
+        const prototype = Object.getPrototypeOf(value);
+        if (isArray ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) {
+            return INVALID_SELECTED_VALUE;
+        }
+        ancestors.add(value);
+        try {
+            const keys = Reflect.ownKeys(value);
+            if (keys.some((key) => typeof key !== 'string')) {
+                return INVALID_SELECTED_VALUE;
+            }
+            if (isArray) {
+                const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
+                const length = lengthDescriptor && 'value' in lengthDescriptor
+                    ? lengthDescriptor.value
+                    : null;
+                if (!Number.isSafeInteger(length)
+                    || length < 0
+                    || length > MAX_NAVIGATION_SELECTED_NODES
+                    || keys.length !== length + 1) {
+                    return INVALID_SELECTED_VALUE;
+                }
+                const copy = [];
+                for (let index = 0; index < length; index += 1) {
+                    const key = String(index);
+                    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                    if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+                        return INVALID_SELECTED_VALUE;
+                    }
+                    const nested = visit(descriptor.value, depth + 1);
+                    if (nested === INVALID_SELECTED_VALUE) {
+                        return INVALID_SELECTED_VALUE;
+                    }
+                    copy.push(nested);
+                }
+                return Object.freeze(copy);
+            }
+            if (keys.length > MAX_NAVIGATION_SELECTED_KEYS) {
+                return INVALID_SELECTED_VALUE;
+            }
+            const copy = Object.create(null);
+            for (const key of keys) {
+                if (key.length > MAX_NAVIGATION_SELECTED_KEY_LENGTH) {
+                    return INVALID_SELECTED_VALUE;
+                }
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+                    return INVALID_SELECTED_VALUE;
+                }
+                const nested = visit(descriptor.value, depth + 1);
+                if (nested === INVALID_SELECTED_VALUE) {
+                    return INVALID_SELECTED_VALUE;
+                }
+                Object.defineProperty(copy, key, {
+                    configurable: false,
+                    enumerable: true,
+                    value: nested,
+                    writable: false,
+                });
+            }
+            return Object.freeze(copy);
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    };
+    try {
+        const selected = visit(input, 0);
+        return selected === INVALID_SELECTED_VALUE || selected === null || Array.isArray(selected)
+            ? null
+            : selected;
+    }
+    catch (_a) {
+        return null;
+    }
+};
+function resolveNavigationOutcome(input, stepContractVersion) {
+    if (input === undefined) {
+        return stepContractVersion === LEGACY_UNVERSIONED_STEP_CONTRACT_VERSION
+            ? { type: 'complete' }
+            : null;
+    }
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return null;
+    }
+    const record = copyOwnDataProperties(input, 2);
+    if (!record) {
+        return null;
+    }
+    try {
+        const keys = Object.keys(record);
+        if (record.type === 'complete') {
+            if (keys.some((key) => key !== 'type' && key !== 'selected')) {
+                return null;
+            }
+            if (record.selected === undefined) {
+                return { type: 'complete' };
+            }
+            if (record.selected === null || typeof record.selected !== 'object' || Array.isArray(record.selected)) {
+                return null;
+            }
+            const selected = canonicalizeSelected(record.selected);
+            return selected ? { type: 'complete', selected } : null;
+        }
+        if (record.type === 'exit'
+            && keys.every((key) => key === 'type' || key === 'reason')
+            && typeof record.reason === 'string'
+            && EXIT_REASONS.has(record.reason)) {
+            return { type: 'exit', reason: record.reason };
+        }
+    }
+    catch (_a) {
+        return null;
+    }
+    return null;
+}
 export function computeRenderSuspended(input) {
     var _a;
-    if (input.isPreviewRuntime || input.postHogReady) {
+    if (input.isPreviewRuntime) {
+        return false;
+    }
+    if (input.attributionReady === false) {
+        return true;
+    }
+    if (input.postHogReady) {
         return false;
     }
     const activeExperiment = input.experiments.find((experiment) => experiment.stepId === input.activeStepId);
@@ -65,15 +269,16 @@ export function resolveRenderedExperimentStepId(input) {
     const variantStepId = resolveRenderableStepId(assignment.routeToStepId);
     return variantStepId !== null && variantStepId !== void 0 ? variantStepId : safeActiveStepId;
 }
-export function useFunnelFlowController({ analytics, initialStepId, initialAttributes, lockToInitialStep = false, defaultStepId, stepSequence, stepById, stepComponentById, funnelExperiments, getPathForStep, getStepIdFromPath, getSequentialNextStepId, getChoiceTargetsForStep, isFunnelStepId, resolveConfiguredNextStep, resolveRuntimeInitialStepId, }) {
+export function useFunnelFlowController({ api = apiService, analytics, stepContractVersion, initialStepId, initialAttributes, 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 [editorModeEnabled, setEditorModeEnabled] = useState(() => isEditorEnabled());
     const [editorPanelExpanded, setEditorPanelExpanded] = useState(false);
     const [postHogReady, setPostHogReady] = useState(() => isPostHogReady());
     const [editorVariantOverrides, setEditorVariantOverrides] = useState({});
     const shouldLockToInitialStep = lockToInitialStep || isPreviewStepLockRequested();
     const isPreviewRuntime = useMemo(() => isPreviewFrameRuntime(), []);
+    const lifecycleEventsSuppressed = isPreviewRuntime || editorModeEnabled;
     const resolveRenderableStepId = useCallback((stepId) => {
         if (!stepId || !isFunnelStepId(stepId)) {
             return null;
@@ -106,7 +311,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
     const [activeStepId, setActiveStepId] = useState(safeInitialStepId);
     const [attributes, setAttributes] = useState(() => (Object.assign({}, (initialAttributes || {}))));
     const [user, setUser] = useState(() => ({
-        id: apiService.getOrCreateClientUserId(),
+        id: api.getOrCreateClientUserId(),
         name: '',
         email: '',
         attributes: {},
@@ -114,21 +319,35 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         completedSteps: [],
     }));
     const [userBootstrapped, setUserBootstrapped] = useState(isPreviewRuntime);
+    const [attributionReady, setAttributionReady] = useState(isPreviewRuntime);
     const attributesAtStepStart = useRef({});
     const attributesRef = useRef(attributes);
     const postHogFeatureFlagsRef = useRef({});
     const prevStepIdRef = useRef(null);
-    const firstStepViewedTrackedRef = useRef(false);
-    const stepStartedAtByIdRef = useRef({});
+    const funnelStartedTrackedRef = useRef(false);
+    const firstStepViewedVisitRef = useRef(null);
+    const firstStepClickedVisitRef = useRef(null);
+    // One controller mount is one funnel run. A full reload intentionally begins a new run.
+    const funnelCompletionClaimedRef = useRef(false);
     const currentUserIdRef = useRef(user.id);
+    const initialAttributionRef = useRef(null);
+    const choiceCompletionMarkerRef = useRef(null);
+    const choiceCommitInFlightRef = useRef(null);
+    const choiceNavigationRetryRef = useRef(null);
+    const stepLifecycleStateRef = useRef(createFunnelStepLifecycleState());
+    const activeVisitTokenRef = useRef(null);
+    const emailCaptureSingleFlightRef = useRef(createEmailCaptureSingleFlight());
+    const pendingEmailCaptureNavigationRef = useRef(null);
+    const appliedInitialStepIdRef = useRef(safeInitialStepId);
     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,
+        attributionReady,
         postHogReady,
         experiments: funnelExperiments,
         isPreviewRuntime,
-    }), [funnelExperiments, isPreviewRuntime, postHogReady, safeActiveStepId]);
+    }), [attributionReady, funnelExperiments, isPreviewRuntime, postHogReady, safeActiveStepId]);
     const resolveExperimentVariantKey = useCallback((experiment) => {
         var _a;
         const override = editorVariantOverrides[experiment.experimentId];
@@ -157,6 +376,16 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
     }), [activeExperimentForStep, editorVariantOverrides, postHogReady, resolveRenderableStepId, safeActiveStepId]);
     const renderedStepMeta = stepById[renderedStepId];
     const activeStepComponent = stepComponentById[renderedStepId];
+    const reportChoiceDiagnostic = useCallback((diagnostic) => {
+        logger.error(`[FunnelFlow] ${diagnostic.code}: ${diagnostic.reason}`);
+        dispatchWindowCustomEvent('funnel:contract-diagnostic', {
+            code: diagnostic.code,
+            stepId: diagnostic.stepId,
+            reason: diagnostic.reason,
+            repair: diagnostic.repair,
+        });
+    }, []);
+    const choiceGuardEnvironment = isDevelopmentRuntime() ? 'development' : 'production';
     const postHogFeatureFlags = useMemo(() => {
         if (!postHogReady || isPreviewRuntime) {
             return {};
@@ -166,12 +395,20 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             return variantKey ? [[experiment.experimentId, variantKey]] : [];
         }));
     }, [funnelExperiments, isPreviewRuntime, postHogReady]);
-    const goToStep = useCallback((stepId) => {
-        var _a;
+    const resolveNavigationTarget = useCallback((stepId) => {
+        var _a, _b;
         if (shouldLockToInitialStep) {
-            return;
+            return null;
         }
         const safeStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : safeInitialStepId;
+        const activeVisitStepId = (_b = activeVisitTokenRef.current) === null || _b === void 0 ? void 0 : _b.stepId;
+        return safeStepId === safeActiveStepId
+            || safeStepId === renderedStepId
+            || safeStepId === activeVisitStepId
+            ? null
+            : safeStepId;
+    }, [renderedStepId, resolveRenderableStepId, safeActiveStepId, safeInitialStepId, shouldLockToInitialStep]);
+    const navigateToStep = useCallback((safeStepId) => {
         const stepPath = getPathForStep(safeStepId);
         const nextLocation = buildHostedStepLocation({
             currentHref: window.location.href,
@@ -188,16 +425,38 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             }
         }
         setActiveStepId(safeStepId);
-    }, [getPathForStep, resolveRenderableStepId, safeInitialStepId, shouldLockToInitialStep]);
+    }, [getPathForStep]);
     const setAnswer = useCallback((key, value) => {
+        if (!enforceChoiceBypassGuard({
+            operation: 'setAnswer',
+            activeStepId: renderedStepId,
+            key: String(key),
+            stepById,
+            stepContractVersion,
+            environment: choiceGuardEnvironment,
+            reportDiagnostic: reportChoiceDiagnostic,
+        })) {
+            return;
+        }
         setAttributes((prev) => (Object.assign(Object.assign({}, prev), { [key]: value })));
-    }, []);
+    }, [choiceGuardEnvironment, renderedStepId, reportChoiceDiagnostic, stepById, stepContractVersion]);
     const getAnswer = useCallback((key) => {
         return attributesRef.current[key];
     }, []);
     const setAttribute = useCallback((key, value) => {
+        if (!enforceChoiceBypassGuard({
+            operation: 'setAttribute',
+            activeStepId: renderedStepId,
+            key,
+            stepById,
+            stepContractVersion,
+            environment: choiceGuardEnvironment,
+            reportDiagnostic: reportChoiceDiagnostic,
+        })) {
+            return;
+        }
         setAttributes((prev) => (Object.assign(Object.assign({}, prev), { [key]: value })));
-    }, []);
+    }, [choiceGuardEnvironment, renderedStepId, reportChoiceDiagnostic, stepById, stepContractVersion]);
     useEffect(() => {
         currentUserIdRef.current = user.id;
     }, [user.id]);
@@ -224,9 +483,10 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         return () => window.clearInterval(intervalId);
     }, [postHogReady]);
     const resolveNextStepId = useCallback((stepId, options) => {
+        var _a;
         return resolveNextStepFromContext({
             stepId,
-            attributes: attributesRef.current,
+            attributes: (_a = options === null || options === void 0 ? void 0 : options.attributes) !== null && _a !== void 0 ? _a : attributesRef.current,
             safeInitialStepId,
             resolveRenderableStepId,
             getConfiguredNextStepId: (currentStepId, context) => resolveConfiguredNextStep(currentStepId, context),
@@ -241,21 +501,18 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         resolveRenderableStepId,
         safeInitialStepId,
     ]);
-    const goNext = useCallback(() => {
-        goToStep(resolveNextStepId(renderedStepId, {
-            ignoreExperiment: Boolean(activeExperimentForStep && renderedStepId === safeActiveStepId),
-        }));
-    }, [activeExperimentForStep, goToStep, renderedStepId, resolveNextStepId, safeActiveStepId]);
     useEffect(() => {
-        const localUserId = apiService.getOrCreateClientUserId();
+        const localUserId = api.getOrCreateClientUserId();
         const urlUserAttributes = resolveUrlUserAttributes();
-        const bootstrapCandidateUserId = apiService.getBootstrapCandidateUserId(localUserId);
+        const bootstrapCandidateUserId = api.getBootstrapCandidateUserId(localUserId);
         const initialAttribution = collectCurrentFunnelAttribution();
+        initialAttributionRef.current = initialAttribution;
         setUserBootstrapped(isPreviewRuntime);
         setUser((prev) => (Object.assign(Object.assign({}, prev), { id: localUserId })));
         if (isPreviewRuntime) {
             return;
         }
+        const cancelAttributionFailOpen = scheduleAttributionFailOpen(() => setAttributionReady(true), 5000);
         const postHogBootstrap = bootstrapPostHog({
             apiKey: POSTHOG_PROJECT_API_KEY,
             apiHost: POSTHOG_API_HOST,
@@ -268,7 +525,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             logger.error('Failed to bootstrap PostHog feature flags:', error);
             setPostHogReady(true);
         });
-        const sessionBootstrap = apiService
+        const sessionBootstrap = api
             .bootstrapSession({
             userId: bootstrapCandidateUserId || localUserId,
             email: urlUserAttributes.email || undefined,
@@ -276,15 +533,18 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             attribution: initialAttribution,
         })
             .then((sessionUser) => {
+            cancelAttributionFailOpen();
             const sessionAttributes = Object.keys(sessionUser.attributes || {}).length > 0
                 ? sessionUser.attributes
                 : null;
             if (sessionAttributes) {
                 setAttributes((prev) => (Object.assign(Object.assign({}, sessionAttributes), prev)));
             }
+            initialAttributionRef.current = resolveFunnelEventAttribution(sessionUser.document, initialAttribution);
             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 })));
             setUserBootstrapped(true);
-            void apiService.pingUserContext(sessionUser.id)
+            setAttributionReady(true);
+            void api.pingUserContext(sessionUser.id)
                 .then((pingedUser) => {
                 if (!pingedUser) {
                     return;
@@ -301,8 +561,10 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             return sessionUser;
         })
             .catch((error) => {
+            cancelAttributionFailOpen();
             logger.error('Failed to bootstrap user session:', error);
             setUserBootstrapped(false);
+            setAttributionReady(true);
             return null;
         });
         Promise.all([postHogBootstrap, sessionBootstrap])
@@ -314,16 +576,21 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             .catch((error) => {
             logger.error('Failed to identify PostHog user:', error);
         });
-    }, [isPreviewRuntime]);
-    const recordStepCompletion = useCallback((stepId, explicitChoices) => {
+        return cancelAttributionFailOpen;
+    }, [api, isPreviewRuntime]);
+    const recordStepCompletion = useCallback((intent, options = {}) => {
         var _a;
-        const meta = stepById[stepId];
-        if (!meta) {
+        const meta = stepById[intent.visit.stepId];
+        if (!meta || lifecycleEventsSuppressed) {
+            return;
+        }
+        const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+        if (attributionMetadata === null) {
             return;
         }
         let choices;
-        if (explicitChoices) {
-            choices = explicitChoices;
+        if (options.explicitChoices !== undefined) {
+            choices = options.explicitChoices;
         }
         else {
             const snapshot = attributesAtStepStart.current;
@@ -341,28 +608,14 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             choices,
         };
         const stepType = meta.type;
-        const startedAt = stepStartedAtByIdRef.current[meta.id] || record.completedAt;
+        const completionAttributes = Object.assign({}, attributesRef.current);
         dispatchWindowCustomEvent('funnel:step-completed', record);
-        if (!isPreviewRuntime) {
-            const analyticsRuntimeMode = getRuntimeMode();
-            (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepCompleted) === null || _a === void 0 ? void 0 : _a.call(analytics, {
-                userId: currentUserIdRef.current,
-                environment: analyticsRuntimeMode,
-                stepId: record.stepId,
-                stepName: record.stepName,
-                stepType,
-                startedAt,
-                endedAt: record.completedAt,
-                selected: record.choices,
-                featureFlags: postHogFeatureFlagsRef.current,
-            });
-        }
         setUser((prev) => {
             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), document: prev.document, completedSteps: updatedSteps });
+            const updatedUser = Object.assign(Object.assign({}, prev), { attributes: Object.assign(Object.assign({}, prev.attributes), completionAttributes), document: prev.document, completedSteps: updatedSteps });
             if (!isPreviewRuntime) {
-                apiService
+                api
                     .updateUser({
                     id: updatedUser.id,
                     name: updatedUser.name,
@@ -378,14 +631,347 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             }
             return updatedUser;
         });
-    }, [analytics, isPreviewRuntime, stepById]);
+        if (!isPreviewRuntime) {
+            const analyticsRuntimeMode = getRuntimeMode();
+            try {
+                (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepCompleted) === null || _a === void 0 ? void 0 : _a.call(analytics, Object.assign(Object.assign({ userId: currentUserIdRef.current, environment: analyticsRuntimeMode, stepId: record.stepId, stepName: record.stepName, stepType, startedAt: intent.visit.startedAt, endedAt: record.completedAt, stepContractVersion }, (options.omitSelected ? {} : { selected: record.choices })), { metadata: Object.assign(Object.assign(Object.assign({}, attributionMetadata), options.metadata), { step_contract_version: stepContractVersion }), featureFlags: postHogFeatureFlagsRef.current }));
+            }
+            catch (error) {
+                logger.error('Failed to track step completion:', error);
+            }
+        }
+    }, [analytics, api, attributionReady, isPreviewRuntime, lifecycleEventsSuppressed, stepById, stepContractVersion]);
+    const emitStepExit = useCallback((intent) => {
+        var _a;
+        const meta = stepById[intent.visit.stepId];
+        if (!meta || lifecycleEventsSuppressed) {
+            return;
+        }
+        const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+        if (attributionMetadata === null) {
+            return;
+        }
+        (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepExited) === null || _a === void 0 ? void 0 : _a.call(analytics, {
+            userId: currentUserIdRef.current,
+            environment: getRuntimeMode(),
+            stepId: meta.id,
+            stepName: meta.name || meta.title,
+            stepType: meta.type,
+            startedAt: intent.visit.startedAt,
+            endedAt: new Date().toISOString(),
+            exitReason: intent.reason,
+            stepContractVersion,
+            metadata: Object.assign(Object.assign({}, attributionMetadata), { step_contract_version: stepContractVersion }),
+            featureFlags: postHogFeatureFlagsRef.current,
+        });
+    }, [analytics, attributionReady, lifecycleEventsSuppressed, stepById, stepContractVersion]);
+    const claimActiveVisit = useCallback((stepId, outcome, options = {}) => {
+        const token = activeVisitTokenRef.current;
+        if (!token || token.stepId !== stepId) {
+            return false;
+        }
+        const safeOutcome = resolveNavigationOutcome(outcome, stepContractVersion);
+        if (!safeOutcome) {
+            return false;
+        }
+        if (isTerminalCompletion(stepById[stepId], safeOutcome)
+            && options.allowTerminalCompletion !== true) {
+            logger.warn('[FunnelFlow] Terminal completion must use completeFunnel().');
+            return false;
+        }
+        const intent = finishVisit(stepLifecycleStateRef.current, token.visitId, safeOutcome);
+        if (!intent) {
+            return false;
+        }
+        if (intent.type === 'exit') {
+            emitStepExit(intent);
+            return true;
+        }
+        recordStepCompletion(intent, Object.assign(Object.assign({}, (safeOutcome.type === 'complete' && safeOutcome.selected !== undefined
+            ? { explicitChoices: Object.assign({}, safeOutcome.selected) }
+            : {})), { metadata: options.metadata, omitSelected: options.omitSelected }));
+        return true;
+    }, [emitStepExit, recordStepCompletion, stepById, stepContractVersion]);
+    const claimCurrentVisit = useCallback((outcome) => {
+        const token = activeVisitTokenRef.current;
+        return token ? claimActiveVisit(token.stepId, outcome) : false;
+    }, [claimActiveVisit]);
+    const goToStep = useCallback((stepId, outcome) => {
+        const resolvedOutcome = resolveNavigationOutcome(outcome, stepContractVersion);
+        const targetStepId = resolveNavigationTarget(stepId);
+        if (!resolvedOutcome || !targetStepId) {
+            return;
+        }
+        if (isTerminalCompletion(stepById[renderedStepId], resolvedOutcome)) {
+            logger.warn('[FunnelFlow] Terminal completion navigation must use completeFunnel().');
+            return;
+        }
+        claimCurrentVisit(resolvedOutcome);
+        navigateToStep(targetStepId);
+    }, [
+        claimCurrentVisit,
+        navigateToStep,
+        renderedStepId,
+        resolveNavigationTarget,
+        stepById,
+        stepContractVersion,
+    ]);
+    const goNext = useCallback(() => {
+        goToStep(resolveNextStepId(renderedStepId, {
+            ignoreExperiment: Boolean(activeExperimentForStep && renderedStepId === safeActiveStepId),
+        }), { type: 'complete' });
+    }, [activeExperimentForStep, goToStep, renderedStepId, resolveNextStepId, safeActiveStepId]);
+    const submitEmailCapture = useCallback((email) => {
+        var _a, _b;
+        const submittedStepId = renderedStepId;
+        const submittedStepMeta = stepById[submittedStepId];
+        const submittedVisitId = (_b = (_a = activeVisitTokenRef.current) === null || _a === void 0 ? void 0 : _a.visitId) !== null && _b !== void 0 ? _b : null;
+        const submittedUserId = currentUserIdRef.current;
+        const navigateManifestTarget = (stepId) => {
+            if (!isFunnelStepId(stepId)) {
+                return;
+            }
+            const targetStepId = resolveNavigationTarget(stepId);
+            if (targetStepId) {
+                navigateToStep(targetStepId);
+            }
+        };
+        return submitEmailCapturePrimitive({
+            email,
+            isPreview: isPreviewRuntime,
+            singleFlight: emailCaptureSingleFlightRef.current,
+            retryPendingNavigation: () => {
+                var _a;
+                const pending = pendingEmailCaptureNavigationRef.current;
+                if (!pending) {
+                    return false;
+                }
+                if (pending.visitId !== ((_a = activeVisitTokenRef.current) === null || _a === void 0 ? void 0 : _a.visitId)
+                    || pending.stepId !== submittedStepId) {
+                    pendingEmailCaptureNavigationRef.current = null;
+                    return false;
+                }
+                navigateManifestTarget(pending.targetStepId);
+                pendingEmailCaptureNavigationRef.current = null;
+                return true;
+            },
+            persist: (normalizedEmail) => api.captureEmail({
+                userId: submittedUserId,
+                email: normalizedEmail,
+                environment: getRuntimeMode(),
+            }),
+            applyUser: (capturedUser) => {
+                currentUserIdRef.current = capturedUser.id;
+                setUser((prev) => (Object.assign(Object.assign(Object.assign({}, prev), capturedUser), { completedSteps: prev.completedSteps })));
+            },
+            applyPreviewEmail: (normalizedEmail) => {
+                setUser((prev) => (Object.assign(Object.assign({}, prev), { email: normalizedEmail })));
+            },
+            fanOutBrowserDestinations: (eventId) => {
+                var _a;
+                if (!submittedStepMeta) {
+                    return;
+                }
+                (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackEmailCapturedBrowserDestinations) === null || _a === void 0 ? void 0 : _a.call(analytics, {
+                    eventId,
+                    stepId: submittedStepMeta.id,
+                    stepName: submittedStepMeta.name || submittedStepMeta.title,
+                    stepType: submittedStepMeta.type,
+                });
+            },
+            completeVisit: () => {
+                var _a;
+                return (submittedVisitId !== null
+                    && ((_a = activeVisitTokenRef.current) === null || _a === void 0 ? void 0 : _a.visitId) === submittedVisitId
+                    && claimActiveVisit(submittedStepId, { type: 'complete' }));
+            },
+            resolveNextStep: () => {
+                const targetStepId = resolveNextStepId(submittedStepId, {
+                    ignoreExperiment: Boolean(activeExperimentForStep && submittedStepId === safeActiveStepId),
+                });
+                if (submittedVisitId !== null) {
+                    pendingEmailCaptureNavigationRef.current = {
+                        visitId: submittedVisitId,
+                        stepId: submittedStepId,
+                        targetStepId,
+                    };
+                }
+                return targetStepId;
+            },
+            navigate: (stepId) => {
+                navigateManifestTarget(stepId);
+                pendingEmailCaptureNavigationRef.current = null;
+            },
+        });
+    }, [
+        activeExperimentForStep,
+        api,
+        analytics,
+        claimActiveVisit,
+        isFunnelStepId,
+        isPreviewRuntime,
+        navigateToStep,
+        renderedStepId,
+        resolveNavigationTarget,
+        resolveNextStepId,
+        safeActiveStepId,
+        stepById,
+    ]);
+    useEffect(() => {
+        const abandonCurrentVisit = (event) => {
+            if (event.persisted) {
+                return;
+            }
+            claimCurrentVisit({ type: 'exit', reason: 'abandon' });
+        };
+        window.addEventListener('pagehide', abandonCurrentVisit);
+        return () => window.removeEventListener('pagehide', abandonCurrentVisit);
+    }, [claimCurrentVisit]);
     const completeStep = useCallback((stepId, choices) => {
-        recordStepCompletion(stepId, choices);
-    }, [recordStepCompletion]);
+        if (!enforceChoiceBypassGuard({
+            operation: 'completeStep',
+            activeStepId: renderedStepId,
+            sourceStepId: stepId,
+            stepById,
+            stepContractVersion,
+            environment: choiceGuardEnvironment,
+            reportDiagnostic: reportChoiceDiagnostic,
+        })) {
+            return;
+        }
+        claimActiveVisit(stepId, Object.assign({ type: 'complete' }, (choices === undefined ? {} : { selected: choices })));
+    }, [
+        choiceGuardEnvironment,
+        claimActiveVisit,
+        renderedStepId,
+        reportChoiceDiagnostic,
+        stepById,
+        stepContractVersion,
+    ]);
+    const completeFunnel = useCallback((stepId) => {
+        var _a, _b;
+        const stepMeta = stepById[stepId];
+        if (!stepMeta
+            || ((_a = FUNNEL_STEP_CONTRACTS[stepMeta.type]) === null || _a === void 0 ? void 0 : _a.terminal) !== true) {
+            return;
+        }
+        const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+        if (attributionMetadata === null
+            || !claimActiveVisit(stepId, { type: 'complete' }, { allowTerminalCompletion: true })) {
+            return;
+        }
+        const alreadyCompletedThisRun = funnelCompletionClaimedRef.current;
+        funnelCompletionClaimedRef.current = true;
+        if (lifecycleEventsSuppressed || alreadyCompletedThisRun) {
+            return;
+        }
+        const occurredAt = new Date().toISOString();
+        try {
+            (_b = analytics === null || analytics === void 0 ? void 0 : analytics.trackFunnelCompleted) === null || _b === void 0 ? void 0 : _b.call(analytics, {
+                userId: currentUserIdRef.current,
+                environment: getRuntimeMode(),
+                stepId: stepMeta.id,
+                stepName: stepMeta.name || stepMeta.title,
+                stepType: stepMeta.type,
+                stepContractVersion,
+                occurredAt,
+                metadata: Object.assign(Object.assign({}, attributionMetadata), { step_contract_version: stepContractVersion }),
+                featureFlags: postHogFeatureFlagsRef.current,
+            });
+        }
+        catch (error) {
+            logger.error('Failed to track funnel completion:', error);
+        }
+        if (!(analytics === null || analytics === void 0 ? void 0 : analytics.flush)) {
+            return;
+        }
+        try {
+            const flushResult = analytics.flush();
+            void Promise.resolve(flushResult).catch((error) => {
+                logger.error('Failed to flush funnel completion:', error);
+            });
+        }
+        catch (error) {
+            logger.error('Failed to flush funnel completion:', error);
+        }
+    }, [
+        analytics,
+        attributionReady,
+        claimActiveVisit,
+        lifecycleEventsSuppressed,
+        stepById,
+        stepContractVersion,
+    ]);
+    const commitChoiceCompletion = useCallback((stepMeta, result) => {
+        runAtomicChoiceCommit({
+            activeStepId: renderedStepId,
+            activeStepMeta: renderedStepMeta,
+            stepMeta,
+            result,
+            environment: choiceGuardEnvironment,
+            getAttributes: () => attributesRef.current,
+            writeAttributes: (nextAttributes) => {
+                attributesRef.current = nextAttributes;
+                setAttributes(nextAttributes);
+            },
+            isInFlight: () => choiceCommitInFlightRef.current === renderedStepId,
+            beginCommit: () => {
+                choiceCommitInFlightRef.current = renderedStepId;
+            },
+            cancelCommit: () => {
+                choiceCommitInFlightRef.current = null;
+            },
+            recordCompletion: (completion) => {
+                let claimed;
+                try {
+                    claimed = claimActiveVisit(renderedStepId, Object.assign({ type: 'complete' }, (completion.selected === undefined ? {} : { selected: completion.selected })), {
+                        metadata: completion.metadata,
+                        omitSelected: completion.selected === undefined,
+                    });
+                }
+                catch (error) {
+                    choiceNavigationRetryRef.current = renderedStepId;
+                    throw error;
+                }
+                if (claimed) {
+                    choiceNavigationRetryRef.current = null;
+                }
+                return claimed || choiceNavigationRetryRef.current === renderedStepId;
+            },
+            markCompletedBeforeNavigation: () => {
+                choiceCompletionMarkerRef.current = renderedStepId;
+            },
+            clearCompletedBeforeNavigation: (markerWasInstalled) => {
+                if (markerWasInstalled) {
+                    choiceNavigationRetryRef.current = renderedStepId;
+                }
+                if (choiceCompletionMarkerRef.current === renderedStepId) {
+                    choiceCompletionMarkerRef.current = null;
+                }
+            },
+            resolveNext: (proposedAttributes) => resolveNextStepId(renderedStepId, {
+                attributes: proposedAttributes,
+                ignoreExperiment: Boolean(activeExperimentForStep && renderedStepId === safeActiveStepId),
+            }),
+            navigate: (stepId) => goToStep(stepId, { type: 'complete' }),
+            reportDiagnostic: reportChoiceDiagnostic,
+        });
+    }, [
+        activeExperimentForStep,
+        choiceGuardEnvironment,
+        goToStep,
+        claimActiveVisit,
+        renderedStepId,
+        renderedStepMeta,
+        reportChoiceDiagnostic,
+        resolveNextStepId,
+        safeActiveStepId,
+    ]);
     useEffect(() => {
         var _a, _b, _c;
         if (safeActiveStepId !== activeStepId) {
             logger.warn(`[FunnelFlow] Unknown or non-renderable step "${activeStepId}", falling back to "${safeActiveStepId}".`);
+            claimCurrentVisit({ type: 'exit', reason: 'replace' });
             setActiveStepId(safeActiveStepId);
             return;
         }
@@ -397,14 +983,32 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             return;
         }
         if (prevId && prevId !== renderedStepId) {
-            recordStepCompletion(prevId);
+            const marker = consumeChoiceCompletionMarker(choiceCompletionMarkerRef.current, prevId);
+            choiceCompletionMarkerRef.current = marker.nextMarker;
+            if (marker.consumed) {
+                choiceCommitInFlightRef.current = null;
+                choiceNavigationRetryRef.current = null;
+            }
         }
         const startedAt = new Date().toISOString();
-        const stepName = (renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.name) || (renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.title) || renderedStepId;
-        const stepType = renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.type;
-        stepStartedAtByIdRef.current[renderedStepId] = startedAt;
+        const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+        if (attributionMetadata === null || !renderedStepMeta) {
+            return;
+        }
+        const startIntent = startVisit(stepLifecycleStateRef.current, { stepId: renderedStepId, startedAt });
+        if (!startIntent) {
+            return;
+        }
+        activeVisitTokenRef.current = {
+            visitId: startIntent.visit.visitId,
+            stepId: renderedStepId,
+        };
+        const stepName = renderedStepMeta.name || renderedStepMeta.title;
+        const stepType = renderedStepMeta.type;
         const analyticsRuntimeMode = getRuntimeMode();
-        if (!isPreviewRuntime) {
+        attributesAtStepStart.current = Object.assign({}, attributesRef.current);
+        prevStepIdRef.current = renderedStepId;
+        if (!lifecycleEventsSuppressed) {
             (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackStepStarted) === null || _a === void 0 ? void 0 : _a.call(analytics, {
                 userId: currentUserIdRef.current,
                 environment: analyticsRuntimeMode,
@@ -412,48 +1016,122 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
                 stepName,
                 stepType,
                 startedAt,
+                stepContractVersion,
+                metadata: Object.assign(Object.assign({}, attributionMetadata), { step_contract_version: stepContractVersion }),
                 featureFlags: postHogFeatureFlagsRef.current,
             });
-            if (!firstStepViewedTrackedRef.current && safeActiveStepId === defaultStepId) {
-                firstStepViewedTrackedRef.current = true;
-                (_b = analytics === null || analytics === void 0 ? void 0 : analytics.trackFunnelStarted) === null || _b === void 0 ? void 0 : _b.call(analytics, {
-                    userId: currentUserIdRef.current,
-                    environment: analyticsRuntimeMode,
-                    stepId: renderedStepId,
-                    stepName,
-                    stepType,
-                    occurredAt: startedAt,
-                    featureFlags: postHogFeatureFlagsRef.current,
-                });
-                (_c = analytics === null || analytics === void 0 ? void 0 : analytics.trackFirstStepViewed) === null || _c === void 0 ? void 0 : _c.call(analytics, {
+            if (safeActiveStepId === defaultStepId) {
+                const initialAttribution = takeInitialFunnelAttributionMetadata(funnelStartedTrackedRef.current, attributionReady, initialAttributionRef.current);
+                funnelStartedTrackedRef.current = initialAttribution.tracked;
+                if (initialAttribution.metadata) {
+                    (_b = analytics === null || analytics === void 0 ? void 0 : analytics.trackFunnelStarted) === null || _b === void 0 ? void 0 : _b.call(analytics, {
+                        userId: currentUserIdRef.current,
+                        environment: analyticsRuntimeMode,
+                        stepId: renderedStepId,
+                        stepName,
+                        stepType,
+                        stepContractVersion,
+                        occurredAt: startedAt,
+                        metadata: initialAttribution.metadata,
+                        featureFlags: postHogFeatureFlagsRef.current,
+                    });
+                }
+                if (firstStepViewedVisitRef.current !== startIntent.visit.visitId) {
+                    firstStepViewedVisitRef.current = startIntent.visit.visitId;
+                    (_c = analytics === null || analytics === void 0 ? void 0 : analytics.trackFirstStepViewed) === null || _c === void 0 ? void 0 : _c.call(analytics, {
+                        userId: currentUserIdRef.current,
+                        environment: analyticsRuntimeMode,
+                        stepId: renderedStepId,
+                        stepName,
+                        stepType,
+                        stepContractVersion,
+                        occurredAt: startedAt,
+                        metadata: attributionMetadata,
+                        featureFlags: postHogFeatureFlagsRef.current,
+                    });
+                }
+            }
+        }
+    }, [
+        activeStepId,
+        analytics,
+        attributionReady,
+        claimCurrentVisit,
+        defaultStepId,
+        isPreviewRuntime,
+        lifecycleEventsSuppressed,
+        renderSuspended,
+        renderedStepId,
+        renderedStepMeta,
+        safeActiveStepId,
+        stepContractVersion,
+    ]);
+    useEffect(() => {
+        if (lifecycleEventsSuppressed
+            || renderSuspended
+            || safeActiveStepId !== defaultStepId
+            || !renderedStepMeta) {
+            return;
+        }
+        const visit = activeVisitTokenRef.current;
+        if (!visit || visit.stepId !== renderedStepId) {
+            return;
+        }
+        const handleFirstStepClick = () => {
+            var _a;
+            const activeVisit = activeVisitTokenRef.current;
+            if (!activeVisit
+                || activeVisit.visitId !== visit.visitId
+                || activeVisit.stepId !== renderedStepId
+                || firstStepClickedVisitRef.current === visit.visitId) {
+                return;
+            }
+            const attributionMetadata = buildReadyFunnelAttributionEventMetadata(attributionReady, initialAttributionRef.current);
+            if (attributionMetadata === null) {
+                return;
+            }
+            firstStepClickedVisitRef.current = visit.visitId;
+            try {
+                (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackFirstStepClicked) === null || _a === void 0 ? void 0 : _a.call(analytics, {
                     userId: currentUserIdRef.current,
-                    environment: analyticsRuntimeMode,
+                    environment: getRuntimeMode(),
                     stepId: renderedStepId,
-                    stepName,
-                    stepType,
-                    occurredAt: startedAt,
+                    stepName: renderedStepMeta.name || renderedStepMeta.title,
+                    stepType: renderedStepMeta.type,
+                    stepContractVersion,
+                    occurredAt: new Date().toISOString(),
+                    metadata: Object.assign(Object.assign({}, attributionMetadata), { step_contract_version: stepContractVersion }),
                     featureFlags: postHogFeatureFlagsRef.current,
                 });
             }
-        }
-        attributesAtStepStart.current = Object.assign({}, attributesRef.current);
-        prevStepIdRef.current = renderedStepId;
+            catch (error) {
+                logger.error('Failed to track first step click:', error);
+            }
+        };
+        window.addEventListener('click', handleFirstStepClick, true);
+        return () => window.removeEventListener('click', handleFirstStepClick, true);
     }, [
-        activeStepId,
         analytics,
+        attributionReady,
         defaultStepId,
-        isPreviewRuntime,
-        recordStepCompletion,
+        lifecycleEventsSuppressed,
         renderSuspended,
         renderedStepId,
-        renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.name,
-        renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.title,
-        renderedStepMeta === null || renderedStepMeta === void 0 ? void 0 : renderedStepMeta.type,
+        renderedStepMeta,
         safeActiveStepId,
+        stepContractVersion,
     ]);
     useEffect(() => {
+        if (appliedInitialStepIdRef.current === safeInitialStepId) {
+            return;
+        }
+        appliedInitialStepIdRef.current = safeInitialStepId;
+        if (safeActiveStepId === safeInitialStepId) {
+            return;
+        }
+        claimCurrentVisit({ type: 'exit', reason: 'replace' });
         setActiveStepId(safeInitialStepId);
-    }, [safeInitialStepId]);
+    }, [claimCurrentVisit, safeActiveStepId, safeInitialStepId]);
     useEffect(() => {
         setEditorModeEnabled(isEditorEnabled());
     }, [safeActiveStepId]);
@@ -464,18 +1142,34 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
     }, [editorModeEnabled]);
     useEffect(() => {
         if (shouldLockToInitialStep) {
-            setActiveStepId(safeInitialStepId);
+            if (safeActiveStepId !== safeInitialStepId) {
+                claimCurrentVisit({ type: 'exit', reason: 'replace' });
+                setActiveStepId(safeInitialStepId);
+            }
             return;
         }
         const syncStepWithPath = () => {
             var _a;
             const resolvedPathStep = getStepIdFromPath(window.location.pathname);
             const resolvedStep = (_a = resolveRenderableStepId(resolvedPathStep)) !== null && _a !== void 0 ? _a : safeInitialStepId;
-            setActiveStepId(resolvedStep);
+            const targetStepId = resolveNavigationTarget(resolvedStep);
+            if (!targetStepId) {
+                return;
+            }
+            claimCurrentVisit({ type: 'exit', reason: 'back' });
+            setActiveStepId(targetStepId);
         };
         window.addEventListener('popstate', syncStepWithPath);
         return () => window.removeEventListener('popstate', syncStepWithPath);
-    }, [getStepIdFromPath, resolveRenderableStepId, safeInitialStepId, shouldLockToInitialStep]);
+    }, [
+        claimCurrentVisit,
+        getStepIdFromPath,
+        resolveNavigationTarget,
+        resolveRenderableStepId,
+        safeActiveStepId,
+        safeInitialStepId,
+        shouldLockToInitialStep,
+    ]);
     const nextStepId = useMemo(() => resolveNextStepFromContext({
         stepId: renderedStepId,
         attributes,
@@ -511,7 +1205,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             ignoreExperiment: Boolean(activeExperimentForStep && renderedStepId === safeActiveStepId),
         });
         const timer = window.setTimeout(() => {
-            goToStep(autoAdvanceTarget);
+            goToStep(autoAdvanceTarget, { type: 'complete' });
         }, autoAdvanceMs);
         return () => window.clearTimeout(timer);
     }, [
@@ -525,25 +1219,53 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         shouldLockToInitialStep,
     ]);
     const handleContinue = useCallback(() => {
-        goToStep(nextStepId);
+        goToStep(nextStepId, { type: 'complete' });
     }, [goToStep, nextStepId]);
-    const goToStepFromContext = useCallback((stepId) => {
+    const goToStepFromContext = useCallback((stepId, outcome) => {
         if (!isFunnelStepId(stepId)) {
             return;
         }
-        goToStep(stepId);
+        goToStep(stepId, outcome);
     }, [goToStep, isFunnelStepId]);
     const goChoice = useCallback((choice, stepId) => {
         var _a, _b;
         const sourceStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : renderedStepId;
-        setAttributes((prev) => writeStepChoice(prev, sourceStepId, choice));
+        const guardSourceStepId = stepId && stepById[stepId] ? stepId : sourceStepId;
+        if (!enforceChoiceBypassGuard({
+            operation: 'goChoice',
+            activeStepId: renderedStepId,
+            sourceStepId: guardSourceStepId,
+            stepById,
+            stepContractVersion,
+            environment: choiceGuardEnvironment,
+            reportDiagnostic: reportChoiceDiagnostic,
+        })) {
+            return;
+        }
+        const nextAttributes = writeStepChoice(attributesRef.current, sourceStepId, choice);
+        attributesRef.current = nextAttributes;
+        setAttributes(nextAttributes);
         const sourceChoiceTargets = getChoiceTargetsForStep(sourceStepId);
         const choiceTarget = (_b = resolveRenderableStepId(sourceChoiceTargets === null || sourceChoiceTargets === void 0 ? void 0 : sourceChoiceTargets[choice])) !== null && _b !== void 0 ? _b : resolveNextStepId(sourceStepId);
-        goToStep(choiceTarget);
-    }, [getChoiceTargetsForStep, goToStep, renderedStepId, resolveNextStepId, resolveRenderableStepId]);
+        goToStep(choiceTarget, { type: 'complete' });
+    }, [
+        choiceGuardEnvironment,
+        getChoiceTargetsForStep,
+        goToStep,
+        renderedStepId,
+        reportChoiceDiagnostic,
+        resolveNextStepId,
+        resolveRenderableStepId,
+        stepById,
+        stepContractVersion,
+    ]);
     usePreviewBridge({
         activeStepId: safeActiveStepId,
-        onGoToStep: goToStepFromContext,
+        onGoToStep: (stepId) => {
+            if (isFunnelStepId(stepId)) {
+                goToStep(stepId, { type: 'exit', reason: 'replace' });
+            }
+        },
         resolveRenderableStepId,
         setRuntimeMode,
         shouldLockToInitialStep,
@@ -554,11 +1276,12 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
             return;
         }
         const selectedVariant = experiment.variants.find((variant) => variant.variantKey === nextVariantKey);
-        if (!selectedVariant) {
+        if (!selectedVariant || selectedVariant.routeToStepId === renderedStepId) {
             return;
         }
+        claimCurrentVisit({ type: 'exit', reason: 'replace' });
         setEditorVariantOverrides((prev) => (Object.assign(Object.assign({}, prev), { [experiment.experimentId]: selectedVariant.variantKey })));
-    }, []);
+    }, [claimCurrentVisit, renderedStepId]);
     const experimentAssignmentForEditor = useCallback((experiment) => {
         var _a;
         const override = editorVariantOverrides[experiment.experimentId];
@@ -583,30 +1306,40 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         }
         return ((_a = experiment.variants[0]) === null || _a === void 0 ? void 0 : _a.variantKey) || '';
     }, [editorVariantOverrides, postHogReady]);
-    const contextValue = useMemo(() => ({
-        activeStepId: renderedStepId,
-        featureFlags: postHogFeatureFlags,
-        isBuilder: isPreviewRuntime,
-        goToStep: goToStepFromContext,
-        goNext,
-        goChoice,
-        getChoiceTargets: (stepId) => {
-            var _a;
-            const sourceStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : renderedStepId;
-            return getChoiceTargetsForStep(sourceStepId);
-        },
-        setAnswer,
-        getAnswer,
-        answers: attributes,
-        setAttribute,
-        attributes,
-        user,
-        userBootstrapped,
-        setUser,
-        completeStep,
-    }), [
+    const contextValue = useMemo(() => {
+        const value = {
+            activeStepId: renderedStepId,
+            featureFlags: postHogFeatureFlags,
+            isBuilder: isPreviewRuntime,
+            goToStep: goToStepFromContext,
+            goNext,
+            goChoice,
+            getChoiceTargets: (stepId) => {
+                var _a;
+                const sourceStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : renderedStepId;
+                return getChoiceTargetsForStep(sourceStepId);
+            },
+            setAnswer,
+            getAnswer,
+            answers: attributes,
+            setAttribute,
+            attributes,
+            user,
+            userBootstrapped,
+            setUser,
+            submitEmailCapture,
+            completeStep,
+            completeFunnel,
+        };
+        // The WeakMap stores callback identity only; it never reads captured refs during render.
+        // eslint-disable-next-line react-hooks/refs
+        registerInternalChoiceCommit(value, commitChoiceCompletion);
+        return value;
+    }, [
         attributes,
         completeStep,
+        completeFunnel,
+        commitChoiceCompletion,
         getAnswer,
         getChoiceTargetsForStep,
         goChoice,
@@ -618,6 +1351,7 @@ export function useFunnelFlowController({ analytics, initialStepId, initialAttri
         resolveRenderableStepId,
         setAnswer,
         setAttribute,
+        submitEmailCapture,
         user,
         userBootstrapped,
     ]);