@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-uikit-interop/SKILL.md

@@ -1,430 +1,438 @@
 ---
 name: swiftui-uikit-interop
-description: "Bridges UIKit and SwiftUI by wrapping UIKit views and view controllers in SwiftUI with UIViewRepresentable and UIViewControllerRepresentable, embedding SwiftUI in UIKit with UIHostingController, and coordinating delegate callbacks. Use when integrating camera previews, map views, mail compose, document scanners, PDF renderers, text views with attributed text, or other UIKit-only or third-party UIKit SDK surfaces into a SwiftUI app, or when migrating a UIKit app to SwiftUI incrementally."
+description: "UIKit and SwiftUI interop: UIViewRepresentable, UIViewControllerRepresentable, UIHostingController, UIHostingConfiguration, Coordinator delegate bridging. Use when SwiftUI needs a camera preview, map view, mail compose, document scanner, PDF renderer, attributed text view or another UIKit-only or third-party UIKit SDK surface, or when migrating a UIKit app to SwiftUI step by step. Not for web content (swiftui-webkit)."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# SwiftUI-UIKit Interop
+# SwiftUI and UIKit Interop
 
-Bridge UIKit and SwiftUI in both directions. Wrap UIKit views and view controllers for use in SwiftUI, embed SwiftUI views inside UIKit screens, and synchronize state across the boundary. Targets iOS 26+ with Swift 6.3 patterns; notes backward-compatible to iOS 16 unless stated otherwise.
+SwiftUI and UIKit meet at three seams: a UIKit view or controller shown inside
+SwiftUI (the representable protocols), SwiftUI shown inside UIKit (the hosting
+controller and the hosting cell configuration), and the object that carries
+UIKit callbacks back into SwiftUI state (the Coordinator). This skill covers all
+three. Patterns target iOS 26 and Swift 6.3 and stay usable back to iOS 16
+unless a section says otherwise.
 
-See [references/representable-recipes.md](references/representable-recipes.md) for complete wrapping recipes and [references/hosting-migration.md](references/hosting-migration.md) for UIKit-to-SwiftUI migration patterns.
+Detailed material lives in two references:
 
