@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_scaffold/src/contract/funnel-project.validation.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createFunnelContractDiagnostic,
+  CURRENT_STEP_CONTRACT_HASH,
+  CURRENT_STEP_CONTRACT_VERSION,
+  type FunnelStepContractProjectSnapshot,
+} from '@funnelsgrove/runtime';
+import docsManifest from '../../.funnelsgrove-docs.json';
+import { manifestExperiments } from '@/config/experiments';
+import { funnelManifest, rawFunnelManifest } from '@/config/funnel.manifest';
+import { stepRegistry } from '@/runtime/step-registry';
+import { contentOptionsByStepId } from '@/steps/step-content.registry';
+
+const loadProjectValidation = async () => {
+  return import('./funnel-project.validation');
+};
+
+describe('funnel project validation', () => {
+  it('builds the complete project snapshot from the authored registries', async () => {
+    const projectValidation = await loadProjectValidation();
+
+    expect(projectValidation).not.toBeNull();
+    const snapshot = projectValidation.buildFunnelProjectSnapshot();
+
+    expect(snapshot).toEqual({
+      manifest: rawFunnelManifest,
+      componentMetaByKey: Object.fromEntries(
+        Object.entries(stepRegistry).map(([componentKey, entry]) => [componentKey, entry.meta]),
+      ),
+      registeredComponentKeys: Object.keys(stepRegistry),
+      contentOptionsByStepId,
+      edgesByStepId: rawFunnelManifest.edgesByStepId,
+      experiments: manifestExperiments,
+      docs: {
+        schemaVersion: docsManifest.schemaVersion,
+        bundleVersion: docsManifest.bundleVersion,
+        stepContractVersion: docsManifest.stepContractVersion,
+        contractHash: docsManifest.contractHash,
+        missing: [],
+        changed: [],
+        conflicts: [],
+      },
+    });
+    expect(projectValidation.FUNNEL_PROJECT_CONTRACT_VERSION)
+      .toBe(CURRENT_STEP_CONTRACT_VERSION);
+    expect(funnelManifest).toBe(rawFunnelManifest);
+  });
+
+  it('returns pure authoring diagnostics without changing their fields', async () => {
+    const { buildFunnelProjectSnapshot, validateFunnelProject } = await loadProjectValidation();
+    const snapshot = structuredClone(
+      buildFunnelProjectSnapshot(),
+    ) as FunnelStepContractProjectSnapshot;
+    const paywall = snapshot.componentMetaByKey.stepPaywall;
+    snapshot.componentMetaByKey.stepPaywall = {
+      ...paywall,
+      name: 'renamed-paywall',
+    };
+    const expectedDiagnostic = createFunnelContractDiagnostic({
+      code: 'FG-PARITY-001',
+      file: 'src/steps/step-32-paywall.tsx',
+      stepId: 'paywall',
+      expected: 'paywall',
+      received: 'renamed-paywall',
+      reason: 'Component metadata name does not match the manifest step.',
+      guide: 'docs/product-specs/funnel-template-step-authoring.md',
+      repair: 'Update the component metadata name to match the manifest step.',
+    });
+
+    expect(validateFunnelProject(snapshot)).toEqual([expectedDiagnostic]);
+    expect(snapshot.componentMetaByKey.stepPaywall.name).toBe('renamed-paywall');
+  });
+
+  it('validates the checked-in template without diagnostics', async () => {
+    const { validateFunnelProject } = await loadProjectValidation();
+
+    expect(validateFunnelProject()).toEqual([]);
+    expect(CURRENT_STEP_CONTRACT_HASH).toBe(docsManifest.contractHash);
+  });
+});

package/template_scaffold/src/contract/funnel-project.validation.ts

