@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/push-notifications/references/rich-notifications.md

@@ -1,262 +1,236 @@
 # Rich Notifications
 
-Rich notifications enhance the standard notification banner with images, video, audio, custom UI, and interactive elements. They use two extension types: Notification Service Extension (modifies content before display) and Notification Content Extension (provides custom UI in the expanded notification).
+Two app extensions shape how a notification looks:
+
+- **Notification Service Extension**: edits the content of a remote
+  notification before the user sees it.
+- **Notification Content Extension**: draws a custom interface when the user
+  expands the notification.
 
 ## Contents
 
-- [Notification Service Extension](#notification-service-extension)
-- [Notification Attachments](#notification-attachments)
-- [Notification Content Extension](#notification-content-extension)
+- [Service Extension](#service-extension)
+- [Attachments](#attachments)
+- [Content Extension](#content-extension)
 - [Communication Notifications](#communication-notifications)
-- [Extension Gotchas](#extension-gotchas)
-- [Complete Service Extension Example](#complete-service-extension-example)
+- [Troubleshooting Extensions](#troubleshooting-extensions)
+- [A Complete Service Extension](#a-complete-service-extension)
+
+## Service Extension
+
+The extension is launched only for a remote notification that alerts the user
+(its `alert` has a title, subtitle or body) and carries `mutable-content: 1`.
+It then has about 30 seconds.
 
-## Notification Service Extension
+When a design gets this wrong, correct these four points:
+1. A silent push never launches the extension.
+2. Attachments are supported files on disk; the system validates them and
+   moves them into its own storage.
+3. A communication notification needs the capability, an
+   `NSUserActivityTypes` entry, a donated `INInteraction`, and a call to
+   `content.updating(from:)`.
+4. The content handler runs exactly once on every path: success, partial
+   failure, bad payload and `serviceExtensionTimeWillExpire()`.
 
-A Notification Service Extension runs for an alerting remote notification whose payload has `mutable-content: 1` and an `alert` dictionary with title, subtitle, or body content. It has approximately 30 seconds to modify the notification content before the system displays it. Call the content handler on every path: success, partial failure, invalid payload, and `serviceExtensionTimeWillExpire()`. If the extension does not call the handler in time, the system displays the original notification.
+If the handler is never called in time, the user sees the original,
+unmodified notification.
 
-When reviewing a flawed rich-notification design, explicitly correct four contracts: silent pushes do not trigger service extensions; attachments must be supported files on disk and are validated and stored by the system; communication notifications require the capability, `NSUserActivityTypes`, `INInteraction` donation, and `content.updating(from:)`; every service-extension path, including download/decryption failures and `serviceExtensionTimeWillExpire()`, must call the content handler exactly once with original, best-attempt, or updated content.
+### Creating it
 
-### Creating the Extension
+Add a target in Xcode (File > New > Target) and pick the Notification Service
+Extension template. It adds a `NotificationService` class that subclasses
+`UNNotificationServiceExtension`.
 
-In Xcode: File > New > Target > Notification Service Extension. This creates a new target with a `NotificationService` class.
+The template's shape has a trap: the async work and the timeout callback can
+both try to deliver. Guard delivery so only the first caller wins:
 
 ```swift
 import UserNotifications
 
-class NotificationService: UNNotificationServiceExtension {
-    private var contentHandler: ((UNNotificationContent) -> Void)?
-    private var bestAttemptContent: UNMutableNotificationContent?
-    private var didComplete = false
+final class NotificationService: UNNotificationServiceExtension, @unchecked Sendable {
+    private let lock = NSLock()
+    private var handler: ((UNNotificationContent) -> Void)?
+    private var draft: UNMutableNotificationContent?
 
     override func didReceive(
         _ request: UNNotificationRequest,
         withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
     ) {
-        self.contentHandler = contentHandler
-        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent
-
-        guard let content = bestAttemptContent else {
-            contentHandler(request.content)
+        let original = request.content
+        guard let copy = original.mutableCopy() as? UNMutableNotificationContent else {
+            contentHandler(original)
             return
         }
+        lock.withLock {
+            handler = contentHandler
+            draft = copy
+        }
+        let headline = request.content.userInfo["headline"] as? String
 
-        // Modify the notification content here
         Task {
-            await processNotification(content: content)
-            contentHandler(content)
+            let cleaned = await HeadlineFormatter.clean(headline)
+            self.deliver { content in
+                if let cleaned { content.title = cleaned }
+            }
         }
     }
 
-    /// Called if the extension is about to be terminated (ran out of time).
-    /// Deliver the best attempt -- even a partially modified notification
-    /// is better than nothing.
     override func serviceExtensionTimeWillExpire() {
-        if let handler = contentHandler, let content = bestAttemptContent {
-            handler(content)
-        }
+        deliver()   // hand over whatever the draft holds now
     }
 
-    private func processNotification(content: UNMutableNotificationContent) async {
-        // Download image if URL is provided
-        if let imageUrlString = content.userInfo["imageUrl"] as? String {
-            await attachImage(from: imageUrlString, to: content)
-        }
-
-        // Decrypt body if encrypted
-        if let encrypted = content.userInfo["encryptedBody"] as? String {
-            content.body = decrypt(encrypted)
+    /// Calls the content handler at most once, whichever path gets here first.
+    private func deliver(_ edit: (UNMutableNotificationContent) -> Void = { _ in }) {
+        let pending: (((UNNotificationContent) -> Void), UNMutableNotificationContent)? = lock.withLock {
+            guard let handler, let draft else { return nil }
+            self.handler = nil
+            self.draft = nil
+            return (handler, draft)
         }
+        guard let (deliverTo, content) = pending else { return }
+        edit(content)
+        deliverTo(content)
     }
 }
 ```
 
-### Downloading Images and Media
-
-Download media from a URL and attach it to the notification. The attachment must be written to disk in the extension's temporary directory.
+### Downloading media
 
 ```swift
-extension NotificationService {
-    private func attachImage(
-        from urlString: String,
-        to content: UNMutableNotificationContent
-    ) async {
-        guard let url = URL(string: urlString) else { return }
-
+enum MediaFetcher {
+    static func attachment(from remote: URL) async -> UNNotificationAttachment? {
+        let session = URLSession.shared
+        guard let (bytes, reply) = try? await session.data(from: remote) else {
+            return nil   // show the notification without media
+        }
+        let suffix = fileExtension(for: reply.mimeType)
+        let local = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString)
+            .appendingPathExtension(suffix)
         do {
-            let (data, response) = try await URLSession.shared.data(from: url)
-
-            // Determine file extension from MIME type
-            let ext = fileExtension(for: response.mimeType)
-            let tempDir = FileManager.default.temporaryDirectory
-            let fileURL = tempDir.appendingPathComponent(UUID().uuidString + ext)
-
-            try data.write(to: fileURL)
-
-            let attachment = try UNNotificationAttachment(
-                identifier: "image",
-                url: fileURL,
-                options: nil
-            )
-            content.attachments = [attachment]
+            try bytes.write(to: local)
+            return try UNNotificationAttachment(identifier: "media", url: local, options: nil)
         } catch {
-            print("Failed to download notification image: \(error)")
-            // Notification displays without the image -- graceful degradation
+            return nil
         }
     }
 
-    private func fileExtension(for mimeType: String?) -> String {
-        switch mimeType {
-        case "image/jpeg": return ".jpg"
-        case "image/png": return ".png"
-        case "image/gif": return ".gif"
-        case "video/mp4", "video/mpeg4": return ".mp4"
-        case "audio/mpeg", "audio/mp3": return ".mp3"
-        case "audio/wav": return ".wav"
-        default: return ".jpg"
+    static func fileExtension(for mime: String?) -> String {
+        switch mime {
+        case "image/jpeg": "jpg"
+        case "image/png": "png"
+        case "image/gif": "gif"
+        case "video/mp4", "video/mpeg4": "mp4"
+        case "audio/mpeg", "audio/mp3": "mp3"
+        case "audio/wav", "audio/x-wav": "wav"
+        default: "jpg"
         }
     }
 }
 ```
 
-### Decrypting Encrypted Payloads
+A failed download is not an error to the user: deliver the text without media.
+
+### Decrypting the payload
 
-Use the service extension to decrypt sensitive notification content. The APNs payload carries an encrypted blob; the extension decrypts it before display.
+For end-to-end encrypted messages the server sends a base64 ciphertext and the
+extension decrypts it before display. If decoding or decryption fails, show
+neutral text such as "New message" rather than nothing.
 
 ```swift
-extension NotificationService {
-    private func decrypt(_ encryptedBase64: String) -> String {
-        guard let data = Data(base64Encoded: encryptedBase64) else {
-            return "New notification"  // fallback
-        }
-        // Use your encryption library (CryptoKit, etc.) to decrypt
-        // Store notification decryption keys in a Keychain access group shared
-        // by the app and extension, not in UserDefaults or the APNs payload.
-        do {
-            let decrypted = try EncryptionService.shared.decrypt(data)
-            return String(data: decrypted, encoding: .utf8) ?? "New notification"
-        } catch {
-            return "New notification"
-        }
-    }
+if let sealed = info["sealed"] as? String,
+   let bytes = Data(base64Encoded: sealed),
+   let key = try? SharedKeychain.messageKey(),
+   let plain = try? MessageCrypto.open(bytes, using: key) {
+    content.body = plain
+} else {
+    content.body = "New message"
 }
 ```
 
-### Sharing Data with Extensions
+The key belongs in a Keychain access group that the app and the extension both
+use. Never put it in `UserDefaults`, and never in the push payload.
 
-The service extension runs in a separate process from the main app. Use App Groups for shared files and `UserDefaults`; use Keychain Sharing for secrets or tokens.
+### Sharing data with the app
 
-1. Enable "App Groups" capability on both the main app target and the extension target.
-2. Use the same group identifier (e.g., `group.com.example.myapp`).
-3. Enable "Keychain Sharing" on both targets for shared keychain items. The `kSecAttrAccessGroup` value must be one of the target's keychain access groups, not the App Group container identifier.
+The extension is a separate process.
 
-```swift
-// Shared UserDefaults
-let sharedDefaults = UserDefaults(suiteName: "group.com.example.myapp")
-
-// Shared file container
-let sharedContainer = FileManager.default.containerURL(
-    forSecurityApplicationGroupIdentifier: "group.com.example.myapp"
-)
-
-// Shared Keychain: set kSecAttrAccessGroup to a Keychain Sharing access group
-// that both targets include in their entitlements.
-```
+- **App Groups**: turn on the capability for both targets with the same
+  identifier (for example `group.com.example.garden`). Use
+  `UserDefaults(suiteName:)` for small values and
+  `FileManager.default.containerURL(forSecurityApplicationGroupIdentifier:)` for
+  files.
+- **Keychain Sharing**: turn it on for both targets. The
+  `kSecAttrAccessGroup` value has to appear in the target's list of keychain
+  access groups; the App Group identifier does not work there.
 
-**Extension memory:** Notification Service Extensions are memory-constrained. Do not load large frameworks or perform memory-intensive operations. If the system terminates the extension, it shows the original notification.
+Service extensions get little memory. Keep dependencies small; if the system
+kills the extension, the original notification is shown.
 
-## Notification Attachments
+## Attachments
 
-`UNNotificationAttachment` supports images, GIFs, video, and audio. The system displays a thumbnail in the collapsed notification and the full media in the expanded view.
+`UNNotificationAttachment` handles pictures (GIFs included), sound and movies. The collapsed
+notification shows a thumbnail; the expanded one shows the media.
 
-### Supported Formats and Limits
+| Kind | Size limit | Formats |
+|------|------------|---------|
+| Image | 10 MB | JPEG, GIF, PNG |
+| Audio | 5 MB | WAV, AIFF, M4A, MP3 |
+| Video | 50 MB | MPEG-4, MPEG-2, MPEG, AVI |
 
-| Type | Formats | Max Size |
-|------|---------|----------|
-| Image | JPEG, PNG, GIF | 10 MB |
-| Audio | AIFF, WAV, MP3, M4A | 5 MB |
-| Video | MPEG, MPEG-2, MPEG-4, AVI | 50 MB |
-
-### Creating Attachments
+Thumbnail options:
 
 ```swift
-// From a local file URL
-let attachment = try UNNotificationAttachment(
-    identifier: "photo",
-    url: localFileURL,
-    options: nil
-)
-
-// With options for thumbnailing
-let attachment = try UNNotificationAttachment(
-    identifier: "photo",
-    url: localFileURL,
-    options: [
-        UNNotificationAttachmentOptionsThumbnailClippingRectKey:
-            CGRect(x: 0, y: 0, width: 1, height: 0.5).dictionaryRepresentation,
-        UNNotificationAttachmentOptionsThumbnailTimeKey: 0  // for video: thumbnail at 0 seconds
-    ]
-)
-
-// Attach to content
-content.attachments = [attachment]
+let options: [AnyHashable: Any] = [
+    // Normalized rect: show the centre half of the image as the thumbnail.
+    UNNotificationAttachmentOptionsThumbnailClippingRectKey:
+        CGRect(origin: CGPoint(x: 0.25, y: 0.25), size: CGSize(width: 0.5, height: 0.5))
+            .dictionaryRepresentation,
+    // For video: the frame at 3 seconds.
+    UNNotificationAttachmentOptionsThumbnailTimeKey: 3
+]
 ```
 
-**Important:** The file URL must point to a supported audio, image, or video file on disk. For service extensions, write downloads to the extension's temporary directory before creating `UNNotificationAttachment`; do not attach arbitrary remote URLs or unsupported file types. For local notifications, create the attachment from a file the app can read when scheduling. The system validates attachments and moves them into its attachment data store; it copies attachments located inside the app bundle.
-
-### Multiple Attachments
-
-You can attach multiple items, but only the first attachment is shown as the thumbnail in the collapsed notification. The expanded view can show all attachments.
-
-```swift
-content.attachments = [imageAttachment, audioAttachment]
-// imageAttachment appears as the thumbnail
-```
+Rules:
+- The URL points to a supported file on disk. A remote URL or an unsupported
+  type fails.
+- For a local notification, the file must be readable when you schedule it.
+- The system validates the file and moves it into its own data store. Files
+  inside the app bundle are copied instead.
+- Several attachments are allowed; the first one is the thumbnail.
+- GIFs can animate in the expanded view; check the real presentation on a
+  device.
 
-### GIF Animations
+## Content Extension
 
-GIF files are supported image attachments and may contain an animated image sequence. Test the expanded notification UI for the actual presentation you need.
+A content extension supplies a view controller that appears when the user
+long-presses or expands the notification. Use it when an attachment is not
+enough.
 
-```swift
-let gifURL = tempDir.appendingPathComponent("animation.gif")
-try gifData.write(to: gifURL)
-let attachment = try UNNotificationAttachment(
-    identifier: "animation",
-    url: gifURL,
-    options: nil
-)
-```
+Add it the same way (File > New > Target), choosing the Notification Content
+Extension template; Xcode adds
+a storyboard and a `NotificationViewController`.
 
-## Notification Content Extension
-
-A Notification Content Extension provides a custom view controller that displays when the user long-presses (or expands) a notification. Use it for richer UI than attachments alone can provide.
-
-### Creating the Extension
-
-In Xcode: File > New > Target > Notification Content Extension. This creates a new target with a storyboard and a `NotificationViewController`.
-
-### Configuration (Info.plist)
-
-The extension's `Info.plist` must declare which notification categories it handles:
+### Info.plist
 
 ```xml
 <key>NSExtension</key>
 <dict>
     <key>NSExtensionAttributes</key>
     <dict>
+        <!-- One category as a string, or several as an array -->
         <key>UNNotificationExtensionCategory</key>
-        <!-- Use a string for one category, or an array for multiple. -->
         <array>
-            <string>MESSAGE_CATEGORY</string>
-            <string>PHOTO_CATEGORY</string>
+            <string>ORDER_UPDATE</string>
+            <string>DELIVERY_PHOTO</string>
         </array>
-        <!-- Optional: size ratio (height / width). Default 1.0 -->
+        <!-- Height as a fraction of width; 1.0 when omitted -->
         <key>UNNotificationExtensionInitialContentSizeRatio</key>
-        <real>0.5</real>
-        <!-- Optional: hide the default notification body below the custom UI -->
+        <real>0.6</real>
+        <!-- Hide the standard title/body under the custom view -->
         <key>UNNotificationExtensionDefaultContentHidden</key>
         <true/>
-        <!-- Optional: allow user interaction in the custom UI -->
+        <!-- Let the custom view receive touches -->
         <key>UNNotificationExtensionUserInteractionEnabled</key>
         <true/>
     </dict>
@@ -267,498 +241,291 @@ The extension's `Info.plist` must declare which notification categories it handl
 </dict>
 ```
 
-### View Controller Implementation
+### The view controller
 
 ```swift
 import UIKit
 import UserNotifications
 import UserNotificationsUI
 
-class NotificationViewController: UIViewController, UNNotificationContentExtension {
-    @IBOutlet weak var titleLabel: UILabel!
-    @IBOutlet weak var bodyLabel: UILabel!
-    @IBOutlet weak var imageView: UIImageView!
+final class NotificationViewController: UIViewController, @preconcurrency UNNotificationContentExtension {
+    @IBOutlet private var statusLabel: UILabel!
+    @IBOutlet private var photoView: UIImageView!
 
     func didReceive(_ notification: UNNotification) {
         let content = notification.request.content
-        titleLabel.text = content.title
-        bodyLabel.text = content.body
-
-        // Display the first attachment
-        if let attachment = content.attachments.first,
-           attachment.url.startAccessingSecurityScopedResource() {
-            defer { attachment.url.stopAccessingSecurityScopedResource() }
-            if let data = try? Data(contentsOf: attachment.url) {
-                imageView.image = UIImage(data: data)
-            }
+        statusLabel.text = content.body
+
+        if let file = content.attachments.first?.url, file.startAccessingSecurityScopedResource() {
+            defer { file.stopAccessingSecurityScopedResource() }
+            photoView.image = UIImage(contentsOfFile: file.path)
         }
     }
 
-    /// Called when the user taps a notification action while the content
-    /// extension is visible.
-    func didReceive(
-        _ response: UNNotificationResponse,
-        completionHandler completion: @escaping (UNNotificationContentExtensionResponseOption) -> Void
-    ) {
+    func didReceive(_ response: UNNotificationResponse,
+                    completionHandler completion: @escaping (UNNotificationContentExtensionResponseOption) -> Void) {
         switch response.actionIdentifier {
-        case "LIKE_ACTION":
-            // Update UI to show "liked" state
-            animateLikeConfirmation()
-            // Dismiss after a short delay
+        case "CONFIRM_DELIVERY":
+            statusLabel.text = "Thanks, noted."
             Task {
-                try? await Task.sleep(for: .seconds(0.5))
+                try? await Task.sleep(for: .milliseconds(900))
                 completion(.dismiss)
             }
-
-        case "REPLY_ACTION":
-            if let textResponse = response as? UNTextInputNotificationResponse {
-                // Handle reply inline without opening the app
-                showReplySentConfirmation(text: textResponse.userText)
-                Task {
-                    try? await Task.sleep(for: .seconds(1.0))
-                    completion(.dismiss)
-                }
-            }
-
         default:
-            // Forward to the app's notification delegate
             completion(.dismissAndForwardAction)
         }
     }
 }
 ```
 
-### Response Options
+The conformance is marked `@preconcurrency` because the protocol has no
+concurrency annotations while the view controller is main-actor isolated; the
+system drives a content extension on the main thread.
 
-| Option | Behavior |
-|--------|----------|
-| `.doNotDismiss` | Keep the content extension visible. Use for multi-step interactions. |
-| `.dismiss` | Dismiss the notification. The action is handled entirely in the extension. |
-| `.dismissAndForwardAction` | Dismiss and forward the action to `UNUserNotificationCenterDelegate.didReceive`. Use when the app needs to handle the action. |
+Attachment files are security scoped inside the extension: wrap access in
+`startAccessingSecurityScopedResource()` and
+`stopAccessingSecurityScopedResource()`.
 
-### Media Playback in Notifications
+### Response options
 
-The content extension can play audio or video. Implement `mediaPlayPauseButtonType` and `mediaPlayPauseButtonFrame` for a system-provided play/pause button.
+| Option | Result |
+|--------|--------|
+| `.doNotDismiss` | Stays on screen; for multi-step interactions |
+| `.dismiss` | Closes; the extension handled the action |
+| `.dismissAndForwardAction` | Closes and passes the action to the app's `didReceive` |
 
-```swift
-class MediaNotificationViewController: UIViewController, UNNotificationContentExtension {
-    var player: AVPlayer?
+### Media playback
 
-    override var mediaPlayPauseButtonType: UNNotificationContentExtensionMediaPlayPauseButtonType {
-        return .overlay  // .none, .default, .overlay
-    }
+For audio or video, ask the system for its play/pause button and respond to it.
 
-    override var mediaPlayPauseButtonFrame: CGRect {
-        return CGRect(x: 0, y: 0, width: view.bounds.width, height: view.bounds.height)
-    }
+```swift
+import AVFoundation
 
-    func mediaPlay() {
-        player?.play()
-    }
+final class ClipViewController: UIViewController, @preconcurrency UNNotificationContentExtension {
+    private var player: AVPlayer?
 
-    func mediaPause() {
-        player?.pause()
-    }
+    var mediaPlayPauseButtonType: UNNotificationContentExtensionMediaPlayPauseButtonType { .overlay }
+    var mediaPlayPauseButtonFrame: CGRect { CGRect(x: 16, y: 16, width: 44, height: 44) }
 
     func didReceive(_ notification: UNNotification) {
-        guard let attachment = notification.request.content.attachments.first,
-              attachment.url.startAccessingSecurityScopedResource() else { return }
-
-        let playerItem = AVPlayerItem(url: attachment.url)
-        player = AVPlayer(playerItem: playerItem)
-
-        let playerLayer = AVPlayerLayer(player: player)
-        playerLayer.frame = view.bounds
-        view.layer.addSublayer(playerLayer)
+        guard let url = notification.request.content.attachments.first?.url else { return }
+        let player = AVPlayer(url: url)
+        let layer = AVPlayerLayer(player: player)
+        layer.frame = view.bounds
+        view.layer.addSublayer(layer)
+        self.player = player
     }
+
+    func mediaPlay() { player?.play() }
+    func mediaPause() { player?.pause() }
 }
 ```
 
-### Interactive Custom UI
+`mediaPlayPauseButtonType` can be `.none`, `.default` or `.overlay`.
 
-With `UNNotificationExtensionUserInteractionEnabled` set to `true`, the content extension supports gesture recognizers, buttons, and other interactive elements.
-
-```swift
-class InteractiveNotificationViewController: UIViewController, UNNotificationContentExtension {
-    private var ratingStars: [UIButton] = []
-    private var selectedRating = 0
+### Interactive views
 
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        setupRatingUI()
-    }
-
-    func didReceive(_ notification: UNNotification) {
-        // Configure with notification content
-    }
+With `UNNotificationExtensionUserInteractionEnabled` set, buttons and gesture
+recognizers in the custom view work like anywhere else in UIKit:
 
-    private func setupRatingUI() {
-        let stack = UIStackView()
-        stack.axis = .horizontal
-        stack.spacing = 8
-        stack.translatesAutoresizingMaskIntoConstraints = false
-        view.addSubview(stack)
-
-        for i in 1...5 {
-            let button = UIButton(type: .system)
-            button.setImage(UIImage(systemName: "star"), for: .normal)
-            button.tag = i
-            button.addTarget(self, action: #selector(starTapped(_:)), for: .touchUpInside)
-            stack.addArrangedSubview(button)
-            ratingStars.append(button)
-        }
-
-        NSLayoutConstraint.activate([
-            stack.centerXAnchor.constraint(equalTo: view.centerXAnchor),
-            stack.centerYAnchor.constraint(equalTo: view.centerYAnchor),
-        ])
-    }
-
-    @objc private func starTapped(_ sender: UIButton) {
-        selectedRating = sender.tag
-        for (index, button) in ratingStars.enumerated() {
-            let imageName = index < selectedRating ? "star.fill" : "star"
-            button.setImage(UIImage(systemName: imageName), for: .normal)
-        }
-        // Send rating to server
-        Task {
-            await submitRating(selectedRating)
-        }
+```swift
+private func makeReactionBar(for orderID: String) -> UIStackView {
+    let reactions = ["Great", "Okay", "Late"].map { title in
+        UIButton(configuration: .tinted(), primaryAction: UIAction(title: title) { _ in
+            Task { await FeedbackAPI.submit(orderID: orderID, reaction: title) }
+        })
     }
+    let bar = UIStackView(arrangedSubviews: reactions)
+    bar.axis = .horizontal
+    bar.distribution = .fillEqually
+    bar.spacing = 8
+    return bar
 }
 ```
 
 ## Communication Notifications
 
-Communication notifications display the sender's avatar and name prominently. They use SiriKit intents (`INSendMessageIntent` or `INStartCallIntent`) to provide participant information and can have different Focus and summary behavior, so use them only for real person-to-person communication.
+These show the sender's name and picture and are built on the SiriKit intents
+`INSendMessageIntent` and `INStartCallIntent`. They change how Focus and the
+notification summary treat the app, so use them only for messages or calls
+between real people.
 
-### Setup
-
-1. Enable the Communication Notifications capability on the app target.
-2. Add supported intent class names, such as `INSendMessageIntent`, to `NSUserActivityTypes` in `Info.plist`.
-3. Add the `Intents` framework to the Notification Service Extension target.
-4. Configure an `INSendMessageIntent`, create an `INInteraction`, set `direction = .incoming`, donate the interaction, then call `content.updating(from:)` before passing the updated content to the content handler.
+Setup:
+1. Add the Communication Notifications capability to the app target.
+2. List the intent classes (for example `INSendMessageIntent`) under
+   `NSUserActivityTypes` in the app's Info.plist.
+3. Link the `Intents` framework into the service extension.
+4. In the extension: build the intent, wrap it in
+   `INInteraction(intent:response:)`, set `direction = .incoming`, call
+   `donate()`, then pass `content.updating(from:)` to the handler.
 
 ```swift
 import Intents
-import UserNotifications
-
-extension NotificationService {
-    func configureCommunicationNotification(
-        content: UNMutableNotificationContent,
-        senderName: String,
-        senderImageURL: String?,
-        conversationId: String
-    ) async -> UNNotificationContent? {
-        // Create the sender identity
-        let handle = INPersonHandle(value: conversationId, type: .unknown)
-        var avatar: INImage? = nil
-
-        // Download sender avatar
-        if let urlString = senderImageURL,
-           let url = URL(string: urlString) {
-            if let (data, _) = try? await URLSession.shared.data(from: url) {
-                avatar = INImage(imageData: data)
-            }
-        }
-
-        let nameComponents = PersonNameComponentsFormatter()
-            .personNameComponents(from: senderName)
 
+enum SenderStyling {
+    static func apply(to content: UNNotificationContent,
+                      senderID: String,
+                      senderName: String,
+                      avatar: Data?,
+                      conversationID: String) async -> UNNotificationContent {
         let sender = INPerson(
-            personHandle: handle,
-            nameComponents: nameComponents,
+            personHandle: INPersonHandle(value: senderID, type: .unknown),
+            nameComponents: PersonNameComponentsFormatter().personNameComponents(from: senderName),
             displayName: senderName,
-            image: avatar,
+            image: avatar.map { INImage(imageData: $0) },
             contactIdentifier: nil,
-            customIdentifier: conversationId
+            customIdentifier: senderID
         )
-
-        // Create the messaging intent
         let intent = INSendMessageIntent(
             recipients: nil,
             outgoingMessageType: .outgoingMessageText,
             content: content.body,
             speakableGroupName: nil,
-            conversationIdentifier: conversationId,
+            conversationIdentifier: conversationID,
             serviceName: nil,
             sender: sender,
             attachments: nil
         )
-
-        // Donate the interaction so Siri learns about this contact
-        let interaction = INInteraction(intent: intent, response: nil)
-        interaction.direction = .incoming
-        try? await interaction.donate()
+        let donation = INInteraction(intent: intent, response: nil)
+        donation.direction = .incoming
+        try? await donation.donate()
 
         do {
-            return try content.updating(from: intent)
+            let styled = try content.updating(from: intent)
+            return styled
         } catch {
-            print("Failed to update content with intent: \(error)")
-            return nil
+            return content   // fall back to the plain notification
         }
     }
 }
 ```
 
-### Handling in the Service Extension
+### In the service extension
 
-The complete flow integrates communication notifications into the standard service extension:
+Attach media first. Then, if the payload names a sender, run the styling
+above and deliver its result; if not, deliver the plain content. The
+[complete example](#a-complete-service-extension) shows the whole flow.
 
-```swift
-override func didReceive(
-    _ request: UNNotificationRequest,
-    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
-) {
-    guard let content = request.content.mutableCopy() as? UNMutableNotificationContent else {
-        contentHandler(request.content)
-        return
-    }
+## Troubleshooting Extensions
 
-    Task {
-        // Download and attach image
-        if let imageUrl = content.userInfo["imageUrl"] as? String {
-            await attachImage(from: imageUrl, to: content)
-        }
+**Service extension never runs**
+- The payload includes an alert and sets `mutable-content: 1`.
+- The extension is embedded in the app and has a valid bundle ID and profile.
+- Both targets carry the shared App Group and Keychain entitlements they use.
 
-        // Configure as communication notification if sender info is present
-        if let senderName = content.userInfo["senderName"] as? String,
-           let conversationId = content.userInfo["conversationId"] as? String {
-            let senderImage = content.userInfo["senderImageUrl"] as? String
-
-            let handle = INPersonHandle(value: conversationId, type: .unknown)
-            var avatar: INImage? = nil
-            if let urlString = senderImage,
-               let url = URL(string: urlString),
-               let (data, _) = try? await URLSession.shared.data(from: url) {
-                avatar = INImage(imageData: data)
-            }
+**Content extension never appears**
+- `UNNotificationExtensionCategory` matches the notification's
+  `categoryIdentifier` exactly.
+- The storyboard or view is actually set up, and the size ratio is sensible.
 
-            let nameComponents = PersonNameComponentsFormatter()
-                .personNameComponents(from: senderName)
+**Memory**
+- The system kills extensions that use too much memory. Keep dependencies
+  small and use `URLSession` directly rather than a large networking library.
+  A service extension has no UI, so a UI framework buys nothing there; a
+  content extension may host SwiftUI through `UIHostingController`, but keep
+  it light.
 
-            let sender = INPerson(
-                personHandle: handle,
-                nameComponents: nameComponents,
-                displayName: senderName,
-                image: avatar,
-                contactIdentifier: nil,
-                customIdentifier: conversationId
-            )
+**Fallbacks**
+- The handler runs exactly once. If a download, decryption, donation or
+  `updating(from:)` fails, deliver the original or the best attempt so far.
+- In `serviceExtensionTimeWillExpire()`, stop waiting and deliver the best
+  content right away.
 
-            let intent = INSendMessageIntent(
-                recipients: nil,
-                outgoingMessageType: .outgoingMessageText,
-                content: content.body,
-                speakableGroupName: nil,
-                conversationIdentifier: conversationId,
-                serviceName: nil,
-                sender: sender,
-                attachments: nil
-            )
+**Network**
+- Extensions may use the network; a `URLSession` with the `.default`
+  configuration is fine. Stay well inside the roughly 30-second budget and
+  fall back to the payload text on failure.
 
-            let interaction = INInteraction(intent: intent, response: nil)
-            interaction.direction = .incoming
-            try? await interaction.donate()
+**Debugging**
+- Run the extension's scheme, or attach from the Debug menu (Attach to
+  Process by PID or Name) using the extension's name.
+- Log with `os_log` or `Logger` and filter Console.app by the extension's
+  bundle ID.
+- Set breakpoints, then send a notification to trigger the extension.
 
-            if let updatedContent = try? content.updating(from: intent) {
-                contentHandler(updatedContent)
-                return
-            }
-        }
+## A Complete Service Extension
 
-        contentHandler(content)
-    }
-}
-```
-
-## Extension Gotchas
-
-**Service extension not running:**
-- Verify `mutable-content: 1` is set in the APNs payload.
-- The notification must have an alert (title or body). Silent pushes do not trigger the service extension.
-- Confirm the service extension target is embedded in the containing app and its bundle identifier/provisioning profile are valid.
-- Confirm both targets include the same App Group or Keychain Sharing entitlements if they share data.
-
-**Content extension not showing:**
-- Verify the `UNNotificationExtensionCategory` in Info.plist matches the `categoryIdentifier` in the notification.
-- Check that the storyboard or programmatic UI is properly configured.
-- Ensure `UNNotificationExtensionInitialContentSizeRatio` is set to a reasonable value.
-
-**Memory pressure:**
-- Extensions are memory-constrained and can be terminated under pressure.
-- Avoid loading large frameworks (no SwiftUI, no heavy networking libraries).
-- Use `URLSession` directly for network requests in extensions.
-
-**Fallback handling:**
-- Always call the content handler exactly once on every path.
-- On download, decryption, donation, or `content.updating(from:)` failure, return the original or best-attempt content rather than dropping the notification.
-- In `serviceExtensionTimeWillExpire()`, stop waiting for in-flight work and call the content handler immediately with the best content available.
-
-**Network access in extensions:**
-- Extensions can make network requests. Use `URLSession` with the `.default` configuration.
-- Keep requests fast -- the service extension has approximately 30 seconds total.
-- Handle network failures gracefully; fall back to showing what the original payload contains.
-
-**Debugging extensions:**
-- In Xcode, select the extension scheme and attach to the extension process.
-- Use `Debug > Attach to Process by PID or Name` with the extension's process name.
-- Use `os_log` or `print` statements and view them in Console.app filtered by the extension's bundle identifier.
-- Set breakpoints in the extension target and trigger a notification to hit them.
-
-## Complete Service Extension Example
-
-A production-ready service extension that handles image download, body decryption, and communication notifications:
+The steps run in order: decrypt the body with a key from the shared Keychain,
+attach media, style as a communication notification, then deliver once. The
+timeout path delivers whatever is ready.
 
 ```swift
-import UserNotifications
 import Intents
+import UserNotifications
 
-class NotificationService: UNNotificationServiceExtension {
-    private var contentHandler: ((UNNotificationContent) -> Void)?
-    private var bestAttemptContent: UNMutableNotificationContent?
+final class NotificationService: UNNotificationServiceExtension, @unchecked Sendable {
+    private let lock = NSLock()
+    private var handler: ((UNNotificationContent) -> Void)?
+    private var bestAttempt: UNNotificationContent?
 
     override func didReceive(
         _ request: UNNotificationRequest,
         withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
     ) {
-        self.contentHandler = contentHandler
-        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent
-
-        guard let content = bestAttemptContent else {
-            contentHandler(request.content)
-            return
+        lock.withLock {
+            handler = contentHandler
+            bestAttempt = request.content
         }
+        let payload = IncomingPayload(request.content.userInfo)
 
         Task {
-            // Step 1: Decrypt body if needed
-            if let encrypted = content.userInfo["encryptedBody"] as? String,
-               let decrypted = decryptBody(encrypted) {
-                content.body = decrypted
+            guard let draft = self.snapshot()?.mutableCopy() as? UNMutableNotificationContent else {
+                self.finish(with: nil)
+                return
             }
 
-            // Step 2: Download and attach image
-            if let imageUrl = content.userInfo["imageUrl"] as? String {
-                await attachMedia(from: imageUrl, to: content)
-            }
+            // 1. Decrypt, falling back to neutral text.
+            draft.body = payload.decryptedBody() ?? "New message"
+            self.remember(draft)
 
-            // Step 3: Configure communication notification
-            if let senderName = content.userInfo["senderName"] as? String,
-               let convId = content.userInfo["conversationId"] as? String {
-                if let updated = await configureAsCommunication(
-                    content: content,
-                    senderName: senderName,
-                    senderImageURL: content.userInfo["senderImage"] as? String,
-                    conversationId: convId
-                ) {
-                    finish(with: updated)
-                    return
-                }
+            // 2. Media, skipped silently on failure.
+            if let url = payload.mediaURL, let media = await MediaFetcher.attachment(from: url) {
+                draft.attachments = [media]
+                self.remember(draft)
             }
 
-            finish(with: content)
+            // 3. Sender styling, only when the payload names a sender.
+            guard let sender = payload.sender else {
+                self.finish(with: draft)
+                return
+            }
+            let styled = await SenderStyling.apply(
+                to: draft,
+                senderID: sender.id,
+                senderName: sender.name,
+                avatar: await payload.avatarData(),
+                conversationID: sender.conversationID
+            )
+            self.finish(with: styled)
         }
     }
 
     override func serviceExtensionTimeWillExpire() {
-        if let content = bestAttemptContent {
-            finish(with: content)
-        }
+        finish(with: nil)   // best attempt so far
     }
 
-    // MARK: - Private
-
-    private func finish(with content: UNNotificationContent) {
-        guard !didComplete, let handler = contentHandler else { return }
-        didComplete = true
-        handler(content)
-    }
-
-    private func decryptBody(_ base64: String) -> String? {
-        guard let data = Data(base64Encoded: base64) else { return nil }
-        guard let keyData = SharedKeychain.loadData(
-            account: "notificationEncryptionKey"
-        ) else { return nil }
-        // Decrypt using CryptoKit or similar
-        return try? Decryptor.decrypt(data, key: keyData)
+    private func snapshot() -> UNNotificationContent? {
+        lock.withLock { bestAttempt }
     }
 
-    private func attachMedia(
-        from urlString: String,
-        to content: UNMutableNotificationContent
-    ) async {
-        guard let url = URL(string: urlString) else { return }
-        do {
-            let (data, response) = try await URLSession.shared.data(from: url)
-            let ext = fileExtension(for: response.mimeType)
-            let fileURL = FileManager.default.temporaryDirectory
-                .appendingPathComponent(UUID().uuidString + ext)
-            try data.write(to: fileURL)
-            let attachment = try UNNotificationAttachment(
-                identifier: UUID().uuidString,
-                url: fileURL,
-                options: nil
-            )
-            content.attachments = [attachment]
-        } catch {
-            // Image download failed -- notification displays without media
-        }
-    }
-
-    private func configureAsCommunication(
-        content: UNMutableNotificationContent,
-        senderName: String,
-        senderImageURL: String?,
-        conversationId: String
-    ) async -> UNNotificationContent? {
-        let handle = INPersonHandle(value: conversationId, type: .unknown)
-        var avatar: INImage? = nil
-
-        if let urlStr = senderImageURL,
-           let url = URL(string: urlStr),
-           let (data, _) = try? await URLSession.shared.data(from: url) {
-            avatar = INImage(imageData: data)
-        }
-
-        let nameComponents = PersonNameComponentsFormatter()
-            .personNameComponents(from: senderName)
-
-        let sender = INPerson(
-            personHandle: handle,
-            nameComponents: nameComponents,
-            displayName: senderName,
-            image: avatar,
-            contactIdentifier: nil,
-            customIdentifier: conversationId
-        )
-
-        let intent = INSendMessageIntent(
-            recipients: nil,
-            outgoingMessageType: .outgoingMessageText,
-            content: content.body,
-            speakableGroupName: nil,
-            conversationIdentifier: conversationId,
-            serviceName: nil,
-            sender: sender,
-            attachments: nil
-        )
-
-        let interaction = INInteraction(intent: intent, response: nil)
-        interaction.direction = .incoming
-        try? await interaction.donate()
-
-        return try? content.updating(from: intent)
+    private func remember(_ content: UNNotificationContent) {
+        lock.withLock { if handler != nil { bestAttempt = content.copy() as? UNNotificationContent } }
     }
 
-    private func fileExtension(for mimeType: String?) -> String {
-        switch mimeType {
-        case "image/jpeg": return ".jpg"
-        case "image/png": return ".png"
-        case "image/gif": return ".gif"
-        case "video/mp4": return ".mp4"
-        case "audio/mpeg": return ".mp3"
-        default: return ".jpg"
+    /// Single delivery point. `nil` means "use the best attempt".
+    private func finish(with ready: UNNotificationContent?) {
+        let delivery: (((UNNotificationContent) -> Void), UNNotificationContent)? = lock.withLock {
+            guard let handler, let fallback = bestAttempt else { return nil }
+            self.handler = nil
+            return (handler, ready ?? fallback)
         }
+        guard let (deliverTo, result) = delivery else { return }
+        deliverTo(result)
     }
 }
 ```
+
+`IncomingPayload` is the app's own parser over `userInfo`: it reads the sealed
+body and decrypts it with the shared-Keychain key, and exposes `mediaURL`, the
+sender fields and an avatar download. Keep it free of UI and large
+dependencies.