-## Contents
-
-- [UIViewRepresentable Protocol](#uiviewrepresentable-protocol)
-- [UIViewControllerRepresentable Protocol](#uiviewcontrollerrepresentable-protocol)
-- [The Coordinator Pattern](#the-coordinator-pattern)
-- [UIHostingController](#uihostingcontroller)
-- [Sizing and Layout](#sizing-and-layout)
-- [State Synchronization Patterns](#state-synchronization-patterns)
-- [Sendable Considerations](#sendable-considerations)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+- [wrapper recipes](references/representable-recipes.md):
+  nine complete wrappers (map, attributed text view, camera preview, photo
+  picker, mail, share sheet, search bar, PDF view, SMS) with usage and pitfalls.
+- [migration guide](references/hosting-migration.md): moving a
+  UIKit app to SwiftUI one piece at a time, including navigation, shared data
+  and environment bridging.
 
-## UIViewRepresentable Protocol
+Embedded web content is out of scope: on iOS 26 use the native SwiftUI WebKit
+types and the `swiftui-webkit` skill.
 
-Use `UIViewRepresentable` to wrap any `UIView` subclass for use in SwiftUI.
+## Contents
 
-### Required Methods
+1. [Wrapping a view](#1-uiviewrepresentable)
+2. [Wrapping a controller](#2-uiviewcontrollerrepresentable)
+3. [Coordinators](#3-the-coordinator-pattern)
+4. [Hosting SwiftUI in a controller](#4-uihostingcontroller)
+5. [Hosting SwiftUI in cells](#5-uihostingconfiguration-ios-16)
+6. [Sizing](#6-sizing-and-layout)
+7. [Keeping state in sync](#7-state-synchronization)
+8. [Concurrency](#8-swift-concurrency-and-sendable)
+9. [Mistakes](#9-common-mistakes)
+10. [Checklist](#10-review-checklist)
+
+## 1. UIViewRepresentable
+
+`UIViewRepresentable` lets SwiftUI display any `UIView` subclass. Two methods
+are required:
+
+- `makeUIView(context:)` builds and returns the UIKit view. SwiftUI calls it a
+  single time, when the representable is inserted. Put one-time setup here:
+  delegate assignment, fonts, static configuration.
+- `updateUIView(_:context:)` pushes SwiftUI state into the view. It runs again
+  for every relevant state change, so compare before you assign. Writing a value
+  the view already holds can trigger a delegate callback that writes the binding
+  that calls update again.
 
 ```swift
-struct WrappedTextView: UIViewRepresentable {
-    @Binding var text: String
+import UIKit
+import SwiftUI
+
+struct PlainTextEditor: UIViewRepresentable {
+    @Binding var draft: String
+
+    func makeCoordinator() -> Coordinator { Coordinator(parent: self) }
 
     func makeUIView(context: Context) -> UITextView {
-        // Called ONCE when SwiftUI inserts this view into the hierarchy.
-        // Create and return the UIKit view. One-time setup goes here.
-        let textView = UITextView()
-        textView.delegate = context.coordinator
-        textView.font = .preferredFont(forTextStyle: .body)
-        return textView
+        let editor = UITextView(frame: .zero)
+        editor.delegate = context.coordinator
+        editor.font = .preferredFont(forTextStyle: .body)
+        return editor
     }
 
-    func updateUIView(_ uiView: UITextView, context: Context) {
-        // Called on EVERY SwiftUI state change that affects this view.
-        // Synchronize SwiftUI state into the UIKit view.
-        // Guard against redundant updates to avoid loops.
-        if uiView.text != text {
-            uiView.text = text
+    func updateUIView(_ editor: UITextView, context: Context) {
+        context.coordinator.parent = self
+        guard editor.text != draft else { return }
+        editor.text = draft
+    }
+
+    @MainActor
+    final class Coordinator: NSObject, UITextViewDelegate {
+        init(parent: PlainTextEditor) { self.parent = parent }
+        var parent: PlainTextEditor
+
+        func textViewDidChange(_ editor: UITextView) {
+            parent.draft = editor.text
         }
     }
 }
 ```
 
-### Lifecycle Timing
+### Lifecycle order
 
-| Method | When Called | Purpose |
-|--------|-----------|---------|
-| `makeCoordinator()` | Before `makeUIView`. Once per representable lifetime. | Create the delegate/datasource reference type. |
-| `makeUIView(context:)` | Once, when the representable enters the view tree. | Allocate and configure the UIKit view. |
-| `updateUIView(_:context:)` | Immediately after `makeUIView`, then on every relevant state change. | Push SwiftUI state into the UIKit view. |
-| `dismantleUIView(_:coordinator:)` | When the representable is removed from the view tree. | Clean up observers, timers, subscriptions. |
-| `sizeThatFits(_:uiView:context:)` | During layout, when SwiftUI needs the view's ideal size. iOS 16+. | Return a custom size proposal. |
+| Step | Method | When it runs | Job |
+|------|--------|--------------|-----|
+| 1 | `makeCoordinator()` | Before `makeUIView`, once for the representable's lifetime | Create the reference object that acts as delegate or data source |
+| 2 | `makeUIView(context:)` | Once, when the view joins the tree | Build the UIKit object and set it up |
+| 3 | `updateUIView(_:context:)` | Immediately after make, then on each relevant change | Copy SwiftUI state into UIKit |
+| 4 | `dismantleUIView(_:coordinator:)` | When the view leaves the tree | Tear down: observers removed, timers invalidated, subscriptions cancelled |
+| - | `sizeThatFits(_:uiView:context:)` | While laying out, if SwiftUI wants an ideal size (iOS 16+) | Report a custom size |
 
-**Why `updateUIView` is the most important method:** SwiftUI calls it every time any `@Binding`, `@State`, `@Environment`, or `@Observable` property read by the representable changes. All state synchronization from SwiftUI to UIKit happens here. If you skip a property, the UIKit view will fall out of sync.
+SwiftUI calls `updateUIView` whenever anything the representable reads changes:
+a `@Binding`, `@State`, `@Environment` value or a property of an `@Observable`
+model. A property you forget to apply in `updateUIView` silently goes stale.
 
 ### Optional: dismantleUIView
 
+`dismantleUIView` is a `static` function. SwiftUI hands it both the UIKit view
+and the Coordinator, so anything the coordinator stores can be released there.
+
+For a coordinator that keeps a list of cancellable observation tokens:
+
 ```swift
-static func dismantleUIView(_ uiView: UITextView, coordinator: Coordinator) {
-    // Remove observers, invalidate timers, cancel subscriptions.
-    // The coordinator is passed in so you can access state stored on it.
-    coordinator.cancellables.removeAll()
+static func dismantleUIView(_ editor: UITextView, coordinator: Coordinator) {
+    coordinator.observationTokens.forEach { $0.cancel() }
+    coordinator.observationTokens.removeAll()
 }
 ```
 
 ### Optional: sizeThatFits (iOS 16+)
 
+A `nil` result means SwiftUI falls back to the view's `intrinsicContentSize`. Return a
+`CGSize` and SwiftUI uses that size instead of its own choice.
+
 ```swift
 @available(iOS 16.0, *)
-func sizeThatFits(
-    _ proposal: ProposedViewSize,
-    uiView: UITextView,
-    context: Context
-) -> CGSize? {
-    // Return nil to fall back to UIKit's intrinsicContentSize.
-    // Return a CGSize to override SwiftUI's sizing for this view.
-    let width = proposal.width ?? UIView.layoutFittingExpandedSize.width
-    let size = uiView.sizeThatFits(CGSize(width: width, height: .greatestFiniteMagnitude))
-    return size
+func sizeThatFits(_ proposal: ProposedViewSize,
+                  uiView editor: UITextView,
+                  context: Context) -> CGSize? {
+    let targetWidth = proposal.width ?? UIView.layoutFittingExpandedSize.width
+    return editor.sizeThatFits(
+        CGSize(width: targetWidth, height: .greatestFiniteMagnitude)
+    )
 }
 ```
 
-## UIViewControllerRepresentable Protocol
+## 2. UIViewControllerRepresentable
 
-Use `UIViewControllerRepresentable` to wrap a `UIViewController` subclass -- typically for system pickers, document scanners, mail compose, or any controller that presents modally.
+Wrap a `UIViewController` subclass with `UIViewControllerRepresentable`. It is
+the right choice for pickers the system provides, a scanner for documents, the
+mail composer, and other controllers that are normally presented modally.
+The methods mirror the view version: `makeUIViewController(context:)`, `updateUIViewController(_:context:)`
+and `makeCoordinator()`. For a modal controller the update method usually
+has nothing to push after presentation; it only refreshes the coordinator's
+`parent`.
 
 ```swift
-struct DocumentScannerView: UIViewControllerRepresentable {
-    @Binding var scannedImages: [UIImage]
-    @Environment(\.dismiss) private var dismiss
+import VisionKit
+import SwiftUI
+
+struct PageScannerView: UIViewControllerRepresentable {
+    @Environment(\.dismiss) var close
+    @Binding var pages: [UIImage]
+
+    func makeCoordinator() -> Coordinator { Coordinator(parent: self) }
 
     func makeUIViewController(context: Context) -> VNDocumentCameraViewController {
-        let scanner = VNDocumentCameraViewController()
-        scanner.delegate = context.coordinator
-        return scanner
+        let camera = VNDocumentCameraViewController()
+        camera.delegate = context.coordinator
+        return camera
     }
 
-    func updateUIViewController(_ uiViewController: VNDocumentCameraViewController, context: Context) {
-        // Usually empty for modal controllers -- nothing to push from SwiftUI.
+    func updateUIViewController(_ camera: VNDocumentCameraViewController,
+                                context: Context) {
+        context.coordinator.parent = self
     }
-
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
 }
 ```
 
-### Handling Results from Presented Controllers
+### Returning results from a presented controller
 
-The coordinator captures delegate callbacks and routes results back to SwiftUI through the parent's `@Binding` or closures:
+Delegate callbacks land in the Coordinator, which passes results on by writing
+a `@Binding` or calling a closure stored on `parent`. Every exit path, success, cancel
+and failure, ends by dismissing.
 
 ```swift
-extension DocumentScannerView {
-    final class Coordinator: NSObject, VNDocumentCameraViewControllerDelegate {
-        let parent: DocumentScannerView
-
-        init(_ parent: DocumentScannerView) { self.parent = parent }
-
-        func documentCameraViewController(
-            _ controller: VNDocumentCameraViewController,
-            didFinishWith scan: VNDocumentCameraScan
-        ) {
-            parent.scannedImages = (0..<scan.pageCount).map { scan.imageOfPage(at: $0) }
-            parent.dismiss()
+extension PageScannerView {
+    @MainActor
+    final class Coordinator: NSObject, @preconcurrency VNDocumentCameraViewControllerDelegate {
+        init(parent: PageScannerView) { self.parent = parent }
+        var parent: PageScannerView
+
+        func documentCameraViewController(_ camera: VNDocumentCameraViewController,
+                                          didFinishWith result: VNDocumentCameraScan) {
+            parent.pages = (0..<result.pageCount).map { index in result.imageOfPage(at: index) }
+            parent.close()
         }
 
-        func documentCameraViewControllerDidCancel(_ controller: VNDocumentCameraViewController) {
-            parent.dismiss()
+        func documentCameraViewControllerDidCancel(_ camera: VNDocumentCameraViewController) {
+            parent.close()
         }
 
-        func documentCameraViewController(
-            _ controller: VNDocumentCameraViewController,
-            didFailWithError error: Error
-        ) {
-            parent.dismiss()
+        func documentCameraViewController(_ camera: VNDocumentCameraViewController,
+                                          didFailWithError failure: Error) {
+            parent.close()
         }
     }
 }
 ```
 
-## The Coordinator Pattern
+The coordinator is a `final class` that subclasses `NSObject`, adopts the
+delegate protocol, stores `parent`, and is built from `makeCoordinator()` by
+passing `self`.
+
+## 3. The Coordinator Pattern
 
-### Why Coordinators Exist
+### Why it exists
 
-UIKit delegates, data sources, and target-action patterns require a reference type (`class`). SwiftUI representable structs are value types and cannot serve as delegates. The Coordinator is a `class` instance that SwiftUI creates and manages for you -- it lives as long as the representable view.
+Delegates, data sources and target-action receivers in UIKit have to be class
+instances. A representable is a struct, so it cannot play that role. The
+Coordinator is the class that does. SwiftUI creates it, owns it, and keeps it
+alive exactly as long as the representable.
 
-### Structure
+### Shape
 
-Always nest the Coordinator inside the representable or in an extension. Store a reference to `parent` (the representable struct) so the coordinator can write back to `@Binding` properties.
+Declare the Coordinator as a nested type of the representable, directly or
+through an extension. Give it a `parent` property holding the representable
+struct; that is how it writes to `@Binding` properties and calls closures.
 
 ```swift
-struct SearchBarView: UIViewRepresentable {
-    @Binding var text: String
-    var onSearch: (String) -> Void
+struct LegacySearchField: UIViewRepresentable {
+    @Binding var query: String
+    var onSubmit: (String) -> Void
 
-    func makeCoordinator() -> Coordinator { Coordinator(self) }
+    func makeCoordinator() -> Coordinator { .init(parent: self) }
 
     func makeUIView(context: Context) -> UISearchBar {
-        let bar = UISearchBar()
-        bar.delegate = context.coordinator  // Set delegate HERE, not in updateUIView
+        let bar = UISearchBar(frame: .zero)
+        bar.delegate = context.coordinator
         return bar
     }
 
-    func updateUIView(_ uiView: UISearchBar, context: Context) {
-        if uiView.text != text {
-            uiView.text = text
-        }
+    func updateUIView(_ bar: UISearchBar, context: Context) {
+        context.coordinator.parent = self
+        if bar.text != query { bar.text = query }
     }
 
+    @MainActor
     final class Coordinator: NSObject, UISearchBarDelegate {
-        var parent: SearchBarView
-
-        init(_ parent: SearchBarView) { self.parent = parent }
+        init(parent: LegacySearchField) { self.parent = parent }
+        var parent: LegacySearchField
 
-        func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
-            parent.text = searchText
+        func searchBar(_ bar: UISearchBar, textDidChange newText: String) {
+            parent.query = newText
         }
 
-        func searchBarSearchButtonClicked(_ searchBar: UISearchBar) {
-            parent.onSearch(parent.text)
-            searchBar.resignFirstResponder()
+        func searchBarSearchButtonClicked(_ bar: UISearchBar) {
+            parent.onSubmit(parent.query)
+            bar.resignFirstResponder()
         }
     }
 }
 ```
 
-### Key Rules
+### Rules
 
-1. **Set the delegate in `makeUIView`/`makeUIViewController`, never in `updateUIView`.** The update method runs on every state change -- setting the delegate there causes redundant assignment and can trigger unexpected side effects.
+- Assign the coordinator as delegate in `makeUIView` or
+  `makeUIViewController`. Doing it in the update method repeats the assignment
+  on every state change and can cause side effects inside the UIKit object.
+- SwiftUI does not refresh `coordinator.parent` for you. The coordinator is
+  created once with the first struct value, while SwiftUI builds a new struct
+  on every update. Start `updateUIView` (or `updateUIViewController`) with
+  `context.coordinator.parent = self`, so the coordinator always reads the
+  current bindings and closures before the next delegate callback arrives.
+- When a UIKit object stores a closure that refers to the coordinator, capture
+  it as `[weak coordinator]` to avoid a retain cycle.
 
-2. **The coordinator's `parent` property is updated automatically.** SwiftUI updates the coordinator's reference to the latest representable struct value before each call to `updateUIView`. This means the coordinator always sees current `@Binding` values through `parent`.
+## 4. UIHostingController
 
-3. **Use `[weak coordinator]` in closures** to avoid retain cycles between the coordinator and UIKit objects that capture it.
+### Basic embedding
 
-## UIHostingController
-
-Embed SwiftUI views inside UIKit view controllers using `UIHostingController`.
-
-### Basic Embedding
+`UIHostingController(rootView:)` puts a SwiftUI view inside a UIKit
+controller. Containment has three steps and the order is fixed:
 
 ```swift
-final class ProfileViewController: UIViewController {
-    private let hostingController = UIHostingController(rootView: ProfileView())
+final class ProfileScreenController: UIViewController {
+    let summaryHost = UIHostingController(rootView: ProfileSummary(profile: .empty))
 
     override func viewDidLoad() {
         super.viewDidLoad()
+        addChild(summaryHost)                                   // 1
 
-        // 1. Add as child
-        addChild(hostingController)
-
-        // 2. Add and constrain the view
-        hostingController.view.translatesAutoresizingMaskIntoConstraints = false
-        view.addSubview(hostingController.view)
+        let hosted: UIView = summaryHost.view
+        hosted.translatesAutoresizingMaskIntoConstraints = false // 2
+        view.addSubview(hosted)
         NSLayoutConstraint.activate([
-            hostingController.view.topAnchor.constraint(equalTo: view.topAnchor),
-            hostingController.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
-            hostingController.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
-            hostingController.view.bottomAnchor.constraint(equalTo: view.bottomAnchor),
+            hosted.topAnchor.constraint(equalTo: view.topAnchor),
+            hosted.bottomAnchor.constraint(equalTo: view.bottomAnchor),
+            hosted.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+            hosted.trailingAnchor.constraint(equalTo: view.trailingAnchor)
         ])
 
-        // 3. Notify the child
-        hostingController.didMove(toParent: self)
+        summaryHost.didMove(toParent: self)                     // 3
     }
 }
 ```
 
-The three-step sequence (addChild, add view, didMove) is mandatory. Skipping any step causes containment callbacks to misfire, which breaks appearance transitions and trait propagation.
+Leave out any step and containment callbacks, appearance transitions and trait
+propagation stop working correctly.
 
-### Sizing Options (iOS 16+)
+### Sizing options (iOS 16+)
 
-```swift
-@available(iOS 16.0, *)
-hostingController.sizingOptions = [.intrinsicContentSize]
-```
+`sizingOptions` is an option set on the hosting controller:
 
-| Option | Effect |
-|--------|--------|
-| `.intrinsicContentSize` | The hosting controller's view reports its SwiftUI content size as `intrinsicContentSize`. Use in Auto Layout when the hosted view should size itself. |
-| `.preferredContentSize` | Updates `preferredContentSize` to match SwiftUI content. Use when presenting as a popover or form sheet. |
+| Option | Effect | Use for |
+|--------|--------|---------|
+| `.intrinsicContentSize` | The hosting view reports the SwiftUI content size as its `intrinsicContentSize` | Self-sizing under Auto Layout |
+| `.preferredContentSize` | `preferredContentSize` follows the SwiftUI content size | Popovers and form sheets |
 
-### Updating the Root View
+### Updating the root view
 
-When data changes in UIKit, push new state into the hosted SwiftUI view:
+To push new data from UIKit, assign a new value: `summaryHost.rootView =
+ProfileSummary(profile: updated)`. If the SwiftUI view instead receives an
+`@Observable` model, SwiftUI tracks its changes and no reassignment is needed.
 
-```swift
-func updateProfile(_ profile: Profile) {
-    hostingController.rootView = ProfileView(profile: profile)
-}
-```
+## 5. UIHostingConfiguration (iOS 16+)
 
-For observable models, pass an `@Observable` object and SwiftUI tracks changes automatically -- no need to reassign `rootView`.
-
-### UIHostingConfiguration (iOS 16+)
-
-Render SwiftUI content directly inside `UICollectionViewCell` or `UITableViewCell` without managing a child hosting controller:
+For cells, set `contentConfiguration` to a `UIHostingConfiguration`. SwiftUI
+content renders directly in a `UICollectionViewCell` or `UITableViewCell`
+without creating a child hosting controller yourself.
 
 ```swift
-@available(iOS 16.0, *)
-func collectionView(
-    _ collectionView: UICollectionView,
-    cellForItemAt indexPath: IndexPath
-) -> UICollectionViewCell {
-    let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "cell", for: indexPath)
+func collectionView(_ grid: UICollectionView,
+                    cellForItemAt position: IndexPath) -> UICollectionViewCell {
+    let contact = contacts[position.item]
+    let cell = grid.dequeueReusableCell(withReuseIdentifier: "contact", for: position)
     cell.contentConfiguration = UIHostingConfiguration {
-        ItemRow(item: items[indexPath.item])
+        ContactRow(contact: contact)
     }
     return cell
 }
 ```
 
-## Sizing and Layout
-
-### intrinsicContentSize Bridging
+Margins, backgrounds, self-sizing and reuse rules are in
+[the migration guide, pattern 5](references/hosting-migration.md#5-uihostingconfiguration-ios-16).
 
-UIKit views wrapped in `UIViewRepresentable` communicate their natural size to SwiftUI through `intrinsicContentSize`. SwiftUI respects this during layout unless overridden by `frame()` or `fixedSize()`.
+## 6. Sizing and Layout
 
-### fixedSize() and frame() Interactions
+A wrapped UIKit view tells SwiftUI its natural size through
+`intrinsicContentSize`. SwiftUI respects it unless `frame()` or `fixedSize()`
+says otherwise.
 
-| SwiftUI Modifier | Effect on Representable |
-|-----------------|------------------------|
-| No modifier | SwiftUI uses `intrinsicContentSize` as ideal size; the view is flexible. |
-| `.fixedSize()` | Forces the representable to its ideal (intrinsic) size in both axes. |
-| `.fixedSize(horizontal: true, vertical: false)` | Fixes width to intrinsic; height remains flexible. |
-| `.frame(width:height:)` | Overrides the proposed size; UIKit view receives this size. |
+| Modifier on the representable | Result |
+|-------------------------------|--------|
+| none | Intrinsic size is the ideal size; the view can still grow or shrink |
+| `.frame(width:height:)` | Replaces the proposed size; the UIKit view gets exactly that size |
+| `.fixedSize()` | Locked to the intrinsic size in width and height |
+| `.fixedSize(horizontal: true, vertical: false)` | Width locked to intrinsic, height flexible |
 
-### Auto Layout with UIHostingController
+When SwiftUI is the child inside UIKit, pin the hosting view with constraints
+and set `sizingOptions = [.intrinsicContentSize]`; that is how Auto Layout
+learns the natural size. Self-sizing cells and sections of variable height
+depend on this.
 
-When embedding `UIHostingController` as a child, pin its view with constraints. Use `.sizingOptions = [.intrinsicContentSize]` so Auto Layout can query the SwiftUI content's natural size for self-sizing cells or variable-height sections.
+## 7. State Synchronization
 
-## State Synchronization Patterns
+**Two-way with `@Binding`.** The coordinator writes `parent.value` from a
+delegate method; `updateUIView` reads the binding and applies it to the view.
+The `PlainTextEditor` above does both halves (`textViewDidChange(_:)` writes,
+the update method applies).
 
-### `@Binding`: Two-Way Sync (SwiftUI <-> UIKit)
-
-Use `@Binding` when both sides read and write the same value. The coordinator writes to `parent.bindingProperty` in delegate callbacks; `updateUIView` reads the binding and pushes it into the UIKit view.
+**One-way with closures.** For events that flow only from UIKit to SwiftUI
+(tap, submit, scan finished), give the representable an optional closure
+property such as `var onScanComplete: ((String) -> Void)?`. The coordinator
+calls `parent.onScanComplete?(code)` when UIKit reports the event, and SwiftUI
+supplies the closure at the call site:
 
 ```swift
-// SwiftUI -> UIKit: in updateUIView
-if uiView.text != text { uiView.text = text }
-
-// UIKit -> SwiftUI: in Coordinator delegate method
-func textViewDidChange(_ textView: UITextView) {
-    parent.text = textView.text
-}
+TicketBarcodeView(onScanComplete: { code in checkIn.validate(code) })
 ```
 
-### Closures: One-Way Events (UIKit -> SwiftUI)
-
-For fire-and-forget events (button tapped, search submitted, scan completed), pass a closure instead of a binding:
+**Environment.** Inside the representable methods read SwiftUI environment
+values from `context.environment`:
 
 ```swift
-struct WebViewWrapper: UIViewRepresentable {
-    let url: URL
-    var onNavigationFinished: ((URL) -> Void)?
+func updateUIView(_ editor: UITextView, context: Context) {
+    context.coordinator.parent = self
+    let environment = context.environment
+    editor.isEditable = environment.isEnabled
+    editor.backgroundColor = environment.colorScheme == .dark
+        ? .secondarySystemBackground : .systemBackground
 }
 ```
 
-### Environment Values
-
-Access SwiftUI environment values inside representable methods via `context.environment`:
-
-```swift
-func updateUIView(_ uiView: UITextView, context: Context) {
-    let isEnabled = context.environment.isEnabled
-    uiView.isEditable = isEnabled
-
-    // Respond to color scheme changes
-    let colorScheme = context.environment.colorScheme
-    uiView.backgroundColor = colorScheme == .dark ? .systemGray6 : .white
-}
-```
-
-### Avoiding Update Loops
-
-`updateUIView` is called whenever SwiftUI state changes -- including changes triggered by the coordinator writing to a `@Binding`. Guard against redundant updates to prevent infinite loops:
-
-```swift
-func updateUIView(_ uiView: UITextView, context: Context) {
-    // GUARD: Only update if values actually differ
-    if uiView.text != text {
-        uiView.text = text
-    }
-}
-```
-
-Without the guard, setting `uiView.text` may trigger the delegate's `textViewDidChange`, which writes to `parent.text`, which triggers `updateUIView` again.
-
-## Sendable Considerations
-
-UIKit delegate protocols are not `Sendable`. When the coordinator conforms to a UIKit delegate, it inherits main-actor isolation from UIKit. Mark coordinators `@MainActor` or use `nonisolated` only for methods that truly do not touch UIKit state. In Swift 6 strict concurrency:
-
-```swift
-@MainActor
-final class Coordinator: NSObject, UISearchBarDelegate {
-    var parent: SearchBarView
-    init(_ parent: SearchBarView) { self.parent = parent }
-    // Delegate methods are main-actor-isolated -- safe to access UIKit and @Binding.
-}
-```
-
-If passing closures across isolation boundaries, ensure they are `@Sendable` or captured on the correct actor.
-
-## Common Mistakes
-
-### DO / DON'T
-
-**DON'T:** Create the UIKit view in `updateUIView`.
-**DO:** Create the view once in `makeUIView`; only configure/update it in `updateUIView`.
-*Why:* `updateUIView` runs on every state change. Creating a new view each time destroys all UIKit state (selection, scroll position, first responder) and leaks memory.
-
-**DON'T:** Set delegates in `updateUIView`.
-**DO:** Set delegates in `makeUIView`/`makeUIViewController` only.
-*Why:* Redundant delegate assignment on every update can reset internal delegate state in UIKit views like `WKWebView` or `MKMapView`.
-
-**DON'T:** Hold strong references to the Coordinator from closures.
-**DO:** Use `[weak coordinator]` in closures.
-*Why:* UIKit objects often store closures (completion handlers, action blocks). A strong reference to the coordinator that holds a reference to the UIKit view creates a retain cycle.
-
-**DON'T:** Forget to call `parent.dismiss()` or completion handlers.
-**DO:** Use the coordinator to track dismissal and invoke `parent.dismiss()` in all delegate exit paths.
-*Why:* Modal controllers presented by SwiftUI (via `.sheet`) need their dismiss binding toggled, or the sheet state becomes inconsistent.
-
-**DON'T:** Ignore `dismantleUIView` for views that hold observers or timers.
-**DO:** Clean up `NotificationCenter` observers, `Combine` subscriptions, and `Timer` instances in `dismantleUIView`.
-*Why:* Without cleanup, observers and timers continue firing after the view is removed, causing crashes or stale state updates.
-
-**DON'T:** Force `UIHostingController`'s view to fill the parent without proper constraints.
-**DO:** Use Auto Layout constraints or `sizingOptions` for proper embedding.
-*Why:* Setting `frame` manually breaks adaptive layout, trait propagation, and safe area handling.
-
-**DON'T:** Try to use `@State` in the Coordinator -- it is not a `View`.
-**DO:** Use regular stored properties on the Coordinator and communicate to SwiftUI via `parent`'s `@Binding` properties.
-*Why:* `@State` only works inside `View` conformances. Using it on a class has no effect.
-
-**DON'T:** Skip the `addChild`/`didMove(toParent:)` dance when embedding `UIHostingController`.
-**DO:** Always call `addChild(_:)`, add the view to the hierarchy, then call `didMove(toParent:)`.
-*Why:* Skipping containment causes viewWillAppear/viewDidAppear to never fire, breaks trait collection propagation, and causes visual glitches.
-
-## Review Checklist
-
-- [ ] View/controller created in `make*`, not `update*`
-- [ ] Coordinator set as delegate in `make*`, not `update*`
-- [ ] `@Binding` used for two-way state sync
-- [ ] `updateUIView` handles all SwiftUI state changes with redundancy guards
-- [ ] `dismantleUIView` cleans up observers/timers if needed
-- [ ] No retain cycles between coordinator and closures (`[weak coordinator]`)
-- [ ] `UIHostingController` properly added as child (`addChild` + `didMove(toParent:)`)
-- [ ] Sizing strategy chosen (`intrinsicContentSize` vs fixed `frame` vs `sizeThatFits`)
-- [ ] Environment values read in `updateUIView` via `context.environment` where needed
-- [ ] Coordinator marked `@MainActor` for strict concurrency
-- [ ] Modal controllers dismiss in all delegate exit paths (success, cancel, error)
-- [ ] `UIHostingConfiguration` used for collection/table view cells instead of manual hosting (iOS 16+)
+**Why the equality guard matters.** Assigning to the UIKit view may fire its
+delegate, the delegate writes the binding, the binding change calls
+`updateUIView`, which assigns again. Checking for a difference before assigning
+is what ends that cycle.
+
+## 8. Swift Concurrency and Sendable
+
+- Delegate protocols in UIKit are main-actor protocols, not `Sendable` ones. A
+  coordinator adopting one is isolated to the main actor through that
+  conformance.
+- Some framework delegates carry no isolation at all, for example
+  `VNDocumentCameraViewControllerDelegate`, `MFMailComposeViewControllerDelegate`
+  and `MFMessageComposeViewControllerDelegate`. A `@MainActor` coordinator that
+  adopts one plainly fails in Swift 6 with "conformance ... crosses into main
+  actor-isolated code". Write `@preconcurrency` before the protocol name: the
+  conformance compiles, and the callbacks are checked at run time to arrive on
+  the main thread, which is where these controllers deliver them.
+- Mark coordinators `@MainActor`. Use `nonisolated` only on methods that never
+  touch UIKit state.
+- A closure that crosses an isolation boundary must be `@Sendable` or captured
+  on the actor it runs on.
+
+## 9. Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Creating the UIKit view inside `updateUIView` | Selection, scroll offset and first responder are lost, and memory leaks | Create once in `makeUIView` |
+| Setting delegates inside `updateUIView` | Objects such as `WKWebView` or `MKMapView` may reset their own delegate bookkeeping | Assign in `make*` |
+| Strong capture of the coordinator in a closure a UIKit object keeps | Retain cycle coordinator to view and back | `[weak coordinator]` |
+| Forgetting `parent.dismiss()` or the completion on one delegate path | A `.sheet` presenting the controller is left in an inconsistent state | Dismiss on every exit path |
+| Leaving `NotificationCenter` observers, Combine subscriptions or `Timer`s alive | They keep firing after removal: crashes and stale updates | Tear down in `dismantleUIView` |
+| Sizing the hosting view by setting `frame` by hand | Safe areas, trait propagation and adaptive layout stop working | Constraints or `sizingOptions` |
+| Using `@State` in a Coordinator | Does nothing, the coordinator is not a `View` | Plain stored properties, talk to SwiftUI through `parent` bindings |
+| Skipping `addChild` or `didMove(toParent:)` | `viewWillAppear` and `viewDidAppear` never run, traits do not propagate, visual glitches | Full containment sequence |
+
+## 10. Review Checklist
+
+- [ ] View or controller created in `make*`, never in `update*`
+- [ ] Delegate assignment to the coordinator happens in `make*`, never in `update*`
+- [ ] `@Binding` used where data flows both ways
+- [ ] `updateUIView` applies every piece of state it depends on, each behind a difference check
+- [ ] `dismantleUIView` removes observers and timers where any exist
+- [ ] No retain cycle between coordinator and stored closures (`[weak coordinator]`)
+- [ ] Hosting controller added as a child with `addChild` and `didMove(toParent:)`
+- [ ] Sizing chosen deliberately: `intrinsicContentSize`, fixed `frame`, or `sizeThatFits`
+- [ ] Environment values read from `context.environment` in `updateUIView` where relevant
+- [ ] Coordinators carry `@MainActor` so strict concurrency checking passes
+- [ ] Modal controllers dismiss on success, cancel and error
+- [ ] Cells use `UIHostingConfiguration` rather than hand-managed hosting controllers (iOS 16+)
 
 ## References
 
-- Wrapping recipes: [references/representable-recipes.md](references/representable-recipes.md)
-- Migration patterns: [references/hosting-migration.md](references/hosting-migration.md)
-- Apple docs: [UIViewRepresentable](https://sosumi.ai/documentation/swiftui/UIViewRepresentable)
-- Apple docs: [UIViewControllerRepresentable](https://sosumi.ai/documentation/swiftui/UIViewControllerRepresentable)
-- Apple docs: [UIHostingController](https://sosumi.ai/documentation/swiftui/UIHostingController)
+- [wrapper recipes](references/representable-recipes.md): complete wrapper recipes
+- [migration guide](references/hosting-migration.md): incremental UIKit to SwiftUI migration
+- Apple: [UIViewRepresentable](https://developer.apple.com/documentation/swiftui/uiviewrepresentable),
+  [UIViewControllerRepresentable](https://developer.apple.com/documentation/swiftui/uiviewcontrollerrepresentable),
+  [UIHostingController](https://developer.apple.com/documentation/swiftui/uihostingcontroller)