@funnelsgrove/runtime 0.1.0 → 0.1.1

package/dist/runtime/experiment-assignment.d.ts

@@ -1,4 +1,13 @@
-import type { FunnelManifestExperiment } from '../config/funnel.manifest.types';
-export declare const getExperimentAssignmentStorageKey: (funnelId: string, userId: string, experimentId: string) => string;
-export declare const getExperimentAssignmentAttributeKey: (experimentId: string) => string;
-export declare const chooseAssignedVariantId: (experiment: FunnelManifestExperiment, userId: string, existingVariantId?: string | null) => string | null;
+export type ManifestVariant = {
+    variantKey: string;
+    routeToStepId: string;
+};
+export type ResolveInput = {
+    experimentId: string;
+    variants: readonly ManifestVariant[];
+};
+export type Assignment = {
+    variantKey: string;
+    routeToStepId: string;
+};
+export declare const resolveExperimentAssignment: (input: ResolveInput) => Assignment | null;

package/dist/runtime/experiment-assignment.js

@@ -1,32 +1,14 @@
-const hashToBucket = (input) => {
-    let hash = 0;
-    for (let index = 0; index < input.length; index += 1) {
-        hash = (hash * 31 + input.charCodeAt(index)) % 104729;
-    }
-    return Math.abs(hash % 100);
-};
-export const getExperimentAssignmentStorageKey = (funnelId, userId, experimentId) => {
-    return `funnel:experiment:${funnelId}:${userId}:${experimentId}`;
-};
-export const getExperimentAssignmentAttributeKey = (experimentId) => {
-    return `experiment.${experimentId}.variant`;
-};
-export const chooseAssignedVariantId = (experiment, userId, existingVariantId) => {
+import { resolveExperimentVariant } from './posthog-flags.js';
+export const resolveExperimentAssignment = (input) => {
     var _a;
-    if (!userId.trim()) {
+    if (input.variants.length === 0) {
         return null;
     }
-    const variantsById = new Map(experiment.variants.map((variant) => [variant.id, variant]));
-    if (existingVariantId && variantsById.has(existingVariantId)) {
-        return existingVariantId;
-    }
-    const bucket = hashToBucket(`${experiment.experimentId}:${userId}`);
-    let cumulative = 0;
-    for (const variant of experiment.variants) {
-        cumulative += Number.isFinite(variant.trafficPercent) ? variant.trafficPercent : 0;
-        if (bucket < cumulative) {
-            return variant.id;
-        }
+    const resolved = resolveExperimentVariant(input.experimentId);
+    const match = resolved ? input.variants.find((variant) => variant.variantKey === resolved) : undefined;
+    if (match) {
+        return { variantKey: match.variantKey, routeToStepId: match.routeToStepId };
     }
-    return ((_a = experiment.variants[experiment.variants.length - 1]) === null || _a === void 0 ? void 0 : _a.id) || null;
+    const control = (_a = input.variants.find((variant) => variant.variantKey === 'control')) !== null && _a !== void 0 ? _a : input.variants[0];
+    return { variantKey: control.variantKey, routeToStepId: control.routeToStepId };
 };

package/dist/runtime/funnel-attribution.d.ts

@@ -0,0 +1,18 @@
+export type FunnelUserTouch = Record<string, string>;
+export type FunnelUserAttribution = {
+    firstTouch: FunnelUserTouch;
+    lastTouch: FunnelUserTouch;
+    context: Record<string, unknown>;
+};
+export declare const collectCurrentFunnelAttribution: (input?: {
+    href?: string | null;
+    referrer?: string | null;
+    userAgent?: string | null;
+    language?: string | null;
+    platform?: string | null;
+    vendor?: string | null;
+    timeZone?: string | null;
+    posthogProperties?: Record<string, unknown> | null;
+}) => FunnelUserAttribution;
+export declare const mergeFunnelUserAttribution: (current: unknown, incoming: FunnelUserAttribution | null | undefined) => FunnelUserAttribution;
+export declare const getFunnelUserAttribution: (document: unknown) => FunnelUserAttribution | null;

package/dist/runtime/funnel-attribution.js

@@ -0,0 +1,226 @@
+import { getPostHog } from './posthog-flags.js';
+const INTERNAL_ATTRIBUTION_QUERY_KEYS = new Set([
+    'editor',
+    'previewframe',
+    'source',
+    'step',
+    'user_id',
+]);
+const POSTHOG_CONTEXT_MAPPINGS = {
+    $geoip_country_code: 'countryCode',
+    $geoip_country_name: 'countryName',
+    $browser: 'browser',
+    $browser_version: 'browserVersion',
+    $os: 'os',
+    $os_version: 'osVersion',
+    $device_type: 'deviceType',
+    $referrer: 'referrer',
+    $referring_domain: 'referringDomain',
+};
+const asTrimmedString = (value) => {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed || null;
+};
+const isRecord = (value) => {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+};
+const normalizeTouch = (value) => {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).flatMap(([key, candidate]) => {
+        const normalizedKey = key.trim();
+        const normalizedValue = asTrimmedString(candidate);
+        if (!normalizedKey || !normalizedValue) {
+            return [];
+        }
+        return [[normalizedKey, normalizedValue]];
+    }));
+};
+const normalizeContext = (value) => {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).flatMap(([key, candidate]) => {
+        const normalizedKey = key.trim();
+        if (!normalizedKey || candidate === undefined || candidate === null || candidate === '') {
+            return [];
+        }
+        return [[normalizedKey, candidate]];
+    }));
+};
+const deepMergeRecords = (base, patch) => {
+    const next = Object.assign({}, base);
+    for (const [key, patchValue] of Object.entries(patch)) {
+        const currentValue = next[key];
+        if (isRecord(currentValue) && isRecord(patchValue)) {
+            next[key] = deepMergeRecords(currentValue, patchValue);
+            continue;
+        }
+        next[key] = patchValue;
+    }
+    return next;
+};
+const resolveDeviceType = (userAgent) => {
+    if (!userAgent) {
+        return null;
+    }
+    const normalized = userAgent.toLowerCase();
+    if (/iphone|android.+mobile|ipod|mobile/.test(normalized)) {
+        return 'mobile';
+    }
+    if (/ipad|tablet/.test(normalized)) {
+        return 'tablet';
+    }
+    return 'desktop';
+};
+const resolveOsFamily = (userAgent) => {
+    if (!userAgent) {
+        return null;
+    }
+    const normalized = userAgent.toLowerCase();
+    if (/iphone|ipad|ipod|ios/.test(normalized)) {
+        return 'ios';
+    }
+    if (/android/.test(normalized)) {
+        return 'android';
+    }
+    if (/mac os x|macintosh/.test(normalized)) {
+        return 'macos';
+    }
+    if (/windows/.test(normalized)) {
+        return 'windows';
+    }
+    if (/linux/.test(normalized)) {
+        return 'linux';
+    }
+    return null;
+};
+const toUrl = (value) => {
+    const normalized = asTrimmedString(value);
+    if (!normalized) {
+        return null;
+    }
+    try {
+        return new URL(normalized);
+    }
+    catch (_a) {
+        return null;
+    }
+};
+const collectTouchFromUrl = (url) => {
+    if (!url) {
+        return {};
+    }
+    const nextTouch = {};
+    for (const [key, value] of url.searchParams.entries()) {
+        const normalizedKey = key.trim();
+        const normalizedValue = value.trim();
+        if (!normalizedKey || !normalizedValue) {
+            continue;
+        }
+        if (INTERNAL_ATTRIBUTION_QUERY_KEYS.has(normalizedKey.toLowerCase())) {
+            continue;
+        }
+        nextTouch[normalizedKey] = normalizedValue;
+    }
+    return nextTouch;
+};
+const collectPostHogContext = (posthogProperties) => {
+    if (!posthogProperties) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(POSTHOG_CONTEXT_MAPPINGS).flatMap(([sourceKey, targetKey]) => {
+        const normalizedValue = asTrimmedString(posthogProperties[sourceKey]);
+        return normalizedValue ? [[targetKey, normalizedValue]] : [];
+    }));
+};
+const resolvePostHogProperties = (explicitProperties) => {
+    if (explicitProperties) {
+        return explicitProperties;
+    }
+    const posthog = getPostHog();
+    if (!posthog) {
+        return null;
+    }
+    return Object.fromEntries(Object.keys(POSTHOG_CONTEXT_MAPPINGS).flatMap((key) => {
+        const value = posthog.get_property(key);
+        const normalized = asTrimmedString(value);
+        return normalized ? [[key, normalized]] : [];
+    }));
+};
+const getCurrentBrowserContext = () => {
+    if (typeof window === 'undefined') {
+        return {
+            href: null,
+            referrer: null,
+            userAgent: null,
+            language: null,
+            platform: null,
+            vendor: null,
+            timeZone: null,
+        };
+    }
+    return {
+        href: window.location.href,
+        referrer: typeof document !== 'undefined' ? document.referrer : null,
+        userAgent: navigator.userAgent,
+        language: navigator.language,
+        platform: navigator.platform,
+        vendor: navigator.vendor,
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone || null,
+    };
+};
+export const collectCurrentFunnelAttribution = (input = {}) => {
+    const browserContext = getCurrentBrowserContext();
+    const href = asTrimmedString(input.href) || browserContext.href;
+    const referrer = asTrimmedString(input.referrer) || browserContext.referrer;
+    const userAgent = asTrimmedString(input.userAgent) || browserContext.userAgent;
+    const language = asTrimmedString(input.language) || browserContext.language;
+    const platform = asTrimmedString(input.platform) || browserContext.platform;
+    const vendor = asTrimmedString(input.vendor) || browserContext.vendor;
+    const timeZone = asTrimmedString(input.timeZone) || browserContext.timeZone;
+    const currentUrl = toUrl(href);
+    const referrerUrl = toUrl(referrer);
+    const firstTouch = collectTouchFromUrl(currentUrl);
+    const posthogContext = collectPostHogContext(resolvePostHogProperties(input.posthogProperties));
+    return {
+        firstTouch,
+        lastTouch: Object.assign({}, firstTouch),
+        context: normalizeContext(Object.assign({ host: (currentUrl === null || currentUrl === void 0 ? void 0 : currentUrl.host) || null, path: (currentUrl === null || currentUrl === void 0 ? void 0 : currentUrl.pathname) || null, referrer, referringDomain: (referrerUrl === null || referrerUrl === void 0 ? void 0 : referrerUrl.host) || null, userAgent,
+            language,
+            platform,
+            vendor,
+            timeZone, deviceType: resolveDeviceType(userAgent), osFamily: resolveOsFamily(userAgent) }, posthogContext)),
+    };
+};
+export const mergeFunnelUserAttribution = (current, incoming) => {
+    const currentRecord = isRecord(current) ? current : {};
+    const currentFirstTouch = normalizeTouch(currentRecord.firstTouch);
+    const currentLastTouch = normalizeTouch(currentRecord.lastTouch);
+    const currentContext = normalizeContext(currentRecord.context);
+    const nextIncoming = incoming !== null && incoming !== void 0 ? incoming : {
+        firstTouch: {},
+        lastTouch: {},
+        context: {},
+    };
+    const nextFirstTouch = normalizeTouch(nextIncoming.firstTouch);
+    const nextLastTouch = normalizeTouch(nextIncoming.lastTouch);
+    const nextContext = normalizeContext(nextIncoming.context);
+    return {
+        firstTouch: Object.keys(currentFirstTouch).length > 0 ? currentFirstTouch : nextFirstTouch,
+        lastTouch: Object.keys(nextLastTouch).length > 0
+            ? nextLastTouch
+            : currentLastTouch,
+        context: deepMergeRecords(currentContext, nextContext),
+    };
+};
+export const getFunnelUserAttribution = (document) => {
+    if (!isRecord(document) || !isRecord(document.attribution)) {
+        return null;
+    }
+    return mergeFunnelUserAttribution(document.attribution, null);
+};

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

