@funnelsgrove/runtime 0.1.18 → 0.1.20

package/dist/components/FunnelContext.d.ts

@@ -33,6 +33,7 @@ export type FunnelContextValue = {
     setAttribute: (key: string, value: unknown) => void;
     attributes: FunnelUserAnswers;
     user: FunnelUser;
+    userBootstrapped: boolean;
     setUser: (user: FunnelUser) => void;
     /** Manually record a step as completed (used by custom step components). */
     completeStep: (stepId: string, choices?: Record<string, unknown>) => void;

package/dist/components/SubscriptionHandoffScreen.js

@@ -44,7 +44,7 @@ const renderStoreIcon = (variant) => {
     return _jsx(WebLinkIcon, {});
 };
 export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, nodeId, }) {
-    const { user } = useFunnel();
+    const { isBuilder, user, userBootstrapped } = useFunnel();
     const [autoOpenAttempted, setAutoOpenAttempted] = useState(false);
     const [emailSent, setEmailSent] = useState(false);
     const browserSnapshotKey = useSyncExternalStore(subscribeToBrowserSnapshot, () => [
@@ -61,10 +61,11 @@ export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, no
             userAgent: userAgent || null,
         };
     }, [browserSnapshotKey]);
+    const handoffReady = isBuilder || (userBootstrapped && user.email.trim().length > 0);
     const handoff = useMemo(() => {
         return resolveSubscriptionHandoff({
-            userId: user.id,
-            email: user.email,
+            userId: handoffReady ? user.id : null,
+            email: handoffReady ? user.email : null,
             confirmationUrl: browserSnapshot.confirmationUrl,
             userAgent: browserSnapshot.userAgent,
             attribution: getFunnelUserAttribution(user.document),
@@ -76,50 +77,60 @@ export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, no
                 androidDeepLink: runtimePublicConfig.androidDeepLink,
             },
         });
-    }, [browserSnapshot, user.document, user.email, user.id]);
+    }, [browserSnapshot, handoffReady, user.document, user.email, user.id]);
     const qrCodeImageUrl = useMemo(() => buildQrCodeImageUrl(handoff.qrConfirmationUrl), [handoff.qrConfirmationUrl]);
     const installLinks = useMemo(() => {
         const links = [];
         const iosLinkContent = getStoreLinkContent(content.storeLinks, 'ios');
-        if (handoff.iosStoreUrl && iosLinkContent) {
+        if ((handoff.iosStoreUrl || (!handoffReady && runtimePublicConfig.iosAppStoreUrl)) && iosLinkContent) {
             links.push({
                 id: 'ios',
-                href: handoff.iosStoreUrl,
+                href: handoffReady ? handoff.iosStoreUrl : null,
                 eyebrow: iosLinkContent.eyebrow,
                 title: iosLinkContent.title,
                 variant: 'ios',
+                disabled: !handoffReady,
             });
         }
         const androidLinkContent = getStoreLinkContent(content.storeLinks, 'android');
-        if (handoff.androidStoreUrl && androidLinkContent) {
+        if ((handoff.androidStoreUrl || (!handoffReady && runtimePublicConfig.androidPlayStoreUrl)) &&
+            androidLinkContent) {
             links.push({
                 id: 'android',
-                href: handoff.androidStoreUrl,
+                href: handoffReady ? handoff.androidStoreUrl : null,
                 eyebrow: androidLinkContent.eyebrow,
                 title: androidLinkContent.title,
                 variant: 'android',
+                disabled: !handoffReady,
             });
         }
         const webLinkContent = getStoreLinkContent(content.storeLinks, 'web');
         const shouldShowWebLink = handoff.platform === 'desktop' || handoff.platform === 'android';
-        if (shouldShowWebLink && handoff.webLinkUrl && webLinkContent) {
+        if (shouldShowWebLink &&
+            (handoff.webLinkUrl || (!handoffReady && runtimePublicConfig.universalLink)) &&
+            webLinkContent) {
             links.push({
                 id: 'web',
-                href: handoff.webLinkUrl,
+                href: handoffReady ? handoff.webLinkUrl : null,
                 eyebrow: webLinkContent.eyebrow,
                 title: webLinkContent.title,
                 variant: 'web',
+                disabled: !handoffReady,
             });
         }
         return links;
     }, [
         content.storeLinks,
         handoff.androidStoreUrl,
+        handoffReady,
         handoff.iosStoreUrl,
         handoff.platform,
         handoff.webLinkUrl,
     ]);
     const emailHref = useMemo(() => {
+        if (!handoffReady) {
+            return null;
+        }
         const lines = [
             content.emailIntro,
             '',
@@ -142,10 +153,19 @@ export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, no
             subject: content.emailSubject,
             lines,
         });
-    }, [content, handoff, user.email]);
+    }, [content, handoff, handoffReady, user.email]);
+    const hasConfiguredOpenAppTarget = handoff.platform === 'ios'
+        ? Boolean(runtimePublicConfig.iosDeepLink || runtimePublicConfig.universalLink || runtimePublicConfig.iosAppStoreUrl)
+        : handoff.platform === 'android'
+            ? Boolean(runtimePublicConfig.androidDeepLink ||
+                runtimePublicConfig.universalLink ||
+                runtimePublicConfig.androidPlayStoreUrl)
+            : false;
+    const shouldShowOpenAppButton = handoff.platform !== 'desktop' &&
+        (Boolean(handoff.openAppUrl) || (!handoffReady && hasConfiguredOpenAppTarget));
     useEffect(() => {
         const openAppUrl = handoff.openAppUrl;
-        if (handoff.platform === 'desktop' || typeof window === 'undefined' || !openAppUrl) {
+        if (!handoffReady || handoff.platform === 'desktop' || typeof window === 'undefined' || !openAppUrl) {
             return;
         }
         const attemptKey = `app-deals:deep-link-attempt:${stepId}:${user.id}`;
@@ -153,13 +173,18 @@ export function SubscriptionHandoffScreen({ stepId, content, confirmationUrl, no
             return;
         }
         window.sessionStorage.setItem(attemptKey, '1');
-        const timer = window.setTimeout(() => {
-            window.location.assign(openAppUrl);
+        window.location.assign(openAppUrl);
+        const statusTimer = window.setTimeout(() => {
             setAutoOpenAttempted(true);
-        }, 500);
-        return () => window.clearTimeout(timer);
-    }, [handoff.openAppUrl, handoff.platform, stepId, user.id]);
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: 'subscription-handoff-step', "data-node-id": nodeId || stepId, children: [_jsxs("header", { className: 'subscription-handoff-head', children: [_jsx("p", { className: 'subscription-handoff-kicker', children: content.kicker }), _jsx("h2", { className: 'subscription-handoff-title', children: content.title })] }), installLinks.length > 0 ? (_jsx("div", { className: 'subscription-handoff-store-links', children: installLinks.map((link) => (_jsxs("a", { href: link.href, target: '_blank', rel: 'noopener noreferrer', "aria-label": `${link.eyebrow} ${link.title}`, className: `subscription-handoff-store-badge is-${link.variant}`, children: [renderStoreIcon(link.variant), _jsxs("span", { className: 'subscription-handoff-store-copy', children: [_jsx("span", { className: 'subscription-handoff-store-eyebrow', children: link.eyebrow }), _jsx("span", { className: 'subscription-handoff-store-title', children: link.title })] })] }, link.id))) })) : null, _jsx("p", { className: 'subscription-handoff-copy', children: qrCodeImageUrl ? content.copyWithQr : content.copyWithoutQr }), qrCodeImageUrl && handoff.qrConfirmationUrl ? (_jsx("a", { href: handoff.qrConfirmationUrl, className: 'subscription-handoff-qr-card', target: '_blank', rel: 'noopener noreferrer', "aria-label": content.qrOpenLabel, children: _jsx("span", { "aria-hidden": 'true', className: 'subscription-handoff-qr-image', style: { backgroundImage: `url(${qrCodeImageUrl})` } }) })) : null, _jsx("p", { className: 'subscription-handoff-note', children: content.note }), handoff.platform !== 'desktop' && handoff.openAppUrl ? (_jsx("a", { href: handoff.openAppUrl, className: 'subscription-handoff-open-app', children: content.openAppLabel })) : null, _jsx("a", { href: emailHref, className: 'subscription-handoff-email-button', onClick: () => setEmailSent(true), children: content.emailButtonLabel }), emailSent ? (_jsx("p", { className: 'subscription-handoff-status', children: content.emailSentStatus })) : null, autoOpenAttempted ? (_jsx("p", { className: 'subscription-handoff-status', children: content.autoOpenStatus })) : null] }), _jsx("style", { children: subscriptionHandoffScreenStyles })] }));
+        }, 0);
+        return () => window.clearTimeout(statusTimer);
+    }, [handoff.openAppUrl, handoff.platform, handoffReady, stepId, user.id]);
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: 'subscription-handoff-step', "data-node-id": nodeId || stepId, children: [_jsxs("header", { className: 'subscription-handoff-head', children: [_jsx("p", { className: 'subscription-handoff-kicker', children: content.kicker }), _jsx("h2", { className: 'subscription-handoff-title', children: content.title })] }), installLinks.length > 0 ? (_jsx("div", { className: 'subscription-handoff-store-links', children: installLinks.map((link) => {
+                            const label = `${link.eyebrow} ${link.title}`;
+                            const className = `subscription-handoff-store-badge is-${link.variant}${link.disabled ? ' is-disabled' : ''}`;
+                            const body = (_jsxs(_Fragment, { children: [renderStoreIcon(link.variant), _jsxs("span", { className: 'subscription-handoff-store-copy', children: [_jsx("span", { className: 'subscription-handoff-store-eyebrow', children: link.eyebrow }), _jsx("span", { className: 'subscription-handoff-store-title', children: link.title })] })] }));
+                            return link.href ? (_jsx("a", { href: link.href, target: '_blank', rel: 'noopener noreferrer', "aria-label": label, className: className, children: body }, link.id)) : (_jsx("span", { role: 'link', "aria-label": label, "aria-disabled": 'true', "aria-busy": 'true', className: className, children: body }, link.id));
+                        }) })) : null, _jsx("p", { className: 'subscription-handoff-copy', children: qrCodeImageUrl ? content.copyWithQr : content.copyWithoutQr }), qrCodeImageUrl && handoff.qrConfirmationUrl ? (_jsx("a", { href: handoff.qrConfirmationUrl, className: 'subscription-handoff-qr-card', target: '_blank', rel: 'noopener noreferrer', "aria-label": content.qrOpenLabel, children: _jsx("span", { "aria-hidden": 'true', className: 'subscription-handoff-qr-image', style: { backgroundImage: `url(${qrCodeImageUrl})` } }) })) : null, _jsx("p", { className: 'subscription-handoff-note', children: content.note }), shouldShowOpenAppButton && handoff.openAppUrl ? (_jsx("a", { href: handoff.openAppUrl, className: 'subscription-handoff-open-app', children: content.openAppLabel })) : null, shouldShowOpenAppButton && !handoff.openAppUrl ? (_jsx("span", { role: 'link', "aria-disabled": 'true', "aria-busy": 'true', className: 'subscription-handoff-open-app is-disabled', children: content.openAppLabel })) : null, emailHref ? (_jsx("a", { href: emailHref, className: 'subscription-handoff-email-button', onClick: () => setEmailSent(true), children: content.emailButtonLabel })) : (_jsx("span", { role: 'link', "aria-disabled": 'true', "aria-busy": 'true', className: 'subscription-handoff-email-button is-disabled', children: content.emailButtonLabel })), emailSent ? (_jsx("p", { className: 'subscription-handoff-status', children: content.emailSentStatus })) : null, autoOpenAttempted ? (_jsx("p", { className: 'subscription-handoff-status', children: content.autoOpenStatus })) : null] }), _jsx("style", { children: subscriptionHandoffScreenStyles })] }));
 }
 const subscriptionHandoffScreenStyles = `
 .subscription-handoff-step {
@@ -229,6 +254,14 @@ const subscriptionHandoffScreenStyles = `
   color: var(--color-text, #262729);
 }
 