@@ -0,0 +1,44 @@
+import {
+  CURRENT_STEP_CONTRACT_VERSION,
+  validateFunnelStepContractSnapshot,
+  type FunnelContractDiagnostic,
+  type FunnelStepContractProjectSnapshot,
+  type FunnelStepMeta,
+} from '@funnelsgrove/runtime';
+import docsManifest from '../../.funnelsgrove-docs.json';
+import { manifestExperiments } from '@/config/experiments';
+import { rawFunnelManifest } from '@/config/funnel.manifest';
+import { stepRegistry } from '@/runtime/step-registry';
+import { contentOptionsByStepId } from '@/steps/step-content.registry';
+
+export const FUNNEL_PROJECT_CONTRACT_VERSION = CURRENT_STEP_CONTRACT_VERSION;
+
+export const buildFunnelProjectSnapshot = (): FunnelStepContractProjectSnapshot => {
+  const componentMetaByKey = Object.fromEntries(
+    Object.entries(stepRegistry).map(([componentKey, entry]) => [componentKey, entry.meta]),
+  ) as Record<string, FunnelStepMeta>;
+
+  return {
+    manifest: rawFunnelManifest,
+    componentMetaByKey,
+    registeredComponentKeys: Object.keys(stepRegistry),
+    contentOptionsByStepId,
+    edgesByStepId: rawFunnelManifest.edgesByStepId,
+    experiments: manifestExperiments,
+    docs: {
+      schemaVersion: docsManifest.schemaVersion,
+      bundleVersion: docsManifest.bundleVersion,
+      stepContractVersion: docsManifest.stepContractVersion,
+      contractHash: docsManifest.contractHash,
+      missing: [],
+      changed: [],
+      conflicts: [],
+    },
+  };
+};
+
+export const validateFunnelProject = (
+  snapshot: FunnelStepContractProjectSnapshot = buildFunnelProjectSnapshot(),
+): FunnelContractDiagnostic[] => {
+  return validateFunnelStepContractSnapshot(snapshot, { mode: 'authoring' });
+};

package/template_scaffold/src/contract/funnel-validator.vite.config.ts

@@ -0,0 +1,11 @@
+import { fileURLToPath } from 'node:url';
+
+const sourceRoot = fileURLToPath(new URL('../', import.meta.url));
+
+export default {
+  resolve: {
+    alias: {
+      '@': sourceRoot,
+    },
+  },
+};

package/template_scaffold/src/contract/golden/cancellation_offer.fixture.ts

@@ -0,0 +1,29 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'save-offer',
+  name: 'save-offer',
+  path: '/save-offer',
+  filePath: 'src/steps/step-save-offer.tsx',
+  componentKey: 'stepSaveOffer',
+  type: 'cancellation_offer',
+  kind: 'cancellation',
+  title: 'Stay with us',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'save-offer',
+  name: 'save-offer',
+  type: 'cancellation_offer',
+  kind: 'cancellation',
+  figmaNodeId: 'golden:cancellation-offer',
+  title: 'Stay with us',
+  description: 'Offer a retention path before cancellation.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'cancellation_offer',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime subscription helpers',
+} as const;

package/template_scaffold/src/contract/golden/checkout.fixture.ts

@@ -0,0 +1,37 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'checkout',
+  name: 'checkout',
+  path: '/checkout',
+  filePath: 'src/steps/step-checkout.tsx',
+  componentKey: 'stepCheckout',
+  type: 'checkout',
+  title: 'Secure checkout',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'checkout',
+  name: 'checkout',
+  type: 'checkout',
+  figmaNodeId: 'golden:checkout',
+  title: 'Secure checkout',
+  description: 'Collect payment through shared checkout UI.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'checkout',
+  manifestStep,
+  componentMeta,
+  requiredEventMetadata: [
+    'funnelId',
+    'funnelVersionId',
+    'environment',
+    'stepContractVersion',
+    'stepId',
+    'stepName',
+    'stepType',
+    'eventId',
+  ],
+  semanticHelpers: ['trackCheckoutStarted', 'trackPaymentInfoSubmitted', 'trackCheckoutCompleted'],
+} as const;

package/template_scaffold/src/contract/golden/form_input.fixture.ts

