@funnelsgrove/cli 0.1.14 → 0.1.18

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

@@ -0,0 +1,122 @@
+# `single_step_choice`
+
+## Use when / do not use when
+
+Use when exactly one standard option completes the step on selection. Do not use for emoji-led choices, multi-select, or a separate form submission.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/single_step_choice -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `single_step_choice`
+- Family: `choice`
+- Description: Exactly one standard option is selected.
+- Action owner: `step`
+- 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: `one`
+- Presentation: `standard`
+- Completion: `selection`
+- Allow empty config: `false`
+
+#### 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: '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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/single_step_choice -->
+
+## Interaction and persisted answer shape
+
+Declare `choice.answerKey` in both metadata copies. Persist one stable option ID as a scalar string, never the label or an object.
+
+## Automatic lifecycle events
+
+`useStepChoices` coordinates the answer write with the controller-owned completion lifecycle. Preview keeps provider delivery suppressed.
+
+## Required semantic conversions
+
+None. Selecting an option is answer state plus automatic lifecycle completion.
+
+## Approved shared helpers
+
+Use `useStepChoices`; let it complete and route after the stable ID is persisted.
+
+## MUST rules
+
+- Give every option a stable ID that survives copy changes.
+- Keep the manifest and component `choice.answerKey` identical.
+
+## NEVER rules
+
+- Never call answer SDK methods directly from the choice component.
+- Never store a display label, index, or whole option object.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `single_step_choice.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Select every option once; confirm exactly one stable ID is saved and each selection completes/routes only once.

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

@@ -0,0 +1,122 @@
+# `single_step_choice_emoji`
+
+## Use when / do not use when
+
+Use when exactly one emoji-led option completes on selection. Do not use when emoji is merely decorative on a standard list or when multiple answers are allowed.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/single_step_choice_emoji -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `single_step_choice_emoji`
+- Family: `choice`
+- Description: Exactly one emoji-led option is selected.
+- Action owner: `step`
+- 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: `one`
+- Presentation: `emoji`
+- Completion: `selection`
+- Allow empty config: `false`
+
+#### 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: '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;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/single_step_choice_emoji -->
+
+## Interaction and persisted answer shape
+
+Declare `choice.answerKey`; every option includes an emoji and stable ID. Persist the selected ID as a scalar string.
+
+## Automatic lifecycle events
+
+`useStepChoices` coordinates persistence, controller completion, and manifest routing. Preview suppresses provider delivery.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use `useStepChoices` and the shared emoji-choice rendering pattern.
+
+## MUST rules
+
+- Provide meaningful emoji data for every option.
+- Keep IDs stable when labels or emoji change.
+
+## NEVER rules
+
+- Never persist emoji or labels as the answer.
+- Never bypass the choice helper.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `single_step_choice_emoji.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm keyboard and pointer selection both save one stable ID, show the intended emoji, and advance once.

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

@@ -0,0 +1,110 @@
+# `social_proof`
+
+## Use when / do not use when
+
+Use for testimonials, reviews, credibility, or evidence. Do not use for general benefits, a survey, or an offer.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/social_proof -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `social_proof`
+- Family: `content`
+- Description: Testimonials, reviews, credibility, or evidence.
+- 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: 'member-results',
+  name: 'member-results',
+  path: '/member-results',
+  filePath: 'src/steps/step-member-results.tsx',
+  componentKey: 'stepMemberResults',
+  type: 'social_proof',
+  title: 'Member results',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'member-results',
+  name: 'member-results',
+  type: 'social_proof',
+  figmaNodeId: 'golden:social-proof',
+  title: 'Member results',
+  description: 'Show attributable testimonials and evidence.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'social_proof',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'shared-shell',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/social_proof -->
+
+## Interaction and persisted answer shape
+
+This content screen does not persist an answer. Standard progression belongs to the shared shell.
+
+## Automatic lifecycle events
+
+The controller owns lifecycle tracking and suppresses provider delivery in preview.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use shared content/image components and the shared action bar.
+
+## MUST rules
+
+- Keep proof content attributable and builder-editable where required.
+- Keep metadata parity.
+
+## NEVER rules
+
+- Never turn proof interactions into invented conversion events.
+- Never call providers directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `social_proof.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm all proof content and assets render accessibly at supported breakpoints and Continue follows manifest routing.

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

@@ -0,0 +1,113 @@
+# `subscription_handoff`
+
+## Use when / do not use when
+
+Use for a non-terminal app, store, or deep-link handoff. Do not use for the canonical post-purchase registration-completion terminal.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/subscription_handoff -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `subscription_handoff`
+- Family: `commerce`
+- Description: A non-terminal app, store, or deep-link handoff.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: `subscription-handoff`
+- Allowed kinds: `subscription-handoff`
+- Allowed semantic events: _None_
+- 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
+
+_No reserved identity for this type._
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'open-app',
+  name: 'open-app',
+  path: '/open-app',
+  filePath: 'src/steps/step-open-app.tsx',
+  componentKey: 'stepOpenApp',
+  type: 'subscription_handoff',
+  kind: 'subscription-handoff',
+  title: 'Continue in the app',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'open-app',
+  name: 'open-app',
+  type: 'subscription_handoff',
+  kind: 'subscription-handoff',
+  figmaNodeId: 'golden:subscription-handoff',
+  title: 'Continue in the app',
+  description: 'Continue through a non-terminal app handoff.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'subscription_handoff',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime handoff helper',
+  isRegistrationCompletion: false,
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/subscription_handoff -->
+
+## Interaction and persisted answer shape
+
+Build the outbound destination through the runtime handoff helper. This screen persists no choice answer.
+
+## Automatic lifecycle events
+
+Leaving through the handoff is not funnel registration completion. The controller owns the step outcome.
+
+## Required semantic conversions
+
+None. This non-terminal handoff must not emit funnel or registration completion.
+
+## Approved shared helpers
+
+Use the runtime subscription-handoff helper with the safe default `SubscriptionHandoffScreen` completion mode of `step`; never opt a non-terminal handoff into `completionMode="funnel"`.
+
+## MUST rules
+
+- Treat the destination as configuration/runtime data.
+- Keep non-terminal semantics explicit.
+
+## NEVER rules
+
+- Never emit trusted `purchase_completed`, `registration_completed`, or terminal `funnel_completed`.
+- Never build an unvalidated deep link by string concatenation.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `subscription_handoff.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test installed/uninstalled destinations, query propagation, return behavior, and absence of completion conversions.

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

