@funnelsgrove/runtime 0.1.0

package/dist/runtime/use-funnel-flow-controller.d.ts

@@ -0,0 +1,58 @@
+import { type Dispatch, type SetStateAction, type ComponentType } from 'react';
+import type { FunnelContextValue } from '../components/FunnelContext';
+import type { FunnelManifestExperiment } from '../config/funnel.manifest.types';
+import type { FunnelStepMeta } from '../steps/types';
+export type FunnelFlowControllerExperiment<StepId extends string> = FunnelManifestExperiment & {
+    stepId: StepId;
+    variants: readonly (FunnelManifestExperiment['variants'][number] & {
+        routeToStepId: StepId;
+    })[];
+};
+type UseFunnelFlowControllerInput<StepId extends string> = {
+    initialStepId?: StepId;
+    lockToInitialStep?: boolean;
+    defaultStepId: StepId;
+    stepSequence: readonly StepId[];
+    stepById: Record<string, FunnelStepMeta>;
+    stepComponentById: Record<string, ComponentType>;
+    funnelExperiments: readonly FunnelFlowControllerExperiment<StepId>[];
+    getPathForStep: (stepId: StepId) => string;
+    getStepIdFromPath: (pathname: string) => StepId | null;
+    getSequentialNextStepId: (stepId: StepId) => StepId | null;
+    getChoiceTargetsForStep: (stepId: StepId) => {
+        yes?: StepId;
+        no?: StepId;
+    } | null;
+    isFunnelStepId: (value: string) => value is StepId;
+    resolveConfiguredNextStep: (stepId: StepId, context: {
+        attributes: Record<string, unknown>;
+        userId: string;
+        getAssignedVariantId: (experiment: FunnelManifestExperiment) => string | null;
+    }) => StepId | null;
+    resolveRuntimeInitialStepId: (input: {
+        requestedStepId?: string | null;
+        entryPointId?: string | null;
+    }) => StepId;
+};
+type UseFunnelFlowControllerResult<StepId extends string> = {
+    activeStepComponent: ComponentType | undefined;
+    activeStepId: StepId;
+    activeStepMeta: FunnelStepMeta | undefined;
+    buttonText: string;
+    buttonVariant: 'muted' | null;
+    contextValue: FunnelContextValue;
+    editorModeEnabled: boolean;
+    editorPanelExpanded: boolean;
+    experimentAssignmentForEditor: (experiment: FunnelFlowControllerExperiment<StepId>) => string;
+    funnelExperiments: readonly FunnelFlowControllerExperiment<StepId>[];
+    handleContinue: () => void;
+    renderedStepId: StepId;
+    renderedStepMeta: FunnelStepMeta | undefined;
+    runtimeMode: 'test' | 'live';
+    setEditorPanelExpanded: Dispatch<SetStateAction<boolean>>;
+    setEditorVariantSelection: (experiment: FunnelFlowControllerExperiment<StepId>, variantId: string) => void;
+    setRuntimeMode: (mode: 'test' | 'live') => void;
+    showShellContinue: boolean;
+};
+export declare function useFunnelFlowController<StepId extends string>({ initialStepId, lockToInitialStep, defaultStepId, stepSequence, stepById, stepComponentById, funnelExperiments, getPathForStep, getStepIdFromPath, getSequentialNextStepId, getChoiceTargetsForStep, isFunnelStepId, resolveConfiguredNextStep, resolveRuntimeInitialStepId, }: UseFunnelFlowControllerInput<StepId>): UseFunnelFlowControllerResult<StepId>;
+export {};

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