@@ -0,0 +1,28 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'email-capture',
+  name: 'email-capture',
+  path: '/email-capture',
+  filePath: 'src/steps/step-email-capture.tsx',
+  componentKey: 'stepEmailCapture',
+  type: 'form_input',
+  title: 'Your email',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'email-capture',
+  name: 'email-capture',
+  type: 'form_input',
+  figmaNodeId: 'golden:form-input',
+  title: 'Your email',
+  description: 'Capture an email through the transactional helper.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'form_input',
+  manifestStep,
+  componentMeta,
+  helper: 'submitEmailCapture',
+  forbiddenCalls: ['trackLead', 'provider APIs', 'hard-coded paywall navigation'],
+} as const;

package/template_scaffold/src/contract/golden/golden-fixtures.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CURRENT_STEP_CONTRACT_VERSION,
+  FUNNEL_STEP_TYPES,
+  resolveStepTypeContract,
+  validateFunnelManifestContract,
+  validateFunnelStepMetadataParity,
+  type FunnelContextValue,
+  type FunnelManifest,
+} from '@funnelsgrove/runtime';
+import { publicAnalyticsSdk } from '@funnelsgrove/analytics';
+import { goldenFixture as cancellationOffer } from './cancellation_offer.fixture';
+import { goldenFixture as checkout } from './checkout.fixture';
+import { goldenFixture as purchaseCompleted } from './purchase_completed.fixture';
+import { goldenFixture as formInput } from './form_input.fixture';
+import { goldenFixture as introHero } from './intro_hero.fixture';
+import { goldenFixture as multiSelectChoice } from './multi_select_choice.fixture';
+import { goldenFixture as paywallOffer } from './paywall_offer.fixture';
+import { goldenFixture as progressInterstitial } from './progress_interstitial.fixture';
+import { goldenFixture as singleStepChoice } from './single_step_choice.fixture';
+import { goldenFixture as singleStepChoiceEmoji } from './single_step_choice_emoji.fixture';
+import { goldenFixture as socialProof } from './social_proof.fixture';
+import { goldenFixture as subscriptionHandoff } from './subscription_handoff.fixture';
+import { goldenFixture as subscriptionManagement } from './subscription_management.fixture';
+import { goldenFixture as summaryConfirmation } from './summary_confirmation.fixture';
+import { goldenFixture as upsellOffer } from './upsell_offer.fixture';
+import { goldenFixture as valuePropStory } from './value_prop_story.fixture';
+
+const fixtures = [
+  cancellationOffer,
+  checkout,
+  purchaseCompleted,
+  formInput,
+  introHero,
+  multiSelectChoice,
+  paywallOffer,
+  progressInterstitial,
+  singleStepChoice,
+  singleStepChoiceEmoji,
+  socialProof,
+  subscriptionHandoff,
+  subscriptionManagement,
+  summaryConfirmation,
+  upsellOffer,
+  valuePropStory,
+];
+
+const validationFixtures = [
+  introHero,
+  valuePropStory,
+  singleStepChoice,
+  singleStepChoiceEmoji,
+  multiSelectChoice,
+  formInput,
+  socialProof,
+  progressInterstitial,
+  paywallOffer,
+  upsellOffer,
+  checkout,
+  subscriptionManagement,
+  subscriptionHandoff,
+  cancellationOffer,
+  summaryConfirmation,
+  purchaseCompleted,
+];
+
+const commerceSemanticHelpers = [
+  'trackCheckoutStarted',
+  'trackPaymentInfoSubmitted',
+  'trackCheckoutCompleted',
+] as const satisfies readonly (keyof typeof publicAnalyticsSdk)[];
+const terminalSemanticHelpers = (
+  purchaseCompleted.semanticHelpers
+) satisfies readonly (keyof FunnelContextValue)[];
+
+describe('step contract golden fixtures', () => {
+  it('covers all 16 step types exactly once with component/manifest metadata parity', () => {
+    expect(fixtures).toHaveLength(16);
+    expect(new Set(fixtures.map((fixture) => fixture.stepType)).size).toBe(16);
+    expect(fixtures.map((fixture) => fixture.stepType).sort()).toEqual(
+      FUNNEL_STEP_TYPES.filter((type) => (
+        resolveStepTypeContract(CURRENT_STEP_CONTRACT_VERSION, type)
+      )).sort(),
+    );
+    for (const fixture of fixtures) {
+      expect(fixture.manifestStep.type).toBe(fixture.stepType);
+      expect(fixture.componentMeta).toMatchObject({
+        id: fixture.manifestStep.id,
+        name: fixture.manifestStep.name,
+        type: fixture.manifestStep.type,
+      });
+      expect(fixture.manifestStep.filePath).toMatch(/^src\/steps\/.+\.tsx$/);
+      expect(fixture.manifestStep.componentKey).toBeTruthy();
+      expect(fixture.manifestStep.title).toBeTruthy();
+      expect(fixture.componentMeta.figmaNodeId).toBeTruthy();
+      expect(fixture.componentMeta.title).toBeTruthy();
+      expect(fixture.componentMeta.description).toBeTruthy();
+      expect(validateFunnelStepMetadataParity(
+        fixture.manifestStep,
+        fixture.componentMeta,
+      )).toEqual([]);
+    }
+  });
+
+  it('forms one valid self-contained contract-v3 manifest', () => {
+    const manifest = {
+      templateArchitectureVersion: 1,
+      stepContractVersion: CURRENT_STEP_CONTRACT_VERSION,
+      meta: { title: 'Golden fixture funnel', description: 'Validates all canonical types.' },
+      viewport: { width: 430, height: 932 },
+      assets: {},
+      steps: validationFixtures.map((fixture) => fixture.manifestStep),
+      edgesByStepId: Object.fromEntries(validationFixtures.slice(0, -1).map((fixture, index) => [
+        fixture.manifestStep.id,
+        [{ toStepId: validationFixtures[index + 1].manifestStep.id }],
+      ])),
+      experiments: [],
+    } satisfies FunnelManifest;
+
+    expect(validateFunnelManifestContract(manifest, { mode: 'authoring' })).toEqual([]);
+  });
+
+  it('uses stable scalar and array IDs for choice answers', () => {
+    expect(singleStepChoice.persistedAnswer).toBe('daily');
+    expect(singleStepChoiceEmoji.persistedAnswer).toBe('focused');
+    expect(singleStepChoiceEmoji.options.every((option) => Boolean(option.emoji))).toBe(true);
+    expect(multiSelectChoice.persistedAnswer).toEqual(['sleep', 'focus']);
+    expect(multiSelectChoice.emptyAnswer).toEqual([]);
+    expect(multiSelectChoice.manifestStep.choice.allowEmpty).toBe(true);
+    for (const fixture of [singleStepChoice, singleStepChoiceEmoji, multiSelectChoice]) {
+      expect(fixture.manifestStep.choice.answerKey).toBeTruthy();
+      expect(fixture.helper).toBe('useStepChoices');
+    }
+  });
+
+  it('locks reserved identities and trusted conversion ownership', () => {
+    expect(formInput.manifestStep).toMatchObject({ id: 'email-capture', name: 'email-capture' });
+    expect(formInput.helper).toBe('submitEmailCapture');
+    expect(formInput.forbiddenCalls).toEqual(expect.arrayContaining([
+      'trackLead',
+      'provider APIs',
+      'hard-coded paywall navigation',
+    ]));
+    expect(paywallOffer.manifestStep).toMatchObject({
+      id: 'paywall',
+      name: 'paywall',
+      type: 'paywall_offer',
+      kind: 'paywall',
+    });
+    expect(subscriptionManagement.manifestStep).toMatchObject({
+      id: 'manage-subscription',
+      name: 'manage-subscription',
+      kind: 'manage-subscription',
+    });
+    expect(purchaseCompleted.manifestStep).toMatchObject({
+      id: 'subscription-started',
+      name: 'subscription-started',
+      type: 'purchase_completed',
+      kind: 'subscription-handoff',
+    });
+    expect(purchaseCompleted.forbiddenBrowserEvents).toEqual([
+      'purchase_completed',
+      'registration_completed',
+    ]);
+    expect(terminalSemanticHelpers).toEqual(['completeFunnel']);
+    expect(subscriptionHandoff.isRegistrationCompletion).toBe(false);
+    expect(cancellationOffer.manifestStep.kind).toBe('cancellation');
+    expect(upsellOffer.manifestStep.kind).toBe('upsell');
+  });
+
+  it('uses named checkout helpers only on commerce steps', () => {
+    for (const fixture of [paywallOffer, upsellOffer, checkout]) {
+      expect(fixture.semanticHelpers).toEqual(commerceSemanticHelpers);
+    }
+    expect(typeof publicAnalyticsSdk.trackPaymentInfoSubmitted).toBe('function');
+    expect('trackAddPaymentInfo' in publicAnalyticsSdk).toBe(false);
+    expect(progressInterstitial.semanticHelpers).toEqual([]);
+    expect(progressInterstitial.isPaywall).toBe(false);
+    expect(checkout.requiredEventMetadata).toEqual([
+      'funnelId',
+      'funnelVersionId',
+      'environment',
+      'stepContractVersion',
+      'stepId',
+      'stepName',
+      'stepType',
+      'eventId',
+    ]);
+  });
+});

