@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_scaffold/src/runtime/funnel-runtime.ts

@@ -0,0 +1,118 @@
+import { funnelManifest, type FunnelStepId } from '@/config/funnel.manifest';
+import type { FunnelManifestExperiment } from '@funnelsgrove/runtime';
+import {
+  getChoiceTargetsFromEdges,
+  isManifestStepId,
+  resolveInitialStepId,
+  resolveNextStepId,
+} from '@funnelsgrove/runtime';
+
+export { FunnelStepId };
+
+export const funnelStepSequence = funnelManifest.steps.map((step) => step.id) as FunnelStepId[];
+export type FunnelExperimentConfig = FunnelManifestExperiment & {
+  stepId: FunnelStepId;
+  variants: readonly (
+    FunnelManifestExperiment['variants'][number] & {
+      routeToStepId: FunnelStepId;
+    }
+  )[];
+};
+export const funnelExperiments: FunnelExperimentConfig[] = funnelManifest.experiments.map(
+  (experiment) => ({
+    ...experiment,
+    stepId: experiment.stepId as FunnelStepId,
+    variants: experiment.variants.map((variant) => ({
+      ...variant,
+      routeToStepId: variant.routeToStepId as FunnelStepId,
+    })),
+  }),
+);
+
+export const defaultFunnelStepId: FunnelStepId = funnelStepSequence[0];
+
+const stepIdSet = new Set<string>(funnelStepSequence);
+const stepIndexById = new Map<FunnelStepId, number>(
+  funnelStepSequence.map((stepId, index) => [stepId, index] as const),
+);
+const stepPathById = new Map<FunnelStepId, string>(
+  funnelManifest.steps.map((step) => [step.id as FunnelStepId, step.path] as const),
+);
+
+export const isFunnelStepId = (value: string): value is FunnelStepId => {
+  return stepIdSet.has(value);
+};
+
+export const getPathForStep = (stepId: FunnelStepId): string => {
+  return stepPathById.get(stepId) || `/${stepId}`;
+};
+
+export const getStepIdFromPath = (pathname: string): FunnelStepId | null => {
+  const segment = pathname
+    .split('?')[0]
+    .split('#')[0]
+    .split('/')
+    .map((part) => part.trim())
+    .filter(Boolean)[0];
+
+  if (!segment || !isFunnelStepId(segment)) {
+    return null;
+  }
+
+  return segment;
+};
+
+export const getSequentialNextStepId = (stepId: FunnelStepId): FunnelStepId | null => {
+  const stepIndex = stepIndexById.get(stepId);
+  if (stepIndex === undefined) {
+    return null;
+  }
+
+  return funnelStepSequence[stepIndex + 1] ?? null;
+};
+
+export const getChoiceTargetsForStep = (
+  stepId: FunnelStepId,
+): { yes?: FunnelStepId; no?: FunnelStepId } | null => {
+  const choiceTargets = getChoiceTargetsFromEdges(funnelManifest, stepId);
+  if (!choiceTargets) {
+    return null;
+  }
+
+  return {
+    yes: choiceTargets.yes && isFunnelStepId(choiceTargets.yes) ? choiceTargets.yes : undefined,
+    no: choiceTargets.no && isFunnelStepId(choiceTargets.no) ? choiceTargets.no : undefined,
+  };
+};
+
+export const resolveRuntimeInitialStepId = (input: {
+  requestedStepId?: string | null;
+}): FunnelStepId => {
+  const stepId = resolveInitialStepId({
+    manifest: funnelManifest,
+    requestedStepId: input.requestedStepId,
+  });
+
+  return isFunnelStepId(stepId) ? stepId : defaultFunnelStepId;
+};
+
+export const resolveConfiguredNextStep = (
+  stepId: FunnelStepId,
+  context: {
+    attributes: Record<string, unknown>;
+    ignoreExperiment?: boolean;
+    resolveExperimentVariantKey: (experiment: FunnelManifestExperiment) => string | null;
+  },
+): FunnelStepId | null => {
+  const nextStepId = resolveNextStepId({
+    manifest: funnelManifest,
+    currentStepId: stepId,
+    attributes: context.attributes,
+    ignoreExperiment: context.ignoreExperiment,
+    resolveExperimentVariantKey: context.resolveExperimentVariantKey,
+  });
+
+  return nextStepId && isManifestStepId(funnelManifest, nextStepId) && isFunnelStepId(nextStepId)
+    ? nextStepId
+    : null;
+};

