@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/widgetkit/references/widgetkit-advanced.md

@@ -1,415 +1,304 @@
-# WidgetKit Advanced Reference
+# WidgetKit: extended patterns
+
+Companion to the `widgetkit` skill. Everything here assumes iOS 26 SDKs unless a
+heading says otherwise.
 
 ## Contents
 
 - [Timeline Strategies](#timeline-strategies)
-- [Push-Based Timeline Reloads (iOS 26+)](#push-based-timeline-reloads-ios-26)
-- [Widget URL Handling and Deep Links](#widget-url-handling-and-deep-links)
-- [Intent-Driven Widget Configuration](#intent-driven-widget-configuration)
-- [Multiple Widget Support in WidgetBundle](#multiple-widget-support-in-widgetbundle)
-- [Widget Previews and Snapshots](#widget-previews-and-snapshots)
+- [Reloading timelines by push (iOS 26 and later)](#reloading-timelines-by-push-ios-26-and-later)
+- [Deep Links and Widget URLs](#deep-links-and-widget-urls)
+- [User-configurable widgets through App Intents](#user-configurable-widgets-through-app-intents)
+- [Multiple Widget Support](#multiple-widget-support)
+- [Previewing widgets and their snapshot state](#previewing-widgets-and-their-snapshot-state)
 - [AccessoryWidgetBackground](#accessorywidgetbackground)
 - [Lock Screen Accessory Widget Example](#lock-screen-accessory-widget-example)
 - [Live Activity Full ActivityConfiguration Example](#live-activity-full-activityconfiguration-example)
 - [Control Center Control Examples](#control-center-control-examples)
-- [Dynamic Island Expanded Layout Patterns](#dynamic-island-expanded-layout-patterns)
-- [Alert Configuration for Live Activities](#alert-configuration-for-live-activities)
-- [Push Notification Support for Live Activities](#push-notification-support-for-live-activities)
+- [Laying out the expanded Dynamic Island](#laying-out-the-expanded-dynamic-island)
+- [Live Activity alerts](#live-activity-alerts)
+- [Live Activity Push Updates](#live-activity-push-updates)
 - [ActivityAuthorizationInfo](#activityauthorizationinfo)
-- [Widget Performance Best Practices](#widget-performance-best-practices)
+- [Keeping widgets fast](#keeping-widgets-fast)
 - [Xcode Setup](#xcode-setup)
-- [Widget Relevance and Smart Stacks](#widget-relevance-and-smart-stacks)
+- [Smart Stack relevance](#smart-stack-relevance)
 - [ActivityState Lifecycle](#activitystate-lifecycle)
 - [ActivityStyle](#activitystyle)
 - [Dismissal Policies](#dismissal-policies)
-- [Querying Active Widgets and Activities](#querying-active-widgets-and-activities)
+- [Finding which widgets and activities are live](#finding-which-widgets-and-activities-are-live)
 - [Design Patterns](#design-patterns)
-- [Apple Documentation Links](#apple-documentation-links)
+- [Further reading from Apple](#further-reading-from-apple)
 
 ## Timeline Strategies
 
-### TimelineReloadPolicy
-
-Control when WidgetKit requests a new timeline after the current entries expire.
+### Reload policies
 
-| Policy | Behavior | Use When |
+| Policy | What happens | Pick it when |
 |---|---|---|
-| `.atEnd` | Requests a new timeline after the last entry's date. Default. | Data changes unpredictably. |
-| `.after(Date)` | Requests a new timeline after a specific date. | Data updates on a known schedule (market hours, delivery slots). |
-| `.never` | No automatic refresh. App must trigger manually. | Data changes only from user action. |
+| `.atEnd` | The system asks for a new timeline once the last entry's date passes. This is the default. | Data changes at unpredictable times |
+| `.after(Date)` | The system asks again after the given date | You know the schedule, such as trading hours or a booked delivery slot |
+| `.never` | No automatic refresh; the app reloads it | Only a user action in the app changes the data |
 
-### Multiple Timeline Entries
+### Plan several entries ahead
 
-Pre-generate entries for known future states to reduce refresh requests and
-conserve the daily budget.
+One timeline can carry many future entries. Projecting values forward means
+fewer reloads.
 
 ```swift
-func timeline(for configuration: Intent, in context: Context) async -> Timeline<StockEntry> {
-    var entries: [StockEntry] = []
-    let now = Date()
-
-    // Generate hourly entries for the next 6 hours
-    for hourOffset in 0..<6 {
-        let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: now)!
-        let price = await StockService.shared.projectedPrice(at: entryDate, for: configuration.symbol)
-        entries.append(StockEntry(date: entryDate, symbol: configuration.symbol.name, price: price))
+func getTimeline(in context: Context, completion: @escaping @Sendable (Timeline<ParkingEntry>) -> Void) {
+    let base = ParkingForecast.current()
+    let calendar = Calendar.current
+    let entries = (0..<6).compactMap { offset -> ParkingEntry? in
+        guard let slot = calendar.date(byAdding: .hour, value: offset, to: .now) else { return nil }
+        return ParkingEntry(date: slot, freeSpaces: base.projectedSpaces(at: slot))
     }
-
-    let nextRefresh = Calendar.current.date(byAdding: .hour, value: 6, to: now)!
-    return Timeline(entries: entries, policy: .after(nextRefresh))
+    let refresh = calendar.date(byAdding: .minute, value: 360, to: .now) ?? .now
+    completion(Timeline(entries: entries, policy: .after(refresh)))
 }
 ```
 
-### Triggering Manual Reloads
+### Reloading from the app
 
 ```swift
-// Reload a specific widget kind
-WidgetCenter.shared.reloadTimelines(ofKind: "OrderStatusWidget")
-
-// Reload all widgets
+WidgetCenter.shared.reloadTimelines(ofKind: "ParkingWidget")
 WidgetCenter.shared.reloadAllTimelines()
 ```
 
-Call `reloadTimelines(ofKind:)` only when displayed data actually changes. Each
-call counts against the daily refresh budget.
-
-### Refresh Budget
-
-Each configured widget has a daily refresh limit. Exemptions apply for:
-- Foreground app usage
-- Active media sessions
-- Standard location service usage
+The first call reloads one widget kind; the second reloads all of them. Both
+cost budget.
 
-WidgetKit does not impose refresh limits when debugging in Xcode.
+### Budget rules
 
-## Push-Based Timeline Reloads (iOS 26+)
+- Every configured widget gets its own daily allowance.
+- Reloads are free when the app is frontmost, when it has an active media
+  session, or when it uses the standard location service.
+- A widget run from Xcode's debugger has no refresh limit, so budget problems
+  only show up outside the debugger.
 
-### WidgetPushHandler
+## Reloading timelines by push (iOS 26 and later)
 
-Use push notifications to trigger timeline reloads without scheduled polling.
+A `WidgetPushHandler` receives a token for APNs. Send it to your server.
 
 ```swift
-struct MyWidgetPushHandler: WidgetPushHandler {
+struct ScoreboardPushHandler: WidgetPushHandler {
     func pushTokenDidChange(_ pushInfo: WidgetPushInfo, widgets: [WidgetInfo]) {
-        let tokenString = pushInfo.token.map { String(format: "%02x", $0) }.joined()
-        Task {
-            try await ServerAPI.shared.register(widgetPushToken: tokenString)
-        }
+        let hex = hexString(pushInfo.token)
+        Task { await ScoreboardAPI.shared.registerWidgetToken(hex) }
     }
 }
 ```
 
-### Server-Side Integration
-
-Send an APNs push with the widget's push token. The system calls your
-`TimelineProvider.getTimeline` or `AppIntentTimelineProvider.timeline(for:in:)`
-when the push arrives.
-
-### ControlPushHandler
-
-Equivalent handler for Control Center controls:
+`hexString(_:)` is a small helper used throughout this file:
 
 ```swift
-struct MyControlPushHandler: ControlPushHandler {
-    func pushTokensDidChange(controls: [ControlPushInfo]) {
-        for control in controls {
-            let tokenString = control.token.map { String(format: "%02x", $0) }.joined()
-            Task {
-                try await ServerAPI.shared.register(controlPushToken: tokenString)
-            }
-        }
-    }
+func hexString(_ bytes: Data) -> String {
+    bytes.reduce(into: "") { $0 += String(format: "%02x", $1) }
 }
 ```
 
-## Widget URL Handling and Deep Links
-
-### widgetURL(_:)
+When the server sends an APNs push addressed to that token, the system calls
+`getTimeline` or `timeline(for:in:)` again.
 
-Set a single URL for the entire widget. Tapping anywhere opens the app with this URL.
+Controls have their own handler that receives every control at once, as
+`ControlInfo` values; each carries its token in an optional `pushInfo`:
 
 ```swift
-struct SmallWidgetView: View {
-    let entry: OrderEntry
-
-    var body: some View {
-        VStack {
-            Text(entry.orderName)
-            Text(entry.status)
+struct GaragePushHandler: ControlPushHandler {
+    func pushTokensDidChange(controls: [ControlInfo]) {
+        for control in controls {
+            guard let token = control.pushInfo?.token else { continue }
+            let hex = hexString(token)
+            Task { await GarageAPI.shared.registerControlToken(hex) }
         }
-        .widgetURL(URL(string: "myapp://orders/\(entry.orderID)")!)
     }
 }
 ```
 
-### Link (Medium and Larger Widgets)
+## Deep Links and Widget URLs
 
-Use `Link` for multiple tap targets in `.systemMedium` and larger widgets.
+- `.widgetURL(_:)` gives the whole widget one destination.
+- `Link(destination:)` adds separate tap targets, but only in `.systemMedium` and
+  larger. A `.systemSmall` widget supports `widgetURL` only.
 
 ```swift
-struct MediumWidgetView: View {
-    let entry: OrderListEntry
-
-    var body: some View {
-        VStack {
-            ForEach(entry.orders) { order in
-                Link(destination: URL(string: "myapp://orders/\(order.id)")!) {
-                    HStack {
-                        Text(order.name)
-                        Spacer()
-                        Text(order.status)
-                    }
-                }
-            }
-        }
-    }
+VStack {
+    Link(destination: URL(string: "harbor://berth/7")!) { BerthRow(number: 7) }
+    Link(destination: URL(string: "harbor://berth/9")!) { BerthRow(number: 9) }
 }
+.widgetURL(URL(string: "harbor://berths"))
 ```
 
-### Handling in the App
+The app picks the URL up on its scene content:
 
 ```swift
-@main
-struct MyApp: App {
-    var body: some Scene {
-        WindowGroup {
-            ContentView()
-                .onOpenURL { url in
-                    DeepLinkRouter.shared.handle(url)
-                }
-        }
-    }
+WindowGroup {
+    HarborRootView()
+        .onOpenURL { url in router.open(url) }
 }
 ```
 
-**Important:** `.systemSmall` widgets support only `widgetURL`, not `Link`.
-
-## Intent-Driven Widget Configuration
-
-### Defining a WidgetConfigurationIntent
+## User-configurable widgets through App Intents
 
 ```swift
-struct SelectCategoryIntent: WidgetConfigurationIntent {
-    static var title: LocalizedStringResource = "Select Category"
-    static var description: IntentDescription = "Choose a category to display."
+struct PickStationIntent: WidgetConfigurationIntent {
+    static let title: LocalizedStringResource = "Choose Station"
+    static let description = IntentDescription("Pick the weather station to show.")
 
-    @Parameter(title: "Category")
-    var category: CategoryEntity
+    @Parameter(title: "Station")
+    var station: StationEntity
 
     init() {}
-
-    init(category: CategoryEntity) {
-        self.category = category
-    }
+    init(station: StationEntity) { self.station = station }
 }
-```
 
-### Entity Query for Dynamic Options
+struct StationEntity: AppEntity {
+    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Station"
+    static let defaultQuery = StationQuery()
 
-```swift
-struct CategoryEntity: AppEntity {
-    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Category")
-    static var defaultQuery = CategoryQuery()
-
-    var id: String
-    var name: String
+    let id: String
+    let name: String
 
     var displayRepresentation: DisplayRepresentation {
-        DisplayRepresentation(title: "\(name)")
+        DisplayRepresentation(title: LocalizedStringResource(stringLiteral: name))
     }
 }
 
-struct CategoryQuery: EntityQuery {
-    func entities(for identifiers: [String]) async throws -> [CategoryEntity] {
-        await DataStore.shared.categories(for: identifiers)
+struct StationQuery: EntityQuery {
+    func entities(for identifiers: [String]) async throws -> [StationEntity] {
+        await StationCatalog.shared.stations(matching: identifiers)
     }
 
-    func suggestedEntities() async throws -> [CategoryEntity] {
-        await DataStore.shared.allCategories()
+    func suggestedEntities() async throws -> [StationEntity] {
+        await StationCatalog.shared.nearby()
     }
 
-    func defaultResult() async -> CategoryEntity? {
-        await DataStore.shared.defaultCategory()
+    func defaultResult() async -> StationEntity? {
+        await StationCatalog.shared.nearby().first
     }
 }
 ```
 
-### Recommendations
-
-Provide pre-configured suggestions for the widget gallery:
+Preconfigured gallery options come from the provider:
 
 ```swift
-func recommendations() -> [AppIntentRecommendation<SelectCategoryIntent>] {
-    let categories: [(String, CategoryEntity)] = [
-        ("Groceries", .groceries),
-        ("Work Tasks", .work),
-    ]
-    return categories.map { name, entity in
-        let intent = SelectCategoryIntent(category: entity)
-        return AppIntentRecommendation(intent: intent, description: name)
+func recommendations() -> [AppIntentRecommendation<PickStationIntent>] {
+    StationCatalog.featured.map { station in
+        AppIntentRecommendation(intent: PickStationIntent(station: station), description: station.name)
     }
 }
 ```
 
-## Multiple Widget Support in WidgetBundle
+For intent and entity design beyond this, see the `app-intents` skill.
 
-### Declaring Multiple Widgets
+## Multiple Widget Support
 
-```swift
-@main
-struct MyAppWidgets: WidgetBundle {
-    var body: some Widget {
-        OrderStatusWidget()          // Home Screen widget
-        FavoritesWidget()            // Configurable widget
-        StepsAccessoryWidget()       // Lock Screen widget
-        DeliveryActivityWidget()     // Live Activity
-        QuickActionControl()         // Control Center
-    }
-}
-```
-
-### Conditional Widgets
-
-Include widgets conditionally based on platform or availability:
+A bundle can mix every kind of widget, and it can gate newer ones by OS:
 
 ```swift
 @main
-struct MyAppWidgets: WidgetBundle {
+struct GardenWidgets: WidgetBundle {
     var body: some Widget {
-        CoreWidget()
+        SoilMoistureWidget()
+        PickBedWidget()
+        SoilLockScreenWidget()
+        WateringActivityWidget()
         if #available(iOS 18, *) {
-            QuickActionControl()
+            SprinklerControl()
         }
     }
 }
 ```
 
-## Widget Previews and Snapshots
-
-### Xcode Previews
+## Previewing widgets and their snapshot state
 
 ```swift
-#Preview("Small", as: .systemSmall) {
-    OrderStatusWidget()
+#Preview("Moisture", as: .systemSmall) {
+    SoilMoistureWidget()
 } timeline: {
-    OrderEntry(date: .now, orderName: "Pizza", status: "Preparing")
-    OrderEntry(date: .now.addingTimeInterval(600), orderName: "Pizza", status: "Delivering")
+    SoilEntry(date: .now, percent: 62)
+    SoilEntry(date: .now.addingTimeInterval(3600), percent: 48)
 }
 
-#Preview("Circular", as: .accessoryCircular) {
-    StepsAccessoryWidget()
+#Preview("Lock Screen", as: .accessoryCircular) {
+    SoilLockScreenWidget()
 } timeline: {
-    StepsEntry(date: .now, stepCount: 4200)
+    SoilEntry(date: .now, percent: 62)
 }
 ```
 
-### Live Activity Previews
+Live Activities preview against attributes plus a list of states:
 
 ```swift
-#Preview("Lock Screen", as: .content, using: DeliveryAttributes.preview) {
-    DeliveryActivityWidget()
+#Preview("Watering", as: .content, using: WateringAttributes.preview) {
+    WateringActivityWidget()
 } contentStates: {
-    DeliveryAttributes.ContentState(
-        driverName: "Alex",
-        estimatedDeliveryTime: Date()...Date().addingTimeInterval(900),
-        currentStep: .delivering
-    )
+    WateringAttributes.ContentState(zone: 1, remaining: 300)
+    WateringAttributes.ContentState(zone: 2, remaining: 60)
 }
 
-#Preview("Dynamic Island Compact", as: .dynamicIsland(.compact), using: DeliveryAttributes.preview) {
-    DeliveryActivityWidget()
+#Preview("Compact", as: .dynamicIsland(.compact), using: WateringAttributes.preview) {
+    WateringActivityWidget()
 } contentStates: {
-    DeliveryAttributes.ContentState(
-        driverName: "Alex",
-        estimatedDeliveryTime: Date()...Date().addingTimeInterval(900),
-        currentStep: .delivering
-    )
+    WateringAttributes.ContentState(zone: 1, remaining: 300)
 }
 ```
 
-### Snapshot Best Practices
+`placeholder(in:)` is synchronous, so writing `await` inside it does not
+compile. In the snapshot method, return sample data when `context.isPreview` is
+true and the real current state otherwise.
 
-- Return sample data immediately in `placeholder(in:)` -- it must be synchronous.
-- In `getSnapshot` / `snapshot(for:in:)`, check `context.isPreview`:
-  - When `true`, return representative sample data quickly.
-  - When `false`, return the current real state.
+## AccessoryWidgetBackground
 
 ```swift
-// WRONG: Performing a network call in placeholder
-func placeholder(in context: Context) -> MyEntry {
-    // Compilation error: placeholder must be synchronous
-    let data = await fetchData()
-    return MyEntry(date: .now, data: data)
-}
-
-// CORRECT: Return static sample data
-func placeholder(in context: Context) -> MyEntry {
-    MyEntry(date: .now, data: SampleData.placeholder)
+ZStack {
+    AccessoryWidgetBackground()
+    VStack(spacing: 0) {
+        Image(systemName: "leaf")
+            .widgetAccentable()
+        Text("\(entry.percent)%")
+    }
 }
 ```
 
-## AccessoryWidgetBackground
+`AccessoryWidgetBackground()` draws the standard translucent disc or panel.
+`.widgetAccentable()` marks the views that should pick up the tint in `.accented`
+mode.
 
-Provide the standard translucent background for Lock Screen widgets.
+Branch on the rendering mode when full color and monochrome need different views.
+`WidgetRenderingMode` is a struct with static values, not an enum, so the switch
+ends in a plain `default` (`@unknown default` does not compile here):
 
 ```swift
-struct CircularStepsView: View {
-    let steps: Int
+struct SoilBadge: View {
+    @Environment(\.widgetRenderingMode) private var mode
+    let entry: SoilEntry
 
     var body: some View {
-        ZStack {
-            AccessoryWidgetBackground()
-            VStack(spacing: 2) {
-                Image(systemName: "figure.walk")
-                    .font(.caption)
-                Text("\(steps)")
-                    .font(.headline)
-                    .widgetAccentable()
-            }
+        switch mode {
+        case .fullColor:
+            ColorfulSoilBadge(entry: entry)
+        case .vibrant, .accented:
+            MonochromeSoilBadge(entry: entry)
+        default:
+            MonochromeSoilBadge(entry: entry)
         }
     }
 }
 ```
 
-### Rendering Mode Awareness
-
-Lock Screen widgets render in `.vibrant` or `.accented` mode. Adapt content:
-
-```swift
-@Environment(\.widgetRenderingMode) var renderingMode
-
-var body: some View {
-    switch renderingMode {
-    case .fullColor:
-        ColorfulView()
-    case .vibrant, .accented:
-        MonochromeView()
-    @unknown default:
-        MonochromeView()
-    }
-}
-```
-
-Use `.widgetAccentable()` to mark views that should receive the accent tint in
-`.accented` rendering mode.
-
 ## Lock Screen Accessory Widget Example
 
-A full Lock Screen widget using accessory families and `AccessoryWidgetBackground`.
-
 ```swift
-struct StepsWidget: Widget {
-    let kind = "StepsWidget"
+struct SoilLockScreenWidget: Widget {
     var body: some WidgetConfiguration {
-        StaticConfiguration(kind: kind, provider: StepsProvider()) { entry in
+        StaticConfiguration(kind: "SoilLockScreen", provider: SoilProvider()) { entry in
             ZStack {
                 AccessoryWidgetBackground()
-                VStack {
-                    Image(systemName: "figure.walk")
-                    Text("\(entry.stepCount)").font(.headline)
-                }
+                SoilBadge(entry: entry)
             }
         }
+        .configurationDisplayName("Soil")
+        .description("Moisture of your main bed.")
         .supportedFamilies([.accessoryCircular, .accessoryRectangular, .accessoryInline])
     }
 }
@@ -417,661 +306,467 @@ struct StepsWidget: Widget {
 
 ## Live Activity Full ActivityConfiguration Example
 
-A complete `ActivityConfiguration` with Lock Screen content and the Dynamic
-Island closures (expanded regions, compact, minimal).
-
 ```swift
-struct DeliveryActivityWidget: Widget {
+struct RepairActivityWidget: Widget {
     var body: some WidgetConfiguration {
-        ActivityConfiguration(for: DeliveryAttributes.self) { context in
+        ActivityConfiguration(for: RepairAttributes.self) { context in
             VStack(alignment: .leading) {
-                Text(context.attributes.restaurantName).font(.headline)
-                HStack {
-                    Text("Driver: \(context.state.driverName)")
-                    Spacer()
-                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
-                }
+                Text("Ticket \(context.attributes.ticketNumber)")
+                    .font(.headline)
+                Text(context.state.stage.title)
+                Text(timerInterval: context.state.window, countsDown: true)
+                    .font(.title2.monospacedDigit())
             }
             .padding()
         } dynamicIsland: { context in
             DynamicIsland {
                 DynamicIslandExpandedRegion(.leading) {
-                    Image(systemName: "box.truck.fill").font(.title2)
+                    Image(systemName: "wrench.and.screwdriver")
                 }
                 DynamicIslandExpandedRegion(.trailing) {
-                    Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
-                        .font(.caption)
+                    Text(timerInterval: context.state.window, countsDown: true)
+                        .monospacedDigit()
                 }
                 DynamicIslandExpandedRegion(.center) {
-                    Text(context.attributes.restaurantName).font(.headline)
+                    Text(context.state.stage.title)
+                        .lineLimit(1)
                 }
                 DynamicIslandExpandedRegion(.bottom) {
                     HStack {
-                        ForEach(DeliveryStep.allCases, id: \.self) { step in
-                            Image(systemName: step.icon)
-                                .foregroundStyle(step <= context.state.currentStep ? .primary : .tertiary)
+                        ForEach(RepairStage.allCases, id: \.self) { stage in
+                            Capsule()
+                                .fill(stage <= context.state.stage ? .primary : .tertiary)
+                                .frame(height: 4)
                         }
                     }
                 }
             } compactLeading: {
-                Image(systemName: "box.truck.fill")
+                Image(systemName: "wrench.and.screwdriver")
             } compactTrailing: {
-                Text(timerInterval: context.state.estimatedDeliveryTime, countsDown: true)
-                    .frame(width: 40).monospacedDigit()
+                Text(timerInterval: context.state.window, countsDown: true)
+                    .monospacedDigit()
+                    .frame(width: 44)
             } minimal: {
-                Image(systemName: "box.truck.fill")
+                Image(systemName: "wrench")
             }
         }
     }
 }
 ```
 
+The compact trailing timer gets a fixed width and monospaced digits so it does
+not jitter as it counts. `RepairStage` is assumed `Comparable` and `CaseIterable`.
+
 ## Control Center Control Examples
 
-Button and toggle controls for Control Center (iOS 18+). A toggle can read its
-current state from a value provider.
+A toggle reads current state from a value provider and flips it through an intent:
 
 ```swift
-// Button control
-struct OpenCameraControl: ControlWidget {
+struct SprinklerControl: ControlWidget {
     var body: some ControlWidgetConfiguration {
-        StaticControlConfiguration(kind: "OpenCamera") {
-            ControlWidgetButton(action: OpenCameraIntent()) {
-                Label("Camera", systemImage: "camera.fill")
+        StaticControlConfiguration(kind: "SprinklerControl", provider: SprinklerStateProvider()) { isRunning in
+            ControlWidgetToggle(isOn: isRunning, action: ToggleSprinklerIntent()) {
+                Label("Sprinkler", systemImage: isRunning ? "sprinkler.and.droplets.fill" : "sprinkler")
             }
         }
-        .displayName("Open Camera")
+        .displayName("Sprinkler")
     }
 }
 
-// Toggle control with value provider
-struct FlashlightControl: ControlWidget {
-    var body: some ControlWidgetConfiguration {
-        StaticControlConfiguration(kind: "Flashlight", provider: FlashlightValueProvider()) { value in
-            ControlWidgetToggle(isOn: value, action: ToggleFlashlightIntent()) {
-                Label("Flashlight", systemImage: value ? "flashlight.on.fill" : "flashlight.off.fill")
-            }
-        }
-        .displayName("Flashlight")
+struct SprinklerStateProvider: ControlValueProvider {
+    var previewValue: Bool { false }
+
+    func currentValue() async throws -> Bool {
+        await SprinklerHub.shared.isRunning
+    }
+}
+
+struct ToggleSprinklerIntent: SetValueIntent {
+    static let title: LocalizedStringResource = "Toggle Sprinkler"
+
+    @Parameter(title: "Running")
+    var value: Bool
+
+    func perform() async throws -> some IntentResult {
+        await SprinklerHub.shared.setRunning(value)
+        return .result()
     }
 }
 ```
 
-## Dynamic Island Expanded Layout Patterns
+## Laying out the expanded Dynamic Island
 
-### Full Layout Example
+A ferry crossing shows how the regions split the work:
 
 ```swift
 DynamicIsland {
     DynamicIslandExpandedRegion(.leading) {
         VStack(alignment: .leading) {
-            Image(systemName: "airplane")
-                .font(.title2)
-            Text("UA 1234")
-                .font(.caption2)
+            Text(context.attributes.fromPort).font(.headline)
+            Text(context.state.departure, style: .time).font(.caption)
         }
     }
     DynamicIslandExpandedRegion(.trailing) {
         VStack(alignment: .trailing) {
-            Text("SFO")
-                .font(.title3.bold())
-            Text("On Time")
-                .font(.caption2)
-                .foregroundStyle(.green)
+            Text(context.attributes.toPort).font(.headline)
+            Text(context.state.arrival, style: .time).font(.caption)
         }
     }
     DynamicIslandExpandedRegion(.center) {
-        Text("San Francisco to New York")
-            .font(.caption)
-            .lineLimit(1)
+        Text(context.state.statusLine).lineLimit(1)
     }
     DynamicIslandExpandedRegion(.bottom) {
-        ProgressView(value: 0.45)
-            .tint(.blue)
-        HStack {
-            Text("Departed 2:30 PM")
-            Spacer()
-            Text("Arrives 10:45 PM")
-        }
-        .font(.caption2)
-        .foregroundStyle(.secondary)
+        ProgressView(value: context.state.progress)
     }
 } compactLeading: {
-    Image(systemName: "airplane")
+    Image(systemName: "ferry")
 } compactTrailing: {
-    Text("2h 15m")
-        .monospacedDigit()
+    Text(context.state.arrival, style: .timer).monospacedDigit()
 } minimal: {
-    Image(systemName: "airplane")
+    Image(systemName: "ferry")
 }
-```
-
-### Vertical Placement
-
-Control vertical alignment within expanded regions:
-
-```swift
-DynamicIslandExpandedRegion(.leading) {
-    Text("Top")
-        .dynamicIsland(verticalPlacement: .belowIfTooWide)
-}
-```
-
-### Content Margins
-
-Override margins for specific Dynamic Island modes:
-
-```swift
+.keylineTint(.teal)
 .contentMargins(.trailing, 20, for: .expanded)
 .contentMargins(.bottom, 16, for: .expanded)
 ```
 
-### Keyline Tint
-
-Apply a subtle tint to the Dynamic Island border:
-
-```swift
-DynamicIsland { /* ... */ }
-    .keylineTint(.blue)
-```
+- `.dynamicIsland(verticalPlacement: .belowIfTooWide)` on a view inside an
+  expanded region lets it drop under the camera when it does not fit beside it.
+- `.contentMargins(_:_:for:)` overrides the default margins for one presentation
+  mode.
+- `.keylineTint(_:)` on the `DynamicIsland` colors its outline.
 
-## Alert Configuration for Live Activities
+## Live Activity alerts
 
-Trigger a visible and audible alert when updating a Live Activity:
+An update can alert the user visibly and audibly:
 
 ```swift
 let alert = AlertConfiguration(
-    title: "Delivery Update",
-    body: "Your order is out for delivery!",
+    title: "Ferry boarding",
+    body: "Gate B is open.",
     sound: .default
 )
-await activity.update(updatedContent, alertConfiguration: alert)
+await activity.update(content, alertConfiguration: alert)
 ```
 
-### Custom Alert Sound
+For a custom sound, bundle the file with the app and pass `.named("horn.aiff")`.
 
-```swift
-let alert = AlertConfiguration(
-    title: "Score Update",
-    body: "Goal! The score is now 2-1.",
-    sound: .named("goal-horn.aiff")
-)
-```
-
-Place the sound file in the app bundle. Use `.default` when no custom sound is needed.
-
-## Push Notification Support for Live Activities
+## Live Activity Push Updates
 
-### Registering for Push Updates
+Request with `pushType: .token` and forward each token the activity reports.
+`Activity` is a class that is not `Sendable`, so start this task from main-actor
+code such as a view or an `@MainActor` model; in a nonisolated function Swift 6
+rejects capturing `activity` in the `Task`:
 
 ```swift
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token  // Enable push updates
-)
-
-// Observe token changes
 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)
+    for await data in activity.pushTokenUpdates {
+        let hex = hexString(data)
+        await FerryAPI.shared.register(activityToken: hex, activityID: activity.id)
     }
 }
 ```
 
-### Push-to-Start (Remote Activity Creation)
+Push-to-start tokens come from the activity type:
 
 ```swift
-// Observe the push-to-start token
 Task {
-    for await token in Activity<DeliveryAttributes>.pushToStartTokenUpdates {
-        let tokenString = token.map { String(format: "%02x", $0) }.joined()
-        try await ServerAPI.shared.registerPushToStartToken(tokenString)
+    for await data in Activity<FerryAttributes>.pushToStartTokenUpdates {
+        let hex = hexString(data)
+        await FerryAPI.shared.register(startToken: hex)
     }
 }
 ```
 
-### Channel-Based Push (iOS 26+)
-
-```swift
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .channel("delivery-updates")
-)
-```
+From iOS 26 a broadcast channel works too: `pushType: .channel("ferry-route-12")`.
 
-### APNs Payload Format for Live Activity Updates
+Update payload:
 
 ```json
 {
-    "aps": {
-        "timestamp": 1234567890,
-        "event": "update",
-        "content-state": {
-            "driverName": "Alex",
-            "estimatedDeliveryTime": {
-                "lowerBound": 1234567890,
-                "upperBound": 1234568790
-            },
-            "currentStep": "delivering"
-        },
-        "alert": {
-            "title": "Delivery Update",
-            "body": "Your driver is nearby!"
-        }
-    }
+  "aps": {
+    "timestamp": 1790400000,
+    "event": "update",
+    "content-state": {
+      "statusLine": "Crossing",
+      "progress": 0.4,
+      "window": { "lowerBound": 1790399400, "upperBound": 1790401800 }
+    },
+    "alert": { "title": "Halfway", "body": "Arriving in 20 minutes." }
+  }
 }
 ```
 
-The `content-state` must match the `ContentState` Codable structure exactly.
+`content-state` has to mirror the `ContentState` Codable layout key for key; a
+`ClosedRange` encodes as `lowerBound` and `upperBound`. Info.plist keys on the
+app target:
 
-### Info.plist Keys
+| Key | Effect |
+|---|---|
+| `NSSupportsLiveActivities` = YES | Allows Live Activities at all |
+| `NSSupportsLiveActivitiesFrequentUpdates` = YES | Raises the push update budget for frequent updates |
 
-| Key | Value | Purpose |
-|---|---|---|
-| `NSSupportsLiveActivities` | `YES` | Enable Live Activities |
-| `NSSupportsLiveActivitiesFrequentUpdates` | `YES` | Enable frequent push updates (budget increase) |
+The `live-activities` skill goes deeper on the push contract.
 
 ## ActivityAuthorizationInfo
 
-Check whether Live Activities are permitted before attempting to start one.
-
 ```swift
-let authInfo = ActivityAuthorizationInfo()
-
-// Check permission synchronously
-if authInfo.areActivitiesEnabled {
-    try Activity.request(attributes: attributes, content: content, pushType: .token)
-}
+let info = ActivityAuthorizationInfo()
+guard info.areActivitiesEnabled else { return }
 
-// Observe permission changes
 Task {
-    for await enabled in authInfo.activityEnablementUpdates {
-        if enabled {
-            // Activities became available
-        }
+    for await enabled in info.activityEnablementUpdates {
+        await MainActor.run { settings.liveActivitiesOn = enabled }
     }
 }
 
-// Check frequent push support
-if authInfo.frequentPushesEnabled {
-    // Safe to use frequent push updates
-}
-```
-
-### Error Handling
+let canPushOften = info.frequentPushesEnabled
 
-```swift
 do {
-    let activity = try Activity.request(attributes: attributes, content: content, pushType: .token)
+    _ = try Activity.request(attributes: crossing, content: opening, pushType: .token)
 } catch let error as ActivityAuthorizationError {
     switch error {
-    case .denied:
-        // User disabled Live Activities in Settings
-        break
-    case .globalMaximumExceeded:
-        // Too many Live Activities across all apps
-        break
-    case .targetMaximumExceeded:
-        // Too many Live Activities for this app
-        break
-    default:
-        break
+    case .denied: showSettingsHint()
+    case .globalMaximumExceeded: showTryLater()
+    case .targetMaximumExceeded: endOldestActivity()
+    default: showGenericFailure()
     }
 }
 ```
 
-## Widget Performance Best Practices
+- `.denied`: the user switched Live Activities off in Settings.
+- `.globalMaximumExceeded`: too many activities are running across all apps.
+- `.targetMaximumExceeded`: this app already runs its maximum.
 
-### Data Preparation
+## Keeping widgets fast
 
-Pre-compute display values in the timeline provider. Pass display-ready data
-through the entry.
+- Do the math in the provider. The view should receive values ready to draw, not
+  raw records.
+- Extensions have tight memory caps. Avoid big images in the view, large
+  datasets in entries and deep view trees.
+- Store small, pre-resized thumbnails in the shared container and draw them with
+  `.resizable()` and `.aspectRatio(contentMode: .fill)` rather than loading
+  full-resolution files.
 
-```swift
-// WRONG: Heavy computation in the widget view
-struct MyWidgetView: View {
-    let entry: RawDataEntry
-
-    var body: some View {
-        let processed = HeavyProcessor.process(entry.rawData)  // Slow
-        Text(processed.summary)
-    }
-}
-
-// CORRECT: Pre-compute in the provider
-func timeline(for configuration: Intent, in context: Context) async -> Timeline<ProcessedEntry> {
-    let raw = await DataStore.shared.fetch()
-    let processed = HeavyProcessor.process(raw)
-    let entry = ProcessedEntry(date: .now, summary: processed.summary, value: processed.value)
-    return Timeline(entries: [entry], policy: .atEnd)
-}
-```
-
-### Memory Constraints
-
-Widget extensions run with strict memory limits. Avoid:
-- Loading large images directly in the widget view
-- Storing large data sets in the entry
-- Creating complex view hierarchies
-
-### Image Handling
+Sharing through an App Group:
 
 ```swift
-// WRONG: Loading a full-resolution image
-Image(uiImage: UIImage(contentsOfFile: fullResPath)!)
+// App side
+let suite = UserDefaults(suiteName: "group.org.sample.garden")
+suite?.set(62, forKey: "soilPercent")
+WidgetCenter.shared.reloadTimelines(ofKind: "SoilMoisture")
 
-// CORRECT: Use a pre-resized thumbnail stored in the shared container
-Image(uiImage: UIImage(contentsOfFile: thumbnailPath)!)
-    .resizable()
-    .aspectRatio(contentMode: .fill)
+// Provider side
+let percent = UserDefaults(suiteName: "group.org.sample.garden")?.integer(forKey: "soilPercent") ?? 0
 ```
 
-### Shared Data with App Groups
-
-```swift
-// In the main app: write data
-let defaults = UserDefaults(suiteName: "group.com.example.myapp")
-defaults?.set(encodedData, forKey: "widgetData")
-WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget")
-
-// In the widget provider: read data
-func timeline(for configuration: Intent, in context: Context) async -> Timeline<MyEntry> {
-    let defaults = UserDefaults(suiteName: "group.com.example.myapp")
-    let data = defaults?.data(forKey: "widgetData")
-    // Decode and build entry
-}
-```
-
-For larger datasets, use a shared SQLite database or Core Data store in the
-App Group container.
+For bigger data, keep a SQLite or Core Data store inside the App Group container.
 
 ## Xcode Setup
 
-### Adding a Widget Extension Target
-
-1. File > New > Target > Widget Extension.
-2. Name the extension (e.g., "MyAppWidgets").
-3. Select "Include Configuration App Intent" for configurable widgets.
-4. Select "Include Live Activity" if building Live Activities.
-
-### Entitlements
-
-| Entitlement | Purpose |
+- New target options: tick "Include Configuration App Intent" for a configurable
+  widget and "Include Live Activity" to get a Live Activity scaffold.
+- Entitlements: `com.apple.security.application-groups` to share data between
+  targets, Push Notifications (`aps-environment`) when Live Activities update by push.
+- Add the App Group to both targets with the same identifier, such as
+  `group.org.sample.garden`, then read it through `UserDefaults(suiteName:)` or
+  `FileManager.default.containerURL(forSecurityApplicationGroupIdentifier:)`.
+- Debug by running the widget extension scheme, picking the "Widget" destination,
+  or using the canvas preview.
+
+| Error | Fix |
 |---|---|
-| App Groups (`com.apple.security.application-groups`) | Share data between app and widget |
-| Push Notifications (`aps-environment`) | Required for push-based Live Activity updates |
-
-### App Groups Configuration
-
-1. Enable "App Groups" capability on both the main app target and the widget
-   extension target.
-2. Create a shared group identifier (e.g., `group.com.example.myapp`).
-3. Use `UserDefaults(suiteName:)` or `FileManager.containerURL(forSecurityApplicationGroupIdentifier:)`
-   for shared storage.
-
-### Build Schemes
-
-- Use the widget extension scheme to debug widget rendering.
-- Select "Widget" as the run destination to launch the widget directly.
-- Use "Preview" in Xcode canvas for rapid iteration.
+| "Widget extension must include at least one widget" | Put `@main` on the `WidgetBundle` |
+| "No such module 'WidgetKit'" | Link WidgetKit and SwiftUI in the extension target |
+| `ActivityKit.ActivityAuthorizationError error 3` | The `NSSupportsLiveActivities = YES` key belongs in the main app target's Info.plist; setting it on the extension does nothing |
 
-### Common Xcode Issues
+## Smart Stack relevance
 
-```text
-// ERROR: "Widget extension must include at least one widget"
-// FIX: Ensure @main is on the WidgetBundle, not a widget struct.
-
-// ERROR: "No such module 'WidgetKit'"
-// FIX: Ensure the widget extension target links WidgetKit and SwiftUI frameworks.
-
-// ERROR: "The operation couldn't be completed. (ActivityKit.ActivityAuthorizationError error 3.)"
-// FIX: Add NSSupportsLiveActivities = YES to the HOST APP's Info.plist (not the extension).
-```
-
-## Widget Relevance and Smart Stacks
-
-### TimelineEntryRelevance
-
-Score entries to surface widgets in Smart Stacks when relevant:
+An entry can tell Smart Stacks how important it is and for how long:
 
 ```swift
-struct GameEntry: TimelineEntry {
-    var date: Date
-    var score: String
-    var isLive: Bool
+struct MatchEntry: TimelineEntry {
+    let date: Date
+    let score: String
+    let isLive: Bool
 
     var relevance: TimelineEntryRelevance? {
-        isLive ? TimelineEntryRelevance(score: 100, duration: 3600) : nil
+        isLive ? TimelineEntryRelevance(score: 90, duration: 2 * 3600) : nil
     }
 }
 ```
 
-Higher scores make the widget more likely to surface. The `duration` specifies
-how long the relevance lasts.
+A higher score makes the stack more likely to rotate the widget up; `duration`
+says how long the score holds.
 
-### WidgetRelevance (AppIntentTimelineProvider)
+Configurable widgets can also report relevance from the provider (iOS 18+). The
+method returns a `WidgetRelevance` built from an array of
+`WidgetRelevanceAttribute` values, each pairing one intent configuration with a
+RelevanceKit context such as a date window. `.date(interval:kind:)` below needs
+iOS 26; on iOS 18 the date window is `.date(from:to:)`:
 
 ```swift
-func relevance() async -> WidgetRelevance<SelectCategoryIntent> {
-    let topCategory = await DataStore.shared.mostActiveCategory()
-    let intent = SelectCategoryIntent(category: topCategory)
-    return WidgetRelevance(intent, score: 80)
+import RelevanceKit
+
+func relevance() async -> WidgetRelevance<PickTeamIntent> {
+    let fixtures = await FixtureStore.shared.upcoming()
+    let attributes = fixtures.map { fixture in
+        WidgetRelevanceAttribute(
+            configuration: PickTeamIntent(team: fixture.team),
+            context: .date(interval: fixture.window, kind: .scheduled)
+        )
+    }
+    return WidgetRelevance(attributes)
 }
 ```
 
-## ActivityState Lifecycle
+`.date(interval:kind:)` is the iOS 26 form; on iOS 18 use `.date(from:to:)`,
+which iOS 26 deprecates.
 
-Track the full lifecycle of a Live Activity:
+## ActivityState Lifecycle
 
 ```swift
 Task {
-    for await state in activity.activityStateUpdates {
-        switch state {
-        case .active:
-            // Activity is running and visible
-            break
-        case .pending:
-            // Requested but not yet displayed (iOS 26+)
-            break
-        case .stale:
-            // Content is outdated; update or end
-            break
-        case .ended:
-            // Ended but may still be visible on Lock Screen
-            break
-        case .dismissed:
-            // Fully removed from UI; clean up resources
-            break
-        @unknown default:
-            break
+    for await phase in activity.activityStateUpdates {
+        switch phase {
+        case .active: break
+        case .pending: showQueuedBadge()
+        case .stale: await refreshOrEnd(activity)
+        case .ended: markFinished()
+        case .dismissed: cleanUp(activity.id)
+        @unknown default: break
         }
     }
 }
 ```
 
-## ActivityStyle
+| State | Meaning |
+|---|---|
+| `.active` | Running and visible |
+| `.pending` | Requested but not on screen yet (iOS 26+) |
+| `.stale` | Content is out of date; update it or end it |
+| `.ended` | Finished, but may still sit on the Lock Screen |
+| `.dismissed` | Gone from screen; release resources |
 
-Control Live Activity persistence behavior (iOS 18+):
+## ActivityStyle
 
 ```swift
-// Standard: persists until explicitly ended
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token,
-    style: .standard
-)
-
-// Transient: automatically dismissed after a period
-let activity = try Activity.request(
-    attributes: attributes,
-    content: content,
-    pushType: .token,
-    style: .transient
-)
+_ = try Activity.request(attributes: goalAlert, content: snapshot, pushType: nil, style: .transient)
 ```
 
-Use `.transient` for short-lived notifications like sports scores or transit
-arrivals that do not need persistent display.
+`.standard` stays until you end it. `.transient` (iOS 18+) is removed by the
+system after a while; use it for short bursts such as a goal alert or a bus
+arriving.
 
 ## Dismissal Policies
 
-Control when an ended Live Activity disappears from the Lock Screen:
-
-```swift
-// System-determined timing (default)
-await activity.end(finalContent, dismissalPolicy: .default)
-
-// Remove immediately
-await activity.end(finalContent, dismissalPolicy: .immediate)
-
-// Remove after a specific date (max 4 hours)
-let removalDate = Date().addingTimeInterval(3600)
-await activity.end(finalContent, dismissalPolicy: .after(removalDate))
-```
-
-## Querying Active Widgets and Activities
+| Policy | Effect |
+|---|---|
+| `.default` | The system chooses when to remove it |
+| `.immediate` | Removed right away |
+| `.after(date)` | Removed at the given date, at most 4 hours after ending |
 
-### Current Widget Configurations
+## Finding which widgets and activities are live
 
 ```swift
-let widgets = try await WidgetCenter.shared.currentConfigurations()
-for widget in widgets {
-    print("Kind: \(widget.kind), Family: \(widget.family)")
+let configs = try await WidgetCenter.shared.currentConfigurations()
+for info in configs {
+    logger.debug("\(info.kind) \(String(describing: info.family))")
 }
-```
-
-### Current Live Activities
 
-```swift
-let activities = Activity<DeliveryAttributes>.activities
-for activity in activities {
-    print("ID: \(activity.id), State: \(activity.activityState)")
+for activity in Activity<FerryAttributes>.activities {
+    logger.debug("\(activity.id) \(String(describing: activity.activityState))")
 }
-```
-
-### Observing New Activities
 
-```swift
 Task {
-    for await activity in Activity<DeliveryAttributes>.activityUpdates {
-        print("New activity started: \(activity.id)")
+    for await started in Activity<FerryAttributes>.activityUpdates {
+        observe(started)
     }
 }
 ```
 
-## Design Patterns
+`currentConfigurations()` lists placed widgets with their `kind` and `family`.
+`Activity<T>.activities` returns running activities, and `activityUpdates`
+reports ones started later, including by push. `logger` is an `os.Logger`.
 
-### Prefer Gauge for Value Indicators
+## Design Patterns
 
-Use `Gauge` (iOS 16+) instead of manual `Circle` or `Path` arcs to show a value
-within a range. The system handles styling, accessibility, and rendering-mode
-adaptation automatically.
+### Gauge (iOS 16+)
 
-- `.accessoryCircular`  -  open ring with center value label, matches the system
-  complication style. Use for `accessoryCircular` Lock Screen widgets.
-- `.linearCapacity`  -  horizontal bar that fills leading to trailing. Use for
-  home screen widgets when a capacity bar fits.
+`.accessoryCircular` draws an open ring with the value in the middle, the same
+look as system complications. `.linearCapacity` fills from leading to trailing.
 
 ```swift
-// accessoryCircular Lock Screen widget
-struct StepsCircularView: View {
-    let entry: StepsEntry
-
-    var body: some View {
-        Gauge(value: Double(entry.stepCount), in: 0...10000) {
-            Image(systemName: "figure.walk")
-        } currentValueLabel: {
-            Text("\(entry.stepCount)")
-        }
-        .gaugeStyle(.accessoryCircular)
-    }
+Gauge(value: Double(entry.steps), in: 0...10000) {
+    Image(systemName: "figure.walk")
+} currentValueLabel: {
+    Text(entry.steps, format: .number.notation(.compactName))
 }
+.gaugeStyle(.accessoryCircular)
 
-// Home screen capacity bar
-Gauge(value: storageUsed, in: 0...storageTotal) {
-    Text("Storage")
+Gauge(value: entry.usedBytes, in: 0...entry.totalBytes) {
+    Text("Backup")
 } currentValueLabel: {
-    Text(storageUsed, format: .byteCount(style: .file))
+    Text(Int64(entry.usedBytes).formatted(.byteCount(style: .file)))
 }
 .gaugeStyle(.linearCapacity)
 ```
 
-### Use containerBackground for Widget Backgrounds
-
-`.containerBackground(_:for: .widget)` (iOS 17+) is the designated way to set
-widget backgrounds. Replaces older padding and background patterns. The system
-uses this placement to correctly render backgrounds across all widget surfaces.
+### Container background
 
 ```swift
-struct OrderWidgetView: View {
-    let entry: OrderEntry
-
-    var body: some View {
-        VStack(alignment: .leading) {
-            Text(entry.orderName).font(.headline)
-            Text(entry.status).foregroundStyle(.secondary)
-        }
-        .containerBackground(.fill.tertiary, for: .widget)
-    }
-}
+TideSummary(entry: entry)
+    .containerBackground(.fill.tertiary, for: .widget)
 ```
 
-### Use Canvas for Dense Visualizations
+The system knows where the widget is placed and draws the background correctly
+on every surface, including removing it where the surface wants none.
 
-Use `Canvas` for sparklines, mini bar charts, or heat maps inside widgets. The
-lack of per-element accessibility is acceptable since the entire widget surface
-is a single tap target.
+### Canvas sparkline
 
 ```swift
-struct SparklineView: View {
+struct Sparkline: View {
     let values: [Double]
 
     var body: some View {
         Canvas { context, size in
-            guard values.count > 1 else { return }
-            let maxVal = values.max() ?? 1
-            let step = size.width / CGFloat(values.count - 1)
+            guard values.count >= 2, let low = values.min(), let high = values.max() else { return }
+            let span = max(high - low, .ulpOfOne)
+            let spacing = size.width / Double(values.count - 1)
             var path = Path()
-            for (i, value) in values.enumerated() {
-                let x = step * CGFloat(i)
-                let y = size.height * (1 - value / maxVal)
-                if i == 0 { path.move(to: CGPoint(x: x, y: y)) }
-                else { path.addLine(to: CGPoint(x: x, y: y)) }
+            for (index, value) in values.enumerated() {
+                let point = CGPoint(
+                    x: Double(index) * spacing,
+                    y: size.height * (1 - CGFloat((value - low) / span))
+                )
+                index == 0 ? path.move(to: point) : path.addLine(to: point)
             }
-            context.stroke(path, with: .color(.blue), lineWidth: 2)
+            context.stroke(path, with: .color(.green), lineWidth: 1.5)
         }
     }
 }
 ```
 
-### Match Timeline Refresh to Data Granularity
-
-Apple budgets
-[40-70 refreshes per day](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)
-for frequently viewed widgets, with entries at least 5 minutes apart. Align
-reload cadence to how often the underlying data actually changes.
-
-- Generate entries for as many future dates as possible to reduce reload requests.
-- Use `.after(date)` when data updates on a known schedule (market hours, transit).
-- Use `.never` when data only changes from user action.
-- Use `Text(timerInterval:countsDown:)` for live countdowns instead of burning
-  timeline entries on every tick.
-
-## Apple Documentation Links
-
-- [WidgetKit](https://sosumi.ai/documentation/widgetkit)
-- [ActivityKit](https://sosumi.ai/documentation/activitykit)
-- [TimelineProvider](https://sosumi.ai/documentation/widgetkit/timelineprovider)
-- [AppIntentTimelineProvider](https://sosumi.ai/documentation/widgetkit/appintenttimelineprovider)
-- [ActivityAttributes](https://sosumi.ai/documentation/activitykit/activityattributes)
-- [ActivityConfiguration](https://sosumi.ai/documentation/widgetkit/activityconfiguration)
-- [DynamicIsland](https://sosumi.ai/documentation/widgetkit/dynamicisland)
-- [ControlWidgetButton](https://sosumi.ai/documentation/widgetkit/controlwidgetbutton)
-- [ControlWidgetToggle](https://sosumi.ai/documentation/widgetkit/controlwidgettoggle)
-- [Keeping a widget up to date](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)
-- [Adding StandBy and CarPlay support](https://sosumi.ai/documentation/widgetkit/adding-standby-and-carplay-support-to-your-widget)
-- [Optimizing for accented rendering and Liquid Glass](https://sosumi.ai/documentation/widgetkit/optimizing-your-widget-for-accented-rendering-mode-and-liquid-glass)
+### Refresh budget in practice
+
+- Widgets people look at often get about 40 to 70 refreshes a day, with entries
+  no closer than 5 minutes.
+- Put as many future entries into each timeline as you can predict.
+- Use `.after(date)` for scheduled data and `.never` for data only the user changes.
+- Let `Text(timerInterval:countsDown:)` or a timer text style count down instead
+  of writing an entry per second.
+
+## Further reading from Apple
+
+- [WidgetKit](https://developer.apple.com/documentation/widgetkit)
+- [ActivityKit](https://developer.apple.com/documentation/activitykit)
+- [TimelineProvider](https://developer.apple.com/documentation/widgetkit/timelineprovider)
+- [AppIntentTimelineProvider](https://developer.apple.com/documentation/widgetkit/appintenttimelineprovider)
+- [ActivityAttributes](https://developer.apple.com/documentation/activitykit/activityattributes)
+- [ActivityConfiguration](https://developer.apple.com/documentation/widgetkit/activityconfiguration)
+- [DynamicIsland](https://developer.apple.com/documentation/widgetkit/dynamicisland)
+- [ControlWidgetButton](https://developer.apple.com/documentation/widgetkit/controlwidgetbutton)
+- [ControlWidgetToggle](https://developer.apple.com/documentation/widgetkit/controlwidgettoggle)
+- [Keeping a widget up to date](https://developer.apple.com/documentation/widgetkit/keeping-a-widget-up-to-date)
+- [Adding StandBy and CarPlay support to your widget](https://developer.apple.com/documentation/widgetkit/adding-standby-and-carplay-support-to-your-widget)
+- [Optimizing your widget for accented rendering mode and Liquid Glass](https://developer.apple.com/documentation/widgetkit/optimizing-your-widget-for-accented-rendering-mode-and-liquid-glass)