package/template_scaffold/src/contract/golden/intro_hero.fixture.ts

@@ -0,0 +1,27 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'welcome',
+  name: 'welcome',
+  path: '/welcome',
+  filePath: 'src/steps/step-welcome.tsx',
+  componentKey: 'stepWelcome',
+  type: 'intro_hero',
+  title: 'Welcome',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'welcome',
+  name: 'welcome',
+  type: 'intro_hero',
+  figmaNodeId: 'golden:intro-hero',
+  title: 'Welcome',
+  description: 'Opening promise and low-friction entry.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'intro_hero',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'shared-shell',
+} as const;

package/template_scaffold/src/contract/golden/multi_select_choice.fixture.ts

@@ -0,0 +1,37 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const choice = { answerKey: 'priorities', allowEmpty: true } as const;
+
+const manifestStep = {
+  id: 'priorities',
+  name: 'priorities',
+  path: '/priorities',
+  filePath: 'src/steps/step-priorities.tsx',
+  componentKey: 'stepPriorities',
+  type: 'multi_select_choice',
+  choice,
+  title: 'Choose your priorities',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'priorities',
+  name: 'priorities',
+  type: 'multi_select_choice',
+  choice,
+  figmaNodeId: 'golden:multi-select-choice',
+  title: 'Choose your priorities',
+  description: 'Select any priorities that apply.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'multi_select_choice',
+  manifestStep,
+  componentMeta,
+  options: [
+    { id: 'sleep', label: 'Better sleep' },
+    { id: 'focus', label: 'More focus' },
+  ],
+  persistedAnswer: ['sleep', 'focus'],
+  emptyAnswer: [],
+  helper: 'useStepChoices',
+} as const;