package/template_scaffold/src/runtime/step-content-context.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import {
+  getStepContentLocale,
+  getStepCountryCode,
+} from './step-content-context';
+
+describe('step content context helpers', () => {
+  it('prefers stored browser language and explicit country when present', () => {
+    expect(
+      getStepContentLocale(
+        {
+          browserLanguage: 'pt-PT',
+          language: 'en-US',
+        },
+        'de-DE',
+      ),
+    ).toBe('pt-PT');
+
+    expect(
+      getStepCountryCode(
+        {
+          country: 'pt',
+        },
+        'en-US',
+      ),
+    ).toBe('PT');
+  });
+
+  it('falls back to the runtime locale and derives the region when no country is stored', () => {
+    expect(getStepContentLocale({}, 'en-US')).toBe('en-US');
+    expect(getStepCountryCode({}, 'en-US')).toBe('US');
+  });
+
+  it('returns null when no locale or country signal is available', () => {
+    expect(getStepContentLocale({}, null)).toBeNull();
+    expect(getStepCountryCode({}, null)).toBeNull();
+  });
+});

package/template_scaffold/src/runtime/step-content-context.ts

@@ -0,0 +1,65 @@
+import type { FunnelUserAnswers } from '@funnelsgrove/runtime';
+
+const asTrimmedStringOrNull = (value: unknown): string | null => {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed || null;
+};
+
+const readBrowserLocale = (): string | null => {
+  if (typeof navigator === 'undefined') {
+    return null;
+  }
+
+  return asTrimmedStringOrNull(navigator.language);
+};
+
+const normalizeCountryCode = (countryCode: string | null): string | null => {
+  if (!countryCode) {
+    return null;
+  }
+
+  if (/^[a-z]{2}$/i.test(countryCode)) {
+    return countryCode.toUpperCase();
+  }
+
+  return countryCode;
+};
+
+const getCountryFromLocale = (locale: string | null): string | null => {
+  if (!locale) {
+    return null;
+  }
+
+  const region = locale
+    .split('-')[1]
+    ?.trim()
+    .toUpperCase();
+
+  return region && /^[A-Z]{2}$/.test(region) ? region : null;
+};
+
+export function getStepContentLocale(
+  attributes: FunnelUserAnswers,
+  browserLocale: string | null = readBrowserLocale(),
+): string | null {
+  return (
+    asTrimmedStringOrNull(attributes.browserLanguage) ||
+    asTrimmedStringOrNull(attributes.language) ||
+    asTrimmedStringOrNull(attributes.locale) ||
+    asTrimmedStringOrNull(browserLocale)
+  );
+}
+
+export function getStepCountryCode(
+  attributes: FunnelUserAnswers,
+  locale: string | null = getStepContentLocale(attributes),
+): string | null {
+  const explicitCountry =
+    asTrimmedStringOrNull(attributes.countryCode) || asTrimmedStringOrNull(attributes.country);
+
+  return normalizeCountryCode(explicitCountry) || getCountryFromLocale(locale);
+}

package/template_scaffold/src/runtime/step-registry.ts