@@ -1,23 +1,22 @@
-import type { FunnelManifestExperiment } from '../config/funnel.manifest.types';
-import type { FunnelUserAnswers } from '../sdk/userAnswers';
+import type { FunnelManifestExperiment } from '../config/funnel.manifest.types.js';
+import type { FunnelUserAnswers } from '../sdk/userAnswers.js';
 export declare const isPreviewStepLockRequested: () => boolean;
 export declare const getRequestedEntryPointId: () => string | null;
 export declare const getRuntimeFunnelIdentity: () => string;
-export declare const getAssignedVariantId: (experiment: FunnelManifestExperiment, userId: string, storage: {
-    read: (storageKey: string) => string | null;
-    write: (storageKey: string, variantId: string) => void;
-}) => string | null;
+export declare const shouldRunAutoAdvanceTimer: (input: {
+    autoAdvanceMs?: number;
+    isPreviewRuntime: boolean;
+    shouldLockToInitialStep: boolean;
+}) => boolean;
 export declare const resolveNextStepFromContext: <StepId extends string>(input: {
     stepId: StepId;
     attributes: FunnelUserAnswers;
-    userId: string;
     safeInitialStepId: StepId;
     resolveRenderableStepId: (stepId: string | null | undefined) => StepId | null;
     getConfiguredNextStepId: (stepId: StepId, context: {
         attributes: FunnelUserAnswers;
-        userId: string;
-        getAssignedVariantId: (experiment: FunnelManifestExperiment) => string | null;
+        resolveExperimentVariantKey: (experiment: FunnelManifestExperiment) => string | null;
     }) => StepId | null;
     getSequentialNextStepId: (stepId: StepId) => StepId | null;
-    getAssignedVariantId: (experiment: FunnelManifestExperiment, userId: string) => string | null;
+    resolveExperimentVariantKey: (experiment: FunnelManifestExperiment) => string | null;
 }) => StepId;

