Widgets and Live Activities: A Number on the Home Screen, a Turn on the Lock Screen

import SwiftUI
import WidgetKit

/// What the widget may show: a count, a state, a time. Never a note's text or a place:
/// the Home Screen is the most screenshotable surface there is.
struct CaptureSummary: Codable, Sendable {
    var waiting: Int
    var lastCapturedAt: Date?

    static func read(from container: URL?) -> CaptureSummary {
        guard let url = container?.appending(path: "summary.json"),
              let data = try? Data(contentsOf: url),
              let summary = try? JSONDecoder().decode(CaptureSummary.self, from: data)
        else { return CaptureSummary(waiting: 0, lastCapturedAt: nil) }
        return summary
    }
}

struct WaitingEntry: TimelineEntry {
    let date: Date
    let summary: CaptureSummary
}

struct WaitingProvider: TimelineProvider {
    private var container: URL? {
        FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.spark")
    }
    func placeholder(in context: Context) -> WaitingEntry {
        WaitingEntry(date: .now, summary: CaptureSummary(waiting: 3, lastCapturedAt: nil))
    }
    func getSnapshot(in context: Context, completion: @escaping (WaitingEntry) -> Void) {
        completion(WaitingEntry(date: .now, summary: .read(from: container)))
    }
    /// One entry and no schedule: the number changes when the APP changes it, and the app says so.
    func getTimeline(in context: Context, completion: @escaping (Timeline<WaitingEntry>) -> Void) {
        completion(Timeline(entries: [WaitingEntry(date: .now, summary: .read(from: container))], policy: .never))
    }
}

struct WaitingWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "com.example.spark.widget.waiting", provider: WaitingProvider()) { entry in
            VStack(alignment: .leading) {
                Text("\(entry.summary.waiting)").font(.largeTitle.weight(.semibold))
                Text("waiting to sync").font(.caption).foregroundStyle(.secondary)
            }
            .containerBackground(.fill.tertiary, for: .widget)
        }
        .configurationDisplayName("Waiting to Sync")
        .supportedFamilies([.systemSmall, .accessoryRectangular])
    }
}

// In the app, after the outbox changes:
@MainActor
func summaryDidChange() {
    WidgetCenter.shared.reloadTimelines(ofKind: "com.example.spark.widget.waiting")
}

import ActivityKit
import Foundation

struct TurnAttributes: ActivityAttributes {
    struct ContentState: Codable, Hashable, Sendable {
        var phase: String        // "sending", "thinking", "answered"
    }
    var conversationID: String   // for the widgetURL deep link back to this conversation
}

@MainActor
final class TurnActivities {
    /// Local start needs the app in the foreground. Asking for a push token lets the relay end it later.
    func start(conversationID: String) throws -> Activity<TurnAttributes> {
        try Activity.request(
            attributes: TurnAttributes(conversationID: conversationID),
            content: .init(state: .init(phase: "sending"), staleDate: nil),
            pushType: .token)
    }

    /// iOS 17.2+: a push-to-start token lets the relay START an activity when the app cannot,
    /// for example after a message handled in the background. Hand it up; merge, never replace.
    @available(iOS 17.2, *)
    func observePushToStartTokens(send: @escaping @Sendable (String) async -> Void) -> Task<Void, Never> {
        Task {
            for await token in Activity<TurnAttributes>.pushToStartTokenUpdates {
                await send(token.map { String(format: "%02x", $0) }.joined())
            }
        }
    }
}