@@ -0,0 +1,66 @@
+import type { FunctionComponent } from 'react';
+import { StepFour, stepFour } from '@/steps/step-04';
+import { StepOne, stepOne } from '@/steps/step-01';
+import { StepEmailCapture, stepEmailCapture } from '@/steps/step-31-email-capture';
+import { StepPaywall, stepPaywall } from '@/steps/step-32-paywall';
+import { StepPaywallB, stepPaywallB } from '@/steps/step-32b-paywall-b';
+import {
+  StepSubscriptionStarted,
+  stepSubscriptionStarted,
+} from '@/steps/step-33-subscription-started';
+import {
+  StepManageSubscription,
+  stepManageSubscription,
+} from '@/steps/step-35-manage-subscription';
+import { StepThree, stepThree } from '@/steps/step-03';
+import { StepTwo, stepTwo } from '@/steps/step-02';
+import type { FunnelStepComponentKey } from '@/config/funnel.manifest';
+import type { FunnelStepMeta } from '@funnelsgrove/runtime';
+
+export type StepRegistryEntry = {
+  component: FunctionComponent<Record<string, never>>;
+  meta: FunnelStepMeta;
+};
+
+export const stepRegistry: Record<FunnelStepComponentKey, StepRegistryEntry> = {
+  stepOne: {
+    component: StepOne,
+    meta: stepOne,
+  },
+  stepTwo: {
+    component: StepTwo,
+    meta: stepTwo,
+  },
+  stepThree: {
+    component: StepThree,
+    meta: stepThree,
+  },
+  stepFour: {
+    component: StepFour,
+    meta: stepFour,
+  },
+  stepEmailCapture: {
+    component: StepEmailCapture,
+    meta: stepEmailCapture,
+  },
+  stepPaywall: {
+    component: StepPaywall,
+    meta: stepPaywall,
+  },
+  stepPaywallB: {
+    component: StepPaywallB,
+    meta: stepPaywallB,
+  },
+  stepManageSubscription: {
+    component: StepManageSubscription,
+    meta: stepManageSubscription,
+  },
+  stepSubscriptionStarted: {
+    component: StepSubscriptionStarted,
+    meta: stepSubscriptionStarted,
+  },
+};
+
+export const getStepRegistry = (): Record<FunnelStepComponentKey, StepRegistryEntry> => {
+  return stepRegistry;
+};

package/template_scaffold/src/runtime/step-variable-values.ts

@@ -0,0 +1,31 @@
+import type { PaywallPlan } from '@funnelsgrove/payments';
+import {
+  resolveStepEditorUserVariableValues,
+  type StepEditorSection,
+} from '@funnelsgrove/runtime';
+
+export const buildPlanVariableValues = (plans: readonly PaywallPlan[]): Record<string, string> => {
+  return Object.fromEntries(
+    plans.flatMap((plan) => {
+      const prefix = `plan.${plan.id}`;
+      return [
+        [`${prefix}.priceLabel`, plan.priceLabel],
+        [`${prefix}.dailyPrice`, plan.comparison?.perDay || `${plan.perDayAmount}/day`],
+        [`${prefix}.weeklyPrice`, plan.comparison?.perWeek || ''],
+        [`${prefix}.monthlyPrice`, plan.comparison?.perMonth || plan.priceLabel],
+        [`${prefix}.yearlyPrice`, plan.comparison?.perYear || ''],
+      ];
+    }),
+  );
+};
+
+export const buildStepVariableValues = (
+  sections: readonly StepEditorSection[],
+  answers: Record<string, unknown>,
+  extraValues?: Record<string, string>,
+): Record<string, string> => {
+  return {
+    ...resolveStepEditorUserVariableValues(sections, answers),
+    ...(extraValues || {}),
+  };
+};