@@ -0,0 +1,112 @@
+# `subscription_management`
+
+## Use when / do not use when
+
+Use to inspect or manage an existing subscription. Do not use for an acquisition paywall, cancellation save offer, or app handoff.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/subscription_management -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `subscription_management`
+- Family: `commerce`
+- Description: A screen for managing or inspecting an existing subscription.
+- Action owner: `step`
+- Analytics role: _none_
+- Terminal: `false`
+- Required kind: `manage-subscription`
+- Allowed kinds: `manage-subscription`
+- Allowed semantic events: _None_
+- Forbidden capabilities: `choice-write`, `email-capture`, `checkout`, `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
+
+- `subscription-management` must be owned by `runtime-subscription-helpers`.
+
+#### Reserved identities
+
+- `manage-subscription`: id=`manage-subscription`, name=`manage-subscription`; type=`subscription_management`; kind=`manage-subscription`; unique=`true`
+
+#### Golden fixture source
+
+```ts
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'manage-subscription',
+  name: 'manage-subscription',
+  path: '/manage-subscription',
+  filePath: 'src/steps/step-manage-subscription.tsx',
+  componentKey: 'stepManageSubscription',
+  type: 'subscription_management',
+  kind: 'manage-subscription',
+  title: 'Manage subscription',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'manage-subscription',
+  name: 'manage-subscription',
+  type: 'subscription_management',
+  kind: 'manage-subscription',
+  figmaNodeId: 'golden:subscription-management',
+  title: 'Manage subscription',
+  description: 'Inspect and manage an existing subscription.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'subscription_management',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime subscription helpers',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/subscription_management -->
+
+## Interaction and persisted answer shape
+
+Load and mutate subscription state through runtime subscription helpers. This screen does not persist funnel choice answers.
+
+## Automatic lifecycle events
+
+The controller owns step lifecycle; subscription APIs own account-state changes.
+
+## Required semantic conversions
+
+None unless a separately defined server-owned subscription event exists.
+
+## Approved shared helpers
+
+Use runtime subscription-management helpers and manifest routing.
+
+## MUST rules
+
+- Preserve the reserved management identity.
+- Refresh visible state after a successful management action.
+
+## NEVER rules
+
+- Never expose secrets or call a provider with browser credentials.
+- Never relabel this screen as a paywall.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `subscription_management.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Test loading, empty state, action success/failure, refresh, back/exit, and exact reserved metadata.

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

@@ -0,0 +1,110 @@
+# `summary_confirmation`
+
+## Use when / do not use when
+
+Use for a summary, review, or confirmation before the next action. Do not use for choice collection, a progress reveal, or an offer.
+
+## Exact metadata contract
+
+<!-- funnelsgrove:generated:start contract-v3/step/summary_confirmation -->
+### Generated contract facts — do not edit
+
+- Step contract version: `3`
+- Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`
+- Type: `summary_confirmation`
+- Family: `content`
+- Description: A summary, review, or confirmation before the next action.
+- 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: 'review-plan',
+  name: 'review-plan',
+  path: '/review-plan',
+  filePath: 'src/steps/step-review-plan.tsx',
+  componentKey: 'stepReviewPlan',
+  type: 'summary_confirmation',
+  title: 'Review your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'review-plan',
+  name: 'review-plan',
+  type: 'summary_confirmation',
+  figmaNodeId: 'golden:summary-confirmation',
+  title: 'Review your plan',
+  description: 'Review existing answers before continuing.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'summary_confirmation',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'either',
+} as const;
+```
+<!-- funnelsgrove:generated:end contract-v3/step/summary_confirmation -->
+
+## Interaction and persisted answer shape
+
+Read existing answers through runtime state. Only edit an answer through its owning input/choice flow.
+
+## Automatic lifecycle events
+
+The controller owns completion and exit. Preview suppresses provider delivery.
+
+## Required semantic conversions
+
+None.
+
+## Approved shared helpers
+
+Use runtime answer readers, shared action UI, and manifest routing.
+
+## MUST rules
+
+- Render stable answer meaning, not internal object dumps.
+- Keep confirmation and edit routes manifest-owned.
+
+## NEVER rules
+
+- Never invent a completion conversion for viewing a summary.
+- Never mutate answer storage directly.
+
+## Golden template or fixture
+
+See the [embedded canonical fixture](#golden-fixture-source) generated from `summary_confirmation.fixture.ts`.
+
+## Validation command
+
+Run `fgrove validate`.
+
+## Manual QA and completion criteria
+
+Confirm empty/populated answers, edit-return behavior, accessibility, and exactly-once completion through the controller.