---
type: workstream
project: fidelity
status: active
systems: [xflowsdk, xflowviewmaker, ftframeworks, fid4]
work-items: [pdiap-14859, pdiap-15836, pdiap-12284]
related: [consumer-integration, xflow-debugging]
updated: 2026-05-08
tags:
  - workstream
  - fidelity
---
# XFlow SwiftUI Migration

## Goal

Track the durable behavior patterns introduced while moving XFlow from older assumptions toward a more complete SwiftUI implementation.

---

## Stable Themes

- SwiftUI migration was not just a UI rewrite; it exposed contract, lifecycle, and parity gaps.
- Historical Slack evidence repeatedly referenced:
  - component type expansion beyond simple string assumptions
  - Next-button visibility rules driven by full service parameters
  - markdown link handling and analytics integration
  - navigation and modal behavior in pure SwiftUI environments
  - dismissal delegate lifecycle sequencing

---

## What Matters Now

- When a SwiftUI issue appears, check whether the missing behavior is:
  - parity with UIKit behavior
  - an incomplete service contract interpretation
  - a lifecycle sequencing problem
  - a consumer presentation constraint in Fid4
- Do not assume a visual issue is only cosmetic; several historical SwiftUI bugs changed flow behavior materially.
- For UIKit-wrapping removal, prefer a host-mode design that keeps SwiftUI as the default and limits `UIHostingController` to an explicit temporary fallback. Missing or unknown rollout configuration should not silently restore the UIKit host.
- Keep host-mode ownership at the shared integration layer when possible. A Fid4-only per-flow map is less reusable for XFlow's multiple consumers and creates cleanup work when the fallback is retired.
- Dismissal sequencing changes must be validated as lifecycle contracts, not just visual symptom fixes: delegate/session-clear callbacks should fire after confirmed dismissal, and `onDisappear` should not be treated as sufficient proof without simulator-log evidence.

---

## Historical Signals From Slack

- Jeff and Norman repeatedly refined story titles and descriptions around SwiftUI architecture changes, showing that scope wording mattered because the work was often deeper than the first symptom.
- Historical Slack context also shows that SwiftUI-specific work frequently required cross-team clarification when external dependencies or consumer environments behaved differently.