Propagate selected package forward across workflow steps

[facumenzella]

Checklist

• If applicable, unit tests
• If applicable, create follow-up issues for purchases-android and hybrids

Motivation

Multi-step workflow paywalls had no way to carry the user's package selection from one step to the next. If a user selected Annual on step 1 and then navigated forward, step 2 would ignore that choice and fall back to either the workflow's singleStepFallbackId default or the step's own page default. The same issue applied in reverse: tapping back and then forward again would re-apply a stale selection from a previous forward trip.

Android counterpart: RevenueCat/purchases-android#3431

Description

Per-step carry-forward state (WorkflowPackageCarryForwardState)

Replaces the single currentSelectedPackage variable in WorkflowPaywallView with a per-step dictionary. Explicit user selections (recordSelection) always win over the initial resolved default (recordInitialSelection). Back navigation clears only the abandoned step's record so earlier selections can carry forward again on re-entry. clearForBackNavigation is called after the navigator.navigateBack() guard so carry-forward state is never mutated when there is no previous step to return to.

Two distinct environment keys instead of one

workflowFallbackContext (WorkflowPackageContext?) is the workflow-wide static context derived from singleStepFallbackId. It carries both selectedPackage and the full packages array so packageless steps can populate variableContext and resolve price/period template variables. It stays the same for the entire workflow lifetime.

workflowCarriedPackage (Package?) is the per-step carry-forward. It holds the single package selected (or resolved as the default) on the immediately preceding step, changes on each forward navigation, and is cleared on back navigation. Its only job is pre-selection, not variable resolution.

workflowOnPackageSelected and workflowOnInitialPackageResolved are environment callbacks that let PaywallsV2View report selections and initial resolutions back to WorkflowPaywallView without the two being coupled directly.

Initial step recording

The first step is created with recordInitialWorkflowPackageSelection: true so that a user who taps Continue without making an explicit selection still carries the displayed default forward to step 2, rather than falling back to the workflow default SKU.

Packageless step carry-forward

On steps with no packages of their own, effectiveDefaultPackage falls back to workflowDefaultPackage for rendering. initialPackageToRecordForWorkflow detects this case and records the incoming workflowCarriedPackage instead of the fallback, preventing the workflow default from overwriting the user's real selection.

Variable context desync fix

When workflowCarriedPackage resolves within the current step's offering, variableContext is built from the step's own package set rather than the workflow-wide packages. This keeps relative-price variables (e.g. product.relative_discount) referencing the same catalog as the selected package.

Tab preselection

TabsComponentView and LoadedTabsComponentView read workflowCarriedPackage from the environment and validate it against each tab's own package list before applying it as the initial selection. A new static validated(_:in:) helper mirrors the existing logic in PaywallsV2View.

Tab onAppear carry-forward fix

Tab components call packageContext.update() in onAppear to sync the parent context. Because SwiftUI fires child onAppear before parent onAppear, this emission arrived before any user interaction and was overwriting the correctly-carried package. The isReadyForWorkflowPackageSelection flag blocks the onReceive handler until the outer onAppear fires.

RootView sheet dismissal fix

When a package selection sheet is dismissed without a new choice, the paywall now restores defaultPackage (the page-level default) instead of workflowFallbackContext?.selectedPackage. This prevents the workflow fallback SKU from overriding the page's own default on sheet close.

WorkflowContext cleanup

The collectPackages traversal now includes the sticky footer and handles tabs and carousel components. Hidden packages (visible: false) are filtered out using where pkg.visible ?? true rather than an inverted condition.

Testing

PaywallsV2ViewContextPackageTests covers makeSelectedPackageContext, effectiveDefaultPackage, validatedContextPackage, and initialPackageToRecordForWorkflow including the packageless step carry-forward path.

WorkflowPaywallViewTests covers WorkflowPackageCarryForwardState mutations, the workflowFallbackContext resolver (nil cases, default selection, hidden package filtering, sticky footer, tabs/carousel traversal), and variableContext population.

TabsPackageInheritanceTests covers workflowCarriedPackage preselection and validation against tab package lists.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a826546. Configure here.}

[facumenzella]

@RCGitBot please test run-revenuecat-ui-ios-26

[github-actions]

🚀 Triggered run-revenuecat-ui-ios-26 → Pipeline #37702

[vegaro]

why 3-step+ only?

[facumenzella]

You are right, the qualifier was misleading. Removed it — the mechanism applies equally to any multi-step workflow, not just those with three or more steps.

[vegaro]

I think there's inconsistency in the naming of this shouldRecordInitialPackageSelection vs recordWorkflowInitialSelection vs recordInitialSelection

[facumenzella]

Good catch. Unified all three to recordInitialWorkflowPackageSelection throughout — PaywallsV2View init param, the stored property, the static method parameter, and the RenderedPage field. The recordInitialSelection method on WorkflowPackageCarryForwardState is intentionally different since it is a verb-action method on a distinct type, not a flag.

[facumenzella]

Superseded by #6790, which takes a simpler approach: per-step PackageContext caching + step-scoped workflowPackageContext environment, rather than dual env keys and carry-forward state.