package/template_scaffold/src/runtime/use-funnel-flow-controller.integration.test.ts

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { posthogFlagsPath } = vi.hoisted(() => ({
+  posthogFlagsPath: new URL(
+    '../../../funnel-runtime/src/runtime/posthog-flags.ts',
+    import.meta.url,
+  ).pathname,
+}));
+
+// This suite mocks the runtime's internal posthog-flags module by source path,
+// which only exists inside the funnelsgrove monorepo. Standalone funnels
+// scaffolded from the template resolve @funnelsgrove/runtime from node_modules
+// and cover the same routing logic through use-funnel-flow-controller.test.ts.
+const insideMonorepo = existsSync(posthogFlagsPath);
+
+vi.mock(posthogFlagsPath, () => ({
+  resolveExperimentVariant: vi.fn(),
+  bootstrapPostHog: vi.fn(),
+  isPostHogReady: vi.fn(() => true),
+  identifyPostHog: vi.fn(),
+  getPostHog: vi.fn(() => null),
+}));
+
+import type {
+  FunnelManifest,
+  FunnelManifestExperiment,
+} from '@funnelsgrove/runtime';
+import {
+  resolveExperimentAssignment,
+  resolveExperimentVariant,
+  resolveNextStepId,
+} from '@funnelsgrove/runtime';
+import { computeRenderSuspended } from './use-funnel-flow-controller';
+
+const mockedResolveVariant = vi.mocked(resolveExperimentVariant);
+
+const heroExperiment: FunnelManifestExperiment = {
+  experimentId: 'exp_hero',
+  stepId: 'hero',
+  variants: [
+    { variantKey: 'control', routeToStepId: 'hero_v1' },
+    { variantKey: 'variant_a', routeToStepId: 'hero_v2' },
+  ],
+};
+
+const manifest: FunnelManifest = {
+  templateArchitectureVersion: 1,
+  stepContractVersion: 2,
+  meta: { title: 'Hero Experiment Funnel', description: 'integration fixture' },
+  viewport: { width: 390, height: 844 },
+  assets: {},
+  steps: [
+    {
+      id: 'hero',
+      name: 'hero',
+      path: '/hero',
+      filePath: 'src/steps/hero.tsx',
+      componentKey: 'hero',
+      type: 'intro_hero',
+      title: 'Hero',
+    },
+    {
+      id: 'hero_v1',
+      name: 'hero-v1',
+      path: '/hero-v1',
+      filePath: 'src/steps/hero-v1.tsx',
+      componentKey: 'heroV1',
+      type: 'intro_hero',
+      title: 'Hero v1',
+    },
+    {
+      id: 'hero_v2',
+      name: 'hero-v2',
+      path: '/hero-v2',
+      filePath: 'src/steps/hero-v2.tsx',
+      componentKey: 'heroV2',
+      type: 'intro_hero',
+      title: 'Hero v2',
+    },
+  ],
+  edgesByStepId: {
+    hero: [{ toStepId: 'hero_v1' }],
+  },
+  experiments: [heroExperiment],
+};
+
+// The controller's renderedStepId is derived by passing the active step's
+// experiment through resolveExperimentAssignment and routing to the matched
+// variant's routeToStepId (falling back to control). That is exactly the
+// function under test here. See apps/funnel-template/src/runtime/use-funnel-flow-controller.ts
+// (renderedStepId useMemo).
+const computeRenderedStepIdForActiveExperiment = (
+  experiment: FunnelManifestExperiment,
+): string => {
+  const assignment = resolveExperimentAssignment({
+    experimentId: experiment.experimentId,
+    variants: experiment.variants,
+  });
+  return assignment?.routeToStepId ?? experiment.stepId;
+};
+
+describe.skipIf(!insideMonorepo)('PostHog variant resolution (integration)', () => {
+  beforeEach(() => {
+    mockedResolveVariant.mockReset();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('routes to the variant_a target when PostHog resolves exp_hero to variant_a', () => {
+    mockedResolveVariant.mockReturnValue('variant_a');
+
+    expect(computeRenderedStepIdForActiveExperiment(heroExperiment)).toBe('hero_v2');
+
+    expect(
+      resolveNextStepId({
+        manifest,
+        currentStepId: 'hero',
+        attributes: {},
+        resolveExperimentVariantKey: (experiment) =>
+          resolveExperimentVariant(experiment.experimentId) ?? null,
+      }),
+    ).toBe('hero_v2');
+  });
+
+  it('falls back to control (hero_v1) when PostHog is not ready / returns undefined', () => {
+    mockedResolveVariant.mockReturnValue(undefined);
+
+    expect(computeRenderedStepIdForActiveExperiment(heroExperiment)).toBe('hero_v1');
+
+    expect(
+      resolveNextStepId({
+        manifest,
+        currentStepId: 'hero',
+        attributes: {},
+        resolveExperimentVariantKey: (experiment) =>
+          resolveExperimentVariant(experiment.experimentId) ?? null,
+      }),
+    ).toBe('hero_v1');
+  });
+
+  it('falls back to control (hero_v1) when PostHog resolves to an unknown variant key', () => {
+    mockedResolveVariant.mockReturnValue('phantom');
+
+    expect(computeRenderedStepIdForActiveExperiment(heroExperiment)).toBe('hero_v1');
+
+    expect(
+      resolveNextStepId({
+        manifest,
+        currentStepId: 'hero',
+        attributes: {},
+        resolveExperimentVariantKey: (experiment) =>
+          resolveExperimentVariant(experiment.experimentId) ?? null,
+      }),
+    ).toBe('hero_v1');
+  });
+
+  it('suspends render on an experiment step while PostHog is not ready', () => {
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'hero',
+        postHogReady: false,
+        experiments: manifest.experiments,
+      }),
+    ).toBe(true);
+
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'hero',
+        postHogReady: true,
+        experiments: manifest.experiments,
+      }),
+    ).toBe(false);
+  });
+
+  it('does not suspend render on an experiment step in preview runtime', () => {
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'hero',
+        postHogReady: false,
+        experiments: manifest.experiments,
+        isPreviewRuntime: true,
+      }),
+    ).toBe(false);
+  });
+
+  it('renders experiment variants on the source URL before normal continuation', () => {
+    const adapterSource = readFileSync(new URL('./use-funnel-flow-controller.ts', import.meta.url), 'utf8');
+    const runtimeSource = readFileSync(
+      new URL('../../../funnel-runtime/src/runtime/use-funnel-flow-controller.ts', import.meta.url),
+      'utf8',
+    );
+
+    expect(adapterSource).toContain('useFunnelFlowController as useSharedFunnelFlowController');
+    expect(runtimeSource).toContain('activeExperimentForStep');
+    expect(runtimeSource).not.toContain('goToStep(renderedStepId)');
+    expect(runtimeSource).toContain('goToStep(resolveNextStepId(renderedStepId');
+    expect(runtimeSource).toContain('ignoreExperiment: Boolean(activeExperimentForStep && renderedStepId === safeActiveStepId)');
+    expect(runtimeSource).toContain('if (prevId === renderedStepId)');
+  });
+});