@@ -0,0 +1,523 @@
+'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';
+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 shouldLockToInitialStep = lockToInitialStep || isPreviewStepLockRequested();
+    const isPreviewRuntime = useMemo(() => isPreviewFrameRuntime(), []);
+    const experimentAssignmentStorage = useMemo(() => ({
+        read: readWindowStorageValue,
+        write: writeWindowStorageValue,
+    }), []);
+    const resolveRenderableStepId = useCallback((stepId) => {
+        if (!stepId || !isFunnelStepId(stepId)) {
+            return null;
+        }
+        if (!stepById[stepId] || !stepComponentById[stepId]) {
+            return null;
+        }
+        return stepId;
+    }, [isFunnelStepId, stepById, stepComponentById]);
+    const resolveFallbackStepId = useCallback((preferredStepId) => {
+        const preferred = resolveRenderableStepId(preferredStepId);
+        if (preferred) {
+            return preferred;
+        }
+        for (const candidate of stepSequence) {
+            const resolved = resolveRenderableStepId(candidate);
+            if (resolved) {
+                return resolved;
+            }
+        }
+        const fromRegistry = resolveRenderableStepId(Object.keys(stepComponentById)[0] || null);
+        return fromRegistry !== null && fromRegistry !== void 0 ? fromRegistry : defaultStepId;
+    }, [defaultStepId, resolveRenderableStepId, stepComponentById, stepSequence]);
+    const safeInitialStepId = useMemo(() => {
+        const requestedStepId = resolveRuntimeInitialStepId({
+            requestedStepId: initialStepId,
+            entryPointId: getRequestedEntryPointId(),
+        });
+        return resolveFallbackStepId(requestedStepId);
+    }, [initialStepId, resolveFallbackStepId, resolveRuntimeInitialStepId]);
+    const [activeStepId, setActiveStepId] = useState(safeInitialStepId);
+    const [attributes, setAttributes] = useState({});
+    const [user, setUser] = useState(() => ({
+        id: apiService.getOrCreateClientUserId(),
+        name: '',
+        email: '',
+        attributes: {},
+        completedSteps: [],
+    }));
+    const attributesAtStepStart = useRef({});
+    const attributesRef = useRef(attributes);
+    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 renderedStepId = useMemo(() => {
+        const activeExperiment = funnelExperiments.find((experiment) => experiment.status === 'active' && experiment.stepId === safeActiveStepId);
+        if (!activeExperiment) {
+            return safeActiveStepId;
+        }
+        const assignedVariantId = getAssignedVariantId(activeExperiment, user.id, experimentAssignmentStorage);
+        if (!assignedVariantId) {
+            return safeActiveStepId;
+        }
+        const assignedVariant = activeExperiment.variants.find((variant) => variant.id === assignedVariantId);
+        const variantStepId = resolveRenderableStepId((assignedVariant === null || assignedVariant === void 0 ? void 0 : assignedVariant.routeToStepId) || null);
+        return variantStepId !== null && variantStepId !== void 0 ? variantStepId : safeActiveStepId;
+    }, [experimentAssignmentStorage, funnelExperiments, resolveRenderableStepId, safeActiveStepId, user.id]);
+    const renderedStepMeta = stepById[renderedStepId];
+    const activeStepComponent = stepComponentById[renderedStepId];
+    const goToStep = useCallback((stepId) => {
+        var _a;
+        if (shouldLockToInitialStep) {
+            return;
+        }
+        const safeStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : safeInitialStepId;
+        const stepPath = getPathForStep(safeStepId);
+        const nextLocation = buildHostedStepLocation({
+            currentHref: window.location.href,
+            stepPath,
+            stepId: safeStepId,
+        });
+        const currentLocation = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+        if (currentLocation !== nextLocation) {
+            if (isPreviewFrameRuntime()) {
+                window.history.replaceState({ stepId: safeStepId }, '', nextLocation);
+            }
+            else {
+                window.history.pushState({ stepId: safeStepId }, '', nextLocation);
+            }
+        }
+        setActiveStepId(safeStepId);
+    }, [getPathForStep, resolveRenderableStepId, safeInitialStepId, shouldLockToInitialStep]);
+    const setAnswer = useCallback((key, value) => {
+        setAttributes((prev) => (Object.assign(Object.assign({}, prev), { [key]: value })));
+    }, []);
+    const getAnswer = useCallback((key) => {
+        return attributesRef.current[key];
+    }, []);
+    const setAttribute = useCallback((key, value) => {
+        setAttributes((prev) => (Object.assign(Object.assign({}, prev), { [key]: value })));
+    }, []);
+    useEffect(() => {
+        currentUserIdRef.current = user.id;
+    }, [user.id]);
+    useEffect(() => {
+        attributesRef.current = attributes;
+    }, [attributes]);
+    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),
+        });
+    }, [
+        experimentAssignmentStorage,
+        getSequentialNextStepId,
+        resolveConfiguredNextStep,
+        resolveRenderableStepId,
+        safeInitialStepId,
+        user.id,
+    ]);
+    const goNext = useCallback(() => {
+        goToStep(resolveNextStepId(safeActiveStepId));
+    }, [goToStep, resolveNextStepId, safeActiveStepId]);
+    useEffect(() => {
+        const localUserId = apiService.getOrCreateClientUserId();
+        setUser((prev) => (Object.assign(Object.assign({}, prev), { id: localUserId })));
+        if (isPreviewRuntime) {
+            return;
+        }
+        apiService
+            .bootstrapSession({
+            userId: localUserId,
+        })
+            .then((sessionUser) => {
+            const sessionAttributes = Object.keys(sessionUser.attributes || {}).length > 0
+                ? sessionUser.attributes
+                : null;
+            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 })));
+        })
+            .catch((error) => {
+            logger.error('Failed to bootstrap user session:', error);
+        });
+    }, [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;
+            }
+            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;
+        });
+        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]);
+    const recordStepCompletion = useCallback((stepId, explicitChoices) => {
+        const meta = stepById[stepId];
+        if (!meta) {
+            return;
+        }
+        let choices;
+        if (explicitChoices) {
+            choices = explicitChoices;
+        }
+        else {
+            const snapshot = attributesAtStepStart.current;
+            choices = {};
+            for (const [key, value] of Object.entries(attributesRef.current)) {
+                if (snapshot[key] !== value) {
+                    choices[key] = value;
+                }
+            }
+        }
+        const record = {
+            stepId: meta.id,
+            stepName: meta.name || meta.title,
+            completedAt: new Date().toISOString(),
+            choices,
+        };
+        const startedAt = stepStartedAtByIdRef.current[meta.id] || record.completedAt;
+        dispatchWindowCustomEvent('funnel:step-completed', record);
+        if (!isPreviewRuntime) {
+            apiService.trackStepCompleted({
+                userId: currentUserIdRef.current,
+                stepId: record.stepId,
+                stepName: record.stepName,
+                startedAt,
+                endedAt: record.completedAt,
+                selected: record.choices,
+            });
+        }
+        setUser((prev) => {
+            var _a;
+            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 });
+            if (!isPreviewRuntime) {
+                apiService
+                    .updateUser({
+                    id: updatedUser.id,
+                    name: updatedUser.name,
+                    email: updatedUser.email,
+                    attributes: Object.assign(Object.assign({}, updatedUser.attributes), { completedSteps: updatedSteps }),
+                })
+                    .catch((error) => {
+                    logger.error('Failed to persist step completion:', error);
+                });
+            }
+            return updatedUser;
+        });
+    }, [isPreviewRuntime, stepById]);
+    const completeStep = useCallback((stepId, choices) => {
+        recordStepCompletion(stepId, choices);
+    }, [recordStepCompletion]);
+    useEffect(() => {
+        if (safeActiveStepId !== activeStepId) {
+            logger.warn(`[FunnelFlow] Unknown or non-renderable step "${activeStepId}", falling back to "${safeActiveStepId}".`);
+            setActiveStepId(safeActiveStepId);
+            return;
+        }
+        const prevId = prevStepIdRef.current;
+        if (prevId && prevId !== safeActiveStepId) {
+            recordStepCompletion(prevId);
+        }
+        const startedAt = new Date().toISOString();
+        stepStartedAtByIdRef.current[safeActiveStepId] = startedAt;
+        if (!isPreviewRuntime) {
+            apiService.trackStepStarted({
+                userId: currentUserIdRef.current,
+                stepId: safeActiveStepId,
+                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,
+                    },
+                });
+            }
+        }
+        attributesAtStepStart.current = Object.assign({}, attributesRef.current);
+        prevStepIdRef.current = safeActiveStepId;
+    }, [
+        activeStepId,
+        activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.name,
+        activeStepMeta === null || activeStepMeta === void 0 ? void 0 : activeStepMeta.title,
+        experimentAssignmentStorage,
+        funnelExperiments,
+        isPreviewRuntime,
+        recordStepCompletion,
+        safeActiveStepId,
+    ]);
+    useEffect(() => {
+        setActiveStepId(safeInitialStepId);
+    }, [safeInitialStepId]);
+    useEffect(() => {
+        setEditorModeEnabled(isEditorEnabled());
+    }, [safeActiveStepId]);
+    useEffect(() => {
+        if (!editorModeEnabled) {
+            setEditorPanelExpanded(false);
+        }
+    }, [editorModeEnabled]);
+    useEffect(() => {
+        if (shouldLockToInitialStep) {
+            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);
+        };
+        window.addEventListener('popstate', syncStepWithPath);
+        return () => window.removeEventListener('popstate', syncStepWithPath);
+    }, [getStepIdFromPath, resolveRenderableStepId, safeInitialStepId, shouldLockToInitialStep]);
+    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),
+    }), [
+        attributes,
+        experimentAssignmentStorage,
+        getSequentialNextStepId,
+        resolveConfiguredNextStep,
+        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;
+    const isAutoAdvanceStep = typeof (actionBar === null || actionBar === void 0 ? void 0 : actionBar.autoAdvanceMs) === 'number';
+    const autoAdvanceMs = actionBar === null || actionBar === void 0 ? void 0 : actionBar.autoAdvanceMs;
+    const buttonVariant = (_b = actionBar === null || actionBar === void 0 ? void 0 : actionBar.buttonVariant) !== null && _b !== void 0 ? _b : null;
+    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) {
+            return;
+        }
+        const autoAdvanceTarget = resolveNextStepId(safeActiveStepId);
+        const timer = window.setTimeout(() => {
+            goToStep(autoAdvanceTarget);
+        }, autoAdvanceMs);
+        return () => window.clearTimeout(timer);
+    }, [autoAdvanceMs, goToStep, resolveNextStepId, safeActiveStepId, shouldLockToInitialStep]);
+    const handleContinue = useCallback(() => {
+        goToStep(nextStepId);
+    }, [goToStep, nextStepId]);
+    const goToStepFromContext = useCallback((stepId) => {
+        if (!isFunnelStepId(stepId)) {
+            return;
+        }
+        goToStep(stepId);
+    }, [goToStep, isFunnelStepId]);
+    const goChoice = useCallback((choice, stepId) => {
+        var _a, _b;
+        const sourceStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : safeActiveStepId;
+        setAttributes((prev) => writeStepChoice(prev, sourceStepId, choice));
+        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, resolveNextStepId, resolveRenderableStepId, safeActiveStepId]);
+    usePreviewBridge({
+        activeStepId: safeActiveStepId,
+        onGoToStep: goToStepFromContext,
+        resolveRenderableStepId,
+        setRuntimeMode,
+        shouldLockToInitialStep,
+    });
+    const setEditorVariantSelection = useCallback((experiment, variantId) => {
+        const nextVariantId = variantId.trim();
+        if (!nextVariantId) {
+            return;
+        }
+        const selectedVariant = experiment.variants.find((variant) => variant.id === nextVariantId);
+        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]);
+    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 contextValue = useMemo(() => ({
+        activeStepId: safeActiveStepId,
+        goToStep: goToStepFromContext,
+        goNext,
+        goChoice,
+        getChoiceTargets: (stepId) => {
+            var _a;
+            const sourceStepId = (_a = resolveRenderableStepId(stepId)) !== null && _a !== void 0 ? _a : safeActiveStepId;
+            return getChoiceTargetsForStep(sourceStepId);
+        },
+        setAnswer,
+        getAnswer,
+        answers: attributes,
+        setAttribute,
+        attributes,
+        user,
+        setUser,
+        completeStep,
+    }), [
+        attributes,
+        completeStep,
+        getAnswer,
+        getChoiceTargetsForStep,
+        goChoice,
+        goNext,
+        goToStepFromContext,
+        resolveRenderableStepId,
+        safeActiveStepId,
+        setAnswer,
+        setAttribute,
+        user,
+    ]);
+    return {
+        activeStepComponent,
+        activeStepId: safeActiveStepId,
+        activeStepMeta,
+        buttonText,
+        buttonVariant,
+        contextValue,
+        editorModeEnabled,
+        editorPanelExpanded,
+        experimentAssignmentForEditor,
+        funnelExperiments,
+        handleContinue,
+        renderedStepId,
+        renderedStepMeta,
+        runtimeMode,
+        setEditorPanelExpanded,
+        setEditorVariantSelection,
+        setRuntimeMode,
+        showShellContinue: !hideActionBar && !isAutoAdvanceStep && !choiceTargets,
+    };
+}

