@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_docs/docs/funnelsgrove/steps/form_input.md

@@ -0,0 +1,115 @@
+# `form_input`
+
+## Use when / do not use when
+
+Use for non-choice structured input. The reserved email-capture screen also uses this type. Do not use for option lists or payment-entry forms.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/form_input -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `form_input`
+- Family: `form`
+- Description: Non-choice structured input, including reserved email capture.
+- Action owner: `either`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: `email_captured`
+- Forbidden capabilities: `choice-write`, `checkout`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `email-capture` must be owned by `submitEmailCapture`.
+
+#### Reserved identities
+
+- `email-capture`: id=`email-capture`, name=`email-capture`; type=`form_input`; unique=`true`
+
+#### Golden fixture source
+
+```ts
+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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/form_input -->
+
+## Interaction and persisted answer shape
+
+Validate local input before submission. For the reserved email screen, pass the email to `submitEmailCapture`; the helper owns persistence, event creation, lifecycle completion, and routing.
+
+## Automatic lifecycle events
+
+The controller owns lifecycle events. A failed email request leaves state, lifecycle, and navigation unchanged. Preview makes no API or provider call.
+
+## Required semantic conversions
+
+The reserved email screen produces `email_captured` transactionally on the server. Only a newly created conversion may fan out browser Pixel/Google events with the returned event ID.
+
+## Approved shared helpers
+
+Use `submitEmailCapture`. Use the manifest flow controller for the next route.
+
+## MUST rules
+
+- Keep the reserved email identity exact.
+- Disable duplicate submits while one request is in flight.
+- Complete only after the API succeeds.
+
+## NEVER rules
+
+- Never call `trackLead`, PostHog, Meta CAPI, Pixel, Google, or any provider directly.
+- Never generate a browser event ID or hard-code paywall navigation.
+- Never put raw email or other PII in analytics event metadata or logs.
+- Only the server delivery boundary may use raw email as Meta hashing input.
+- PostHog properties must remain non-PII.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `form_input.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test success, duplicate, API failure, double-submit, preview, and stale-visit cases; verify only a newly created conversion triggers browser fanout.

package/template_docs/docs/funnelsgrove/steps/intro_hero.md

@@ -0,0 +1,110 @@
+# `intro_hero`
+
+## Use when / do not use when
+
+Use for the opening promise or a low-friction entry screen. Do not use for a questionnaire, reveal, offer, or checkout.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/intro_hero -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `intro_hero`
+- Family: `content`
+- Description: Opening promise or low-friction entry screen.
+- Action owner: `shared-shell`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: _None_
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+_No special capability is allowed._
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/intro_hero -->
+
+## Interaction and persisted answer shape
+
+This content screen does not persist an answer. Put its primary progression action in the shared shell.
+
+## Automatic lifecycle events
+
+The flow controller owns the applicable automatic view, start, completion, and exit events. `step_engaged` is registered as non-automatic and is not emitted by default. Only an explicit, centralized, tested engagement policy may emit it through the approved controller/helper boundary; step components never emit it manually. Preview suppresses lifecycle delivery.
+
+## Required semantic conversions
+
+None. A hero CTA is navigation, not a conversion event.
+
+## Approved shared helpers
+
+Use `useFunnel()` only when the view needs controller state; use the shared action bar for normal Continue behavior.
+
+## MUST rules
+
+- Keep the component and manifest metadata identical.
+- Keep the opening action low-friction and let the manifest choose the next step.
+
+## NEVER rules
+
+- Never write answers or call an analytics provider.
+- Never hard-code the next route.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `intro_hero.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm the screen starts the funnel once, the CTA advances through manifest routing, and back/exit behavior records the correct lifecycle outcome.

package/template_docs/docs/funnelsgrove/steps/multi_select_choice.md

@@ -0,0 +1,123 @@
+# `multi_select_choice`
+
+## Use when / do not use when
+
+Use when zero or more options can be selected before an explicit Continue action. Do not use for single-selection or implicit selection-to-advance behavior.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/multi_select_choice -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `multi_select_choice`
+- Family: `choice`
+- Description: Multiple options are selected before explicit completion.
+- Action owner: `either`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: _None_
+- Forbidden capabilities: `email-capture`, `checkout`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+- Cardinality: `many`
+- Presentation: `standard`
+- Completion: `explicit`
+- Allow empty config: `true`
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `choice-write` must be owned by `useStepChoices`.
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/multi_select_choice -->
+
+## Interaction and persisted answer shape
+
+Declare `choice.answerKey` and the intended `allowEmpty` value. Persist an array of stable option IDs; an allowed empty selection is `[]`.
+
+## Automatic lifecycle events
+
+`useStepChoices` coordinates array persistence and explicit completion. Preview suppresses provider delivery.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use `useStepChoices` for toggles, saving, completion, and routing.
+
+## MUST rules
+
+- Preserve stable IDs and exact array shape.
+- Make Continue state match `allowEmpty`.
+
+## NEVER rules
+
+- Never store comma-separated text, labels, or option objects.
+- Never auto-advance on the first selection.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `multi_select_choice.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test select, deselect, reload, and empty-state behavior; confirm one ID array persists and explicit Continue completes once.