package/template_scaffold/src/contract/golden/paywall_offer.fixture.ts

@@ -0,0 +1,30 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'paywall',
+  name: 'paywall',
+  path: '/paywall',
+  filePath: 'src/steps/step-paywall.tsx',
+  componentKey: 'stepPaywall',
+  type: 'paywall_offer',
+  kind: 'paywall',
+  title: 'Choose your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'paywall',
+  name: 'paywall',
+  type: 'paywall_offer',
+  kind: 'paywall',
+  figmaNodeId: 'golden:paywall-offer',
+  title: 'Choose your plan',
+  description: 'Present purchasable plans.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'paywall_offer',
+  manifestStep,
+  componentMeta,
+  presentsPurchasablePlans: true,
+  semanticHelpers: ['trackCheckoutStarted', 'trackPaymentInfoSubmitted', 'trackCheckoutCompleted'],
+} as const;

package/template_scaffold/src/contract/golden/progress_interstitial.fixture.ts

@@ -0,0 +1,28 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'building-plan',
+  name: 'building-plan',
+  path: '/building-plan',
+  filePath: 'src/steps/step-building-plan.tsx',
+  componentKey: 'stepBuildingPlan',
+  type: 'progress_interstitial',
+  title: 'Building your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'building-plan',
+  name: 'building-plan',
+  type: 'progress_interstitial',
+  figmaNodeId: 'golden:progress-interstitial',
+  title: 'Building your plan',
+  description: 'Show progress while preparing the next screen.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'progress_interstitial',
+  manifestStep,
+  componentMeta,
+  semanticHelpers: [],
+  isPaywall: false,
+} as const;