package/dist/sdk/userAnswers.d.ts

@@ -0,0 +1,45 @@
+import type { FunnelStepId } from '../runtime/funnel-runtime';
+export type FunnelBinaryChoice = 'yes' | 'no';
+export type FunnelBirthDate = {
+    year: number;
+    month: number;
+    day: number;
+};
+export type FunnelTempUpload = {
+    key: string;
+    publicUrl: string;
+    contentType: string;
+    sizeBytes: number;
+    uploadedAt: string;
+};
+/**
+ * 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.
+ */
+export type FunnelUserAnswers = Record<string, unknown> & {
+    /** Generic branching answers by step id for yes/no splits. */
+    stepChoices?: Partial<Record<FunnelStepId, FunnelBinaryChoice>>;
+    /** Core onboarding answers used by template steps. */
+    selectedDevices?: Array<'iphone' | 'laptop' | 'watch' | 'none'>;
+    /** Upsell answers. */
+    upsellAccepted?: boolean;
+    upsellEmail?: string;
+    upsellSelectedPlanId?: string;
+    selectedPaywallPlanId?: string;
+    /** Manage subscription answers. */
+    manageSubscriptionHasActive?: boolean;
+    manageSubscriptionReason?: string;
+    manageSubscriptionCancelled?: boolean;
+    manageSubscriptionCancelledId?: string;
+    /** Optional location and astro metadata shared by astrology-style funnels. */
+    birthDate?: FunnelBirthDate;
+    birthCity?: string;
+    sunSign?: string;
+    moonSign?: string;
+    ascendantSign?: string;
+    /** Optional media metadata for steps that capture and upload user images. */
+    palmPhotoUpload?: FunnelTempUpload;
+    palmPhotoUrl?: string;
+};
+export declare const readStepChoice: (answers: FunnelUserAnswers, stepId: FunnelStepId) => FunnelBinaryChoice | undefined;
+export declare const writeStepChoice: (answers: FunnelUserAnswers, stepId: FunnelStepId, choice: FunnelBinaryChoice) => FunnelUserAnswers;

package/dist/sdk/userAnswers.js

@@ -0,0 +1,10 @@
+export const readStepChoice = (answers, stepId) => {
+    var _a;
+    const choice = (_a = answers.stepChoices) === null || _a === void 0 ? void 0 : _a[stepId];
+    return choice === 'yes' || choice === 'no' ? choice : undefined;
+};
+export const writeStepChoice = (answers, stepId, choice) => {
+    return Object.assign(Object.assign({}, answers), { 
+        // Keep legacy flat key for backward-compatible routing checks.
+        [stepId]: choice, [`${stepId}:yes`]: choice === 'yes', [`${stepId}:no`]: choice === 'no', stepChoices: Object.assign(Object.assign({}, (answers.stepChoices || {})), { [stepId]: choice }) });
+};