@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/live-activities/references/activitykit-patterns.md

@@ -1,141 +1,117 @@
-# Live Activity Patterns
+# ActivityKit Patterns
 
-Complete implementation patterns for ActivityKit Live Activities, Dynamic
-Island, push-to-update, and lifecycle management. All patterns use modern
-Swift async/await and `ActivityContent`, so they target iOS 16.2+ unless noted.
+Worked patterns for Live Activities. Everything here uses async/await and
+`ActivityContent`, so it needs iOS 16.2 or later unless a heading names a
+newer release.
 
 ## Contents
 
-- [Complete ActivityAttributes and ContentState](#complete-activityattributes-and-contentstate)
-- [Starting a Live Activity with All Parameters](#starting-a-live-activity-with-all-parameters)
-- [Updating from the App](#updating-from-the-app)
-- [Push-to-Update Server Payload Format](#push-to-update-server-payload-format)
-- [Ending with Different Dismissal Policies](#ending-with-different-dismissal-policies)
-- [Complete Dynamic Island Layout (All Regions)](#complete-dynamic-island-layout-all-regions)
-- [Lock Screen Layout with Timer and Progress](#lock-screen-layout-with-timer-and-progress)
-- [Multiple Concurrent Activities](#multiple-concurrent-activities)
-- [Observing Activity State Changes](#observing-activity-state-changes)
-- [Token Update Handling](#token-update-handling)
-- [Authorization Check](#authorization-check)
-- [Error Handling](#error-handling)
-- [Background Handling Considerations](#background-handling-considerations)
-- [Testing in Simulator and on Device](#testing-in-simulator-and-on-device)
-- [Info.plist Keys Reference](#infoplist-keys-reference)
-- [Apple Documentation Links](#apple-documentation-links)
-
-## Complete ActivityAttributes and ContentState
-
-Define the data model for your Live Activity. Static properties go on the
-outer struct; dynamic properties go in `ContentState`.
+- [A complete attributes model](#a-complete-attributes-model)
+- [Starting, with every parameter](#starting-with-every-parameter)
+- [Updating from the app](#updating-from-the-app)
+- [Server payloads](#server-payloads)
+- [Channel pushes (iOS 18+)](#channel-pushes-ios-18)
+- [Ending by outcome](#ending-by-outcome)
+- [Dynamic Island, all regions](#dynamic-island-all-regions)
+- [Lock Screen view with timer and progress](#lock-screen-view-with-timer-and-progress)
+- [Several activities at once](#several-activities-at-once)
+- [Observing state and content](#observing-state-and-content)
+- [Tokens](#tokens)
+- [Authorization](#authorization)
+- [Errors](#errors)
+- [Background behaviour](#background-behaviour)
+- [Testing](#testing)
+- [Info.plist keys](#infoplist-keys)
+- [Apple documentation](#apple-documentation)
+
+## A complete attributes model
+
+A field-service visit: a technician drives to the customer and does the job.
 
 ```swift
 import ActivityKit
 
-struct RideAttributes: ActivityAttributes {
-    // Static -- set at creation, immutable for the activity lifetime
-    var riderName: String
-    var pickupLocation: String
-    var dropoffLocation: String
-
+struct ServiceVisitAttributes: ActivityAttributes {
     struct ContentState: Codable, Hashable {
-        var driverName: String
-        var driverPhoto: String        // SF Symbol name or asset name
-        var vehicleDescription: String
-        var etaStartSeconds: Int
-        var etaEndSeconds: Int
-        // For server pushes, prefer scalar fields or coordinated custom Codable keys.
-        var status: RideStatus
-        var distanceRemaining: Double   // miles
+        var technicianName: String
+        var avatarSymbol: String          // SF Symbol or asset catalog name
+        var vanDescription: String
+        var arrivalStartEpoch: Int        // seconds since 1970
+        var arrivalEndEpoch: Int
+        var status: VisitStatus
+        var kilometresAway: Double
     }
-}
 
-enum RideStatus: String, Codable, Hashable {
-    case driverAssigned
-    case driverEnRoute
-    case driverArrived
-    case inProgress
-    case arriving
-    case completed
-    case cancelled
-    case failed
+    var customerFirstName: String
+    var serviceAddress: String
+    var jobSummary: String
 }
 
-extension RideAttributes.ContentState {
-    var etaRange: ClosedRange<Date> {
-        Date(timeIntervalSince1970: TimeInterval(etaStartSeconds))...
-            Date(timeIntervalSince1970: TimeInterval(etaEndSeconds))
+extension ServiceVisitAttributes.ContentState {
+    var arrivalWindow: ClosedRange<Date> {
+        Date(timeIntervalSince1970: TimeInterval(arrivalStartEpoch))
+            ...
+            Date(timeIntervalSince1970: TimeInterval(arrivalEndEpoch))
     }
 }
+
+enum VisitStatus: String, Codable, Hashable {
+    case scheduled, enRoute, nearby, onSite, finishing, completed, cancelled, failed
+}
 ```
 
-Keep `ContentState` lightweight. ActivityKit attributes and content-state data
-must fit within the framework's 4 KB data limit. Avoid storing images, large
-strings, or deeply nested objects.
+Why the epoch integers: a server has to produce `content-state` JSON that
+decodes into this type. Plain scalars have one obvious encoding, so the Swift
+side and the server cannot drift. The view-friendly `ClosedRange<Date>` is
+derived in an extension. The alternative is a custom `Codable` implementation
+whose keys and value formats are written down and agreed with the server.
 
-## Starting a Live Activity with All Parameters
+Size budget: the attributes and the content state together must fit in the
+4 KB ActivityKit allows. Leave images, long strings and deep nesting out of
+`ContentState`.
+
+## Starting, with every parameter
+
+The token loops below use a small helper:
 
 ```swift
-import ActivityKit
+extension Data {
+    var hexEncoded: String { reduce(into: "") { $0 += String(format: "%02x", $1) } }
+}
+```
+
+```swift
+enum VisitActivityError: Error { case liveActivitiesOff }
 
 @MainActor
-func startRideActivity(
-    rider: String,
-    pickup: String,
-    dropoff: String,
-    driver: String,
-    vehicle: String
-) async throws -> Activity<RideAttributes> {
-    // Check authorization before attempting to start
-    let authInfo = ActivityAuthorizationInfo()
-    guard authInfo.areActivitiesEnabled else {
-        throw RideError.liveActivitiesDisabled
+func startVisitActivity(
+    attributes: ServiceVisitAttributes,
+    initial: ServiceVisitAttributes.ContentState
+) async throws -> Activity<ServiceVisitAttributes> {
+    guard ActivityAuthorizationInfo().areActivitiesEnabled else {
+        throw VisitActivityError.liveActivitiesOff
     }
 
-    let attributes = RideAttributes(
-        riderName: rider,
-        pickupLocation: pickup,
-        dropoffLocation: dropoff
-    )
-
-    let initialState = RideAttributes.ContentState(
-        driverName: driver,
-        driverPhoto: "car.fill",
-        vehicleDescription: vehicle,
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().addingTimeInterval(600).timeIntervalSince1970),
-        status: .driverAssigned,
-        distanceRemaining: 2.5
-    )
-
-    let content = ActivityContent(
-        state: initialState,
-        staleDate: Date().addingTimeInterval(120), // stale after 2 min
+    let opening = ActivityContent(
+        state: initial,
+        staleDate: .now.addingTimeInterval(120),
         relevanceScore: 80
     )
-
     let activity = try Activity.request(
-        attributes: attributes,
-        content: content,
-        pushType: .token  // Enable push updates
+        attributes: attributes, content: opening, pushType: .token
     )
 
-    // Forward push token to server for remote updates
     Task {
-        for await token in activity.pushTokenUpdates {
-            let tokenString = token.map { String(format: "%02x", $0) }.joined()
-            try? await ServerAPI.shared.registerActivityToken(
-                tokenString, rideID: activity.id
+        for await tokenData in activity.pushTokenUpdates {
+            try? await VisitBackend.shared.register(
+                updateToken: tokenData.hexEncoded, activityID: activity.id
             )
         }
     }
 
-    // Observe state changes for cleanup
     Task {
-        for await state in activity.activityStateUpdates {
-            if state == .dismissed {
-                // Activity removed from UI -- clean up local resources
-                RideStore.shared.removeActivity(id: activity.id)
-            }
+        for await lifecycle in activity.activityStateUpdates where lifecycle == .dismissed {
+            VisitCache.shared.purge(activityID: activity.id)
         }
     }
 
@@ -143,811 +119,603 @@ func startRideActivity(
 }
 ```
 
-### Starting with Scheduled Date (iOS 26+)
-
-Schedule the activity to appear at a future time without the app in foreground:
+### Scheduled start (iOS 26+)
 
 ```swift
-let gameTime = Calendar.current.date(
-    from: DateComponents(year: 2026, month: 3, day: 15, hour: 19, minute: 0)
-)!
-
 let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
+    attributes: visit,
+    content: opening,
     pushType: .token,
     style: .standard,
     alertConfiguration: AlertConfiguration(
-        title: "Game Starting",
-        body: "The live score is ready.",
+        title: "Technician on the way",
+        body: "Your visit window has started.",
         sound: .default
     ),
-    start: gameTime  // iOS 26+
+    start: visitWindowOpens
 )
 ```
 
-### Starting with ActivityStyle (iOS 18+ request parameter)
-
-Use `.standard` for persistent Live Activities that should remain visible until
-the app, push, user, or system duration limit ends them. `.transient` is only
-for short-lived expanded Dynamic Island presentations that can auto-end when the
-user locks the device, collapses or shrinks the expanded presentation, leaves
-the app, or does other work outside Dynamic Island; it is wrong for persistent
-Live Activities.
+### Choosing a style (iOS 18+)
 
 ```swift
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token,
-    style: .standard
+let persistent = try Activity.request(
+    attributes: visit, content: opening, pushType: .token, style: .standard
 )
 ```
 
-## Updating from the App
+A `.standard` activity stays until the app, a push, the user or the system
+duration limit ends it. `.transient` is the wrong choice for anything meant to
+persist; reserve it for brief expanded Dynamic Island moments.
+
+## Updating from the app
+
+Copy the fields that did not change from the current state, and convert dates
+back to the agreed scalar form.
 
 ```swift
-func updateRideActivity(
-    _ activity: Activity<RideAttributes>,
-    newStatus: RideStatus,
-    eta: ClosedRange<Date>,
-    distance: Double,
-    showAlert: Bool = false
+func applyStatus(
+    _ status: VisitStatus,
+    newWindow: ClosedRange<Date>,
+    kilometres: Double,
+    to activity: Activity<ServiceVisitAttributes>,
+    notify: Bool
 ) async {
-    let updatedState = RideAttributes.ContentState(
-        driverName: activity.content.state.driverName,
-        driverPhoto: activity.content.state.driverPhoto,
-        vehicleDescription: activity.content.state.vehicleDescription,
-        etaStartSeconds: Int(eta.lowerBound.timeIntervalSince1970),
-        etaEndSeconds: Int(eta.upperBound.timeIntervalSince1970),
-        status: newStatus,
-        distanceRemaining: distance
+    let current = activity.content.state
+    let state = ServiceVisitAttributes.ContentState(
+        technicianName: current.technicianName,
+        avatarSymbol: current.avatarSymbol,
+        vanDescription: current.vanDescription,
+        arrivalStartEpoch: Int(newWindow.lowerBound.timeIntervalSince1970),
+        arrivalEndEpoch: Int(newWindow.upperBound.timeIntervalSince1970),
+        status: status,
+        kilometresAway: kilometres
     )
-
     let content = ActivityContent(
-        state: updatedState,
-        staleDate: Date().addingTimeInterval(120),
-        relevanceScore: newStatus == .driverArrived ? 100 : 80
+        state: state,
+        staleDate: .now.addingTimeInterval(120),
+        relevanceScore: status == .nearby ? 100 : 80
     )
 
-    if showAlert {
-        await activity.update(content, alertConfiguration: AlertConfiguration(
-            title: "Ride Update",
-            body: alertMessage(for: newStatus),
-            sound: .default
-        ))
-    } else {
+    guard notify else {
         await activity.update(content)
+        return
     }
-}
-
-private func alertMessage(for status: RideStatus) -> String {
-    switch status {
-    case .driverArrived: "Your driver has arrived!"
-    case .arriving: "You're almost there!"
-    case .completed: "You've arrived at your destination."
-    default: "Your ride status has changed."
+    let message: LocalizedStringResource = switch status {
+    case .nearby: "Your technician is a few minutes away."
+    case .onSite: "Your technician has arrived."
+    default: "Your visit has an update."
     }
+    await activity.update(
+        content,
+        alertConfiguration: AlertConfiguration(title: "Service visit", body: message, sound: .default)
+    )
 }
 ```
 
-## Push-to-Update Server Payload Format
+`relevanceScore` ranks this activity against the app's other activities when
+the system has to choose what to show; raise it for the moment that matters
+most.
+
+## Server payloads
+
+Keys in `content-state` are the `ContentState` property names; enums travel as
+their raw values; numbers stay numbers.
 
-### Update Payload
+Update:
 
 ```json
 {
-    "aps": {
-        "timestamp": 1700000000,
-        "event": "update",
-        "content-state": {
-            "driverName": "Maria",
-            "driverPhoto": "car.fill",
-            "vehicleDescription": "White Toyota Camry",
-            "etaStartSeconds": 1700000000,
-            "etaEndSeconds": 1700000300,
-            "status": "driverArrived",
-            "distanceRemaining": 0.0
-        },
-        "stale-date": 1700000300,
-        "relevance-score": 100,
-        "alert": {
-            "title": "Ride Update",
-            "body": "Your driver has arrived!",
-            "sound": "default"
-        }
+  "aps": {
+    "timestamp": 1790000000,
+    "event": "update",
+    "content-state": {
+      "technicianName": "Sam",
+      "avatarSymbol": "person.crop.circle",
+      "vanDescription": "White van, blue stripe",
+      "arrivalStartEpoch": 1790000300,
+      "arrivalEndEpoch": 1790000900,
+      "status": "nearby",
+      "kilometresAway": 1.2
+    },
+    "stale-date": 1790000600,
+    "relevance-score": 100,
+    "alert": {
+      "title": "Service visit",
+      "body": "Your technician is a few minutes away.",
+      "sound": "default"
     }
+  }
 }
 ```
 
-### End Payload
+End:
 
 ```json
 {
-    "aps": {
-        "timestamp": 1700002000,
-        "event": "end",
-        "dismissal-date": 1700005600,
-        "content-state": {
-            "driverName": "Maria",
-            "driverPhoto": "car.fill",
-            "vehicleDescription": "White Toyota Camry",
-            "etaStartSeconds": 1700002000,
-            "etaEndSeconds": 1700002000,
-            "status": "completed",
-            "distanceRemaining": 0.0
-        }
+  "aps": {
+    "timestamp": 1790004000,
+    "event": "end",
+    "dismissal-date": 1790007600,
+    "content-state": {
+      "technicianName": "Sam",
+      "avatarSymbol": "person.crop.circle",
+      "vanDescription": "White van, blue stripe",
+      "arrivalStartEpoch": 1790000300,
+      "arrivalEndEpoch": 1790000300,
+      "status": "completed",
+      "kilometresAway": 0
     }
+  }
 }
 ```
 
-### Push-to-Start Payload (iOS 17.2+)
-
-Send to the push-to-start token to remotely create an activity. The `alert` field is required for push-to-start:
+Push-to-start (iOS 17.2+), addressed to the token from `pushToStartTokenUpdates`. `attributes-type`
+is the Swift type name, `attributes` holds the static fields, and `alert` must
+be present:
 
 ```json
 {
-    "aps": {
-        "timestamp": 1700000000,
-        "event": "start",
-        "attributes-type": "RideAttributes",
-        "attributes": {
-            "riderName": "Jordan",
-            "pickupLocation": "123 Main St",
-            "dropoffLocation": "456 Oak Ave"
-        },
-        "content-state": {
-            "driverName": "Maria",
-            "driverPhoto": "car.fill",
-            "vehicleDescription": "White Toyota Camry",
-            "etaStartSeconds": 1700000000,
-            "etaEndSeconds": 1700000600,
-            "status": "driverAssigned",
-            "distanceRemaining": 3.2
-        },
-        "alert": {
-            "title": "Ride Matched",
-            "body": "Maria is on the way in a White Toyota Camry."
-        }
+  "aps": {
+    "timestamp": 1789990000,
+    "event": "start",
+    "attributes-type": "ServiceVisitAttributes",
+    "attributes": {
+      "customerFirstName": "Alex",
+      "serviceAddress": "12 Elm Row",
+      "jobSummary": "Boiler check"
+    },
+    "content-state": {
+      "technicianName": "Sam",
+      "avatarSymbol": "person.crop.circle",
+      "vanDescription": "White van, blue stripe",
+      "arrivalStartEpoch": 1790000300,
+      "arrivalEndEpoch": 1790000900,
+      "status": "scheduled",
+      "kilometresAway": 14.0
+    },
+    "alert": {
+      "title": "Visit booked",
+      "body": "Follow your technician live."
     }
+  }
 }
 ```
 
-### Required APNs HTTP Headers
+### HTTP headers
 
 | Header | Value |
 |---|---|
 | `apns-push-type` | `liveactivity` |
-| `apns-topic` | `<bundle-id>.push-type.liveactivity` |
-| `apns-priority` | `5` (lower priority) or `10` (immediate, counts against budget) |
-| `authorization` | `bearer <jwt>` (token auth) or use certificate auth |
+| `apns-topic` | `BUNDLE_ID.push-type.liveactivity` |
+| `apns-priority` | `5` (low) or `10` (immediate, counts against the budget) |
+| `authorization` | `bearer JWT` with token-based auth; omit when using certificate auth |
 
-The `aps.alert` payload controls visible alert/banner/sound behavior; priority
-alone does not create an alert. The `content-state` JSON must decode into
-`ActivityAttributes.ContentState`. Use the default synthesized `Codable` key and
-value shape unless the Swift model declares custom `CodingKeys`; then coordinate
-those exact keys and value shapes server-side. Do not assume `Date` or
-`ClosedRange<Date>` values are Unix timestamp dictionaries unless your Swift
-model explicitly encodes them that way. A type mismatch (e.g., sending a string
-where a number is expected) can prevent ActivityKit from applying the update.
+A type mismatch, for example `"kilometresAway": "1.2"` for a `Double`, can be
+enough for the update to be dropped.
 
-### Channel / Broadcast Updates (iOS 18+)
+## Channel pushes (iOS 18+)
 
-Use channel-based push only with a valid APNs-created channel ID. Enable the
-broadcast capability outside Xcode, have the server create the channel, and pass
-that channel ID to the app:
+Use a channel only with a valid channel ID that APNs created and your server
+handed to the app:
 
 ```swift
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .channel(channelIDFromServer)
+let broadcastVisit = try Activity.request(
+    attributes: visit,
+    content: opening,
+    pushType: .channel(channelID)
 )
 ```
 
-Channel pushes can update or end Live Activities, but cannot start them. Use
-`apns-channel-id` and expiration for channel requests instead of the device-token
-`apns-topic` header.
+Channel pushes update or end; they never start an activity. They are sent with
+`apns-channel-id` and an expiration rather than the device-token `apns-topic`.
 
-## Ending with Different Dismissal Policies
+## Ending by outcome
 
 ```swift
-func endRideActivity(
-    _ activity: Activity<RideAttributes>,
-    finalStatus: RideStatus
-) async {
-    let finalState = RideAttributes.ContentState(
-        driverName: activity.content.state.driverName,
-        driverPhoto: activity.content.state.driverPhoto,
-        vehicleDescription: activity.content.state.vehicleDescription,
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().timeIntervalSince1970),
-        status: finalStatus,
-        distanceRemaining: 0
-    )
-
-    let content = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
-
-    switch finalStatus {
-    case .completed:
-        // Keep on Lock Screen for 1 hour so user can review trip details
-        await activity.end(content, dismissalPolicy: .after(
-            Date().addingTimeInterval(3600)
-        ))
-    case .cancelled:
-        // Remove immediately -- no useful info to show
-        await activity.end(content, dismissalPolicy: .immediate)
-    default:
-        // Let the system decide
-        await activity.end(content, dismissalPolicy: .default)
+func finishVisit(_ activity: Activity<ServiceVisitAttributes>, outcome: VisitStatus) async {
+    var last = activity.content.state
+    last.status = outcome
+    let final = ActivityContent(state: last, staleDate: nil, relevanceScore: 0)
+
+    let policy: ActivityUIDismissalPolicy = switch outcome {
+    case .completed: .after(.now.addingTimeInterval(3600))
+    case .cancelled: .immediate
+    default: .default
     }
+    await activity.end(final, dismissalPolicy: policy)
 }
 ```
 
-When reviewing duration claims, distinguish the active lifetime (up to 8 hours
-unless the app or user ends it sooner), system-ended Lock Screen presence (up to
-4 additional hours, for 12 hours total from start), and app-ended `.default`
-dismissal linger (up to 4 hours after ending).
+A completed visit keeps its card for an hour so the customer can glance back
+at it; a cancelled one has nothing worth showing and leaves at once.
 
-### Ending on Terminal Server Failure
+Duration limits, stated separately: up to 8 hours active; after a
+system-imposed end, up to 4 more hours on the Lock Screen (12 in total); after
+an app-initiated end with `.default`, up to 4 hours of lingering.
 
-When a server reports that the tracked event failed or can no longer be
-represented accurately, publish a terminal state and end the activity instead of
-leaving stale progress visible.
+### Terminal server failure
 
 ```swift
-func handleTerminalServerFailure(
-    _ activity: Activity<RideAttributes>,
-    message: String
-) async {
-    let failedState = RideAttributes.ContentState(
-        driverName: activity.content.state.driverName,
-        driverPhoto: activity.content.state.driverPhoto,
-        vehicleDescription: message,
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().timeIntervalSince1970),
-        status: .failed,
-        distanceRemaining: 0
+func failVisit(_ activity: Activity<ServiceVisitAttributes>, reason: String) async {
+    var last = activity.content.state
+    last.status = .failed
+    last.vanDescription = reason   // a text field the view shows for failed visits
+    await activity.end(
+        ActivityContent(state: last, staleDate: nil, relevanceScore: 0),
+        dismissalPolicy: .immediate
     )
-
-    let content = ActivityContent(state: failedState, staleDate: nil, relevanceScore: 0)
-    await activity.end(content, dismissalPolicy: .immediate)
 }
 ```
 
-### Ending All Activities (cleanup on sign-out)
+### Sign-out
 
 ```swift
-func endAllRideActivities() async {
-    for activity in Activity<RideAttributes>.activities {
-        await activity.end(nil, dismissalPolicy: .immediate)
+func endAllVisits() async {
+    for running in Activity<ServiceVisitAttributes>.activities {
+        await running.end(nil, dismissalPolicy: .immediate)
     }
 }
 ```
 
-## Complete Dynamic Island Layout (All Regions)
-
-```swift
-struct RideActivityWidget: Widget {
-    var body: some WidgetConfiguration {
-        ActivityConfiguration(for: RideAttributes.self) { context in
-            // Lock Screen presentation
-            RideLockScreenView(context: context)
-        } dynamicIsland: { context in
-            DynamicIsland {
-                // EXPANDED: shown on long-press
-                DynamicIslandExpandedRegion(.leading) {
-                    VStack(alignment: .leading) {
-                        Image(systemName: context.state.driverPhoto)
-                            .font(.title2)
-                        Text(context.state.driverName)
-                            .font(.caption2)
-                            .lineLimit(1)
-                    }
-                }
-
-                DynamicIslandExpandedRegion(.trailing) {
-                    VStack(alignment: .trailing) {
-                        Text(timerInterval: context.state.etaRange, countsDown: true)
-                            .font(.title3.monospacedDigit())
-                        Text(String(format: "%.1f mi", context.state.distanceRemaining))
-                            .font(.caption2)
-                            .foregroundStyle(.secondary)
-                    }
-                }
+Passing `nil` content ends the activity with its last state.
 
-                DynamicIslandExpandedRegion(.center) {
-                    Text(context.state.status.displayName)
-                        .font(.headline)
-                        .lineLimit(1)
-                }
+## Dynamic Island, all regions
 
-                DynamicIslandExpandedRegion(.bottom) {
-                    VStack {
-                        ProgressView(
-                            value: context.state.status.progress,
-                            total: 1.0
-                        )
-                        .tint(.green)
-
-                        HStack {
-                            Label(context.attributes.pickupLocation,
-                                  systemImage: "mappin.circle.fill")
-                            Spacer()
-                            Label(context.attributes.dropoffLocation,
-                                  systemImage: "flag.checkered")
-                        }
-                        .font(.caption2)
-                        .foregroundStyle(.secondary)
-                        .lineLimit(1)
-                    }
-                }
-            } compactLeading: {
-                // COMPACT LEADING: tiny icon identifying the activity
-                Image(systemName: context.state.driverPhoto)
-                    .foregroundStyle(.green)
-            } compactTrailing: {
-                // COMPACT TRAILING: one key value
-                Text(timerInterval: context.state.etaRange, countsDown: true)
-                    .frame(width: 44)
-                    .monospacedDigit()
-            } minimal: {
-                // MINIMAL: shown when multiple activities compete
-                Image(systemName: "car.fill")
-                    .foregroundStyle(.green)
+```swift
+DynamicIsland {
+    DynamicIslandExpandedRegion(.leading) {
+        Label {
+            Text(context.state.technicianName).lineLimit(1)
+        } icon: {
+            Image(systemName: context.state.avatarSymbol)
+        }
+    }
+    DynamicIslandExpandedRegion(.trailing) {
+        VStack(alignment: .trailing) {
+            Text(timerInterval: context.state.arrivalWindow, countsDown: true)
+                .monospacedDigit()
+            Text(context.state.kilometresAway, format: .number.precision(.fractionLength(1)))
+                .font(.caption)
+        }
+    }
+    DynamicIslandExpandedRegion(.center) {
+        Text(context.state.status.rawValue.capitalized)
+    }
+    DynamicIslandExpandedRegion(.bottom) {
+        VStack(spacing: 6) {
+            ProgressView(value: max(0, 15 - context.state.kilometresAway), total: 15)
+                .tint(.orange)
+            HStack {
+                Label(context.attributes.jobSummary, systemImage: "wrench.and.screwdriver")
+                Spacer()
+                Label(context.attributes.serviceAddress, systemImage: "house")
             }
-            .keylineTint(.green)
+            .font(.caption)
+            .lineLimit(1)
         }
     }
+} compactLeading: {
+    Image(systemName: "wrench.and.screwdriver")
+} compactTrailing: {
+    Text(timerInterval: context.state.arrivalWindow, countsDown: true)
+        .monospacedDigit()
+        .frame(width: 44)
+} minimal: {
+    Image(systemName: "wrench.and.screwdriver").foregroundStyle(.orange)
 }
+.keylineTint(.orange)
 ```
 
-## Lock Screen Layout with Timer and Progress
+## Lock Screen view with timer and progress
 
 ```swift
-struct RideLockScreenView: View {
-    let context: ActivityViewContext<RideAttributes>
+struct VisitLockScreenView: View {
+    let context: ActivityViewContext<ServiceVisitAttributes>
 
     var body: some View {
-        VStack {
-            // Header
+        VStack(alignment: .leading, spacing: 8) {
             HStack {
-                VStack(alignment: .leading) {
-                    Text(context.state.status.displayName)
-                        .font(.headline)
-                    Text(context.state.vehicleDescription)
+                Text(context.state.technicianName).font(.headline)
+                Spacer()
+                if context.isStale {
+                    Label("Waiting for fresh data", systemImage: "arrow.trianglehead.2.clockwise")
                         .font(.caption)
                         .foregroundStyle(.secondary)
+                } else {
+                    Text(timerInterval: context.state.arrivalWindow, countsDown: true)
+                        .monospacedDigit()
                 }
-                Spacer()
-                // Live countdown timer (auto-updating, no code needed)
-                Text(timerInterval: context.state.etaRange, countsDown: true)
-                    .font(.title2.monospacedDigit().bold())
-                    .foregroundStyle(.green)
-            }
-
-            if context.isStale {
-                Label("Checking for updates...",
-                      systemImage: "arrow.trianglehead.2.clockwise")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
             }
-
-            // Progress bar
-            ProgressView(value: context.state.status.progress, total: 1.0)
-                .tint(.green)
-
-            // Route
+            ProgressView(value: max(0, 15 - context.state.kilometresAway), total: 15)
             HStack {
-                VStack(alignment: .leading) {
-                    Text("Pickup").font(.caption2).foregroundStyle(.secondary)
-                    Text(context.attributes.pickupLocation).font(.caption).lineLimit(1)
-                }
+                Text(context.attributes.jobSummary)
                 Spacer()
-                Image(systemName: "arrow.right")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-                Spacer()
-                VStack(alignment: .trailing) {
-                    Text("Dropoff").font(.caption2).foregroundStyle(.secondary)
-                    Text(context.attributes.dropoffLocation).font(.caption).lineLimit(1)
-                }
+                Text(context.attributes.serviceAddress)
             }
+            .font(.caption)
+            .lineLimit(1)
         }
         .padding()
     }
 }
 ```
 
-## Multiple Concurrent Activities
+`Text(timerInterval:countsDown:)` ticks by itself; no update is needed to keep
+the countdown moving.
 
-An app can run multiple Live Activities simultaneously (system limit applies).
-Track them by storing references or querying `Activity<T>.activities`.
+## Several activities at once
+
+An app may run more than one Live Activity, up to a system limit. Keep
+references yourself or ask `Activity<T>.activities`.
 
 ```swift
+@preconcurrency import ActivityKit
+import Observation
+
 @Observable
 @MainActor
-final class ActivityManager {
-    private(set) var activeDeliveries: [String: Activity<DeliveryAttributes>] = [:]
+final class ChargingActivityCenter {
+    private(set) var bySession: [String: Activity<ChargingAttributes>] = [:]
 
-    func startDelivery(orderID: String, attributes: DeliveryAttributes,
-                       state: DeliveryAttributes.ContentState) async throws {
-        let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
+    func start(session: String, attributes: ChargingAttributes, state: ChargingAttributes.ContentState) throws {
         let activity = try Activity.request(
-            attributes: attributes, content: content, pushType: .token
+            attributes: attributes,
+            content: ActivityContent(state: state, staleDate: nil),
+            pushType: .token
         )
-        activeDeliveries[orderID] = activity
+        bySession[session] = activity
 
-        // Token forwarding
         Task { [weak self] in
-            for await token in activity.pushTokenUpdates {
-                let tokenString = token.map { String(format: "%02x", $0) }.joined()
-                try? await ServerAPI.shared.registerActivityToken(tokenString, orderID: orderID)
+            for await tokenData in activity.pushTokenUpdates {
+                try? await ChargingBackend.shared.register(tokenData.hexEncoded, session: session)
             }
-            self?.activeDeliveries.removeValue(forKey: orderID)
+            self?.bySession[session] = nil
         }
     }
 
-    func updateDelivery(orderID: String, state: DeliveryAttributes.ContentState) async {
-        guard let activity = activeDeliveries[orderID] else { return }
-        let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 80)
-        await activity.update(content)
+    func update(session: String, to state: ChargingAttributes.ContentState) async {
+        await bySession[session]?.update(ActivityContent(state: state, staleDate: nil))
     }
 
-    func endDelivery(orderID: String, finalState: DeliveryAttributes.ContentState) async {
-        guard let activity = activeDeliveries[orderID] else { return }
-        let content = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
-        await activity.end(content, dismissalPolicy: .default)
-        activeDeliveries.removeValue(forKey: orderID)
+    func end(session: String) async {
+        await bySession[session]?.end(nil, dismissalPolicy: .default)
+        bySession[session] = nil
     }
 
-    /// Reconcile in-memory state with system activities on app launch
     func reconcile() {
-        let systemActivities = Activity<DeliveryAttributes>.activities
-        for activity in systemActivities {
-            let orderID = "\(activity.attributes.orderNumber)"
-            if activeDeliveries[orderID] == nil {
-                activeDeliveries[orderID] = activity
-            }
+        for activity in Activity<ChargingAttributes>.activities
+        where !bySession.values.contains(where: { $0.id == activity.id }) {
+            bySession[activity.id] = activity   // session unknown after relaunch; key by activity ID
         }
     }
 }
 ```
 
-## Observing Activity State Changes
+Call `reconcile()` at launch so activities the system still holds are tracked
+again after the process was killed.
+
+`Activity` is not `Sendable`, and its `update` and `end` are `nonisolated`
+async methods, so calling them on an activity held by a `@MainActor` type fails
+in Swift 6 with "sending value of non-Sendable type 'Activity<...>' risks
+causing data races". `@preconcurrency import ActivityKit` accepts that until
+the SDK annotates the type; the alternative is to keep only activity IDs on
+the main actor and do the calls from `nonisolated` code.
+
+## Observing state and content
 
 ```swift
-func observeActivityState(_ activity: Activity<RideAttributes>) {
-    // State updates: .active, .pending, .stale, .ended, .dismissed
-    Task {
-        for await state in activity.activityStateUpdates {
-            switch state {
-            case .active:
-                print("Activity is visible and running")
-            case .pending:
-                // iOS 26+: scheduled but not yet displayed
-                print("Activity is pending start")
-            case .stale:
-                // iOS 16.2+: staleDate passed without an update
-                print("Content is stale -- update or end")
-            case .ended:
-                // Ended but may still be visible on Lock Screen
-                print("Activity ended, may still linger on Lock Screen")
-            case .dismissed:
-                // Fully removed from UI -- safe to release resources
-                print("Activity dismissed from Lock Screen")
-                cleanupResources(for: activity.id)
-            @unknown default:
-                break
-            }
+Task {
+    for await lifecycle in activity.activityStateUpdates {
+        switch lifecycle {
+        case .active: break                 // on screen and running
+        case .pending: break                // iOS 26+: scheduled, not shown yet
+        case .stale: await refresh(activity) // staleDate passed with no update
+        case .ended: break                  // over, may still be on the Lock Screen
+        case .dismissed: cleanUp(activity.id) // gone; release resources here
+        @unknown default: break
         }
     }
+}
 
-    // Content updates (observe state changes from push or other processes)
-    Task {
-        for await content in activity.contentUpdates {
-            print("New state: \(content.state)")
-        }
+Task {
+    for await snapshot in activity.contentUpdates {
+        render(snapshot.state)   // changes that arrived by push or from another process
     }
 }
 ```
 
-## Token Update Handling
+`.stale` exists from iOS 16.2; `.pending` from iOS 26.
+
+## Tokens
 
-Push tokens can change at any time. Always observe the async sequence and
-re-register with your server.
+The update token is how the server reaches the activity, so a failed
+registration deserves retries with exponential backoff rather than a silent
+`try?`:
 
 ```swift
-func observePushToken(for activity: Activity<RideAttributes>) {
-    Task {
-        for await token in activity.pushTokenUpdates {
-            let tokenString = token.map { String(format: "%02x", $0) }.joined()
-            do {
-                try await ServerAPI.shared.registerActivityToken(
-                    tokenString, activityID: activity.id
-                )
-            } catch {
-                // Retry with exponential backoff; token is critical for updates
-                print("Failed to register token: \(error)")
-            }
+func register(_ hex: String, activityID: String) async {
+    var backoff: Duration = .seconds(1)
+    for _ in 0..<5 {
+        do {
+            try await VisitBackend.shared.register(updateToken: hex, activityID: activityID)
+            return
+        } catch {
+            try? await Task.sleep(for: backoff)
+            backoff *= 2
         }
     }
 }
+```
 
-/// Observe the ActivityKit push-to-start token for remote activity creation (iOS 17.2+).
-/// This token is distinct from ordinary app/device APNs tokens and per-activity update tokens.
-func observePushToStartToken() {
-    Task {
-        for await token in Activity<RideAttributes>.pushToStartTokenUpdates {
-            let tokenString = token.map { String(format: "%02x", $0) }.joined()
-            try? await ServerAPI.shared.registerPushToStartToken(tokenString)
-        }
+Push-to-start tokens (iOS 17.2+) are separate from both the device token and
+the per-activity update tokens:
+
+```swift
+Task {
+    for await tokenData in Activity<ServiceVisitAttributes>.pushToStartTokenUpdates {
+        try? await VisitBackend.shared.register(startToken: tokenData.hexEncoded)
     }
 }
 ```
 
-## Authorization Check
+## Authorization
 
-Always check authorization before starting an activity. The user can disable
-Live Activities in Settings at any time.
+The user can turn Live Activities off in Settings at any time, so check before
+every start.
 
 ```swift
-func checkLiveActivityAuthorization() async -> Bool {
-    let authInfo = ActivityAuthorizationInfo()
-    return authInfo.areActivitiesEnabled
-}
-
-func checkFrequentPushAuthorization() -> Bool {
-    ActivityAuthorizationInfo().frequentPushesEnabled
-}
-
-/// Observe authorization changes to react when user toggles the setting
-func observeAuthorization() {
-    Task {
-        let authInfo = ActivityAuthorizationInfo()
-        for await enabled in authInfo.activityEnablementUpdates {
-            if enabled {
-                observePushToStartToken()
-            } else {
-                try? await ServerAPI.shared.disableActivityPush()
-            }
+let info = ActivityAuthorizationInfo()
+let allowed = info.areActivitiesEnabled
+let highCadence = info.frequentPushesEnabled
+
+Task {
+    for await enabled in info.activityEnablementUpdates {
+        if enabled {
+            observePushToStartTokens()
+        } else {
+            await VisitBackend.shared.stopLiveActivityPushes()
         }
     }
+}
 
-    Task {
-        let authInfo = ActivityAuthorizationInfo()
-        for await frequentPushesEnabled in authInfo.frequentPushEnablementUpdates {
-            try? await ServerAPI.shared.setFrequentPushesEnabled(frequentPushesEnabled)
-        }
+Task {
+    for await enabled in info.frequentPushEnablementUpdates {
+        await VisitBackend.shared.setFrequentPushes(enabled)
     }
 }
 ```
 
-## Error Handling
+## Errors
 
-```swift
-func startActivitySafely(
-    attributes: DeliveryAttributes,
-    state: DeliveryAttributes.ContentState
-) async {
-    let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
+`Activity.request` throws `ActivityAuthorizationError`:
 
-    do {
-        let activity = try Activity.request(
-            attributes: attributes, content: content, pushType: .token
-        )
-        print("Started: \(activity.id)")
-    } catch let error as ActivityAuthorizationError {
-        switch error {
-        case .denied:
-            // User disabled Live Activities in Settings
-            print("Live Activities disabled by user")
-        case .globalMaximumExceeded:
-            // Device-level ongoing Live Activity maximum reached
-            print("System-wide activity limit reached")
-        case .targetMaximumExceeded:
-            // Too many Live Activities for this app
-            print("App activity limit reached -- end an existing one first")
-        default:
-            print("Authorization error: \(error)")
-        }
-    } catch {
-        print("Unexpected error: \(error)")
+```swift
+do {
+    _ = try Activity.request(attributes: visit, content: opening, pushType: .token)
+} catch let error as ActivityAuthorizationError {
+    switch error {
+    case .denied:
+        showLiveActivitiesOffHint()        // user switched them off
+    case .globalMaximumExceeded:
+        logger.notice("Device-wide Live Activity limit reached")
+    case .targetMaximumExceeded:
+        await endOldestVisit()             // this app has too many; free one first
+    default:
+        logger.error("Live Activity not started: \(error.localizedDescription)")
     }
+} catch {
+    logger.error("Unexpected request failure: \(error.localizedDescription)")
 }
 ```
 
-## Background Handling Considerations
+## Background behaviour
 
-Live Activities continue to display when the app is backgrounded or suspended.
-The Live Activity UI runs in a widget extension sandbox and cannot fetch network
-data or receive location updates directly. Push-to-update is the primary
-mechanism for background updates. When the app returns to foreground, reconcile
-local state with the activity's current content.
+- Backgrounding or suspending the app does not remove the card.
+- Live Activity views run in the widget extension's sandbox. They cannot hit
+  the network or receive location updates.
+- Pushes are the main way to change an activity while the app is not running;
+  prefer them to Background App Refresh.
+- A suspended app still receives these pushes, yet delivery, priority, budget
+  and throttling still apply. Combine `staleDate` with a reconcile pass when
+  the app returns to the foreground:
 
 ```swift
-@MainActor
-func handleAppBecameActive() {
-    // Reconcile local state with live activities on foregrounding
-    let activities = Activity<DeliveryAttributes>.activities
-    for activity in activities {
-        switch activity.activityState {
-        case .active:
-            // Refresh from server in case pushes were missed
-            Task {
-                let serverState = try await ServerAPI.shared.fetchDeliveryState(
-                    orderNumber: activity.attributes.orderNumber
-                )
-                let content = ActivityContent(
-                    state: serverState,
-                    staleDate: Date().addingTimeInterval(120),
-                    relevanceScore: 80
-                )
-                await activity.update(content)
-            }
-        case .stale:
-            // Content is outdated -- update immediately
-            Task {
-                let serverState = try await ServerAPI.shared.fetchDeliveryState(
-                    orderNumber: activity.attributes.orderNumber
-                )
-                let content = ActivityContent(
-                    state: serverState,
-                    staleDate: Date().addingTimeInterval(120),
-                    relevanceScore: 80
-                )
-                await activity.update(content)
-            }
-        case .ended, .dismissed:
-            // Clean up local tracking
-            break
-        default:
-            break
+func reconcileOnForeground() async {
+    for running in Activity<ServiceVisitAttributes>.activities {
+        switch running.activityState {
+        case .active: await refreshFromServer(running)   // a push may have been missed
+        case .stale: await refreshFromServer(running)    // update right away
+        case .ended, .dismissed: cleanUp(running.id)
+        default: break
         }
     }
 }
 ```
 
-For truly background-driven updates, rely on push-to-update rather than
-Background App Refresh. Push updates can arrive while the app is suspended, but
-APNs delivery, priority, budget, and throttling still apply; use `staleDate` and
-foreground reconciliation for missed updates.
-
-## Testing in Simulator and on Device
-
-### Simulator
+## Testing
 
-The Simulator supports Live Activity rendering on the Lock Screen and displays
-the Dynamic Island on simulator models that include Dynamic Island. Use Xcode
-previews for rapid iteration:
+The simulator shows Live Activities on its Lock Screen and, on models that
+have one, in the Dynamic Island. Xcode previews cover each presentation:
 
 ```swift
-#Preview("Lock Screen", as: .content, using: RideAttributes.preview) {
-    RideActivityWidget()
-} contentStates: {
-    RideAttributes.ContentState(
-        driverName: "Alex",
-        driverPhoto: "car.fill",
-        vehicleDescription: "White Toyota Camry",
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
-        status: .driverEnRoute,
-        distanceRemaining: 1.5
-    )
-    RideAttributes.ContentState(
-        driverName: "Alex",
-        driverPhoto: "car.fill",
-        vehicleDescription: "White Toyota Camry",
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().addingTimeInterval(60).timeIntervalSince1970),
-        status: .arriving,
-        distanceRemaining: 0.1
-    )
+extension ServiceVisitAttributes {
+    static var preview: ServiceVisitAttributes {
+        ServiceVisitAttributes(customerFirstName: "Alex", serviceAddress: "12 Elm Row", jobSummary: "Boiler check")
+    }
 }
 
-#Preview("Dynamic Island Compact", as: .dynamicIsland(.compact), using: RideAttributes.preview) {
-    RideActivityWidget()
-} contentStates: {
-    RideAttributes.ContentState(
-        driverName: "Alex",
-        driverPhoto: "car.fill",
-        vehicleDescription: "White Toyota Camry",
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
-        status: .driverEnRoute,
-        distanceRemaining: 1.5
-    )
+extension ServiceVisitAttributes.ContentState {
+    static let enRoute = Self(technicianName: "Sam", avatarSymbol: "person.crop.circle",
+        vanDescription: "White van", arrivalStartEpoch: 1790000300, arrivalEndEpoch: 1790000900,
+        status: .enRoute, kilometresAway: 9)
+    static let onSite = Self(technicianName: "Sam", avatarSymbol: "person.crop.circle",
+        vanDescription: "White van", arrivalStartEpoch: 1790000300, arrivalEndEpoch: 1790000300,
+        status: .onSite, kilometresAway: 0)
 }
 
-#Preview("Dynamic Island Expanded", as: .dynamicIsland(.expanded), using: RideAttributes.preview) {
-    RideActivityWidget()
+#Preview("Visit card", as: .content, using: ServiceVisitAttributes.preview) {
+    ServiceVisitLiveActivity()
 } contentStates: {
-    RideAttributes.ContentState(
-        driverName: "Alex",
-        driverPhoto: "car.fill",
-        vehicleDescription: "White Toyota Camry",
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
-        status: .driverEnRoute,
-        distanceRemaining: 1.5
-    )
+    ServiceVisitAttributes.ContentState.enRoute
+    ServiceVisitAttributes.ContentState.onSite
 }
 
-#Preview("Dynamic Island Minimal", as: .dynamicIsland(.minimal), using: RideAttributes.preview) {
-    RideActivityWidget()
+#Preview("Expanded", as: .dynamicIsland(.expanded), using: ServiceVisitAttributes.preview) {
+    ServiceVisitLiveActivity()
 } contentStates: {
-    RideAttributes.ContentState(
-        driverName: "Alex",
-        driverPhoto: "car.fill",
-        vehicleDescription: "White Toyota Camry",
-        etaStartSeconds: Int(Date().timeIntervalSince1970),
-        etaEndSeconds: Int(Date().addingTimeInterval(300).timeIntervalSince1970),
-        status: .driverEnRoute,
-        distanceRemaining: 1.5
-    )
-}
-```
-
-### Preview Data Helper
-
-```swift
-extension RideAttributes {
-    static var preview: RideAttributes {
-        RideAttributes(
-            riderName: "Jordan",
-            pickupLocation: "123 Main St",
-            dropoffLocation: "456 Oak Ave"
-        )
-    }
+    ServiceVisitAttributes.ContentState.enRoute
 }
 ```
 
-### On Device
+Use `.dynamicIsland(.compact)` and `.dynamicIsland(.minimal)` the same way.
+Listing several states in `contentStates:` lets the preview step through the
+transitions between them.
 
-Test push-to-update by sending payloads through APNs using a tool like `curl`
-or a push notification testing app. The Simulator does not support APNs, so
-push-to-update must be tested on a physical device.
+The simulator has no APNs, so push-to-update is tested on a physical device.
+Send a test push with a push testing tool or with curl. Development builds use
+the sandbox host `api.sandbox.push.apple.com`; production builds use
+`api.push.apple.com`:
 
 ```bash
-# Example curl command for APNs push update (HTTP/2)
-curl -v \
-  --http2 \
-  --header "apns-push-type: liveactivity" \
-  --header "apns-topic: com.example.app.push-type.liveactivity" \
-  --header "apns-priority: 10" \
-  --header "authorization: bearer $JWT_TOKEN" \
-  --data '{"aps":{"timestamp":1700000000,"event":"update","content-state":{"driverName":"Alex","driverPhoto":"car.fill","vehicleDescription":"White Toyota Camry","etaStartSeconds":1700000000,"etaEndSeconds":1700000300,"status":"driverArrived","distanceRemaining":0.0},"alert":{"title":"Driver Arrived","body":"Your driver is here!"}}}' \
-  https://api.push.apple.com/3/device/$DEVICE_PUSH_TOKEN
+curl --http2 \
+  -H "apns-push-type: liveactivity" \
+  -H "apns-topic: com.example.fieldservice.push-type.liveactivity" \
+  -H "apns-priority: 10" \
+  -H "authorization: bearer $JWT_TOKEN" \
+  -d @update.json \
+  "https://api.sandbox.push.apple.com/3/device/$ACTIVITY_PUSH_TOKEN"
 ```
 
-### Debugging Tips
+### Debugging
 
-- Check Console.app for `ActivityKit` log messages when activities fail to start.
-- Verify `content-state` JSON keys match the default `ContentState` `Codable`
-  shape or coordinated `CodingKeys`. Mismatches can prevent ActivityKit from
-  applying updates.
-- Use `Activity<T>.activities` to inspect all running activities in the debugger.
-- Set a breakpoint in `pushTokenUpdates` to verify tokens are being delivered.
-- If activities do not appear, confirm `NSSupportsLiveActivities = YES` is in
-  the host app's Info.plist (not the widget extension's).
+- A start that fails usually explains itself in Console.app under the
+  `ActivityKit` subsystem.
+- Compare the `content-state` keys with the synthesized `Codable` shape, or
+  with the agreed `CodingKeys`.
+- In the debugger, `Activity<T>.activities` lists what is running.
+- A breakpoint inside the `pushTokenUpdates` loop shows whether tokens arrive.
+- If nothing ever appears, confirm that the main app target (not just the
+  extension) declares `NSSupportsLiveActivities = YES`.
 
-## Info.plist Keys Reference
+## Info.plist keys
 
-| Key | Value | Purpose |
+| Key | Value | Effect |
 |---|---|---|
-| `NSSupportsLiveActivities` | `YES` | Enable Live Activities (required) |
-| `NSSupportsLiveActivitiesFrequentUpdates` | `YES` | Increase the system-managed push update budget |
-
-Both keys belong in the host app's Info.plist, not the widget extension.
-
-## Apple Documentation Links
-
-- [ActivityKit](https://sosumi.ai/documentation/activitykit)
-- [ActivityAttributes](https://sosumi.ai/documentation/activitykit/activityattributes)
-- [Activity](https://sosumi.ai/documentation/activitykit/activity)
-- [ActivityContent](https://sosumi.ai/documentation/activitykit/activitycontent)
-- [ActivityAuthorizationInfo](https://sosumi.ai/documentation/activitykit/activityauthorizationinfo)
-- [DynamicIsland](https://sosumi.ai/documentation/widgetkit/dynamicisland)
-- [ActivityConfiguration](https://sosumi.ai/documentation/widgetkit/activityconfiguration)
-- [Starting and updating with push notifications](https://sosumi.ai/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications)
-- [Sending broadcast push notifications](https://sosumi.ai/documentation/usernotifications/sending-broadcast-push-notification-requests-to-apns)
+| `NSSupportsLiveActivities` | `YES` | Required for the app to start Live Activities |
+| `NSSupportsLiveActivitiesFrequentUpdates` | `YES` | Raises the system-managed push budget |
+
+Both keys are read from the main app target; adding them to the extension has
+no effect.
+
+## Apple documentation
+
+- [ActivityKit](https://developer.apple.com/documentation/activitykit)
+- [ActivityAttributes](https://developer.apple.com/documentation/activitykit/activityattributes)
+- [Activity](https://developer.apple.com/documentation/activitykit/activity)
+- [ActivityContent](https://developer.apple.com/documentation/activitykit/activitycontent)
+- [ActivityAuthorizationInfo](https://developer.apple.com/documentation/activitykit/activityauthorizationinfo)
+- [DynamicIsland](https://developer.apple.com/documentation/widgetkit/dynamicisland)
+- [ActivityConfiguration](https://developer.apple.com/documentation/widgetkit/activityconfiguration)
+- [Live Activity push notifications guide](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications)
+- [Broadcast push requests to APNs](https://developer.apple.com/documentation/usernotifications/sending-broadcast-push-notification-requests-to-apns)