+.subscription-handoff-store-badge.is-disabled,
+.subscription-handoff-open-app.is-disabled,
+.subscription-handoff-email-button.is-disabled {
+  opacity: 0.55;
+  cursor: progress;
+  pointer-events: none;
+}
+
 .subscription-handoff-store-icon {
   width: 28px;
   height: 28px;

package/dist/config/builder-preview.protocol.d.ts

@@ -5,6 +5,7 @@ export declare const BUILDER_PREVIEW_RUNTIME_MODE_CHANGED = "builder.preview.run
 export declare const BUILDER_PREVIEW_DEFINITION_PATCH = "builder.preview.definitionPatch";
 export declare const BUILDER_PREVIEW_VARIABLE_VALUES_CHANGED = "builder.preview.variableValuesChanged";
 export declare const BUILDER_PREVIEW_PAYWALL_PLANS_CHANGED = "builder.preview.paywallPlansChanged";
+export declare const BUILDER_PREVIEW_THEME_CHANGED = "builder.preview.themeChanged";
 export type BuilderPreviewReadyMessage = {
     type: typeof BUILDER_PREVIEW_READY;
     stepId: string;
@@ -75,3 +76,7 @@ export type BuilderPreviewPaywallPlansChangedMessage = {
     stepId: string;
     plans: BuilderPreviewPaywallPlan[];
 };
+export type BuilderPreviewThemeChangedMessage = {
+    type: typeof BUILDER_PREVIEW_THEME_CHANGED;
+    cssVariables: Record<string, string>;
+};

package/dist/config/builder-preview.protocol.js

@@ -5,3 +5,4 @@ export const BUILDER_PREVIEW_RUNTIME_MODE_CHANGED = 'builder.preview.runtimeMode
 export const BUILDER_PREVIEW_DEFINITION_PATCH = 'builder.preview.definitionPatch';
 export const BUILDER_PREVIEW_VARIABLE_VALUES_CHANGED = 'builder.preview.variableValuesChanged';
 export const BUILDER_PREVIEW_PAYWALL_PLANS_CHANGED = 'builder.preview.paywallPlansChanged';
+export const BUILDER_PREVIEW_THEME_CHANGED = 'builder.preview.themeChanged';

package/dist/config/funnel.experiments.types.d.ts

@@ -1,8 +1,9 @@
 import type { FunnelManifestExperiment } from './funnel.manifest.types.js';
-export type PaywallExperimentDefinition = {
+export type FunnelExperimentDefinition = {
     id: string;
     name: string;
-    type: 'paywall';
+    type: 'paywall' | 'step';
+    status?: 'running' | 'paused' | 'stopped';
     launchDate: string;
     control: {
         stepId: string;
@@ -13,6 +14,8 @@ export type PaywallExperimentDefinition = {
         trafficPercent: number;
     };
 };
-export type FunnelExperimentDefinition = PaywallExperimentDefinition;
+export type PaywallExperimentDefinition = FunnelExperimentDefinition & {
+    type: 'paywall';
+};
 export declare const defineFunnelExperiments: <const T extends readonly FunnelExperimentDefinition[]>(experiments: T) => T;
 export declare const toManifestExperiments: (experiments: readonly FunnelExperimentDefinition[]) => FunnelManifestExperiment[];

package/dist/config/funnel.experiments.types.js

@@ -7,7 +7,9 @@ export const defineFunnelExperiments = (experiments) => {
     }
     return experiments;
 };
-export const toManifestExperiments = (experiments) => experiments.map((experiment) => ({
+export const toManifestExperiments = (experiments) => experiments
+    .filter((experiment) => { var _a; return ((_a = experiment.status) !== null && _a !== void 0 ? _a : 'running') === 'running'; })
+    .map((experiment) => ({
     experimentId: experiment.id,
     stepId: experiment.control.stepId,
     variants: [

package/dist/runtime/posthog-flags.d.ts

@@ -1,4 +1,5 @@
 import type { PostHog } from 'posthog-js';
+export declare const POSTHOG_FEATURE_FLAG_READY_TIMEOUT_MS = 2500;
 type BootstrapConfig = {
     apiKey: string;
     apiHost: string;

package/dist/runtime/posthog-flags.js

@@ -1,6 +1,7 @@
 import posthog from 'posthog-js';
 let initialized = false;
 let readyPromise = null;
+export const POSTHOG_FEATURE_FLAG_READY_TIMEOUT_MS = 2500;
 export const bootstrapPostHog = (config) => {
     if (readyPromise) {
         return readyPromise;
@@ -10,13 +11,18 @@ export const bootstrapPostHog = (config) => {
             resolve();
             return;
         }
+        let readyTimeoutId = null;
         const markReady = () => {
             if (initialized) {
                 return;
             }
             initialized = true;
+            if (readyTimeoutId) {
+                clearTimeout(readyTimeoutId);
+            }
             resolve();
         };
+        readyTimeoutId = setTimeout(markReady, POSTHOG_FEATURE_FLAG_READY_TIMEOUT_MS);
         posthog.init(config.apiKey, {
             api_host: config.apiHost,
             persistence: 'localStorage+cookie',

package/dist/runtime/preview-bridge.d.ts

@@ -41,12 +41,16 @@ type PreviewBridgeMessage = {
     kind: 'paywallPlansChanged';
     stepId: string;
     plans: BuilderPreviewPaywallPlan[];
+} | {
+    kind: 'themeChanged';
+    cssVariables: Record<string, string>;
 } | {
     kind: 'goToStep';
     stepId: string;
 };
 export declare const parsePreviewQuickEditPatch: (value: unknown) => PreviewQuickEditPatch | null;
 export declare const parsePreviewBridgeMessage: (value: unknown) => PreviewBridgeMessage | null;
+export declare const applyPreviewThemeVariables: (cssVariables: Record<string, string>) => void;
 export declare const applyPreviewQuickEditPatch: (patch: PreviewQuickEditPatch) => void;
 export declare function emitPreviewVariableValues(stepId: FunnelStepId, values: Record<string, string>): void;
 export declare function usePreviewVariableValues(stepId: FunnelStepId, values: Record<string, string>): void;

package/dist/runtime/preview-bridge.js

@@ -1,6 +1,6 @@
 'use client';
 import { useEffect, useRef } from 'react';
-import { BUILDER_PREVIEW_ACTIVE_STEP_CHANGED, BUILDER_PREVIEW_DEFINITION_PATCH, BUILDER_PREVIEW_GO_TO_STEP, BUILDER_PREVIEW_PAYWALL_PLANS_CHANGED, BUILDER_PREVIEW_READY, BUILDER_PREVIEW_RUNTIME_MODE_CHANGED, BUILDER_PREVIEW_VARIABLE_VALUES_CHANGED, } from '../config/builder-preview.protocol.js';
+import { BUILDER_PREVIEW_ACTIVE_STEP_CHANGED, BUILDER_PREVIEW_DEFINITION_PATCH, BUILDER_PREVIEW_GO_TO_STEP, BUILDER_PREVIEW_PAYWALL_PLANS_CHANGED, BUILDER_PREVIEW_READY, BUILDER_PREVIEW_RUNTIME_MODE_CHANGED, BUILDER_PREVIEW_THEME_CHANGED, BUILDER_PREVIEW_VARIABLE_VALUES_CHANGED, } from '../config/builder-preview.protocol.js';
 import { isPreviewFrameRuntime } from '../services/preview-frame.service.js';
 import { logger } from '../services/logger.js';
 import { applyPreviewDefinitionPatch, applyPreviewPaywallPlansPatch } from './preview-definition-overrides.js';
@@ -107,6 +107,13 @@ export const parsePreviewQuickEditPatch = (value) => {
     }
     return null;
 };
+const parseThemeCssVariables = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const cssVariables = Object.fromEntries(Object.entries(value).filter((entry) => entry[0].startsWith('--') && typeof entry[1] === 'string'));
+    return Object.keys(cssVariables).length > 0 ? cssVariables : null;
+};
 export const parsePreviewBridgeMessage = (value) => {
     if (!isRecord(value)) {
         return null;
@@ -149,12 +156,33 @@ export const parsePreviewBridgeMessage = (value) => {
             }
             : null;
     }
+    if (messageType === BUILDER_PREVIEW_THEME_CHANGED) {
+        const cssVariables = parseThemeCssVariables(value.cssVariables);
+        return cssVariables ? { kind: 'themeChanged', cssVariables } : null;
+    }
     if (messageType === BUILDER_PREVIEW_GO_TO_STEP) {
         const stepId = typeof value.stepId === 'string' ? value.stepId.trim() : '';
         return stepId ? { kind: 'goToStep', stepId } : null;
     }
     return null;
 };
+export const applyPreviewThemeVariables = (cssVariables) => {
+    if (typeof document === 'undefined') {
+        return;
+    }
+    const targets = [
+        document.documentElement,
+        document.body,
+        ...Array.from(document.querySelectorAll('.page-root')),
+    ].filter((target) => Boolean(target));
+    for (const target of targets) {
+        for (const [key, value] of Object.entries(cssVariables)) {
+            if (key.startsWith('--')) {
+                target.style.setProperty(key, value);
+            }
+        }
+    }
+};
 export const applyPreviewQuickEditPatch = (patch) => {
     if (typeof document === 'undefined') {
         return;
@@ -291,6 +319,10 @@ export function usePreviewBridge({ activeStepId, onGoToStep, resolveRenderableSt
                 applyPreviewPaywallPlansPatch(action.stepId, action.plans);
                 return;
             }
+            if (action.kind === 'themeChanged') {
+                applyPreviewThemeVariables(action.cssVariables);
+                return;
+            }
             if (action.kind === 'runtimeModeChanged') {
                 setRuntimeMode(action.mode);
                 return;

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

@@ -9,7 +9,16 @@ export type FunnelFlowControllerExperiment<StepId extends string> = FunnelManife
     })[];
 };
 type StepComponentRegistry = Record<string, unknown>;
+type FunnelFlowAnalyticsAdapter = {
+    trackFirstStepViewed?: (input: {
+        stepId: string;
+        stepName: string;
+        occurredAt: string;
+        featureFlags?: Record<string, string>;
+    }) => string | null;
+};
 type UseFunnelFlowControllerInput<StepId extends string> = {
+    analytics?: FunnelFlowAnalyticsAdapter;
     initialStepId?: StepId;
     lockToInitialStep?: boolean;
     defaultStepId: StepId;
@@ -63,5 +72,5 @@ export declare function computeRenderSuspended(input: {
     }>;
     isPreviewRuntime?: boolean;
 }): 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 declare function useFunnelFlowController<StepId extends string>({ analytics, 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

@@ -54,7 +54,7 @@ export function computeRenderSuspended(input) {
     }
     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, }) {
+export function useFunnelFlowController({ analytics, 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);
@@ -102,10 +102,12 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         document: {},
         completedSteps: [],
     }));
+    const [userBootstrapped, setUserBootstrapped] = useState(isPreviewRuntime);
     const attributesAtStepStart = useRef({});
     const attributesRef = useRef(attributes);
     const postHogFeatureFlagsRef = useRef({});
     const prevStepIdRef = useRef(null);
+    const firstStepViewedTrackedRef = useRef(false);
     const stepStartedAtByIdRef = useRef({});
     const engagedStepIdsRef = useRef(new Set());
     const currentUserIdRef = useRef(user.id);
@@ -245,6 +247,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         const urlUserAttributes = resolveUrlUserAttributes();
         const bootstrapCandidateUserId = apiService.getBootstrapCandidateUserId(localUserId);
         const initialAttribution = collectCurrentFunnelAttribution();
+        setUserBootstrapped(isPreviewRuntime);
         setUser((prev) => (Object.assign(Object.assign({}, prev), { id: localUserId })));
         if (isPreviewRuntime) {
             return;
@@ -274,6 +277,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
                 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, document: sessionUser.document, attributes: sessionAttributes ? Object.assign(Object.assign({}, sessionAttributes), prev.attributes) : prev.attributes })));
+            setUserBootstrapped(true);
             void apiService.pingUserContext(sessionUser.id)
                 .then((pingedUser) => {
                 if (!pingedUser) {
@@ -292,6 +296,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         })
             .catch((error) => {
             logger.error('Failed to bootstrap user session:', error);
+            setUserBootstrapped(false);
             return null;
         });
         Promise.all([postHogBootstrap, sessionBootstrap])
@@ -368,6 +373,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         recordStepCompletion(stepId, choices);
     }, [recordStepCompletion]);
     useEffect(() => {
+        var _a;
         if (safeActiveStepId !== activeStepId) {
             logger.warn(`[FunnelFlow] Unknown or non-renderable step "${activeStepId}", falling back to "${safeActiveStepId}".`);
             setActiveStepId(safeActiveStepId);
@@ -391,6 +397,15 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
                 startedAt,
             });
             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, environment: runtimeMode, step_id: renderedStepId, step_name: stepName, started_at: startedAt }, buildFeatureFlagProperties(postHogFeatureFlagsRef.current)));
+            if (!firstStepViewedTrackedRef.current && safeActiveStepId === defaultStepId) {
+                firstStepViewedTrackedRef.current = true;
+                (_a = analytics === null || analytics === void 0 ? void 0 : analytics.trackFirstStepViewed) === null || _a === void 0 ? void 0 : _a.call(analytics, {
+                    stepId: renderedStepId,
+                    stepName,
+                    occurredAt: startedAt,
+                    featureFlags: postHogFeatureFlagsRef.current,
+                });
+            }
         }
         attributesAtStepStart.current = Object.assign({}, attributesRef.current);
         prevStepIdRef.current = renderedStepId;
@@ -425,6 +440,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         return () => window.clearTimeout(timer);
     }, [
         activeStepId,
+        analytics,
         defaultStepId,
         isPreviewRuntime,
         recordStepCompletion,
@@ -563,6 +579,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         setAttribute,
         attributes,
         user,
+        userBootstrapped,
         setUser,
         completeStep,
     }), [
@@ -580,6 +597,7 @@ export function useFunnelFlowController({ initialStepId, lockToInitialStep = fal
         setAnswer,
         setAttribute,
         user,
+        userBootstrapped,
     ]);
     return {
         activeStepComponent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/runtime",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "type": "module",
   "private": false,
   "main": "./dist/index.js",