@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-uikit-interop/references/hosting-migration.md

@@ -1,463 +1,310 @@
-# UIKit-to-SwiftUI Migration Patterns
+# Hosting and Incremental Migration
 
-Patterns for incrementally migrating a UIKit app to SwiftUI. Each pattern is self-contained with rationale, implementation, and gotchas.
-
----
+A UIKit app does not have to switch to SwiftUI in one release. These six
+patterns move it over piece by piece while both frameworks share the same
+navigation stack, the same models and the same traits.
 
 ## Contents
 
-- [1. Screen-by-Screen Migration](#1-screen-by-screen-migration)
-- [2. UIHostingController as Child](#2-uihostingcontroller-as-child)
-- [3. Navigation Bridging](#3-navigation-bridging)
-- [4. Data Sharing Between UIKit and SwiftUI](#4-data-sharing-between-uikit-and-swiftui)
-- [5. UIHostingConfiguration (iOS 16+)](#5-uihostingconfiguration-ios-16)
-- [6. Environment Bridging](#6-environment-bridging)
+1. [Replace whole screens](#1-screen-by-screen-migration)
+2. [Embed a SwiftUI region](#2-uihostingcontroller-as-child)
+3. [Share one navigation stack](#3-navigation-bridging)
+4. [Share models](#4-data-sharing-between-uikit-and-swiftui)
+5. [SwiftUI cells](#5-uihostingconfiguration-ios-16)
+6. [Pass environment and traits](#6-environment-bridging)
 
 ## 1. Screen-by-Screen Migration
 
-Replace one `UIViewController` at a time with a `UIHostingController` wrapping a SwiftUI view. This is the safest migration path -- each screen is an isolated unit.
-
-### Strategy
-
-1. Pick a leaf screen (one that does not contain child view controllers).
-2. Rewrite its UI in SwiftUI.
-3. Replace the UIKit view controller with `UIHostingController` wherever it was instantiated.
-4. Wire navigation from the parent UIKit code into the hosting controller.
-
-### Implementation
-
-```swift
-// BEFORE: UIKit screen pushed onto a navigation stack
-let detailVC = ItemDetailViewController(item: item)
-navigationController?.pushViewController(detailVC, animated: true)
-
-// AFTER: SwiftUI screen wrapped in UIHostingController
-let detailView = ItemDetailView(item: item)
-let hostingVC = UIHostingController(rootView: detailView)
-navigationController?.pushViewController(hostingVC, animated: true)
-```
+The lowest-risk route is to replace whole view controllers, one at a time, with
+a `UIHostingController` that wraps the new SwiftUI screen.
 
-### Passing Dismiss/Navigation Callbacks
+Order of work:
 
-When the SwiftUI screen needs to pop itself or trigger navigation in the UIKit stack:
+1. Choose a leaf screen, one that embeds no child view controllers.
+2. Rebuild it in SwiftUI.
+3. Replace the old controller wherever it was instantiated.
+4. Connect the surrounding UIKit navigation to the hosting controller.
 
 ```swift
-struct ItemDetailView: View {
-    let item: Item
-    var onDelete: (() -> Void)?
-
-    @Environment(\.dismiss) private var dismiss
-
-    var body: some View {
-        VStack {
-            Text(item.title)
-            Button("Delete", role: .destructive) {
-                onDelete?()
-                dismiss()
-            }
-        }
-    }
-}
-
-// In UIKit:
-let detailView = ItemDetailView(item: item) {
-    self.dataSource.delete(item)
-    self.navigationController?.popViewController(animated: true)
-}
-let hostingVC = UIHostingController(rootView: detailView)
+// Before: navigationController?.pushViewController(InvoiceDetailViewController(invoice: invoice), animated: true)
+let detail = InvoiceDetailView(invoice: invoice, onVoid: { [weak self] in
+    self?.ledger.void(invoice)
+    self?.navigationController?.popViewController(animated: true)
+})
+let host = UIHostingController(rootView: detail)
+navigationController?.pushViewController(host, animated: true)
 ```
 
-### Gotchas
+The SwiftUI view takes a callback such as `onVoid`; the UIKit side supplies the
+closure that changes data and pops the screen.
 
-- **Navigation bar.** `UIHostingController` inherits navigation bar visibility from its parent `UINavigationController`. Use `.navigationTitle()` and `.toolbar()` in the SwiftUI view -- they propagate to the UIKit navigation bar automatically.
-- **Large titles.** Set `hostingVC.navigationItem.largeTitleDisplayMode` in UIKit code if the SwiftUI `.navigationBarTitleDisplayMode()` modifier does not apply correctly.
-- **Tab bar insets.** `UIHostingController` respects `additionalSafeAreaInsets`. If the content overlaps the tab bar, verify safe area propagation.
+Navigation bar behaviour:
 
----
+- `.navigationTitle()` and `.toolbar()` inside the hosted view show up in the
+  UIKit navigation bar. Whether the bar is visible is decided by the parent
+  `UINavigationController`.
+- If `.navigationBarTitleDisplayMode()` does not take effect, set
+  `host.navigationItem.largeTitleDisplayMode` from UIKit instead.
+- `UIHostingController` respects `additionalSafeAreaInsets`. If content slides
+  under the tab bar, check how the safe area reaches the hosted view.
 
 ## 2. UIHostingController as Child
 
-Embed SwiftUI sections within an existing UIKit screen. Use when migrating part of a screen (a header, a card, a section) before rewriting the entire controller.
-
-### Implementation
+Use a child hosting controller to migrate a region of a screen, such as a
+header, a card or a section, before rewriting the rest.
 
 ```swift
-final class DashboardViewController: UIViewController {
-    private var statsHostingController: UIHostingController<StatsCardView>?
+final class AccountViewController: UIViewController {
+    private var balanceHost: UIHostingController<BalanceCard>?
+    private let cardContainer = UIView()
 
     override func viewDidLoad() {
         super.viewDidLoad()
-
-        let statsView = StatsCardView(stats: currentStats)
-        let hostingVC = UIHostingController(rootView: statsView)
-
-        // Enable intrinsic sizing so Auto Layout can size the hosted view
+        let host = UIHostingController(rootView: BalanceCard(amount: 0))
         if #available(iOS 16.0, *) {
-            hostingVC.sizingOptions = [.intrinsicContentSize]
+            host.sizingOptions = [.intrinsicContentSize]
         }
+        host.view.backgroundColor = .clear
 
-        addChild(hostingVC)
-        hostingVC.view.translatesAutoresizingMaskIntoConstraints = false
-        containerView.addSubview(hostingVC.view)
-
+        addChild(host)
+        host.view.translatesAutoresizingMaskIntoConstraints = false
+        cardContainer.addSubview(host.view)
         NSLayoutConstraint.activate([
-            hostingVC.view.topAnchor.constraint(equalTo: containerView.topAnchor),
-            hostingVC.view.leadingAnchor.constraint(equalTo: containerView.leadingAnchor),
-            hostingVC.view.trailingAnchor.constraint(equalTo: containerView.trailingAnchor),
-            hostingVC.view.bottomAnchor.constraint(equalTo: containerView.bottomAnchor),
+            host.view.topAnchor.constraint(equalTo: cardContainer.topAnchor),
+            host.view.bottomAnchor.constraint(equalTo: cardContainer.bottomAnchor),
+            host.view.leadingAnchor.constraint(equalTo: cardContainer.leadingAnchor),
+            host.view.trailingAnchor.constraint(equalTo: cardContainer.trailingAnchor)
         ])
-
-        hostingVC.didMove(toParent: self)
-        statsHostingController = hostingVC
+        host.didMove(toParent: self)
+        balanceHost = host
     }
 
-    func updateStats(_ stats: Stats) {
-        statsHostingController?.rootView = StatsCardView(stats: stats)
-    }
-}
-```
-
-### With `@Observable` Model
-
-Pass an `@Observable` model to avoid reassigning `rootView` manually. SwiftUI tracks changes automatically:
-
-```swift
-@Observable
-final class DashboardModel {
-    var stats: Stats = .empty
-    var isLoading = false
-}
-
-struct StatsCardView: View {
-    let model: DashboardModel
-
-    var body: some View {
-        // Automatically re-renders when model.stats changes
-        if model.isLoading {
-            ProgressView()
-        } else {
-            StatsGrid(stats: model.stats)
-        }
+    func show(amount: Decimal) {
+        balanceHost?.rootView = BalanceCard(amount: amount)
     }
 }
-
-// In UIKit:
-let model = DashboardModel()
-let hostingVC = UIHostingController(rootView: StatsCardView(model: model))
-
-// Later -- just mutate the model, no rootView reassignment needed
-model.stats = newStats
 ```
 
-### Gotchas
+With an `@Observable` model passed into the card instead, mutate the model and
+leave `rootView` alone; SwiftUI picks up the change.
 
-- **Background color.** `UIHostingController`'s view has an opaque system background by default. Set `hostingVC.view.backgroundColor = .clear` if embedding over existing content.
-- **sizingOptions on iOS 16+.** Without `.intrinsicContentSize`, the hosted view may report zero size in Auto Layout, causing the container to collapse.
-- **Memory.** Store the hosting controller in a property. If it is only held as a child, removing it from the parent deallocates it and the SwiftUI view disappears.
+Pitfalls:
 
----
+- By default the hosting view paints the opaque system background. Set
+  `view.backgroundColor = .clear` when it sits over existing UIKit content.
+- Without `.intrinsicContentSize` the hosted view can report a zero size and
+  the container collapses.
+- Keep a stored reference to the hosting controller. Removing the child would
+  otherwise free it and the view vanishes.
 
 ## 3. Navigation Bridging
 
-Mix UIKit and SwiftUI screens in the same `UINavigationController` stack.
+UIKit screens and SwiftUI screens can live on the same `UINavigationController`
+stack.
 
-### UIKit Pushing SwiftUI
+**UIKit pushes SwiftUI.** Wrap the view, give the host a `title`, push it:
 
 ```swift
-// From a UIKit view controller, push a SwiftUI screen
-func showProfile(for user: User) {
-    let profileView = ProfileView(user: user)
-    let hostingVC = UIHostingController(rootView: profileView)
-    hostingVC.title = user.name
-    navigationController?.pushViewController(hostingVC, animated: true)
-}
+let host = UIHostingController(rootView: ReceiptsView())
+host.title = "Receipts"
+navigationController?.pushViewController(host, animated: true)
 ```
 
-### SwiftUI Pushing UIKit
-
-Use a coordinator or `UIViewControllerRepresentable` bridge:
+**SwiftUI presents UIKit.** Present a representable from `.sheet` that returns
+a `UINavigationController(rootViewController:)` around the legacy controller:
 
 ```swift
-struct ProfileView: View {
-    let user: User
-    @State private var showLegacyEditor = false
-
-    var body: some View {
-        List {
-            // ... profile content
-            Button("Edit (Legacy)") { showLegacyEditor = true }
-        }
-        .sheet(isPresented: $showLegacyEditor) {
-            LegacyEditorWrapper(user: user)
-        }
-    }
-}
-
-struct LegacyEditorWrapper: UIViewControllerRepresentable {
-    let user: User
-
+struct LegacyExportFlow: UIViewControllerRepresentable {
     func makeUIViewController(context: Context) -> UINavigationController {
-        let editor = ProfileEditorViewController(user: user)
-        return UINavigationController(rootViewController: editor)
+        UINavigationController(rootViewController: ExportOptionsViewController())
     }
-
-    func updateUIViewController(_ uiViewController: UINavigationController, context: Context) {}
+    func updateUIViewController(_ nav: UINavigationController, context: Context) {}
 }
-```
 
-### Passing NavigationController Reference
+// .sheet(isPresented: $exporting) { LegacyExportFlow() }
+```
 
-For deep integration where SwiftUI needs to push onto the UIKit navigation stack:
+**Deep integration.** Give SwiftUI views a small bridge to the UIKit stack
+through the environment:
 
 ```swift
-struct NavigationBridge {
+struct UIKitNavigator {
     weak var navigationController: UINavigationController?
 
-    func push(_ viewController: UIViewController, animated: Bool = true) {
-        navigationController?.pushViewController(viewController, animated: animated)
+    @MainActor
+    func push(_ controller: UIViewController, animated: Bool = true) {
+        navigationController?.pushViewController(controller, animated: animated)
     }
 
-    func push<V: View>(_ view: V, title: String? = nil, animated: Bool = true) {
-        let hostingVC = UIHostingController(rootView: view)
-        hostingVC.title = title
-        navigationController?.pushViewController(hostingVC, animated: animated)
+    @MainActor
+    func push<Content: View>(_ view: Content, title: String, animated: Bool = true) {
+        let host = UIHostingController(rootView: view)
+        host.title = title
+        navigationController?.pushViewController(host, animated: animated)
     }
 }
 
-// Inject via environment
-private struct NavigationBridgeKey: EnvironmentKey {
-    static let defaultValue = NavigationBridge()
+private struct UIKitNavigatorKey: EnvironmentKey {
+    static var defaultValue: UIKitNavigator { UIKitNavigator() }
 }
 
 extension EnvironmentValues {
-    var navigationBridge: NavigationBridge {
-        get { self[NavigationBridgeKey.self] }
-        set { self[NavigationBridgeKey.self] = newValue }
+    var uikitNavigator: UIKitNavigator {
+        get { self[UIKitNavigatorKey.self] }
+        set { self[UIKitNavigatorKey.self] = newValue }
     }
 }
 ```
 
-### Gotchas
+Set it on the root view before creating the host:
+`ReceiptsView().environment(\.uikitNavigator, UIKitNavigator(navigationController: navigationController))`.
 
-- **Back button.** When pushing `UIHostingController` onto a `UINavigationController`, the back button works automatically. Do not add a manual back button in the SwiftUI view.
-- **Double navigation bars.** If the SwiftUI view uses `NavigationStack`, it creates its own navigation bar inside the UIKit one. Remove `NavigationStack` from SwiftUI views presented inside `UINavigationController`.
-- **Toolbar items.** SwiftUI `.toolbar` items propagate to the UIKit navigation bar when hosted in `UIHostingController`. This works reliably on iOS 16+.
+Notes:
 
----
+- A pushed hosting controller gets the standard back button automatically. Do
+  not add your own.
+- Do not put a `NavigationStack` inside a hosting controller that is already on
+  a `UINavigationController`; you get two navigation bars. Remove the
+  `NavigationStack`.
+- On iOS 16 and later, SwiftUI `.toolbar` items reliably appear in the UIKit
+  navigation bar.
 
 ## 4. Data Sharing Between UIKit and SwiftUI
 
-### Using `@Observable` (iOS 17+)
-
-The cleanest approach. Create an `@Observable` model, pass it to both UIKit and SwiftUI code:
+**Preferred (iOS 17+): one `@Observable` model for both sides.** SwiftUI tracks
+it automatically; UIKit reads its properties directly.
 
 ```swift
 @Observable
-final class AppState {
-    var currentUser: User?
-    var unreadCount: Int = 0
-    var theme: AppTheme = .system
-}
-
-// UIKit side -- read properties directly
-let state = AppState()
-func viewDidLoad() {
-    titleLabel.text = state.currentUser?.name
-}
-
-// SwiftUI side -- observation is automatic
-struct HeaderView: View {
-    let state: AppState
-
-    var body: some View {
-        HStack {
-            Text(state.currentUser?.name ?? "Guest")
-            if state.unreadCount > 0 {
-                Badge(count: state.unreadCount)
-            }
-        }
-    }
+@MainActor
+final class CartModel {
+    var itemCount = 0
 }
 ```
 
-### Reactive Updates in UIKit with Combine
-
-If UIKit code needs to react to `@Observable` changes, bridge with a `withObservationTracking` loop or use `Combine`:
+`@Observable` does not push changes into UIKit by itself. A UIKit controller
+has to observe explicitly, for example with `withObservationTracking` inside a
+long-lived task:
 
 ```swift
-import Combine
-import Observation
+final class CartBadgeViewController: UIViewController {
+    private let cart: CartModel
+    private var observation: Task<Void, Never>?
 
-final class DashboardViewController: UIViewController {
-    let state: AppState
-    private var observationTask: Task<Void, Never>?
+    init(cart: CartModel) {
+        self.cart = cart
+        super.init(nibName: nil, bundle: .main)
+    }
+    required init?(coder: NSCoder) { fatalError("init(coder:) is not supported") }
 
     override func viewDidLoad() {
         super.viewDidLoad()
-        startObserving()
-    }
-
-    private func startObserving() {
-        observationTask = Task { @MainActor [weak self] in
+        observation = Task { @MainActor [weak self, cart] in
             while !Task.isCancelled {
-                guard let self else { return }
-                withObservationTracking {
-                    self.updateUI(unreadCount: self.state.unreadCount)
-                } onChange: {
-                    // Triggers next iteration
+                await withCheckedContinuation { continuation in
+                    withObservationTracking {
+                        self?.title = "\(cart.itemCount) items"
+                    } onChange: {
+                        continuation.resume()
+                    }
                 }
-                try? await Task.sleep(for: .zero) // Yield to allow onChange to fire
             }
         }
     }
 
-    private func updateUI(unreadCount: Int) {
-        badgeLabel.text = "\(unreadCount)"
-    }
-
-    deinit { observationTask?.cancel() }
+    deinit { observation?.cancel() }
 }
 ```
 
-### Legacy: ObservableObject with Combine
+Each pass applies the current value, registers tracking, and suspends until
+the next change. A variant that loops and yields with `Task.sleep(for: .zero)`
+also works, but it wakes constantly; waiting on the `onChange` signal does not.
+The task holds `self` weakly, and `deinit` cancels it; a cancelled task leaves the loop at the next change.
 
-For iOS 15-16 or existing `ObservableObject` models, subscribe to `objectWillChange`:
+**Legacy (iOS 15 and 16, or an `ObservableObject`).** Subscribe to
+`objectWillChange` with Combine and keep the cancellable:
 
 ```swift
-final class SettingsViewController: UIViewController {
-    let settings: SettingsModel  // ObservableObject
-    private var cancellable: AnyCancellable?
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        cancellable = settings.objectWillChange
-            .receive(on: RunLoop.main)
-            .sink { [weak self] _ in
-                self?.updateUI()
-            }
+cancellable = store.objectWillChange
+    .receive(on: RunLoop.main)
+    .sink { [weak self] _ in
+        self?.refreshBadge()
     }
-}
 ```
 
-### Gotchas
-
-- **`@Observable` does not trigger UIKit updates automatically.** Unlike SwiftUI views, UIKit code must manually observe changes via `withObservationTracking` or `Combine`.
-- **Thread safety.** Mutate `@Observable` properties on `@MainActor` when they drive UI in both UIKit and SwiftUI.
-- **Retain cycles.** Use `[weak self]` in Combine sinks and task closures. Store cancellables and tasks, then cancel in `deinit`.
+Rules:
 
----
+- Change UI-driving properties of an `@Observable` model on the `@MainActor`.
+- Capture `[weak self]` in sinks and task closures. Keep cancellables and tasks
+  in stored properties and cancel them in `deinit`.
 
 ## 5. UIHostingConfiguration (iOS 16+)
 
-Render SwiftUI content inside `UICollectionViewCell` and `UITableViewCell` without managing a child `UIHostingController`. This is the preferred approach for cells in a UIKit collection or table view.
-
-### UICollectionView with SwiftUI Cells
+This is the preferred way to put SwiftUI content into UIKit collection and
+table view cells.
 
 ```swift
-@available(iOS 16.0, *)
-func collectionView(
-    _ collectionView: UICollectionView,
-    cellForItemAt indexPath: IndexPath
-) -> UICollectionViewCell {
-    let cell = collectionView.dequeueReusableCell(
-        withReuseIdentifier: "cell",
-        for: indexPath
-    )
-    let item = dataSource[indexPath.item]
-
-    cell.contentConfiguration = UIHostingConfiguration {
-        HStack {
-            AsyncImage(url: item.imageURL) { image in
-                image.resizable().scaledToFill()
-            } placeholder: {
-                ProgressView()
-            }
-            .frame(width: 60, height: 60)
-            .clipShape(.rect(cornerRadius: 8))
-
-            VStack(alignment: .leading) {
-                Text(item.title).font(.headline)
-                Text(item.subtitle).font(.subheadline).foregroundStyle(.secondary)
-            }
+cell.contentConfiguration = UIHostingConfiguration {
+    HStack(spacing: 12) {
+        AsyncImage(url: product.thumbnailURL) { image in
+            image.resizable().scaledToFill()
+        } placeholder: {
+            ProgressView()
         }
+        .frame(width: 56, height: 56)
+        .clipShape(.rect(cornerRadius: 8))
+        Text(product.name)
     }
-    .margins(.all, 12)
-
-    return cell
 }
+.margins(.all, 12)
 ```
 
-### UITableView with SwiftUI Cells
-
-```swift
-@available(iOS 16.0, *)
-func tableView(
-    _ tableView: UITableView,
-    cellForRowAt indexPath: IndexPath
-) -> UITableViewCell {
-    let cell = tableView.dequeueReusableCell(withIdentifier: "cell", for: indexPath)
-    let item = items[indexPath.row]
-
-    cell.contentConfiguration = UIHostingConfiguration {
-        ItemRowView(item: item)
-    }
-
-    return cell
-}
-```
-
-### Self-Sizing
-
-`UIHostingConfiguration` cells self-size automatically. Ensure:
-- The table/collection view uses `UICollectionViewCompositionalLayout` with estimated dimensions, or `tableView.rowHeight = UITableView.automaticDimension`.
-- The SwiftUI content has defined height (via content or explicit `.frame`).
-
-### Background Customization
+Table views work the same way inside `tableView(_:cellForRowAt:)`:
 
 ```swift
+let cell = tableView.dequeueReusableCell(withIdentifier: "order", for: indexPath)
 cell.contentConfiguration = UIHostingConfiguration {
-    ItemRowView(item: item)
+    OrderRowView(order: orders[indexPath.row])
 }
-.background {
-    RoundedRectangle(cornerRadius: 12)
-        .fill(.background)
-}
-.margins(.horizontal, 16)
-.minSize(height: 60)
+return cell
 ```
 
-### Gotchas
+Configuration modifiers include `.background { }`, `.margins(.horizontal, 16)`
+and `.minSize(height: 60)`.
 
-- **Performance.** Each `UIHostingConfiguration` creates a lightweight hosting controller. For very large lists (10,000+ items), profile with Instruments to ensure smooth scrolling.
-- **State management.** The SwiftUI content inside `UIHostingConfiguration` is recreated on each cell reuse. Do not store `@State` that needs to persist across reuse -- use the data model instead.
-- **Swipe actions.** Configure swipe actions in UIKit (`leadingSwipeActionsConfigurationForRowAt`), not inside the SwiftUI content.
-- **No `@Environment` propagation by default.** Environment values from the UIKit context are not automatically available. Inject them explicitly in the `UIHostingConfiguration` closure.
+Notes:
 
----
+- Self-sizing needs a `UICollectionViewCompositionalLayout` with estimated
+  dimensions (for tables, `rowHeight` set to `UITableView.automaticDimension`), plus
+  SwiftUI content that has a definite height.
+- Behind every configuration sits a small hosting controller. For huge
+  lists (10,000 items and up) measure with Instruments.
+- The content is rebuilt when a cell is reused. `@State` inside it does not
+  survive reuse; keep such state in the data model.
+- Swipe actions belong to UIKit (`leadingSwipeActionsConfigurationForRowAt`),
+  not to the SwiftUI content.
+- Environment values from the surrounding UIKit context are not passed in
+  automatically. Inject what you need inside the configuration closure.
 
 ## 6. Environment Bridging
 
-Pass SwiftUI environment values into hosted SwiftUI views from UIKit, and access UIKit traits from SwiftUI.
-
-### Injecting Environment into UIHostingController
+Environment has to be attached before the hosting controller exists. Apply
+`.environment(model)` (iOS 17, for an `@Observable` model),
+`.environment(\.locale, ...)` and similar modifiers to the root view, then
+create the host. Adding environment afterwards means
+assigning a new `rootView`.
 
 ```swift
-let model = AppState()
-let settingsView = SettingsView()
-    .environment(model)
-    .environment(\.locale, Locale(identifier: "en_US"))
-
-let hostingVC = UIHostingController(rootView: settingsView)
+let root = SettingsView()
+    .environment(session)
+    .environment(\.locale, Locale(identifier: "fr_FR"))
+let host = UIHostingController(rootView: root)
 ```
 
-Apply environment modifiers to the root view before passing it to the hosting controller. The hosting controller does not support adding environment values after creation (you would need to reassign `rootView`).
+Traits that bridge on their own:
 
-### Trait Collection to SwiftUI Environment
-
-`UIHostingController` automatically bridges these UIKit trait collections to SwiftUI environment values:
-
-| UIKit Trait | SwiftUI Environment |
-|------------|-------------------|
+| UIKit trait | SwiftUI environment |
+|-------------|---------------------|
 | `userInterfaceStyle` | `\.colorScheme` |
 | `horizontalSizeClass` | `\.horizontalSizeClass` |
 | `verticalSizeClass` | `\.verticalSizeClass` |
@@ -465,70 +312,40 @@ Apply environment modifiers to the root view before passing it to the hosting co
 | `layoutDirection` | `\.layoutDirection` |
 | `legibilityWeight` | `\.legibilityWeight` |
 
-These update automatically when the UIKit trait environment changes (device rotation, split view resize, accessibility settings change).
+These stay current as the device rotates, a split view resizes, or an
+accessibility setting changes. `host.overrideUserInterfaceStyle` forces light
+or dark and flows through to `\.colorScheme`.
 
-### Custom Environment Values Across the Bridge
+**Custom values.** Declare an `EnvironmentKey` with a `defaultValue`, extend
+`EnvironmentValues`, set it from UIKit with `.environment(\.yourKey, value)`
+and read it in SwiftUI with `@Environment(\.yourKey)`. The navigator in pattern
+3 is an example.
 
-Define a custom environment key and set it from UIKit:
+**Changing environment after creation (iOS 17+).** Wrap the content in a
+container view that reads an `@Observable` state object and applies the environment. Mutating
+that object then updates the environment without touching `rootView`.
 
 ```swift
-private struct UserRoleKey: EnvironmentKey {
-    static let defaultValue: UserRole = .guest
-}
-
-extension EnvironmentValues {
-    var userRole: UserRole {
-        get { self[UserRoleKey.self] }
-        set { self[UserRoleKey.self] = newValue }
-    }
-}
-
-// UIKit side:
-let role = authManager.currentRole
-let profileView = ProfileView().environment(\.userRole, role)
-let hostingVC = UIHostingController(rootView: profileView)
-
-// SwiftUI side:
-struct ProfileView: View {
-    @Environment(\.userRole) private var role
-
-    var body: some View {
-        if role == .admin {
-            AdminDashboard()
-        } else {
-            UserDashboard()
-        }
-    }
+@Observable
+@MainActor
+final class HostedEnvironment {
+    var locale = Locale.current
 }
-```
-
-### Updating Environment After Creation
-
-To change environment values after the hosting controller is created, wrap the root view in a container that takes a binding or observable:
 
-```swift
 struct EnvironmentBridge<Content: View>: View {
-    let state: AppState  // @Observable
-    let content: Content
+    let state: HostedEnvironment
+    @ViewBuilder var content: Content
 
     var body: some View {
-        content
-            .environment(state)
-            .environment(\.userRole, state.currentRole)
+        content.environment(\.locale, state.locale)
     }
 }
-
-// UIKit:
-let state = AppState()
-let bridge = EnvironmentBridge(state: state, content: SettingsView())
-let hostingVC = UIHostingController(rootView: bridge)
-
-// Later: mutating state.currentRole updates the environment automatically
-state.currentRole = .admin
 ```
 
-### Gotchas
+Pitfalls:
 
-- **`@Environment(\.dismiss)` in hosted views.** This works when the `UIHostingController` is presented modally (via `present(_:animated:)`). It does NOT work when the hosting controller is pushed onto a `UINavigationController` -- use the navigation controller's `popViewController` instead.
-- **Missing environment.** If a SwiftUI view expects an `@Environment` object and it is not provided, the app crashes at runtime. Always set required environment values before creating the hosting controller.
-- **Overriding traits.** Use `hostingVC.overrideUserInterfaceStyle` to force light/dark mode for a hosted SwiftUI view. This propagates to `\.colorScheme` automatically.
+- `@Environment(\.dismiss)` inside a hosted view works when the host was shown
+  with `present(_:animated:)`. It does nothing when the host was pushed onto a
+  `UINavigationController`; call `popViewController(animated:)` there instead.
+- A required environment object that is missing crashes at runtime. Set every
+  one before creating the hosting controller.