AI Context

Metadata

• PR: 6911
• Branch: facu/workflow-exit-offer-uikit-bridge
• Author / human owner: facumenzella (Facundo Menzella)
• Agent(s): Claude Code (Opus 4.8, 1M context)
• Session source: current conversation
• Generated: 2026-06-05
• Context document version: 4

Goal

Bridge the step-aware workflow exit offer into the UIKit PaywallViewController so swipe-to-dismiss and the close button surface it when the workflows endpoint is enabled. Follow-up to the TODO left in #6887. Requirement added mid-session: WorkflowA must be able to open WorkflowB as an exit offer (and chain further). Later iteration (this session): fix a code-review regression where reconfiguring the controller dropped a valid workflow exit offer.

Initial Prompt

"Check #6887. We need to add support for ExitOffers + Workflows in PaywallViewController. Take a look at how that works, and let's pick it up from there." (Resolved to: implement the UIKit exit-offer bridge that #6887 deferred.) Follow-up session: "Check #6911" resolved to addressing reviewer (vegaro) feedback on the bridge.

Important Follow-up Prompts

• "WorkflowA must be able to open WorkflowB as an exitOffer" — rejected SwiftUI-style nested-offer suppression; mandated chaining, which drove the always-bridge (no suppression flag) design.
• "I wonder if it would be simpler to handle everything within the SwiftUI world" — evaluated; rejected because swipe-to-dismiss interception must stay in UIKit and the SwiftUI sheet path can't chain. Chose the UIKit bridge (Option A).
• Codex review surfaced a P2 (stale offer on host rebuild); addressed.
• Review feedback from vegaro (this session): (1) configuration.didSet cleared the exit offer on every mutation, including non-content ones; (2) the binding get is never read. Decided: bring vegaro's regression tests (test(paywalls): regression tests for workflow exit offer surviving non-content reconfigures #6919) into this branch and fix here (Option A), using the "more targeted" fix rather than making Content Equatable.

Agent Contribution

• Traced both exit-offer paths (UIKit PaywallViewController and SwiftUI View+PresentPaywall / WorkflowPaywallView / WorkflowExitOfferPreferenceKey / workflowExitOfferOfferingBinding).
• Implemented the original bridge in RevenueCatUI/UIKit/PaywallViewController.swift: env-binding injection + preference fallback into exitOfferOffering, a guarded updateWorkflowExitOffer, and a stale-offer clear.
• This session: diagnosed vegaro's comment 1, confirmed PaywallViewConfiguration.Content is not Equatable (so her literal content != oldValue.content would not compile and would cascade conformance into Offering/PresentedOfferingContext), and implemented the targeted alternative.
• Cherry-picked vegaro's two commits (regression tests + test hooks) onto this branch, preserving her authorship.
• Ran the cherry-picked tests RED (2 failures) against the buggy code, applied the fix, re-ran GREEN (0 failures).
• Replied to both review threads; added a clarifying comment on the binding get.

Human Decisions

• Chose Option A (UIKit bridge reusing existing machinery) over handling it all in SwiftUI.
• Mandated workflow-as-exit-offer chaining (no suppression).
• This session: chose to merge vegaro's regression test into this branch and fix here (not in test(paywalls): regression tests for workflow exit offer surviving non-content reconfigures #6919); chose the "better"/targeted fix for comment 1; chose to reply to comment 2 (keep the getter) rather than remove it; authorized push.

Key Implementation Decisions

• Decision: feed the offer up into the existing UIKit exitOfferOffering and reuse presentationControllerShouldDismiss / handleDismissalRequest / presentExitOffer.
  • Rationale: the VC is presented by UIKit, so swipe-to-dismiss interception must use UIAdaptivePresentationControllerDelegate; SwiftUI inside a UIHostingController can't intercept the parent sheet's interactive dismissal.
  • Rejected: SwiftUI-owned presentation (Option B) — still needs UIKit swipe interception, can't chain, and drops the willPresentExitOfferController delegate callback.
• Decision: environment binding primary, preference key fallback.
  • Rationale: environment propagates downward deterministically; WorkflowPaywallView writes the binding in onAppear/onChange.
• Decision: no suppression flag — exit-offer children bridge too (enables WorkflowA -> WorkflowB chaining).
• Decision (this session): clear the workflow exit offer only on offering/content change, by moving updateWorkflowExitOffer(nil) out of configuration.didSet and into the three content mutators (update(with:offering), update(with:offeringIdentifier), update(with:offeringIdentifier:presentedOfferingContext:)), before the assignment.
  • Rationale: didSet fires on all mutations, so update(with displayCloseButton:) and updateFont(with:) were wiping a valid exit offer. Placing the clear in only the content mutators is precise and needs no new conformances. Kept routed through updateWorkflowExitOffer, so the "don't clear while presenting" guard (from the earlier Codex P2 fix) and the legacy no-op still hold.
  • Rejected: vegaro's literal if configuration.content != oldValue.content — Content is not Equatable; conforming it cascades into Offering (NSObject, reference equality) and PresentedOfferingContext.
• Decision (this session): keep the binding get even though it is never read.
  • Rationale: the env key is Binding<Offering?> because the SwiftUI path (View+PresentPaywall.swift:643) injects a real two-way $exitOfferOffering; Binding structurally requires a get. Added a comment marking it write-only here.
• Decision (this session): in PaywallContainerView, forward only non-nil values from the WorkflowExitOfferPreferenceKey onPreferenceChange into the binding (guard let offering = context?.exitOfferOffering else { return }).
  • Rationale: addresses a bug introduced by this PR's bridge commit (not in main): on a host rebuild (update(with:displayCloseButton:) / updateFont), the new container can emit a default-nil preference before WorkflowPaywallView re-syncs, momentarily clearing a still-valid exit offer. The preference is a set-only fallback; clears are owned by the direct binding (syncExitOfferBinding on step change), so ignoring nil is safe.
  • Note: render-path behavior, so verified by no-regression on the binding-path tests + manual; not separately unit-tested (a helper would only assert a tautological guard let).

Files / Symbols Touched

• RevenueCatUI/UIKit/PaywallViewController.swift
  • Why: the bridge + this session's regression fix.
  • Symbols: updateWorkflowExitOffer(_:), configuration didSet (clear removed), update(with:) content mutators (clear added), createHostingController() (binding + comment), PaywallContainerView (onPreferenceChange now forwards non-nil only), prefetchExitOffer(), and the test hooks (workflowsEndpointEnabled var, exitOfferOfferingForTesting, simulateWorkflowExitOfferUpdate).
  • Review relevance: the clear now lives only in content mutators; confirm cosmetic reconfigures (close button, font) keep the offer and replacing the offering clears it; the preference forwarding ignores nil.
• RevenueCat.xcodeproj/project.pbxproj
  • Why: register the new test file (danger requires it). Added as a file reference under a new UIKit group, NOT in the UnitTests target (RevenueCatUITests files build via SPM/Tuist; adding it to UnitTests broke run-test-ios-26 with Unable to find module dependency: 'RevenueCatUI', since that target doesn't link RevenueCatUI).
• Tests/RevenueCatUITests/UIKit/PaywallViewControllerExitOfferTests.swift
  • Why: vegaro's regression tests covering exit-offer retention vs clearing on reconfigure (cherry-picked, her authorship).
  • Symbols: testUpdateDisplayCloseButtonDoesNotClearWorkflowExitOffer, testUpdateFontDoesNotClearWorkflowExitOffer, testUpdateOfferingClearsWorkflowExitOffer.
• Tests/TestingApps/PaywallsTester/PaywallsTester/UI/Views/OfferingList/APIKeyDashboardList.swift
  • Why: adds a "UIKit View Controller" Live Paywalls menu entry that modally presents PaywallViewController.

Dependencies / Config / Migrations

• Feature flag: -EnableWorkflowsEndpoint (ProcessInfo.processInfo.workflowsEndpointEnabled). No new deps, no public API change.

Validation

• Commands run:
  • xcodebuild test -scheme RevenueCatUI -destination 'platform=iOS Simulator,id=…iPhone 16 Pro' -only-testing:RevenueCatUITests/PaywallViewControllerExitOfferTests (RED, before fix): Executed 3 tests, 2 failures (…DisplayCloseButton… and …Font… failed; …Offering… passed).
  • Same command after the fix (GREEN): Executed 3 tests, 0 failures.
  • swiftlint lint RevenueCatUI/UIKit/PaywallViewController.swift: no violations.
  • After the preference-nil guard: same command, Executed 3 tests, 0 failures (no regression on the binding path).
• Manual verification:
  • Original bridge exercised on a simulator via the PaywallsTester "UIKit View Controller" mode; the workflow exit offer surfaced on swipe-to-dismiss / close.
• Source control:
  • Rebased onto origin/main (resolved a project.pbxproj conflict: kept only the new file ref; WorkflowsCacheTests was relocated upstream). Force-pushed.
• CI:
  • run-test-ios-26 initially failed because the test file was added to the UnitTests target; fixed by making it a file reference only. Full suite re-runs on push; the run-all-tests job stays on its manual-approval hold by design.

Validation Gaps

• Local run covered only PaywallViewControllerExitOfferTests, not the full suite (CI is the backstop). No-regression argument for the rest is structural: updateWorkflowExitOffer is a no-op when workflowsEndpointEnabled is false, so legacy-path behavior is unchanged by both the didSet removal and the new calls.
• No automated test for the SwiftUI-presented bridge path itself (render/UIKit-presentation dependent); covered manually.

Review Focus

• Confirm the clear now fires only for offering/content changes: update(with displayCloseButton:) and updateFont(with:) must keep a valid workflow exit offer; update(with: offering) must clear it.
• Confirm the "don't clear while presenting" guard still holds for a content update during an active exit-offer presentation.
• Chaining: dismissing WorkflowB-as-exit-offer should present its own exit offer with no leak across the fresh child VCs.

Risks / Reviewer Notes

• Risk: a content update arriving mid-dismiss could clear the offer.
  • Evidence: routed through updateWorkflowExitOffer, which no-ops a nil clear while isShowingExitOffer is true.
  • Mitigation: covered by the guard; bugbot's earlier P2 on direct = nil no longer applies (the direct didSet clear was removed).
• Risk: preference doesn't propagate up through the UIHostingController.
  • Mitigation: environment binding is the primary mechanism; preference is a fallback.

Non-goals / Out of Scope

• Removing the workflows flag.
• Wiring workflow exit offers into the SwiftUI .presentPaywall(offering:) modifier (PresentingPaywallBindingModifier). Separate follow-up.

Omitted Context

• Raw transcript, unrelated exploration, sensitive details, repetitive attempts, and chain-of-thought-style content were omitted.