package/template_scaffold/src/contract/golden/purchase_completed.fixture.ts

@@ -0,0 +1,33 @@
+import type { FunnelContextValue, FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const terminalCompletionHelper = 'completeFunnel' as const satisfies keyof FunnelContextValue;
+
+const manifestStep = {
+  id: 'subscription-started',
+  name: 'subscription-started',
+  path: '/subscription-started',
+  filePath: 'src/steps/step-subscription-started.tsx',
+  componentKey: 'stepSubscriptionStarted',
+  type: 'purchase_completed',
+  kind: 'subscription-handoff',
+  title: 'Purchase completed',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'subscription-started',
+  name: 'subscription-started',
+  type: 'purchase_completed',
+  kind: 'subscription-handoff',
+  figmaNodeId: 'golden:purchase-completed',
+  title: 'Purchase completed',
+  description: 'Complete the funnel after purchase and continue into the app.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'purchase_completed',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime handoff helper',
+  semanticHelpers: [terminalCompletionHelper],
+  forbiddenBrowserEvents: ['purchase_completed', 'registration_completed'],
+} as const;

package/template_scaffold/src/contract/golden/single_step_choice.fixture.ts

@@ -0,0 +1,36 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const choice = { answerKey: 'routine' } as const;
+
+const manifestStep = {
+  id: 'routine',
+  name: 'routine',
+  path: '/routine',
+  filePath: 'src/steps/step-routine.tsx',
+  componentKey: 'stepRoutine',
+  type: 'single_step_choice',
+  choice,
+  title: 'Choose a routine',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'routine',
+  name: 'routine',
+  type: 'single_step_choice',
+  choice,
+  figmaNodeId: 'golden:single-step-choice',
+  title: 'Choose a routine',
+  description: 'Select exactly one routine.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'single_step_choice',
+  manifestStep,
+  componentMeta,
+  options: [
+    { id: 'daily', label: 'Every day' },
+    { id: 'weekdays', label: 'Weekdays' },
+  ],
+  persistedAnswer: 'daily',
+  helper: 'useStepChoices',
+} as const;

package/template_scaffold/src/contract/golden/single_step_choice_emoji.fixture.ts

@@ -0,0 +1,36 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const choice = { answerKey: 'goalFeeling' } as const;
+
+const manifestStep = {
+  id: 'goal-feeling',
+  name: 'goal-feeling',
+  path: '/goal-feeling',
+  filePath: 'src/steps/step-goal-feeling.tsx',
+  componentKey: 'stepGoalFeeling',
+  type: 'single_step_choice_emoji',
+  choice,
+  title: 'How do you want to feel?',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'goal-feeling',
+  name: 'goal-feeling',
+  type: 'single_step_choice_emoji',
+  choice,
+  figmaNodeId: 'golden:single-step-choice-emoji',
+  title: 'How do you want to feel?',
+  description: 'Select exactly one emoji-led feeling.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'single_step_choice_emoji',
+  manifestStep,
+  componentMeta,
+  options: [
+    { id: 'focused', label: 'Focused', emoji: '🎯' },
+    { id: 'calm', label: 'Calm', emoji: '🌿' },
+  ],
+  persistedAnswer: 'focused',
+  helper: 'useStepChoices',
+} as const;