npm - @devo-bmad-custom/agent-orchestration - Versions diffs - 1.0.2 → 1.0.4 - Mend

@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (605) hide show

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/live-activities/SKILL.md CHANGED Viewed

@@ -1,500 +1,500 @@
----
-name: live-activities
-description: "Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit. Use when building real-time updating widgets for the Lock Screen and Dynamic Island — delivery tracking, sports scores, ride-sharing status, workout timers, media playback, or any time-sensitive information that updates in real time. Also use when working with ActivityKit, ActivityAttributes, Activity lifecycle (request/update/end), Dynamic Island layouts (compact/minimal/expanded), push-to-update Live Activities, or Lock Screen live widgets."
----
-# Live Activities and Dynamic Island
-Build real-time, glanceable experiences on the Lock Screen, Dynamic Island,
-StandBy, CarPlay, and Mac menu bar using ActivityKit. Patterns target iOS 26+
-with Swift 6.2, backward-compatible to iOS 16.1 unless noted.
-See `references/live-activity-patterns.md` for complete code patterns including push payload formats, concurrent activities, state observation, and testing.
-## Contents
-- [Workflow](#workflow)
-- [ActivityAttributes Definition](#activityattributes-definition)
-- [Activity Lifecycle](#activity-lifecycle)
-- [Lock Screen Presentation](#lock-screen-presentation)
-- [Dynamic Island](#dynamic-island)
-- [Push-to-Update](#push-to-update)
-- [iOS 26 Additions](#ios-26-additions)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
-## Workflow
-### 1. Create a new Live Activity
-1. Add `NSSupportsLiveActivities = YES` to the host app's Info.plist.
-2. Define an `ActivityAttributes` struct with a nested `ContentState`.
-3. Create an `ActivityConfiguration` in the widget bundle with Lock Screen
-   content and Dynamic Island closures.
-4. Start the activity with `Activity.request(attributes:content:pushType:)`.
-5. Update with `activity.update(_:)` and end with `activity.end(_:dismissalPolicy:)`.
-6. Forward push tokens to your server for remote updates.
-### 2. Review existing Live Activity code
-Run through the Review Checklist at the end of this document.
-## ActivityAttributes Definition
-Define both static data (immutable for the activity lifetime) and dynamic
-`ContentState` (changes with each update). Keep `ContentState` small because
-the entire struct is serialized on every update and push payload.
-```swift
-import ActivityKit
-struct DeliveryAttributes: ActivityAttributes {
-    // Static -- set once at activity creation, never changes
-    var orderNumber: Int
-    var restaurantName: String
-    // Dynamic -- updated throughout the activity lifetime
-    struct ContentState: Codable, Hashable {
-        var driverName: String
-        var estimatedDeliveryTime: ClosedRange<Date>
-        var currentStep: DeliveryStep
-    }
-}
-enum DeliveryStep: String, Codable, Hashable, CaseIterable {
-    case confirmed, preparing, pickedUp, delivering, delivered
-    var icon: String {
-        switch self {
-        case .confirmed: "checkmark.circle"
-        case .preparing: "frying.pan"
-        case .pickedUp: "bag.fill"
-        case .delivering: "box.truck.fill"
-        case .delivered: "house.fill"
-        }
-    }
-}
-```
-### Stale Date
-Set `staleDate` on `ActivityContent` to tell the system when content becomes outdated. The system sets `context.isStale` to `true` after this date; show fallback UI (e.g., "Updating...") in your views.
-```swift
-let content = ActivityContent(
-    state: state,
-    staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
-    relevanceScore: 75
-)
-```
-## Activity Lifecycle
-### Starting
-Use `Activity.request` to create and display a Live Activity. Pass `.token` as
-the `pushType` to enable remote updates via APNs.
-```swift
-let attributes = DeliveryAttributes(orderNumber: 42, restaurantName: "Pizza Place")
-let state = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
-    currentStep: .preparing
-)
-let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
-do {
-    let activity = try Activity.request(
-        attributes: attributes,
-        content: content,
-        pushType: .token
-    )
-    print("Started activity: \(activity.id)")
-} catch {
-    print("Failed to start activity: \(error)")
-}
-```
-### Updating
-Update the dynamic content state from the app. Use `AlertConfiguration` to
-trigger a visible banner and sound alongside the update.
-```swift
-let updatedState = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date().addingTimeInterval(600),
-    currentStep: .delivering
-)
-let updatedContent = ActivityContent(
-    state: updatedState,
-    staleDate: Date().addingTimeInterval(300),
-    relevanceScore: 90
-)
-// Silent update
-await activity.update(updatedContent)
-// Update with an alert
-await activity.update(updatedContent, alertConfiguration: AlertConfiguration(
-    title: "Order Update",
-    body: "Your driver is nearby!",
-    sound: .default
-))
-```
-### Ending
-End the activity when the tracked event completes. Choose a dismissal policy
-to control how long the ended activity lingers on the Lock Screen.
-```swift
-let finalState = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date(),
-    currentStep: .delivered
-)
-let finalContent = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
-// System decides when to remove (up to 4 hours)
-await activity.end(finalContent, dismissalPolicy: .default)
-// Remove immediately
-await activity.end(finalContent, dismissalPolicy: .immediate)
-// Remove after a specific time (max 4 hours from now)
-await activity.end(finalContent, dismissalPolicy: .after(Date().addingTimeInterval(3600)))
-```
-Always end activities on all code paths -- success, error, and cancellation.
-A leaked activity stays on the Lock Screen until the system kills it (up to
-8 hours), which frustrates users.
-## Lock Screen Presentation
-The Lock Screen is the primary surface for Live Activities. Every device with
-iOS 16.1+ displays Live Activities here. Design this layout first.
-```swift
-struct DeliveryActivityWidget: Widget {
-    var body: some WidgetConfiguration {
-        ActivityConfiguration(for: DeliveryAttributes.self) { context in
-            // Lock Screen / StandBy / CarPlay / Mac menu bar content
-            VStack(alignment: .leading, spacing: 8) {
-                HStack {
-                    Text(context.attributes.restaurantName)
-                        .font(.headline)
-                    Spacer()
-                    Text("Order #\(context.attributes.orderNumber)")
-                        .font(.caption)
-                        .foregroundStyle(.secondary)
-                }
-                if context.isStale {
-                    Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
-                        .font(.subheadline)
-                        .foregroundStyle(.secondary)
-                } else {
-                    HStack {
-                        Label(context.state.driverName, systemImage: "person.fill")
-                        Spacer()
-                        Text(timerInterval: context.state.estimatedDeliveryTime,
-                             countsDown: true)
-                            .monospacedDigit()
-                    }
-                    .font(.subheadline)
-                    // Progress steps
-                    HStack(spacing: 12) {
-                        ForEach(DeliveryStep.allCases, id: \.self) { step in
-                            Image(systemName: step.icon)
-                                .foregroundStyle(
-                                    step <= context.state.currentStep ? .primary : .tertiary
-                                )
-                        }
-                    }
-                }
-            }
-            .padding()
-        } dynamicIsland: { context in
-            // Dynamic Island closures (see next section)
-            DynamicIsland {
-                // Expanded regions...
-                DynamicIslandExpandedRegion(.leading) {
-                    Image(systemName: "box.truck.fill").font(.title2)
-                }
-                DynamicIslandExpandedRegion(.trailing) {
-                    Text(timerInterval: context.state.estimatedDeliveryTime,
-                         countsDown: true)
-                        .font(.caption).monospacedDigit()
-                }
-                DynamicIslandExpandedRegion(.center) {
-                    Text(context.attributes.restaurantName).font(.headline)
-                }
-                DynamicIslandExpandedRegion(.bottom) {
-                    HStack(spacing: 12) {
-                        ForEach(DeliveryStep.allCases, id: \.self) { step in
-                            Image(systemName: step.icon)
-                                .foregroundStyle(
-                                    step <= context.state.currentStep ? .primary : .tertiary
-                                )
-                        }
-                    }
-                }
-            } compactLeading: {
-                Image(systemName: "box.truck.fill")
-            } compactTrailing: {
-                Text(timerInterval: context.state.estimatedDeliveryTime,
-                     countsDown: true)
-                    .frame(width: 40).monospacedDigit()
-            } minimal: {
-                Image(systemName: "box.truck.fill")
-            }
-        }
-    }
-}
-```
-### Lock Screen Sizing
-The Lock Screen presentation has limited vertical space. Avoid layouts taller
-than roughly 160 points. Use `supplementalActivityFamilies` to opt into
-`.small` (compact) or `.medium` (standard) sizing:
-```swift
-ActivityConfiguration(for: DeliveryAttributes.self) { context in
-    // Lock Screen content
-} dynamicIsland: { context in
-    // Dynamic Island
-}
-.supplementalActivityFamilies([.small, .medium])
-```
-## Dynamic Island
-The Dynamic Island is available on iPhone 14 Pro and later. It has three
-presentation modes. Design all three, but treat the Lock Screen as the primary
-surface since not all devices have a Dynamic Island.
-### Compact (Leading + Trailing)
-Always visible when a single Live Activity is active. Space is extremely
-limited -- show only the most critical information.
-| Region | Purpose |
-|---|---|
-| `compactLeading` | Icon or tiny label identifying the activity |
-| `compactTrailing` | One key value (timer, score, status) |
-### Minimal
-Shown when multiple Live Activities compete for space. Only one activity gets
-the minimal slot. Display a single icon or glyph.
-### Expanded Regions
-Shown when the user long-presses the Dynamic Island.
-| Region | Position |
-|---|---|
-| `.leading` | Left of the TrueDepth camera; wraps below |
-| `.trailing` | Right of the TrueDepth camera; wraps below |
-| `.center` | Directly below the camera |
-| `.bottom` | Below all other regions |
-### Keyline Tint
-Apply a subtle tint to the Dynamic Island border:
-```swift
-DynamicIsland { /* expanded */ }
-    compactLeading: { /* ... */ }
-    compactTrailing: { /* ... */ }
-    minimal: { /* ... */ }
-    .keylineTint(.blue)
-```
-## Push-to-Update
-Push-to-update sends Live Activity updates through APNs, which is more
-efficient than polling from the app and works when the app is suspended.
-### Setup
-Pass `.token` as the `pushType` when starting the activity, then forward the
-push token to your server:
-```swift
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token
-)
-// Observe token changes -- tokens can rotate
-Task {
-    for await token in activity.pushTokenUpdates {
-        let tokenString = token.map { String(format: "%02x", $0) }.joined()
-        try await ServerAPI.shared.registerActivityToken(
-            tokenString, activityID: activity.id
-        )
-    }
-}
-```
-### APNs Payload Format
-Send an HTTP/2 POST to APNs with these headers and JSON body:
-**Required HTTP headers:**
-- `apns-push-type: liveactivity`
-- `apns-topic: <bundle-id>.push-type.liveactivity`
-- `apns-priority: 5` (low) or `10` (high, triggers alert)
-**Update payload:**
-```json
-{
-    "aps": {
-        "timestamp": 1700000000,
-        "event": "update",
-        "content-state": {
-            "driverName": "Alex",
-            "estimatedDeliveryTime": {
-                "lowerBound": 1700000000,
-                "upperBound": 1700001800
-            },
-            "currentStep": "delivering"
-        },
-        "stale-date": 1700000300,
-        "alert": {
-            "title": "Delivery Update",
-            "body": "Your driver is nearby!"
-        }
-    }
-}
-```
-**End payload:** Same structure with `"event": "end"` and optional `"dismissal-date"`.
-The `content-state` JSON must match the `ContentState` Codable structure
-exactly. Mismatched keys or types cause silent failures.
-### Push-to-Start
-Start a Live Activity remotely without the app running (iOS 17.2+):
-```swift
-Task {
-    for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
-        let tokenString = token.map { String(format: "%02x", $0) }.joined()
-        try await ServerAPI.shared.registerPushToStartToken(tokenString)
-    }
-}
-```
-### Frequent Push Updates
-Add `NSSupportsLiveActivitiesFrequentUpdates = YES` to Info.plist to increase
-the push update budget. Use for activities that update more than once per
-minute (sports scores, ride tracking).
-## iOS 26 Additions
-### Scheduled Live Activities (iOS 26+)
-Schedule a Live Activity to start at a future time. The system starts the
-activity automatically without the app being in the foreground. Use for events
-with known start times (sports games, flights, scheduled deliveries).
-```swift
-let scheduledDate = Calendar.current.date(
-    from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
-)!
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token,
-    start: scheduledDate
-)
-```
-### ActivityStyle (iOS 16.1+ type, `style:` parameter iOS 26+)
-Control persistence: `.standard` (persists until ended, default) or `.transient` (system may dismiss automatically). Use `.transient` for short-lived updates like transit arrivals. The `style:` parameter on `Activity.request` requires iOS 26+.
-```swift
-let activity = try Activity.request(
-    attributes: attributes, content: content,
-    pushType: .token, style: .transient
-)
-```
-### Mac Menu Bar & CarPlay (iOS 26+)
-Live Activities automatically appear in macOS Tahoe menu bar (via iPhone Mirroring) and CarPlay Home Screen. No additional code needed — ensure Lock Screen layout is legible at smaller scales.
-### Channel-Based Push (iOS 18+)
-Broadcast updates to many Live Activities at once with `.channel`:
-```swift
-let activity = try Activity.request(
-    attributes: attributes, content: content,
-    pushType: .channel("delivery-updates")
-)
-```
-## Common Mistakes
-**DON'T:** Put too much content in the compact presentation -- it is tiny.
-**DO:** Show only the most critical info (icon + one value) in compact leading/trailing.
-**DON'T:** Update Live Activities too frequently from the app (drains battery).
-**DO:** Use push-to-update for server-driven updates. Limit app-side updates to user actions.
-**DON'T:** Forget to end the activity when the event completes.
-**DO:** Always end activities on success, error, and cancellation paths. A leaked activity frustrates users.
-**DON'T:** Assume the Dynamic Island is available (only iPhone 14 Pro+).
-**DO:** Design for the Lock Screen as the primary surface; Dynamic Island is supplementary.
-**DON'T:** Store sensitive information in ActivityAttributes (visible on Lock Screen).
-**DO:** Keep sensitive data in the app and show only safe-to-display summaries.
-**DON'T:** Forget to handle stale dates.
-**DO:** Check `context.isStale` in views and show fallback UI ("Updating..." or similar).
-**DON'T:** Ignore push token rotation. Tokens can change at any time.
-**DO:** Use `activity.pushTokenUpdates` async sequence and re-register on every emission.
-**DON'T:** Forget the `NSSupportsLiveActivities` Info.plist key.
-**DO:** Add `NSSupportsLiveActivities = YES` to the host app's Info.plist (not the extension).
-**DON'T:** Use the deprecated `contentState`-based API for request/update/end.
-**DO:** Use `ActivityContent` for all lifecycle calls.
-**DON'T:** Put heavy logic in Live Activity views. They render in a size-limited widget process.
-**DO:** Pre-compute display values and pass them through `ContentState`.
-## Review Checklist
-- [ ] `ActivityAttributes` defines static properties and `ContentState`
-- [ ] `NSSupportsLiveActivities = YES` in host app Info.plist
-- [ ] Activity uses `ActivityContent` (not deprecated contentState API)
-- [ ] Activity ended in all code paths (success, error, cancellation)
-- [ ] Lock Screen layout handles `context.isStale`
-- [ ] Dynamic Island compact, expanded, and minimal implemented
-- [ ] Push token forwarded to server via `activity.pushTokenUpdates`
-- [ ] `AlertConfiguration` used for important updates
-- [ ] `ActivityAuthorizationInfo` checked before starting
-- [ ] ContentState kept small (serialized on every update)
-- [ ] Tested on device (Dynamic Island differs from Simulator)
-- [ ] Ensure ActivityAttributes and ContentState types are Sendable; update Live Activity UI on @MainActor
-## References
-- See `references/live-activity-patterns.md` for patterns and code examples
+---
+name: live-activities
+description: "Implement, review, or improve Live Activities and Dynamic Island experiences in iOS apps using ActivityKit. Use when building real-time updating widgets for the Lock Screen and Dynamic Island — delivery tracking, sports scores, ride-sharing status, workout timers, media playback, or any time-sensitive information that updates in real time. Also use when working with ActivityKit, ActivityAttributes, Activity lifecycle (request/update/end), Dynamic Island layouts (compact/minimal/expanded), push-to-update Live Activities, or Lock Screen live widgets."
+---
+# Live Activities and Dynamic Island
+Build real-time, glanceable experiences on the Lock Screen, Dynamic Island,
+StandBy, CarPlay, and Mac menu bar using ActivityKit. Patterns target iOS 26+
+with Swift 6.2, backward-compatible to iOS 16.1 unless noted.
+See `references/live-activity-patterns.md` for complete code patterns including push payload formats, concurrent activities, state observation, and testing.
+## Contents
+- [Workflow](#workflow)
+- [ActivityAttributes Definition](#activityattributes-definition)
+- [Activity Lifecycle](#activity-lifecycle)
+- [Lock Screen Presentation](#lock-screen-presentation)
+- [Dynamic Island](#dynamic-island)
+- [Push-to-Update](#push-to-update)
+- [iOS 26 Additions](#ios-26-additions)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+## Workflow
+### 1. Create a new Live Activity
+1. Add `NSSupportsLiveActivities = YES` to the host app's Info.plist.
+2. Define an `ActivityAttributes` struct with a nested `ContentState`.
+3. Create an `ActivityConfiguration` in the widget bundle with Lock Screen
+   content and Dynamic Island closures.
+4. Start the activity with `Activity.request(attributes:content:pushType:)`.
+5. Update with `activity.update(_:)` and end with `activity.end(_:dismissalPolicy:)`.
+6. Forward push tokens to your server for remote updates.
+### 2. Review existing Live Activity code
+Run through the Review Checklist at the end of this document.
+## ActivityAttributes Definition
+Define both static data (immutable for the activity lifetime) and dynamic
+`ContentState` (changes with each update). Keep `ContentState` small because
+the entire struct is serialized on every update and push payload.
+```swift
+import ActivityKit
+struct DeliveryAttributes: ActivityAttributes {
+    // Static -- set once at activity creation, never changes
+    var orderNumber: Int
+    var restaurantName: String
+    // Dynamic -- updated throughout the activity lifetime
+    struct ContentState: Codable, Hashable {
+        var driverName: String
+        var estimatedDeliveryTime: ClosedRange<Date>
+        var currentStep: DeliveryStep
+    }
+}
+enum DeliveryStep: String, Codable, Hashable, CaseIterable {
+    case confirmed, preparing, pickedUp, delivering, delivered
+    var icon: String {
+        switch self {
+        case .confirmed: "checkmark.circle"
+        case .preparing: "frying.pan"
+        case .pickedUp: "bag.fill"
+        case .delivering: "box.truck.fill"
+        case .delivered: "house.fill"
+        }
+    }
+}
+```
+### Stale Date
+Set `staleDate` on `ActivityContent` to tell the system when content becomes outdated. The system sets `context.isStale` to `true` after this date; show fallback UI (e.g., "Updating...") in your views.
+```swift
+let content = ActivityContent(
+    state: state,
+    staleDate: Date().addingTimeInterval(300), // stale after 5 minutes
+    relevanceScore: 75
+)
+```
+## Activity Lifecycle
+### Starting
+Use `Activity.request` to create and display a Live Activity. Pass `.token` as
+the `pushType` to enable remote updates via APNs.
+```swift
+let attributes = DeliveryAttributes(orderNumber: 42, restaurantName: "Pizza Place")
+let state = DeliveryAttributes.ContentState(
+    driverName: "Alex",
+    estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
+    currentStep: .preparing
+)
+let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
+do {
+    let activity = try Activity.request(
+        attributes: attributes,
+        content: content,
+        pushType: .token
+    )
+    print("Started activity: \(activity.id)")
+} catch {
+    print("Failed to start activity: \(error)")
+}
+```
+### Updating
+Update the dynamic content state from the app. Use `AlertConfiguration` to
+trigger a visible banner and sound alongside the update.
+```swift
+let updatedState = DeliveryAttributes.ContentState(
+    driverName: "Alex",
+    estimatedDeliveryTime: Date()...Date().addingTimeInterval(600),
+    currentStep: .delivering
+)
+let updatedContent = ActivityContent(
+    state: updatedState,
+    staleDate: Date().addingTimeInterval(300),
+    relevanceScore: 90
+)
+// Silent update
+await activity.update(updatedContent)
+// Update with an alert
+await activity.update(updatedContent, alertConfiguration: AlertConfiguration(
+    title: "Order Update",
+    body: "Your driver is nearby!",
+    sound: .default
+))
+```
+### Ending
+End the activity when the tracked event completes. Choose a dismissal policy
+to control how long the ended activity lingers on the Lock Screen.
+```swift
+let finalState = DeliveryAttributes.ContentState(
+    driverName: "Alex",
+    estimatedDeliveryTime: Date()...Date(),
+    currentStep: .delivered
+)
+let finalContent = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
+// System decides when to remove (up to 4 hours)
+await activity.end(finalContent, dismissalPolicy: .default)
+// Remove immediately
+await activity.end(finalContent, dismissalPolicy: .immediate)
+// Remove after a specific time (max 4 hours from now)
+await activity.end(finalContent, dismissalPolicy: .after(Date().addingTimeInterval(3600)))
+```
+Always end activities on all code paths -- success, error, and cancellation.
+A leaked activity stays on the Lock Screen until the system kills it (up to
+8 hours), which frustrates users.
+## Lock Screen Presentation
+The Lock Screen is the primary surface for Live Activities. Every device with
+iOS 16.1+ displays Live Activities here. Design this layout first.
+```swift
+struct DeliveryActivityWidget: Widget {
+    var body: some WidgetConfiguration {
+        ActivityConfiguration(for: DeliveryAttributes.self) { context in
+            // Lock Screen / StandBy / CarPlay / Mac menu bar content
+            VStack(alignment: .leading, spacing: 8) {
+                HStack {
+                    Text(context.attributes.restaurantName)
+                        .font(.headline)
+                    Spacer()
+                    Text("Order #\(context.attributes.orderNumber)")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+                if context.isStale {
+                    Label("Updating...", systemImage: "arrow.trianglehead.2.clockwise")
+                        .font(.subheadline)
+                        .foregroundStyle(.secondary)
+                } else {
+                    HStack {
+                        Label(context.state.driverName, systemImage: "person.fill")
+                        Spacer()
+                        Text(timerInterval: context.state.estimatedDeliveryTime,
+                             countsDown: true)
+                            .monospacedDigit()
+                    }
+                    .font(.subheadline)
+                    // Progress steps
+                    HStack(spacing: 12) {
+                        ForEach(DeliveryStep.allCases, id: \.self) { step in
+                            Image(systemName: step.icon)
+                                .foregroundStyle(
+                                    step <= context.state.currentStep ? .primary : .tertiary
+                                )
+                        }
+                    }
+                }
+            }
+            .padding()
+        } dynamicIsland: { context in
+            // Dynamic Island closures (see next section)
+            DynamicIsland {
+                // Expanded regions...
+                DynamicIslandExpandedRegion(.leading) {
+                    Image(systemName: "box.truck.fill").font(.title2)
+                }
+                DynamicIslandExpandedRegion(.trailing) {
+                    Text(timerInterval: context.state.estimatedDeliveryTime,
+                         countsDown: true)
+                        .font(.caption).monospacedDigit()
+                }
+                DynamicIslandExpandedRegion(.center) {
+                    Text(context.attributes.restaurantName).font(.headline)
+                }
+                DynamicIslandExpandedRegion(.bottom) {
+                    HStack(spacing: 12) {
+                        ForEach(DeliveryStep.allCases, id: \.self) { step in
+                            Image(systemName: step.icon)
+                                .foregroundStyle(
+                                    step <= context.state.currentStep ? .primary : .tertiary
+                                )
+                        }
+                    }
+                }
+            } compactLeading: {
+                Image(systemName: "box.truck.fill")
+            } compactTrailing: {
+                Text(timerInterval: context.state.estimatedDeliveryTime,
+                     countsDown: true)
+                    .frame(width: 40).monospacedDigit()
+            } minimal: {
+                Image(systemName: "box.truck.fill")
+            }
+        }
+    }
+}
+```
+### Lock Screen Sizing
+The Lock Screen presentation has limited vertical space. Avoid layouts taller
+than roughly 160 points. Use `supplementalActivityFamilies` to opt into
+`.small` (compact) or `.medium` (standard) sizing:
+```swift
+ActivityConfiguration(for: DeliveryAttributes.self) { context in
+    // Lock Screen content
+} dynamicIsland: { context in
+    // Dynamic Island
+}
+.supplementalActivityFamilies([.small, .medium])
+```
+## Dynamic Island
+The Dynamic Island is available on iPhone 14 Pro and later. It has three
+presentation modes. Design all three, but treat the Lock Screen as the primary
+surface since not all devices have a Dynamic Island.
+### Compact (Leading + Trailing)
+Always visible when a single Live Activity is active. Space is extremely
+limited -- show only the most critical information.
+| Region | Purpose |
+|---|---|
+| `compactLeading` | Icon or tiny label identifying the activity |
+| `compactTrailing` | One key value (timer, score, status) |
+### Minimal
+Shown when multiple Live Activities compete for space. Only one activity gets
+the minimal slot. Display a single icon or glyph.
+### Expanded Regions
+Shown when the user long-presses the Dynamic Island.
+| Region | Position |
+|---|---|
+| `.leading` | Left of the TrueDepth camera; wraps below |
+| `.trailing` | Right of the TrueDepth camera; wraps below |
+| `.center` | Directly below the camera |
+| `.bottom` | Below all other regions |
+### Keyline Tint
+Apply a subtle tint to the Dynamic Island border:
+```swift
+DynamicIsland { /* expanded */ }
+    compactLeading: { /* ... */ }
+    compactTrailing: { /* ... */ }
+    minimal: { /* ... */ }
+    .keylineTint(.blue)
+```
+## Push-to-Update
+Push-to-update sends Live Activity updates through APNs, which is more
+efficient than polling from the app and works when the app is suspended.
+### Setup
+Pass `.token` as the `pushType` when starting the activity, then forward the
+push token to your server:
+```swift
+let activity = try Activity.request(
+    attributes: attributes,
+    content: content,
+    pushType: .token
+)
+// Observe token changes -- tokens can rotate
+Task {
+    for await token in activity.pushTokenUpdates {
+        let tokenString = token.map { String(format: "%02x", $0) }.joined()
+        try await ServerAPI.shared.registerActivityToken(
+            tokenString, activityID: activity.id
+        )
+    }
+}
+```
+### APNs Payload Format
+Send an HTTP/2 POST to APNs with these headers and JSON body:
+**Required HTTP headers:**
+- `apns-push-type: liveactivity`
+- `apns-topic: <bundle-id>.push-type.liveactivity`
+- `apns-priority: 5` (low) or `10` (high, triggers alert)
+**Update payload:**
+```json
+{
+    "aps": {
+        "timestamp": 1700000000,
+        "event": "update",
+        "content-state": {
+            "driverName": "Alex",
+            "estimatedDeliveryTime": {
+                "lowerBound": 1700000000,
+                "upperBound": 1700001800
+            },
+            "currentStep": "delivering"
+        },
+        "stale-date": 1700000300,
+        "alert": {
+            "title": "Delivery Update",
+            "body": "Your driver is nearby!"
+        }
+    }
+}
+```
+**End payload:** Same structure with `"event": "end"` and optional `"dismissal-date"`.
+The `content-state` JSON must match the `ContentState` Codable structure
+exactly. Mismatched keys or types cause silent failures.
+### Push-to-Start
+Start a Live Activity remotely without the app running (iOS 17.2+):
+```swift
+Task {
+    for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
+        let tokenString = token.map { String(format: "%02x", $0) }.joined()
+        try await ServerAPI.shared.registerPushToStartToken(tokenString)
+    }
+}
+```
+### Frequent Push Updates
+Add `NSSupportsLiveActivitiesFrequentUpdates = YES` to Info.plist to increase
+the push update budget. Use for activities that update more than once per
+minute (sports scores, ride tracking).
+## iOS 26 Additions
+### Scheduled Live Activities (iOS 26+)
+Schedule a Live Activity to start at a future time. The system starts the
+activity automatically without the app being in the foreground. Use for events
+with known start times (sports games, flights, scheduled deliveries).
+```swift
+let scheduledDate = Calendar.current.date(
+    from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
+)!
+let activity = try Activity.request(
+    attributes: attributes,
+    content: content,
+    pushType: .token,
+    start: scheduledDate
+)
+```
+### ActivityStyle (iOS 16.1+ type, `style:` parameter iOS 26+)
+Control persistence: `.standard` (persists until ended, default) or `.transient` (system may dismiss automatically). Use `.transient` for short-lived updates like transit arrivals. The `style:` parameter on `Activity.request` requires iOS 26+.
+```swift
+let activity = try Activity.request(
+    attributes: attributes, content: content,
+    pushType: .token, style: .transient
+)
+```
+### Mac Menu Bar & CarPlay (iOS 26+)
+Live Activities automatically appear in macOS Tahoe menu bar (via iPhone Mirroring) and CarPlay Home Screen. No additional code needed — ensure Lock Screen layout is legible at smaller scales.
+### Channel-Based Push (iOS 18+)
+Broadcast updates to many Live Activities at once with `.channel`:
+```swift
+let activity = try Activity.request(
+    attributes: attributes, content: content,
+    pushType: .channel("delivery-updates")
+)
+```
+## Common Mistakes
+**DON'T:** Put too much content in the compact presentation -- it is tiny.
+**DO:** Show only the most critical info (icon + one value) in compact leading/trailing.
+**DON'T:** Update Live Activities too frequently from the app (drains battery).
+**DO:** Use push-to-update for server-driven updates. Limit app-side updates to user actions.
+**DON'T:** Forget to end the activity when the event completes.
+**DO:** Always end activities on success, error, and cancellation paths. A leaked activity frustrates users.
+**DON'T:** Assume the Dynamic Island is available (only iPhone 14 Pro+).
+**DO:** Design for the Lock Screen as the primary surface; Dynamic Island is supplementary.
+**DON'T:** Store sensitive information in ActivityAttributes (visible on Lock Screen).
+**DO:** Keep sensitive data in the app and show only safe-to-display summaries.
+**DON'T:** Forget to handle stale dates.
+**DO:** Check `context.isStale` in views and show fallback UI ("Updating..." or similar).
+**DON'T:** Ignore push token rotation. Tokens can change at any time.
+**DO:** Use `activity.pushTokenUpdates` async sequence and re-register on every emission.
+**DON'T:** Forget the `NSSupportsLiveActivities` Info.plist key.
+**DO:** Add `NSSupportsLiveActivities = YES` to the host app's Info.plist (not the extension).
+**DON'T:** Use the deprecated `contentState`-based API for request/update/end.
+**DO:** Use `ActivityContent` for all lifecycle calls.
+**DON'T:** Put heavy logic in Live Activity views. They render in a size-limited widget process.
+**DO:** Pre-compute display values and pass them through `ContentState`.
+## Review Checklist
+- [ ] `ActivityAttributes` defines static properties and `ContentState`
+- [ ] `NSSupportsLiveActivities = YES` in host app Info.plist
+- [ ] Activity uses `ActivityContent` (not deprecated contentState API)
+- [ ] Activity ended in all code paths (success, error, cancellation)
+- [ ] Lock Screen layout handles `context.isStale`
+- [ ] Dynamic Island compact, expanded, and minimal implemented
+- [ ] Push token forwarded to server via `activity.pushTokenUpdates`
+- [ ] `AlertConfiguration` used for important updates
+- [ ] `ActivityAuthorizationInfo` checked before starting
+- [ ] ContentState kept small (serialized on every update)
+- [ ] Tested on device (Dynamic Island differs from Simulator)
+- [ ] Ensure ActivityAttributes and ContentState types are Sendable; update Live Activity UI on @MainActor
+## References
+- See `references/live-activity-patterns.md` for patterns and code examples