@funnelsgrove/cli 0.1.9 → 0.1.11

package/template_docs/docs/editing-step.md

@@ -1,66 +1,125 @@
-# Editing or Creating a Step
+# Adding or Editing a Step
 
-A step is one screen or decision point. Keep its view, local state, validation, and step-specific CSS in the step file. Keep editable copy/images in a matching content file and builder fields in a matching editor file.
+A step is one screen, one decision. Target: a new step compiles and renders in local preview in under 3 minutes. Exactly six files are involved — no others.
 
-## Source Files
+| # | File | What goes there |
+| --- | --- | --- |
+| 1 | `src/steps/step-NN-<name>.tsx` | View, step meta, local state, one-off CSS |
+| 2 | `src/steps/content/step-NN-<name>.content.ts` | All copy and image refs (localized) |
+| 3 | `src/steps/editor/step-NN-<name>.editor.ts` | Which content fields the builder may edit |
+| 4 | `src/runtime/step-registry.ts` | `componentKey` → component + meta |
+| 5 | `src/steps/step-content.registry.ts` | step id → content/editor file paths |
+| 6 | `src/config/funnel.manifest.ts` | Step entry + `edgesByStepId` routing |
 
-For an existing step, start from `src/config/funnel.manifest.ts` and find:
+Before writing UI, read [step-ui-guidelines.md](step-ui-guidelines.md) — it defines the layout shell, the sticky action bar, and the viewport rules every step must pass.
 
-- `steps[].id`: stable route/runtime id, such as `paywall`.
-- `steps[].path`: URL path, such as `/paywall`.
-- `steps[].filePath`: React view file, such as `src/steps/step-32-paywall.tsx`.
-- `steps[].componentKey`: key registered in `src/runtime/step-registry.ts`.
+## Naming and URLs
 
-Most steps also have:
+Files may use ordered names like `step-07-motivation.tsx`, and step ids may stay
+sequential if the existing funnel uses sequential ids. Public route paths must
+be meaningful product slugs. Use `/motivation`, `/fitness-goal`, or
+`/email-capture`; do not create routes like `/step-1`, `/step-07`, or
+`/question-3`.
 
-- `src/steps/content/<step>.content.ts`: localized content using `LocalizedStepContent`.
-- `src/steps/editor/<step>.editor.ts`: builder editor fields using `StepEditorSection`.
-- `src/steps/step-content.registry.ts`: maps the runtime step id to those content/editor files.
+## Recipe: New Step
 
-## View Pattern
+Copy the closest existing step as the starting point (`step-02` for selections, `step-03` for interstitials). Then:
 
-Step files usually export:
+**1. View** — `src/steps/step-07-motivation.tsx`:
 
-- A stable `stepXId`.
-- A `FunnelStepMeta` object with `id`, `type`, `title`, optional `kind`, and optional `actionBar`.
-- A React component that reads content with `usePreviewStepLocalizedContent(...)` or the funnel's wrapper, such as `useClaimbeeStepContent(...)`.
+```tsx
+export const stepMotivationId = 'motivation';
+
+export const stepMotivation: FunnelStepMeta = {
+  id: stepMotivationId,
+  name: 'motivation',
+  type: 'single_step_choice',
+  title: 'Motivation',
+  description: 'Asks the user what motivates them.',
+  actionBar: { buttonText: 'Continue' }, // omit for auto-advance; { hidden: true } if the step owns its CTA
+};
+
+export function StepMotivation() {
+  const { attributes, setAnswer, goNext } = useFunnel();
+  const content = usePreviewStepLocalizedContent(
+    stepMotivationId,
+    stepMotivationContent,
+    getStepContentLocale(attributes),
+  );
+  // render options; on select: setAnswer('motivation', id) then goNext() for auto-advance
+  return (
+    <>
+      <section className='motivation-step'>...</section>
+      <style>{stepStyles}</style>
+    </>
+  );
+}
+
+const stepStyles = `...one-off CSS only...`;
+```
 
-Use `useFunnel()` for runtime state:
+**2. Content** — `src/steps/content/step-07-motivation.content.ts`: export a `LocalizedStepContent` object holding every user-visible string and image. The view must not contain literal copy.
 
-- `answers` / `attributes`: current funnel answers.
-- `setAnswer(key, value)` or `setAttribute(key, value)`: store data another step needs.
-- `goNext()`, `goToStep(stepId)`, or `goChoice('yes' | 'no')`: navigate through the manifest.
-- `user`, `setUser`, `completeStep`: only when the step explicitly needs user/session behavior.
+**3. Editor** — `src/steps/editor/step-07-motivation.editor.ts`: export `StepEditorSection[]` exposing only the fields a non-developer should edit (see an existing editor file for the field kinds).
 