package/template_docs/docs/funnelsgrove/steps/paywall_offer.md

@@ -0,0 +1,115 @@
+# `paywall_offer`
+
+## Use when / do not use when
+
+Use only for a monetization screen that presents purchasable plans. Do not use for a loading, calculation, reveal, or pre-offer bridge.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/paywall_offer -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `paywall_offer`
+- Family: `commerce`
+- Description: A monetization offer that presents purchasable plans.
+- Action owner: `step`
+- Analytics role: `paywall`
+- Terminal: `false`
+- Required kind: `paywall`
+- Allowed kinds: `paywall`
+- Allowed semantic events: `checkout_started`, `add_payment_info`, `checkout_completed`
+- Forbidden capabilities: `choice-write`, `email-capture`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `checkout` must be owned by `named-payment-helpers`.
+
+#### Reserved identities
+
+- `paywall`: id=`paywall`, name=`paywall`; type=`paywall_offer`; kind=`paywall`; primary=`true`; unique=`true`
+- `paywall-variant`: idPattern=`^paywall-[a-z0-9-]+$`, namePattern=`^paywall-[a-z0-9-]+$`; type=`paywall_offer`; kind=`paywall`; primary=`false`; unique=`false`
+
+#### Golden fixture source
+
+```ts
+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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/paywall_offer -->
+
+## Interaction and persisted answer shape
+
+Resolve offers and plans through shared payments configuration. Do not persist plan data as a choice answer.
+
+## Automatic lifecycle events
+
+The controller owns view/start/completion/exit lifecycle. Closing or leaving without purchase is an exit, not a completion.
+
+## Required semantic conversions
+
+Use named helpers for checkout started, payment info, and checkout completed at their real boundaries with one stable event ID.
+
+## Approved shared helpers
+
+Use shared plan resolution, checkout, wallet, and `trackCheckoutStarted`, `trackPaymentInfoSubmitted`, and `trackCheckoutCompleted` helpers.
+
+## MUST rules
+
+- Keep the primary paywall identity exact; variants use contract-compliant distinct identities.
+- Present at least one purchasable plan.
+- Read prices, discounts, provider IDs, and payment mode from shared configuration.
+
+## NEVER rules
+
+- Never classify a reveal/interstitial as a paywall.
+- Never put secrets, provider IDs, amount math, or provider analytics in JSX.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `paywall_offer.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Verify plans and discounts, every payment method, decline/retry, checkout event metadata/deduplication, cancel/exit, and manifest routing after success.

package/template_docs/docs/funnelsgrove/steps/progress_interstitial.md