package/template_scaffold/src/runtime/use-funnel-flow-controller.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { computeRenderSuspended } from './use-funnel-flow-controller';
+
+describe('computeRenderSuspended', () => {
+  const experiments = [
+    { stepId: 'step-paywall' },
+    { stepId: 'step-headline' },
+  ];
+
+  it('renderSuspended is true when active step has experiment and posthog is not ready', () => {
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'step-paywall',
+        postHogReady: false,
+        experiments,
+      }),
+    ).toBe(true);
+  });
+
+  it('renderSuspended is false when active step has no experiment', () => {
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'step-intro',
+        postHogReady: false,
+        experiments,
+      }),
+    ).toBe(false);
+  });
+
+  it('renderSuspended is false after posthog becomes ready', () => {
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'step-paywall',
+        postHogReady: true,
+        experiments,
+      }),
+    ).toBe(false);
+  });
+
+  it('renderSuspended is false in preview runtime even when posthog is not ready', () => {
+    expect(
+      computeRenderSuspended({
+        activeStepId: 'step-paywall',
+        postHogReady: false,
+        experiments,
+        isPreviewRuntime: true,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('qualified visitor analytics', () => {
+  it('delegates flow behavior to the shared runtime controller with template analytics', () => {
+    const source = readFileSync(new URL('./use-funnel-flow-controller.ts', import.meta.url), 'utf8');
+
+    expect(source).toContain('useFunnelFlowController as useSharedFunnelFlowController');
+    expect(source).toContain('return useSharedFunnelFlowController<FunnelStepId>({');
+    expect(source).toContain('analytics: publicAnalyticsSdk');
+    expect(source).toContain('stepContractVersion: funnelManifest.stepContractVersion');
+    expect(source).toContain('defaultStepId: defaultFunnelStepId');
+    expect(source).toContain('stepSequence: funnelStepSequence');
+    expect(source).toContain('stepById');
+    expect(source).toContain('stepComponentById');
+    expect(source).toContain('funnelExperiments');
+  });
+
+  it('does not carry a local copy of shared controller internals', () => {
+    const source = readFileSync(new URL('./use-funnel-flow-controller.ts', import.meta.url), 'utf8');
+
+    expect(source).not.toContain('FIRST_STEP_ENGAGEMENT_THRESHOLD_MS');
+    expect(source).not.toContain('apiService.bootstrapSession');
+    expect(source).not.toContain('apiService.pingUserContext');
+    expect(source).not.toContain('window.setTimeout');
+  });
+});

package/template_scaffold/src/runtime/use-funnel-flow-controller.ts

@@ -0,0 +1,53 @@
+'use client';
+
+import {
+  computeRenderSuspended,
+  useFunnelFlowController as useSharedFunnelFlowController,
+} from '@funnelsgrove/runtime';
+import { publicAnalyticsSdk } from '@funnelsgrove/analytics';
+import { funnelManifest } from '@/config/funnel.manifest';
+import { stepById, stepComponentById } from '@/steps';
+import {
+  defaultFunnelStepId,
+  funnelExperiments,
+  funnelStepSequence,
+  getChoiceTargetsForStep,
+  getPathForStep,
+  getSequentialNextStepId,
+  getStepIdFromPath,
+  isFunnelStepId,
+  resolveConfiguredNextStep,
+  resolveRuntimeInitialStepId,
+  type FunnelStepId,
+} from './funnel-runtime';
+
+type FunnelFlowControllerInput = {
+  initialStepId?: FunnelStepId;
+  lockToInitialStep?: boolean;
+};
+
+export { computeRenderSuspended };
+
+export function useFunnelFlowController({
+  initialStepId = defaultFunnelStepId,
+  lockToInitialStep = false,
+}: FunnelFlowControllerInput = {}) {
+  return useSharedFunnelFlowController<FunnelStepId>({
+    analytics: publicAnalyticsSdk,
+    stepContractVersion: funnelManifest.stepContractVersion,
+    initialStepId,
+    lockToInitialStep,
+    defaultStepId: defaultFunnelStepId,
+    stepSequence: funnelStepSequence,
+    stepById,
+    stepComponentById,
+    funnelExperiments,
+    getPathForStep,
+    getStepIdFromPath,
+    getSequentialNextStepId,
+    getChoiceTargetsForStep,
+    isFunnelStepId,
+    resolveConfiguredNextStep,
+    resolveRuntimeInitialStepId,
+  });
+}

package/template_scaffold/src/steps/content/email-capture.content.ts

@@ -0,0 +1,29 @@
+import type { LocalizedStepContent } from '@funnelsgrove/runtime';
+
+export type EmailCaptureLocaleContent = {
+  kicker: string;
+  title: string;
+  description: string;
+  fieldLabel: string;
+  placeholder: string;
+  submitLabel: string;
+  submittingLabel: string;
+  saveErrorMessage: string;
+};
+
+export const emailCaptureContent = {
+  defaultLocale: 'en',
+  locales: {
+    en: {
+      kicker: 'Before we unlock your plan',
+      title: 'Where should we send your access link?',
+      description:
+        'Enter the email address you want to use for access details, updates, and recovery.',
+      fieldLabel: 'Email address',
+      placeholder: 'you@example.com',
+      submitLabel: 'Continue',
+      submittingLabel: 'Saving...',
+      saveErrorMessage: 'Unable to save email',
+    },
+  },
+} as const satisfies LocalizedStepContent<EmailCaptureLocaleContent>;