-Do not bypass the flow controller with raw `window.location` for normal funnel navigation.
+**4. Register the component** — `src/runtime/step-registry.ts`:
 
-## CSS Pattern
+```ts
+stepMotivation: { component: StepMotivation, meta: stepMotivation },
+```
 
-Keep one-off step styling at the bottom of the step file:
+**5. Register content/editor** — `src/steps/step-content.registry.ts`:
 
-```tsx
-return (
-  <>
-    <section className='claimbee-step'>...</section>
-    <style>{stepStyles}</style>
-  </>
-);
-
-const stepStyles = `
-.claimbee-step { ... }
-`;
+```ts
+motivation: {
+  contentPath: 'src/steps/content/step-07-motivation.content.ts',
+  editorPath: 'src/steps/editor/step-07-motivation.editor.ts',
+},
 ```
 
-Use shared CSS under `src/steps/styles/shared/` only for patterns reused by multiple steps. Do not move one-off Figma parity or paywall-specific styling into shared files.
+**6. Manifest + routing** — `src/config/funnel.manifest.ts`:
+
+```ts
+// steps[]
+{
+  id: 'motivation',
+  path: '/motivation', // meaningful public URL, not '/step-07'
+  filePath: 'src/steps/step-07-motivation.tsx',
+  componentKey: 'stepMotivation',
+  type: 'single_step_choice',
+  title: 'Motivation',
+},
+// edgesByStepId — wire it in AND give it an exit
+'step-2': [{ toStepId: 'motivation' }],
+motivation: [{ toStepId: 'step-3' }],
+```
+
+**Verify:** `npm run dev`, open `/motivation`, confirm it renders at 430x932 and 390x844, Continue (or auto-advance) lands on the next step, and `npm run test:run && npm run lint` pass.
+
+## Editing an Existing Step
+
+Find the step in `src/config/funnel.manifest.ts` by `id` — `filePath` points at the view, `componentKey` at the registry entry. Copy changes go in the `content/` file, never inline in the view. Behavior changes go in the view file. Re-run the verify line above for the edited step.
+
+## Navigation Inside a Step
+
+Use `useFunnel()` only:
+
+- `setAnswer(key, value)` / `setAttribute(key, value)` — store data another step needs.
+- `goNext()` — normal manifest progression.
+- `goChoice('yes' | 'no')` — when the manifest has conditional edges for this step.
+- `goToStep(stepId)` — explicit jumps (paywall success, manage-subscription return).
+
+Never navigate with raw `window.location`, and never encode experiment routing in the step ([ab-experiments.md](ab-experiments.md) handles that in config).
+
+## CSS
 
-## Creating a Step
+One-off styling lives in a `const stepStyles` string at the bottom of the step file. Shared styling under `src/steps/styles/shared/` only when several steps already use the same pattern. Do not move paywall-specific styling into shared files.
 
-1. Add the view file in `src/steps/`.
-2. Add `content/<step>.content.ts` with the exact content shape the view needs.
-3. Add `editor/<step>.editor.ts` exposing only fields that should be editable.
-4. Register the component in `src/runtime/step-registry.ts`.
-5. Add content/editor paths in `src/steps/step-content.registry.ts`.
-6. Add the step and route edge in `src/config/funnel.manifest.ts`.
-7. Add focused tests when changing routing, state, checkout, parsing, or non-trivial UI behavior.
+## Rules
 
-Preserve existing ids unless the work is an explicit migration. A renamed step id changes routes, persisted answers, analytics, builder preview patches, and publish history.
+- Keep `id`, `path`, and answer keys stable — renames break routes, persisted answers, analytics, and publish history.
+- For new steps, use a meaningful `path`. Sequential ids and filenames are fine
+  when they match the project, but public URLs should not be `/step-1` style
+  routes.
+- Every step needs an outgoing edge (except terminal steps like subscription handoff).
+- Add a focused test when changing routing, state, checkout, parsing, or non-trivial UI logic.

package/template_docs/docs/payment-plans-and-discounts.md

@@ -33,6 +33,17 @@ Discounts use `BillingDiscountList` or `BillingDiscountCatalog` and are resolved
 
 Use `resolvePaywallDiscountState(...)`, `advancePaywallDiscountState(...)`, `activateSecondPaywallDiscount(...)`, `serializePaywallDiscountState(...)`, and `buildDiscountedPaywallPlans(...)`. Store discount state through runtime paywall state helpers (`readPaywallStateValue`, `updatePaywallStateValue`) so it is scoped by funnel id.
 
+### Discount on Closing Checkout
+
+The standard two-stage flow, wired in the paywall step:
+
+1. Paywall opens with the first-stage discount applied to plan cards.
+2. The checkout controller's `onFirstCheckoutClosed` callback fires when the visitor closes the card checkout without paying. The paywall opens `SharedCheckoutSpecialOfferDialog` (image, discount label, accept button — copy lives in the paywall content file).
+3. Accepting calls `activateSecondPaywallDiscount(...)`, which swaps to the stronger second-stage coupon, restarts its window, and re-renders plans via `buildDiscountedPaywallPlans(...)`.
+4. The next checkout open carries the second-stage coupon id in its payload.
+
+Keep both stages testable: QA must verify stage one on open and stage two after a checkout close ([qa-checklist.md](qa-checklist.md), paywall item 5).
+
 ## Checkout
 
 Prefer shared Stripe surfaces:

package/template_docs/docs/publishing-and-versioning.md

@@ -26,6 +26,18 @@ fgrove publish --env production --domain <domain> --message '<summary>'
 
 Production publish requires a domain. Preview publish returns a deployment URL, version sequence, and version id.
 
+## Publish Image Optimization
+
+Publish builds reduce raster image size before upload. Keep this path enabled:
+PNG/JPEG sources are compressed, AVIF/WebP variants are generated for supported
+browsers, and the original image remains the fallback. Do not bypass this with
+remote funnel-critical image URLs.
+
+After publishing image edits or a production candidate, check the deployment
+metadata, CLI output, or `publishBuild.stageTimings.imageVariants`. If the
+image-variant stage is missing or unavailable, report that explicitly before
+calling the publish ready.
+
 ## Local Sync Contract
 
 The CLI writes `.funnelsgrove-sync.json` into the local tree. Keep it there. It records workspace id, funnel id, and current draft version id so later `sync up` can patch only changed/deleted files.

package/template_docs/docs/qa-checklist.md

@@ -0,0 +1,73 @@
+# QA Checklist
+
+What to test, where to test it, and what blocks a publish. QA can take as long as it needs — it is the gate before anything user-facing ships. Scale the scope to the edit: a copy tweak needs the affected step only; anything touching flow, paywall, checkout, pricing, identity, or experiments needs the full list.
+
+## Where
+
+| Stage | URL | When |
+| --- | --- | --- |
+| Local | `npm run dev` → `http://localhost:3000` | Always, before sync |
+| Preview | URL returned by `fgrove publish --env preview` | Before any production publish |
+| Production | Live domain | After production publish |
+
+A production publish without a QA-passed matching preview build is a blocker unless the user explicitly accepts the risk.
+
+## 1. Flow Coverage
+
+- Open the first step and walk every step to the end.
+- Exercise every branch (`goChoice` yes/no paths) — check both sides.
+- For each experiment in `src/config/experiments.ts`, force both variants (`?editor=true&experimentVariant=control|variant_b`) and confirm each renders and advances.
+- Submit email/identity capture with a test address and confirm advancement.
+- Keep the browser console open the whole walk: zero uncaught errors and no failed requests (ignore third-party analytics noise).
+
+## 2. Visual Pass
+
+At **430x932**, then **390x844** (rules in [step-ui-guidelines.md](step-ui-guidelines.md)):
+
+- Nothing intersects or overlaps: text never collides with images, cards, badges, or the action bar; modals and dialogs fit the viewport.
+- Continue button sits on an opaque bar at the bottom and stays visible on every step, including while content scrolls.
+- No horizontal scroll, no clipped or truncated content, no broken images.
+- Disabled CTA states render correctly and enable when valid.
+
+## 3. Image Performance
+
+For image edits and every preview-to-production candidate:
+
+- Confirm edited step images are listed in `funnelManifest.assets` and attached
+  to the relevant manifest steps with `assetIds`.
+- Confirm first-viewport images use the framework's priority/preload mechanism.
+- Confirm the shell warms only likely next-step images at low priority, not the
+  full funnel image set.
+- After preview or production publish, confirm build metadata includes the
+  `imageVariants` stage or name why it is unavailable.
+- In the browser/network panel, confirm AVIF/WebP variants are served when the
+  browser advertises support, with the original raster image as fallback.
+
+## 4. Paywall and Checkout (most important)
+
+Test the paywall on every QA run that touches it, pricing, discounts, or experiments — on the paywall step **and** every live paywall variant:
+
+1. **Plans render correctly** — titles, struck-through old price, discounted price, per-day price, featured/preselected plan match `src/config/billing.plans.ts` exactly. Verify discount math.
+2. **Countdown / discount state** — first-stage discount applies on open; timer counts down.
+3. **Checkout opens** — CTA opens the checkout with the selected plan; itemized totals match the selected plan and applied coupon.
+4. **Apple Pay / Google Pay buttons** — wallet slots render (Apple Pay needs Safari/iOS context, Google Pay needs Chrome; on unsupported browsers expect the documented fallback, not a broken gap). If wallets never appear in a supported context, treat as a defect.
+   **Note:** wallet buttons silently fail when the domain and checkout return URLs are not configured in the Stripe dashboard (payment method domains + return URL allowlist). New funnels and new domains must have Stripe configured before wallet QA can pass — if it is not configured, report it as a named blocker, not a pass.
+5. **Close-checkout discount** — close the checkout without paying: the special-offer dialog must appear; accepting it must apply the second-stage (larger) discount to the plan cards and the next checkout's payload. Verify the new prices and coupon id.
+6. **Test payment** — complete a payment with Stripe test card `4242 4242 4242 4242` (test mode) or the approved payment path. Confirm redirect to the subscription-started step with `user_id` preserved.
+7. **Success state** — subscription-started renders, registration/next-step handoff works.
+
+If checkout, payment mode, or test credentials are unavailable, name the skipped item explicitly — a silent skip counts as a fail.
+
+## 5. Registration and Links
+
+- Complete the registration page with valid test data; confirm validation errors on invalid data.
+- Click every legal/support/account link on paywall, checkout, and registration: terms, privacy, subscription policy, money-back, support email.
+
+## 6. Subscription Management
+
+- Open `/manage-subscription?user_id=<test-user>` (or with `stripe_customer_id`).
+- Confirm the subscription list loads and the cancellation flow completes when a test subscription is available; otherwise name it as a skipped item.
+
+## Reporting
+
+Every QA run ends with a short report: stage + URLs tested, steps/branches/variants covered, viewports checked, image optimization/preload result when relevant, paywall items 1–7 pass/fail, payment method used, console findings, and named blockers or explicitly skipped items with the reason. Blockers block production unless the user accepts the risk in so many words.