@@ -0,0 +1,111 @@
+# `progress_interstitial`
+
+## Use when / do not use when
+
+Use for progress, calculation, loading, reveal, or transition. Do not use for a screen that presents purchasable plans: that is a paywall offer.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/progress_interstitial -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `progress_interstitial`
+- Family: `transition`
+- Description: Progress, calculation, loading, reveal, or transition screen.
+- Action owner: `either`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: _none_
+- Allowed kinds: _None_
+- Allowed semantic events: _None_
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `subscription-management`, `subscription-handoff`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+_No special capability is allowed._
+
+#### Reserved identities
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/progress_interstitial -->
+
+## Interaction and persisted answer shape
+
+This transition does not persist a choice answer. An automatic delay or explicit Continue may complete it through the controller.
+
+## Automatic lifecycle events
+
+The controller distinguishes completion from abandonment and suppresses provider delivery in preview.
+
+## Required semantic conversions
+
+None. A reveal or “your plan is ready” transition is not a paywall or checkout conversion.
+
+## Approved shared helpers
+
+Use shared progress/action primitives and manifest routing.
+
+## MUST rules
+
+- Keep automatic completion cancellable when the visit becomes stale.
+- Classify by actual interaction, not by funnel position.
+
+## NEVER rules
+
+- Never set paywall identity or emit checkout semantics.
+- Never hard-code a paywall destination.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `progress_interstitial.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm timer/manual completion fires once, leaving early records an exit, and no paywall or checkout event appears.

package/template_docs/docs/funnelsgrove/steps/purchase_completed.md

@@ -0,0 +1,117 @@
+# `purchase_completed`
+
+## Use when / do not use when
+
+Use for the canonical terminal after an initial subscription or one-time purchase flow. Do not use for a generic handoff, receipt, renewal, or pre-purchase summary. Entering this screen does not prove that the backend verified payment.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/purchase_completed -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `purchase_completed`
+- Family: `terminal`
+- Description: The canonical terminal shown after a verified initial purchase.
+- Action owner: `step`
+- Analytics role: `purchase-completed`
+- Terminal: `true`
+- Required kind: `subscription-handoff`
+- Allowed kinds: `subscription-handoff`
+- Allowed semantic events: `funnel_completed`
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `subscription-management`, `hardcoded-navigation`, `provider-direct-analytics`, `browser-registration-completed`
+
+#### Choice contract
+
+_Not a choice type._
+
+#### Automatic lifecycle events
+
+`first_step_clicked`, `first_step_viewed`, `funnel_started`, `step_completed`, `step_exited`, `step_started`
+
+#### Approved capability owners
+
+- `subscription-handoff` must be owned by `runtime-handoff-helper`.
+
+#### Reserved identities
+
+- `subscription-started`: id=`subscription-started`, name=`subscription-started`; type=`purchase_completed`; kind=`subscription-handoff`; unique=`true`
+
+#### Golden fixture source
+
+```ts
+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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/purchase_completed -->
+
+## Interaction and persisted answer shape
+
+The runtime terminal/handoff helper owns completion and destination construction. No choice answer is persisted.
+
+## Automatic lifecycle events
+
+`completeFunnel(stepId)` atomically claims the active terminal visit, emits the normal step completion and one deduplicated `funnel_completed`, then flushes before outbound handoff. Preview/editor still claims the local completion outcome while suppressing persistence and provider delivery.
+
+## Required semantic conversions
+
+The browser may request lifecycle-only funnel completion. The business conversion `purchase_completed` is trusted-server-only after the backend verifies a successful initial subscription or one-time payment. `registration_completed` remains a separate later app-link claim.
+
+## Approved shared helpers
+
+Use `completeFunnel` through the runtime handoff surface. The reserved terminal passes `completionMode="funnel"` to `SubscriptionHandoffScreen`; the shared component defaults to `completionMode="step"` for non-terminal handoffs.
+
+## MUST rules
+
+- Preserve the reserved `subscription-started` identity.
+- Complete the funnel once before the app handoff.
+- Keep terminal completion mode explicit; only the current `purchase_completed` terminal may call `completeFunnel`.
+
+## NEVER rules
+
+- Never emit `purchase_completed` in browser code.
+- Never treat terminal reach, `funnel_completed`, a pending payment, or a renewal as purchase verification.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `purchase_completed.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm funnel completion is deduplicated, the trusted purchase event requires backend verification, preview is silent, and the app destination works.