package/dist/runtime/funnel-flow.js

@@ -1,5 +1,4 @@
-import { canUseDom } from './browser-helpers';
-import { chooseAssignedVariantId, getExperimentAssignmentStorageKey, } from './experiment-assignment';
+import { canUseDom } from './browser-helpers.js';
 export const isPreviewStepLockRequested = () => {
     if (!canUseDom()) {
         return false;
@@ -37,27 +36,14 @@ export const getRuntimeFunnelIdentity = () => {
         return 'default';
     }
 };
-export const getAssignedVariantId = (experiment, userId, storage) => {
-    if (!userId.trim()) {
-        return null;
-    }
-    const storageKey = getExperimentAssignmentStorageKey(getRuntimeFunnelIdentity(), userId, experiment.experimentId);
-    const storedVariantId = storage.read(storageKey);
-    const selectedVariantId = chooseAssignedVariantId(experiment, userId, storedVariantId);
-    if (!selectedVariantId) {
-        return null;
-    }
-    if (storedVariantId !== selectedVariantId) {
-        storage.write(storageKey, selectedVariantId);
-    }
-    return selectedVariantId;
+export const shouldRunAutoAdvanceTimer = (input) => {
+    return Boolean(input.autoAdvanceMs) && !input.isPreviewRuntime && !input.shouldLockToInitialStep;
 };
 export const resolveNextStepFromContext = (input) => {
     var _a, _b;
     const configuredStepId = input.getConfiguredNextStepId(input.stepId, {
         attributes: input.attributes,
-        userId: input.userId,
-        getAssignedVariantId: (experiment) => input.getAssignedVariantId(experiment, input.userId),
+        resolveExperimentVariantKey: input.resolveExperimentVariantKey,
     });
     if (configuredStepId) {
         return (_a = input.resolveRenderableStepId(configuredStepId)) !== null && _a !== void 0 ? _a : input.safeInitialStepId;

package/dist/runtime/funnel-manifest.validation.d.ts

@@ -1,2 +1,2 @@
-import type { FunnelManifest } from '../config/funnel.manifest.types';
+import type { FunnelManifest } from '../config/funnel.manifest.types.js';
 export declare const validateFunnelManifest: <T extends FunnelManifest>(manifest: T) => T;

package/dist/runtime/funnel-manifest.validation.js

@@ -37,11 +37,7 @@ export const validateFunnelManifest = (manifest) => {
     pushDuplicateErrors('step paths', stepPaths, errors);
     pushDuplicateErrors('step file paths', filePaths, errors);
     pushDuplicateErrors('step component keys', componentKeys, errors);
-    const defaultEntryPoints = manifest.entryPoints.filter((entryPoint) => entryPoint.isDefault === true);
-    if (defaultEntryPoints.length !== 1) {
-        errors.push(`manifest must declare exactly one default entry point, found ${defaultEntryPoints.length}`);
-    }
-    for (const entryPoint of manifest.entryPoints) {
+    for (const entryPoint of manifest.entryPoints || []) {
         assertValidReference(`entry point "${entryPoint.id}"`, entryPoint.stepId, validStepIds, errors);
     }
     for (const [stepId, edges] of Object.entries(manifest.edgesByStepId)) {
@@ -53,7 +49,7 @@ export const validateFunnelManifest = (manifest) => {
     for (const experiment of manifest.experiments) {
         assertValidReference(`experiment "${experiment.experimentId}"`, experiment.stepId, validStepIds, errors);
         for (const variant of experiment.variants) {
-            assertValidReference(`experiment variant "${experiment.experimentId}:${variant.id}"`, variant.routeToStepId, validStepIds, errors);
+            assertValidReference(`experiment variant "${experiment.experimentId}:${variant.variantKey}"`, variant.routeToStepId, validStepIds, errors);
         }
     }
     if (errors.length > 0) {

package/dist/runtime/funnel-runtime.d.ts

@@ -1,4 +1,4 @@
-import type { FunnelManifest, FunnelManifestExperiment } from '../config/funnel.manifest.types';
+import type { FunnelManifest, FunnelManifestExperiment } from '../config/funnel.manifest.types.js';
 export type FunnelStepId = string;
 export declare const getFunnelStepSequence: (manifest: FunnelManifest) => FunnelStepId[];
 export declare const getFunnelEntryPoints: (manifest: FunnelManifest) => {
@@ -26,9 +26,8 @@ export declare const getChoiceTargetsForStep: (manifest: FunnelManifest, stepId:
 export declare const resolveRuntimeInitialStepId: (input: {
     manifest: FunnelManifest;
     requestedStepId?: string | null;
-    entryPointId?: string | null;
 }) => FunnelStepId;
 export declare const resolveConfiguredNextStep: (manifest: FunnelManifest, stepId: FunnelStepId, context: {
     attributes: Record<string, unknown>;
-    getAssignedVariantId: (experiment: FunnelManifestExperiment) => string | null;
+    resolveExperimentVariantKey: (experiment: FunnelManifestExperiment) => string | null;
 }) => FunnelStepId | null;

package/dist/runtime/funnel-runtime.js

@@ -1,14 +1,8 @@
-import { getChoiceTargetsFromEdges, isManifestStepId, resolveInitialStepId, resolveNextStepId, } from './route-resolver';
+import { getChoiceTargetsFromEdges, isManifestStepId, resolveInitialStepId, resolveNextStepId, } from './route-resolver.js';
 export const getFunnelStepSequence = (manifest) => manifest.steps.map((step) => step.id);
-export const getFunnelEntryPoints = (manifest) => manifest.entryPoints.map((entryPoint) => (Object.assign(Object.assign({}, entryPoint), { stepId: entryPoint.stepId })));
+export const getFunnelEntryPoints = (manifest) => (manifest.entryPoints || []).map((entryPoint) => (Object.assign(Object.assign({}, entryPoint), { stepId: entryPoint.stepId })));
 export const getFunnelExperiments = (manifest) => manifest.experiments.map((experiment) => (Object.assign(Object.assign({}, experiment), { stepId: experiment.stepId, variants: experiment.variants.map((variant) => (Object.assign(Object.assign({}, variant), { routeToStepId: variant.routeToStepId }))) })));
-export const getDefaultFunnelStepId = (manifest) => {
-    var _a;
-    return ((_a = manifest.entryPoints.find((entryPoint) => {
-        return 'isDefault' in entryPoint && entryPoint.isDefault;
-    })) === null || _a === void 0 ? void 0 : _a.stepId) ||
-        getFunnelStepSequence(manifest)[0];
-};
+export const getDefaultFunnelStepId = (manifest) => getFunnelStepSequence(manifest)[0];
 export const getIsFunnelStepId = (manifest, value) => {
     return new Set(getFunnelStepSequence(manifest)).has(value);
 };
@@ -28,11 +22,11 @@ export const getDefaultEntryPointStepId = (manifest) => {
     return getDefaultFunnelStepId(manifest);
 };
 export const getEntryPointStepId = (manifest, entryPointId) => {
-    var _a;
+    var _a, _b;
     if (!entryPointId) {
         return null;
     }
-    const stepId = (_a = manifest.entryPoints.find((entryPoint) => entryPoint.id === entryPointId)) === null || _a === void 0 ? void 0 : _a.stepId;
+    const stepId = (_b = (_a = manifest.entryPoints) === null || _a === void 0 ? void 0 : _a.find((entryPoint) => entryPoint.id === entryPointId)) === null || _b === void 0 ? void 0 : _b.stepId;
     return stepId && getIsFunnelStepId(manifest, stepId) ? stepId : null;
 };
 export const getSequentialNextStepId = (manifest, stepId) => {
@@ -58,7 +52,6 @@ export const resolveRuntimeInitialStepId = (input) => {
     const stepId = resolveInitialStepId({
         manifest: input.manifest,
         requestedStepId: input.requestedStepId,
-        entryPointId: input.entryPointId,
     });
     return getIsFunnelStepId(input.manifest, stepId) ? stepId : getDefaultFunnelStepId(input.manifest);
 };
@@ -67,7 +60,7 @@ export const resolveConfiguredNextStep = (manifest, stepId, context) => {
         manifest,
         currentStepId: stepId,
         attributes: context.attributes,
-        getAssignedVariantId: context.getAssignedVariantId,
+        resolveExperimentVariantKey: context.resolveExperimentVariantKey,
     });
     return nextStepId && isManifestStepId(manifest, nextStepId) && getIsFunnelStepId(manifest, nextStepId)
         ? nextStepId

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

@@ -0,0 +1,30 @@
+import type { PostHog } from 'posthog-js';
+type BootstrapConfig = {
+    apiKey: string;
+    apiHost: string;
+    distinctId: string;
+};
+export declare const bootstrapPostHog: (config: BootstrapConfig) => Promise<void>;
+export declare const isPostHogReady: () => boolean;
+/**
+ * Aliases an anonymous distinct id to a server-side user id after the user
+ * has been identified (e.g. once bootstrapSession resolves). Preserves the
+ * anonymous user's feature-flag bucket assignments via PostHog's
+ * ensure_experience_continuity behaviour, so they don't get re-bucketed to
+ * a different variant mid-session.
+ *
+ * No-op if PostHog has not finished initializing or if the ids already match.
+ */
+export declare const identifyPostHog: (serverUserId: string, anonymousId: string) => void;
+/**
+ * Returns the variant key for the flag, or undefined if:
+ * - PostHog SDK has not finished loading feature flags yet (see isPostHogReady)
+ * - OR no flag of that key exists
+ *
+ * Callers that render experiment variants should gate on isPostHogReady() first,
+ * otherwise users may see the fallback (control) variant on first paint and
+ * flip once the SDK loads. Task 8's controller handles this gate.
+ */
+export declare const resolveExperimentVariant: (flagKey: string) => string | undefined;
+export declare const getPostHog: () => PostHog | null;
+export {};

package/dist/runtime/posthog-flags.js

@@ -0,0 +1,71 @@
+import posthog from 'posthog-js';
+let initialized = false;
+let readyPromise = null;
+export const bootstrapPostHog = (config) => {
+    if (readyPromise) {
+        return readyPromise;
+    }
+    readyPromise = new Promise((resolve) => {
+        if (!config.apiKey || !config.apiHost) {
+            resolve();
+            return;
+        }
+        const markReady = () => {
+            if (initialized) {
+                return;
+            }
+            initialized = true;
+            resolve();
+        };
+        posthog.init(config.apiKey, {
+            api_host: config.apiHost,
+            persistence: 'localStorage+cookie',
+            person_profiles: 'identified_only',
+            bootstrap: { distinctID: config.distinctId },
+            loaded: () => {
+                let unsubscribe = null;
+                unsubscribe = posthog.onFeatureFlags(() => {
+                    unsubscribe === null || unsubscribe === void 0 ? void 0 : unsubscribe();
+                    markReady();
+                });
+            },
+        });
+    });
+    return readyPromise;
+};
+export const isPostHogReady = () => initialized;
+/**
+ * Aliases an anonymous distinct id to a server-side user id after the user
+ * has been identified (e.g. once bootstrapSession resolves). Preserves the
+ * anonymous user's feature-flag bucket assignments via PostHog's
+ * ensure_experience_continuity behaviour, so they don't get re-bucketed to
+ * a different variant mid-session.
+ *
+ * No-op if PostHog has not finished initializing or if the ids already match.
+ */
+export const identifyPostHog = (serverUserId, anonymousId) => {
+    if (!initialized || serverUserId === anonymousId) {
+        return;
+    }
+    // posthog-js types the 3rd arg as userPropertiesToSetOnce, but passing the
+    // prior anonymous id here is the documented posthog pattern for explicitly
+    // linking an anonymous session to an identified user for experiment continuity.
+    posthog.identify(serverUserId, undefined, anonymousId);
+};
+/**
+ * Returns the variant key for the flag, or undefined if:
+ * - PostHog SDK has not finished loading feature flags yet (see isPostHogReady)
+ * - OR no flag of that key exists
+ *
+ * Callers that render experiment variants should gate on isPostHogReady() first,
+ * otherwise users may see the fallback (control) variant on first paint and
+ * flip once the SDK loads. Task 8's controller handles this gate.
+ */
+export const resolveExperimentVariant = (flagKey) => {
+    if (!initialized) {
+        return undefined;
+    }
+    const value = posthog.getFeatureFlag(flagKey);
+    return typeof value === 'string' ? value : undefined;
+};
+export const getPostHog = () => (initialized ? posthog : null);

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

@@ -1,5 +1,6 @@
-import type { RuntimeMode } from '../services/runtime-mode.service';
-import type { FunnelStepId } from './funnel-runtime';
+import { type BuilderPreviewDefinitionPatch, type BuilderPreviewPaywallPlan } from '../config/builder-preview.protocol.js';
+import type { RuntimeMode } from '../services/runtime-mode.service.js';
+import type { FunnelStepId } from './funnel-runtime.js';
 export type PreviewQuickEditPatch = {
     kind: 'tagText';
     stepId: string;
@@ -28,11 +29,18 @@ export type PreviewQuickEditPatch = {
     value: string;
 };
 type PreviewBridgeMessage = {
+    kind: 'definitionPatch';
+    patch: BuilderPreviewDefinitionPatch;
+} | {
     kind: 'quickEditPatch';
     patch: PreviewQuickEditPatch;
 } | {
     kind: 'runtimeModeChanged';
     mode: RuntimeMode;
+} | {
+    kind: 'paywallPlansChanged';
+    stepId: string;
+    plans: BuilderPreviewPaywallPlan[];
 } | {
     kind: 'goToStep';
     stepId: string;
@@ -40,6 +48,8 @@ type PreviewBridgeMessage = {
 export declare const parsePreviewQuickEditPatch: (value: unknown) => PreviewQuickEditPatch | null;
 export declare const parsePreviewBridgeMessage: (value: unknown) => PreviewBridgeMessage | null;
 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;
 export type PreviewBridgeOptions = {
     activeStepId: FunnelStepId;
     onGoToStep: (stepId: FunnelStepId) => void;
@@ -48,4 +58,4 @@ export type PreviewBridgeOptions = {
     shouldLockToInitialStep: boolean;
 };
 export declare function usePreviewBridge({ activeStepId, onGoToStep, resolveRenderableStepId, setRuntimeMode, shouldLockToInitialStep, }: PreviewBridgeOptions): void;
-export {};
+export { applyPreviewDefinitionPatch, clearPreviewDefinitionPatches, resolvePreviewStepPaywallPlans, resolvePreviewStepCountryPricing, resolvePreviewStepLocalizedContent, usePreviewDefinitionOverrideRevision, usePreviewStepPaywallPlans, usePreviewStepCountryPricing, usePreviewStepLocalizedContent, } from './preview-definition-overrides.js';