package/template_docs/docs/step-ui-guidelines.md

@@ -0,0 +1,106 @@
+# Step UI Guidelines
+
+Every step must pass these rules before it counts as done. They are distilled from high-performing quiz funnels (BetterMe-class) and apply to new steps, edited steps, and paywalls alike.
+
+## Viewports
+
+Funnels are mobile-first. Build and verify at:
+
+| Viewport | Size | Role |
+| --- | --- | --- |
+| iPhone 16 Pro | **430 x 932** | Default. Matches `viewport` in `funnel.manifest.ts`. |
+| iPhone 12 / 13 / 14 | **390 x 844** | Required spot-check on every created or edited step. |
+
+Pass criteria at both sizes: no horizontal scroll, no clipped or overlapping content, the primary CTA visible without scrolling on selection/input steps, and tap targets at least 44px tall.
+
+## Layout Shell Contract
+
+The shell (`src/components/FunnelFlow.tsx`) owns the frame; steps fill the middle:
+
+1. **Fixed top bar** — opaque background, back arrow, brand or section title, optional progress. Thin bottom hairline.
+2. **Scrollable content** — the step body. Must add bottom padding so the last element clears the action bar.
+3. **Fixed bottom action bar** — the Continue button area. **The bar is opaque, never transparent** — content scrolling under a floating button is a defect. Reference implementation:
+
+```css
+position: fixed;
+bottom: 0;
+left: 0;
+right: 0;
+background: var(--color-surface);          /* solid — no alpha */
+border-top: 1px solid rgba(23, 23, 23, 0.08);
+padding: 16px 20px calc(16px + env(safe-area-inset-bottom));
+z-index: 11;
+```
+
+The button itself: full width, ~50px tall, pill radius, theme primary color. Disabled state stays visible (washed-out), it never disappears.
+
+Steps control the shell bar through `FunnelStepMeta.actionBar`:
+
+- omit → default Continue button;
+- `{ buttonText: '...' }` → custom label;
+- `{ hidden: true }` → step owns its CTAs (paywalls);
+- auto-advance steps (single-select) need no bar at all.
+
+## Step Patterns
+
+One decision per screen. Pick the matching pattern; do not invent hybrids.
+
+**Single-select** — tap an option → store answer → `goNext()` immediately. No Continue button. Option cards: icon or image + label + radio indicator, ~16px gap, selected state with tinted background.
+
+**Multi-select** — "Choose all that apply" subtitle, checkbox cards, sticky Continue **disabled until at least one selection**. A "None of the above" option clears and excludes the others.
+
+**Scale question** — statement in quotes as the headline, 1–5 buttons in a row, anchored labels ("Strongly disagree" / "Strongly agree") at the ends. Auto-advance on tap.
+
+**Numeric input** (height, weight, age) — large centered input, unit toggle (kg/lbs, cm/ft) where relevant, visible validation range hint ("enter a value from 90 cm to 243 cm"), Continue disabled until valid. When the value enables personalization, show instant inline feedback below the input (e.g. a BMI callout: amber card, icon, bold key phrase, supportive copy that says how the data will be used). Hard-stop ineligible values with a clear message, not a silent disable.
+
+**Info interstitial** — headline, hero image card, 2–3 short supporting lines, sticky Continue. Insert one every 3–5 questions to re-sell the promise and break monotony; tie it to the answer just given ("Keep your back and knees strong → your plan will include…").
+
+**Personalized summary** — mirror the user's data back (profile card, gauge with the user's position, attribute list, projection chart with goal badge and date). Charts that predict results need a compliance footnote ("illustrative purposes only / results vary").
+
+**Loading / plan-building** — animated percent ring or bar plus rotating social proof (ratings, testimonials) during the wait. Auto-advance on completion.
+
+**Email capture** — single email field, nothing else on screen. Headline names the deliverable ("Enter your email to get your plan"). Padlock icon + one privacy reassurance line + Privacy Policy link. Marketing opt-in is its own subsequent step, never a pre-checked box.
+
+## Paywall Anatomy
+
+The proven block order, top to bottom:
+
+1. **Sticky offer header** — compact bar with countdown timer ("Reserved price for 09:59") and a small CTA, always visible while scrolling.
+2. **Before/after comparison** — "Now" vs "Your Goal" with attribute deltas.
+3. **Applied-discount card** — promo code chip, "applied automatically" copy, countdown.
+4. **Plan cards** — usually three; mark one "MOST POPULAR" and preselect it; show struck-through old total → discounted total and a large per-day price anchor.
+5. **Primary CTA** directly under the cards.
+6. **Auto-renewal disclosure** — full renewal price, interval, cancellation path. Required, directly below the CTA.
+7. **Plan highlights** — icon + bold benefit + one-line explanation.
+8. **Trust blocks** — press logos, testimonials with concrete results, results disclaimer.
+9. **FAQ** ("What happens after payment?") and **money-back guarantee** with conditions.
+10. Repeat plan cards + CTA at the bottom for long pages.
+
+Checkout opens as a modal over the paywall: itemized breakdown (regular price, discount line, promo chip, VAT, total, "you save" line), wallet buttons first (Apple Pay / Google Pay / PayPal as available), card entry collapsed behind a radio. Closing the checkout without paying triggers the second-stage discount dialog ([payment-plans-and-discounts.md](payment-plans-and-discounts.md)) — verify both discount stages whenever you touch the paywall.
+
+## Image Performance
+
+Use the ClaimBee/Blessly image loading pattern:
+
+- Keep raster artwork on the build-time optimization path so publish can shrink
+  PNG/JPEG sources and create AVIF/WebP variants.
+- Put step image metadata in `funnelManifest.assets` and reference those images
+  from each step with `assetIds`.
+- Above-the-fold images on the current step use the framework's priority/preload
+  mechanism.
+- The flow shell may warm likely next-step images at low priority shortly after
+  the active step loads. Do not preload the whole funnel image set on first load.
+- Any image-heavy funnel should keep a contract test that every `assetId`
+  resolves and the shell uses manifest-driven next-step preloads.
+
+## Content-Fit Audit
+
+Run on every created or edited step, at 430x932 then 390x844:
+
+1. Open the step in local preview (`npm run dev`).
+2. Check: nothing clipped, nothing overlapping, no text truncated mid-word, images loaded with correct aspect, CTA fully visible above the fold on selection/input steps.
+3. Scroll to both ends — last content clears the action bar; nothing hides under the top bar.
+4. Check disabled→enabled CTA transition where applicable.
+5. Fix and re-check before moving to another step.
+
+Report the audit (both viewports, pass/fail per step) in your summary.