@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/widgetkit/SKILL.md

@@ -1,429 +1,357 @@
 ---
 name: widgetkit
-description: "Implement, review, or improve widgets, Live Activities, and controls using WidgetKit and ActivityKit. Use when building home screen, Lock Screen, or StandBy widgets with timeline providers; when creating interactive widgets with Button/Toggle and AppIntent actions; when adding Live Activities with Dynamic Island layouts (compact, minimal, expanded); when building Control Center widgets with ControlWidgetButton/ControlWidgetToggle; when configuring widget families, refresh budgets, deep links, push-based reloads, or Liquid Glass rendering; or when setting up widget extensions, App Groups, and entitlements."
+description: "WidgetKit and ActivityKit surfaces on iOS 26+: timeline-driven widgets for the Home Screen, the Lock Screen and StandBy, interactive widgets using Button or Toggle with AppIntent actions, Live Activities and their Dynamic Island layouts (compact, expanded, minimal), Control Center controls with ControlWidgetButton or ControlWidgetToggle, families, deep links, the refresh budget, reloads triggered by push, Liquid Glass accented rendering, extension setup, App Groups and entitlements. Use when implementing, reviewing or improving widgets, Live Activities or controls."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
-# WidgetKit and ActivityKit
+# WidgetKit
 
-Build home screen widgets, Lock Screen widgets, Live Activities, Dynamic Island
-presentations, Control Center controls, and StandBy surfaces for iOS 26+.
+Widgets are small SwiftUI snapshots that the system renders from data your
+extension hands it ahead of time. This skill targets iOS 26+ and covers every
+surface WidgetKit and ActivityKit draw on: the Home Screen, the Lock Screen,
+Live Activities and the Dynamic Island, Control Center and StandBy.
 
-See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) for timeline strategies, push-based
-updates, Xcode setup, and advanced patterns.
+Related skills: `app-intents` for intent and entity design beyond what a widget
+needs, `live-activities` for deeper ActivityKit push contracts.
 
-## Contents
+Longer examples are in [the advanced reference](references/widgetkit-advanced.md).
 
-- [Workflow](#workflow)
-- [Widget Protocol and WidgetBundle](#widget-protocol-and-widgetbundle)
-- [Configuration Types](#configuration-types)
-- [TimelineProvider](#timelineprovider)
-- [AppIntentTimelineProvider](#appintenttimelineprovider)
-- [Widget Families](#widget-families)
-- [Interactive Widgets (iOS 17+)](#interactive-widgets-ios-17)
-- [Live Activities and Dynamic Island](#live-activities-and-dynamic-island)
-- [Control Center Widgets (iOS 18+)](#control-center-widgets-ios-18)
-- [Lock Screen Widgets](#lock-screen-widgets)
-- [StandBy Mode](#standby-mode)
-- [Design Patterns](#design-patterns)
-- [iOS 26 Additions](#ios-26-additions)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+## Workflows
 
-## Workflow
+### New widget
 
-### 1. Create a new widget
+1. In Xcode choose File > New > Target > Widget Extension.
+2. Turn on App Groups for both the app and the extension so they can share data.
+3. Write a `TimelineEntry` type: a `date` plus whatever the view shows.
+4. Write a provider: `TimelineProvider` for a fixed widget,
+   `AppIntentTimelineProvider` for a configurable one.
+5. Write the SwiftUI view and let it adapt to the current `WidgetFamily`.
+6. Declare a `Widget` type with its configuration and supported families.
+7. List every widget in one `WidgetBundle` and put `@main` on the bundle.
 
-1. Add a Widget Extension target in Xcode (File > New > Target > Widget Extension).
-2. Enable App Groups for shared data between the app and widget extension.
-3. Define a `TimelineEntry` struct with a `date` property and display data.
-4. Implement a `TimelineProvider` (static) or `AppIntentTimelineProvider` (configurable).
-5. Build the widget view using SwiftUI, adapting layout per `WidgetFamily`.
-6. Declare the `Widget` conforming struct with a configuration and supported families.
-7. Register all widgets in a `WidgetBundle` annotated with `@main`.
+### Live Activity
 
-### 2. Add a Live Activity
+1. Declare `ActivityAttributes` with a nested `ContentState`.
+2. Set `NSSupportsLiveActivities` to `YES` in the main app's Info.plist.
+3. Add an `ActivityConfiguration` to the widget bundle with the Lock Screen view
+   and the Dynamic Island closures.
+4. `Activity.request(attributes:content:pushType:)` starts it,
+   `activity.update(_:)` changes it and `activity.end(_:dismissalPolicy:)` closes it.
 
-1. Define an `ActivityAttributes` struct with a nested `ContentState`.
-2. Add `NSSupportsLiveActivities = YES` to the app's Info.plist.
-3. Create an `ActivityConfiguration` in the widget bundle with Lock Screen content
-   and Dynamic Island closures.
-4. Start the activity with `Activity.request(attributes:content:pushType:)`.
-5. Update with `activity.update(_:)` and end with `activity.end(_:dismissalPolicy:)`.
+### Control Center control
 
-### 3. Add a Control Center control
+1. Write the `AppIntent` the control runs.
+2. Build a `ControlWidgetButton` or `ControlWidgetToggle`.
+3. Wrap it in `StaticControlConfiguration` or `AppIntentControlConfiguration`.
 
-1. Define an `AppIntent` for the action.
-2. Create a `ControlWidgetButton` or `ControlWidgetToggle` in the widget bundle.
-3. Use `StaticControlConfiguration` or `AppIntentControlConfiguration`.
+### Review
 
-### 4. Review existing widget code
+Go through the [checklist](#review-checklist) below.
 
-Run through the Review Checklist at the end of this document.
+## Widget and WidgetBundle
 
-## Widget Protocol and WidgetBundle
-
-### Widget
-
-Every widget conforms to the `Widget` protocol and returns a `WidgetConfiguration`
-from its `body`.
+A widget is a type conforming to `Widget`. Its `body` returns a
+`WidgetConfiguration`, and it carries a `kind` string that identifies it for
+reloads.
 
 ```swift
-struct OrderStatusWidget: Widget {
-    let kind: String = "OrderStatusWidget"
+struct TideWidget: Widget {
+    let kind = "TideWidget"
 
     var body: some WidgetConfiguration {
-        StaticConfiguration(kind: kind, provider: OrderProvider()) { entry in
-            OrderWidgetView(entry: entry)
+        StaticConfiguration(kind: kind, provider: TideProvider()) { entry in
+            TideView(entry: entry)
         }
-        .configurationDisplayName("Order Status")
-        .description("Track your current order.")
+        .configurationDisplayName("Tides")
+        .description("Next high and low water at your beach.")
         .supportedFamilies([.systemSmall, .systemMedium])
     }
 }
-```
 
-### WidgetBundle
-
-Use `WidgetBundle` to expose multiple widgets from a single extension.
-
-```swift
 @main
-struct MyAppWidgets: WidgetBundle {
+struct HarborWidgets: WidgetBundle {
     var body: some Widget {
-        OrderStatusWidget()
-        FavoritesWidget()
-        DeliveryActivityWidget()   // Live Activity
-        QuickActionControl()       // Control Center
+        TideWidget()
+        HarborActivityWidget()
+        LighthouseControl()
     }
 }
 ```
 
-## Configuration Types
+One `WidgetBundle` can expose ordinary widgets, Live Activity widgets and
+Control Center controls from the same extension.
 
-Use `StaticConfiguration` for non-configurable widgets. Use `AppIntentConfiguration`
-(recommended) for configurable widgets paired with `AppIntentTimelineProvider`.
+## Configuration Types
 
-```swift
-// Static
-StaticConfiguration(kind: "MyWidget", provider: MyProvider()) { entry in
-    MyWidgetView(entry: entry)
-}
-// Configurable
-AppIntentConfiguration(kind: "ConfigWidget", intent: SelectCategoryIntent.self,
-                       provider: CategoryProvider()) { entry in
-    CategoryWidgetView(entry: entry)
-}
-```
+| Type | Use |
+|---|---|
+| `StaticConfiguration` | Widget with no user settings |
+| `AppIntentConfiguration(kind:intent:provider:)` | Preferred for configurable widgets; pairs with `AppIntentTimelineProvider` |
 
-### Shared Modifiers
+Modifiers shared by both:
 
-| Modifier | Purpose |
-|---|---|
-| `.configurationDisplayName(_:)` | Name shown in the widget gallery |
-| `.description(_:)` | Description shown in the widget gallery |
-| `.supportedFamilies(_:)` | Array of `WidgetFamily` values |
-| `.supplementalActivityFamilies(_:)` | Live Activity sizes (`.small`, `.medium`) |
+- `.configurationDisplayName(_:)`: title shown in the widget gallery.
+- `.description(_:)`: gallery blurb.
+- `.supportedFamilies(_:)`: the `WidgetFamily` cases you support.
+- `.supplementalActivityFamilies(_:)`: extra Live Activity sizes, `.small` and `.medium`.
 
 ## TimelineProvider
 
-For static (non-configurable) widgets. Uses completion handlers. Three required methods:
+For fixed widgets. It uses completion handlers and needs three methods.
 
 ```swift
-struct WeatherProvider: TimelineProvider {
-    typealias Entry = WeatherEntry
-
-    func placeholder(in context: Context) -> WeatherEntry {
-        WeatherEntry(date: .now, temperature: 72, condition: "Sunny")
+struct TideProvider: TimelineProvider {
+    func placeholder(in context: Context) -> TideEntry {
+        .sample
     }
 
-    func getSnapshot(in context: Context, completion: @escaping (WeatherEntry) -> Void) {
-        let entry = context.isPreview
-            ? placeholder(in: context)
-            : WeatherEntry(date: .now, temperature: currentTemp, condition: currentCondition)
-        completion(entry)
+    func getSnapshot(in context: Context, completion: @escaping @Sendable (TideEntry) -> Void) {
+        if context.isPreview {
+            completion(.sample)
+        } else {
+            completion(TideStore.shared.latestEntry())
+        }
     }
 
-    func getTimeline(in context: Context, completion: @escaping (Timeline<WeatherEntry>) -> Void) {
+    func getTimeline(in context: Context, completion: @escaping @Sendable (Timeline<TideEntry>) -> Void) {
         Task {
-            let weather = await WeatherService.shared.fetch()
-            let entry = WeatherEntry(date: .now, temperature: weather.temp, condition: weather.condition)
-            let nextUpdate = Calendar.current.date(byAdding: .hour, value: 1, to: .now)!
-            completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
+            let reading = await TideStore.shared.loadReading()
+            let current = TideEntry(date: .now, reading: reading)
+            let refresh = Calendar.current.date(byAdding: .minute, value: 60, to: .now) ?? .now
+            completion(Timeline(entries: [current], policy: .after(refresh)))
         }
     }
 }
 ```
 
+`placeholder(in:)` hands back sample data instantly. The snapshot shows sample
+data when `context.isPreview` is true and real data otherwise. The protocol
+declares both completion handlers `@Sendable`; keep that in the signature, or
+Swift 6 rejects handing `completion` to the `Task` as a data race.
+
 ## AppIntentTimelineProvider
 
-For configurable widgets. Uses async/await natively. Receives user intent configuration.
+For configurable widgets. It is async/await from the start and receives the
+user's intent.
 
 ```swift
-struct CategoryProvider: AppIntentTimelineProvider {
-    typealias Entry = CategoryEntry
-    typealias Intent = SelectCategoryIntent
+struct BeachProvider: AppIntentTimelineProvider {
+    typealias Entry = TideEntry
+    typealias Intent = PickBeachIntent
 
-    func placeholder(in context: Context) -> CategoryEntry {
-        CategoryEntry(date: .now, categoryName: "Sample", items: [])
-    }
+    func placeholder(in context: Context) -> TideEntry { .sample }
 
-    func snapshot(for config: SelectCategoryIntent, in context: Context) async -> CategoryEntry {
-        let items = await DataStore.shared.items(for: config.category)
-        return CategoryEntry(date: .now, categoryName: config.category.name, items: items)
+    func snapshot(for configuration: PickBeachIntent, in context: Context) async -> TideEntry {
+        context.isPreview ? .sample : await TideStore.shared.entry(for: configuration.beach)
     }
 
-    func timeline(for config: SelectCategoryIntent, in context: Context) async -> Timeline<CategoryEntry> {
-        let items = await DataStore.shared.items(for: config.category)
-        let entry = CategoryEntry(date: .now, categoryName: config.category.name, items: items)
-        return Timeline(entries: [entry], policy: .atEnd)
+    func timeline(for configuration: PickBeachIntent, in context: Context) async -> Timeline<TideEntry> {
+        let latest = await TideStore.shared.entry(for: configuration.beach)
+        return Timeline(entries: [latest], policy: .atEnd)
     }
 }
 ```
 
 ## Widget Families
 
-| Family | Platform |
+| Family | Where it runs |
 |---|---|
-| `.systemSmall` | iOS, iPadOS, macOS, CarPlay (iOS 26+) |
-| `.systemMedium` | iOS, iPadOS, macOS |
-| `.systemLarge` | iOS, iPadOS, macOS |
+| `.systemSmall` | iOS, iPadOS, macOS, and CarPlay from iOS 26 |
+| `.systemMedium`, `.systemLarge` | iOS, iPadOS, macOS |
 | `.systemExtraLarge` | iPadOS only |
-| `.accessoryCircular` | iOS, watchOS |
-| `.accessoryRectangular` | iOS, watchOS |
-| `.accessoryInline` | iOS, watchOS |
+| `.accessoryCircular`, `.accessoryRectangular`, `.accessoryInline` | iOS, watchOS |
 | `.accessoryCorner` | watchOS only |
 
-Adapt layout per family using `@Environment(\.widgetFamily)`:
-
 ```swift
-@Environment(\.widgetFamily) var family
-
-var body: some View {
-    switch family {
-    case .systemSmall: CompactView(entry: entry)
-    case .systemMedium: DetailedView(entry: entry)
-    case .accessoryCircular: CircularView(entry: entry)
-    default: FullView(entry: entry)
+struct TideView: View {
+    @Environment(\.widgetFamily) private var family
+    let entry: TideEntry
+
+    var body: some View {
+        switch family {
+        case .accessoryInline: Text(entry.reading.shortLine)
+        case .systemMedium: TideChartRow(entry: entry)
+        default: TideSummary(entry: entry)
+        }
     }
 }
 ```
 
 ## Interactive Widgets (iOS 17+)
 
-Use `Button` and `Toggle` with `AppIntent` conforming types to perform actions
-directly from a widget without launching the app.
+`Button` and `Toggle` that take an `AppIntent` run the action inside the widget
+without opening the app.
 
 ```swift
-struct ToggleFavoriteIntent: AppIntent {
-    static var title: LocalizedStringResource = "Toggle Favorite"
-    @Parameter(title: "Item ID") var itemID: String
+struct WaterPlantIntent: AppIntent {
+    static let title: LocalizedStringResource = "Water Plant"
+
+    @Parameter(title: "Plant")
+    var plantID: String
+
+    init() {}
+    init(plantID: String) { self.plantID = plantID }
 
     func perform() async throws -> some IntentResult {
-        await DataStore.shared.toggleFavorite(itemID)
+        await PlantLog.shared.recordWatering(plantID)
         return .result()
     }
 }
 
-// In the widget view:
-Button(intent: ToggleFavoriteIntent(itemID: entry.itemID)) {
-    Image(systemName: entry.isFavorite ? "star.fill" : "star")
+Button(intent: WaterPlantIntent(plantID: plant.id)) {
+    Image(systemName: "drop.fill")
 }
 ```
 
 ## Live Activities and Dynamic Island
 
-### ActivityAttributes
-
-Define the static and dynamic data model.
+Fields that never change go on the `ActivityAttributes` type; changing fields go
+on its nested `ContentState`, which must be `Codable` and `Hashable`.
 
 ```swift
-struct DeliveryAttributes: ActivityAttributes {
+struct RepairAttributes: ActivityAttributes {
     struct ContentState: Codable, Hashable {
-        var driverName: String
-        var estimatedDeliveryTime: ClosedRange<Date>
-        var currentStep: DeliveryStep
+        var window: ClosedRange<Date>
+        var stage: RepairStage
     }
-
-    var orderNumber: Int
-    var restaurantName: String
+    var ticketNumber: String
 }
 ```
 
-### ActivityConfiguration
-
-Provide Lock Screen content and Dynamic Island closures in the widget bundle. The
-`ActivityConfiguration(for:)` body returns the Lock Screen view; its
-`dynamicIsland` closure declares the expanded regions plus `compactLeading`,
-`compactTrailing`, and `minimal`. See [references/widgetkit-advanced.md](references/widgetkit-advanced.md)
-("Live Activity Full ActivityConfiguration Example") for a complete implementation.
+`ActivityConfiguration(for:)` takes the Lock Screen view in its main closure
+and a `dynamicIsland` closure that declares the expanded regions plus
+`compactLeading`, `compactTrailing` and `minimal`.
 
-### Dynamic Island Regions
+Expanded regions:
 
-| Region | Position |
+| Region | Placement |
 |---|---|
-| `.leading` | Left of the TrueDepth camera; wraps below |
-| `.trailing` | Right of the TrueDepth camera; wraps below |
-| `.center` | Directly below the camera |
-| `.bottom` | Below all other regions |
+| `.leading` | Beside the TrueDepth camera on its left, continuing below |
+| `.trailing` | Beside the camera on its right, continuing below |
+| `.center` | Right under the camera |
+| `.bottom` | Under every other region |
 
-### Starting, Updating, and Ending
+Lifecycle:
 
 ```swift
-let attributes = DeliveryAttributes(orderNumber: 123, restaurantName: "Pizza Place")
-let state = DeliveryAttributes.ContentState(
-    driverName: "Alex",
-    estimatedDeliveryTime: Date()...Date().addingTimeInterval(1800),
-    currentStep: .preparing
+let initial = RepairAttributes.ContentState(window: start...finish, stage: .diagnosing)
+let opening = ActivityContent(state: initial, staleDate: finish, relevanceScore: 75)
+let activity = try Activity.request(
+    attributes: RepairAttributes(ticketNumber: "R-2291"),
+    content: opening,
+    pushType: .token
 )
-let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
-let activity = try Activity.request(attributes: attributes, content: content, pushType: .token)
 
-let updated = ActivityContent(state: newState, staleDate: nil, relevanceScore: 90)
-await activity.update(updated)
+let next = ActivityContent(state: updatedState, staleDate: finish, relevanceScore: 90)
+await activity.update(next)
 
-let final = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
-await activity.end(final, dismissalPolicy: .after(.now.addingTimeInterval(3600)))
+let done = ActivityContent(state: closedState, staleDate: nil, relevanceScore: 0)
+await activity.end(done, dismissalPolicy: .after(.now.addingTimeInterval(1800)))
 ```
 
+A complete configuration with every region is in
+[Live Activity Full ActivityConfiguration Example](references/widgetkit-advanced.md#live-activity-full-activityconfiguration-example).
+
 ## Control Center Widgets (iOS 18+)
 
-Wrap a `ControlWidgetButton` or `ControlWidgetToggle` in a
-`StaticControlConfiguration` (or `AppIntentControlConfiguration`). Each control
-runs an `AppIntent` action.
+Put a `ControlWidgetButton` or `ControlWidgetToggle` inside
+`StaticControlConfiguration` or `AppIntentControlConfiguration`. Every control
+performs an `AppIntent`.
 
 ```swift
-struct OpenCameraControl: ControlWidget {
+struct LighthouseControl: ControlWidget {
     var body: some ControlWidgetConfiguration {
-        StaticControlConfiguration(kind: "OpenCamera") {
-            ControlWidgetButton(action: OpenCameraIntent()) {
-                Label("Camera", systemImage: "camera.fill")
+        StaticControlConfiguration(kind: "LighthouseControl") {
+            ControlWidgetButton(action: FlashBeaconIntent()) {
+                Label("Beacon", systemImage: "light.beacon.max")
             }
         }
-        .displayName("Open Camera")
+        .displayName("Flash Beacon")
     }
 }
 ```
 
-See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) ("Control Center Control
-Examples") for a toggle control backed by a value provider.
+A toggle with live state is in
+[Control Center Control Examples](references/widgetkit-advanced.md#control-center-control-examples).
 
 ## Lock Screen Widgets
 
-Use accessory families (`.accessoryCircular`, `.accessoryRectangular`,
-`.accessoryInline`) and wrap content in `AccessoryWidgetBackground()` for the
-standard translucent backing. See [references/widgetkit-advanced.md](references/widgetkit-advanced.md)
-("Lock Screen Accessory Widget Example") for a full widget, and
-"AccessoryWidgetBackground" for rendering-mode adaptation.
+Use the accessory families and put `AccessoryWidgetBackground()` behind the
+content for the system's translucent backing. See
+[Lock Screen Accessory Widget Example](references/widgetkit-advanced.md#lock-screen-accessory-widget-example)
+and [AccessoryWidgetBackground](references/widgetkit-advanced.md#accessorywidgetbackground).
 
 ## StandBy Mode
 
-`.systemSmall` widgets automatically appear in StandBy (iPhone on charger in
-landscape). Use `@Environment(\.widgetLocation)` for conditional rendering:
-
-```swift
-@Environment(\.widgetLocation) var location
-// location == .standBy, .homeScreen, .lockScreen, .carPlay, etc.
-```
+`.systemSmall` widgets show up in StandBy automatically when an iPhone charges
+on its side. Read `@Environment(\.widgetLocation)` to tell where you are drawn:
+`.homeScreen`, `.lockScreen`, `.standBy` or `.carPlay`.
 
 ## Design Patterns
 
-- **Prefer `Gauge` over manual arcs.** Use `.gaugeStyle(.accessoryCircular)` for
-  Lock Screen circular widgets and `.linearCapacity` for home screen capacity bars.
-  The system handles styling, accessibility, and rendering-mode adaptation.
-- **Use `.containerBackground(_:for: .widget)`** (iOS 17+) for widget backgrounds
-  instead of padding and background modifiers.
-- **Use `Canvas` for dense visualizations** like sparklines or mini bar charts.
-  The lack of per-element accessibility is acceptable since the entire widget
-  surface is a single tap target.
-- **Match timeline refresh to data granularity.** Apple budgets
-  [40-70 refreshes per day](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)
-  with entries at least 5 minutes apart. Use `Text(timerInterval:countsDown:)`
-  for live countdowns instead of burning timeline entries.
-
-See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) for
-code examples and detailed guidance on each pattern.
+- Reach for `Gauge` before drawing arcs by hand. `.gaugeStyle(.accessoryCircular)`
+  suits circular Lock Screen widgets and `.linearCapacity` suits Home Screen
+  capacity bars; the system then handles styling, accessibility and rendering modes.
+- From iOS 17, give the widget its background through
+  `.containerBackground(_:for: .widget)` instead of padding plus `.background`.
+- Draw dense visuals such as sparklines or tiny bar charts with `Canvas`. Losing
+  per-element accessibility is acceptable because the whole widget is one tap target.
+- Budget: roughly 40 to 70 refreshes a day, with entries 5 minutes apart or more.
+  For countdowns use `Text(timerInterval:countsDown:)` instead of one entry per tick.
 
 ## iOS 26 Additions
 
-### Liquid Glass Support
-
-Adapt widgets to the Liquid Glass visual style using `WidgetAccentedRenderingMode`.
-
-| Mode | Description |
-|---|---|
-| `.accented` | Accented rendering for Liquid Glass |
-| `.accentedDesaturated` | Accented with desaturation |
-| `.desaturated` | Fully desaturated |
-| `.fullColor` | Full-color rendering |
-
-### WidgetPushHandler
-
-Enable push-based timeline reloads without scheduled polling: implement
-`WidgetPushHandler.pushTokenDidChange(_:widgets:)`, register the token with your
-server, and send an APNs push to trigger a reload. See
-[references/widgetkit-advanced.md](references/widgetkit-advanced.md) ("Push-Based Timeline Reloads") for
-the handler plus the `ControlPushHandler` equivalent.
-
-### CarPlay Widgets
-
-`.systemSmall` widgets render in CarPlay on iOS 26+. Ensure small widget layouts
-are legible at a glance for driver safety.
+- `WidgetAccentedRenderingMode` (`.accented`, `.accentedDesaturated`,
+  `.desaturated`, `.fullColor`) controls how images adapt to Liquid Glass tinting.
+- `WidgetPushHandler.pushTokenDidChange(_:widgets:)` gives you a token to send to
+  your server; an APNs push to it reloads the widget. `ControlPushHandler` does
+  the same for controls. See
+  [Reloading timelines by push](references/widgetkit-advanced.md#reloading-timelines-by-push-ios-26-and-later).
+- `.systemSmall` widgets render in CarPlay from iOS 26. Keep them readable at a
+  glance so a driver is never pulled into detail.
 
 ## Common Mistakes
 
-1. **Using IntentTimelineProvider instead of AppIntentTimelineProvider.**
-   `IntentTimelineProvider` is the older SiriKit Intents-based provider. Prefer
-   `AppIntentTimelineProvider` with the App Intents framework for new widgets.
-
-2. **Exceeding the refresh budget.** Widgets have a daily refresh limit. Do not
-   call `WidgetCenter.shared.reloadTimelines(ofKind:)` on every minor data change.
-   Batch updates and use appropriate `TimelineReloadPolicy` values.
-
-3. **Forgetting App Groups for shared data.** The widget extension runs in a
-   separate process. Use `UserDefaults(suiteName:)` or a shared App Group
-   container for data the widget reads.
-
-4. **Performing network calls in placeholder().** `placeholder(in:)` must return
-   synchronously with sample data. Use `getTimeline` or `timeline(for:in:)` for
-   async work.
-
-5. **Missing NSSupportsLiveActivities Info.plist key.** Live Activities will not
-   start without `NSSupportsLiveActivities = YES` in the host app's Info.plist.
-
-6. **Using the deprecated contentState API.** Use `ActivityContent` for all
-   `Activity.request`, `update`, and `end` calls. The `contentState`-based
-   methods are deprecated.
-
-7. **Not handling the stale state.** Check `context.isStale` in Live Activity
-   views and show a fallback (e.g., "Updating...") when content is outdated.
-
-8. **Putting heavy logic in the widget view.** Widget views are rendered in a
-   size-limited process. Pre-compute data in the timeline provider and pass
-   display-ready values through the entry.
-
-9. **Ignoring accessory rendering modes.** Lock Screen widgets render in
-   `.vibrant` or `.accented` mode, not `.fullColor`. Test with
-   `@Environment(\.widgetRenderingMode)` and avoid relying on color alone.
-
-10. **Not testing on device.** Dynamic Island and StandBy behavior differ
-    significantly from Simulator. Always verify on physical hardware.
+- **Old provider.** `IntentTimelineProvider` belongs to the SiriKit Intents era;
+  write `AppIntentTimelineProvider`.
+- **Burning the budget.** Calling `WidgetCenter.shared.reloadTimelines(ofKind:)`
+  after every small change drains refreshes. Batch changes and pick the right
+  `TimelineReloadPolicy`.
+- **No App Group.** The extension runs in its own process. Share data through
+  `UserDefaults(suiteName:)` or the shared container.
+- **Networking in `placeholder()`.** It must return sample data synchronously;
+  fetch in `getTimeline` or `timeline(for:in:)`.
+- **Missing plist key.** If the main app's Info.plist lacks
+  `NSSupportsLiveActivities = YES`, no Live Activity will start.
+- **Deprecated state APIs.** The request, update and end calls that take a bare
+  `contentState` are deprecated; pass `ActivityContent`.
+- **Ignoring staleness.** Read `context.isStale` in the Live Activity view and
+  show something like "Updating..." when it is true.
+- **Work in the view.** Widget views render in a memory-capped process. Compute
+  in the provider and pass ready-to-show values.
+- **Assuming full color on the Lock Screen.** Lock Screen widgets draw in
+  `.vibrant` or `.accented`, not `.fullColor`. Check
+  `@Environment(\.widgetRenderingMode)` and never carry meaning by color alone.
+- **Trusting the Simulator.** Dynamic Island and StandBy behave differently on
+  real devices; test there.
 
 ## Review Checklist
 
-- [ ] Widget extension target has App Groups entitlement matching the main app
-- [ ] `@main` is on the `WidgetBundle`, not on individual widgets
-- [ ] `placeholder(in:)` returns synchronously; `getSnapshot`/`snapshot(for:in:)` fast when `isPreview`
-- [ ] Timeline reload policy matches update frequency; `reloadTimelines(ofKind:)` only on data change
-- [ ] Layout adapts per `WidgetFamily`; accessory widgets tested in `.vibrant` mode
-- [ ] Interactive widgets use `AppIntent` with `Button`/`Toggle` only
-- [ ] Live Activity: `NSSupportsLiveActivities = YES`; `ActivityContent` used; Dynamic Island closures implemented
-- [ ] `activity.end(_:dismissalPolicy:)` called; controls use `StaticControlConfiguration`/`AppIntentControlConfiguration`
-- [ ] Timeline entries and Intent types are Sendable; tested on device
+- [ ] App and extension share the same App Groups entitlement
+- [ ] `@main` sits on the `WidgetBundle`, not on a single widget
+- [ ] `placeholder(in:)` is synchronous; the snapshot is quick when `isPreview`
+- [ ] Reload policy fits how often data changes; `reloadTimelines(ofKind:)` fires only on real changes
+- [ ] Layout adapts per family; accessory widgets checked in `.vibrant`
+- [ ] Interactive elements are `Button` or `Toggle` driven by an `AppIntent`
+- [ ] Live Activity: Info.plist key present, `ActivityContent` used, all Dynamic Island closures written, `activity.end(_:dismissalPolicy:)` reached
+- [ ] Controls use `StaticControlConfiguration` or `AppIntentControlConfiguration`
+- [ ] Entry and intent types conform to `Sendable`
+- [ ] Verified on a physical device
 
 ## References
 
-- Advanced guide: [references/widgetkit-advanced.md](references/widgetkit-advanced.md)
-- Apple docs: [WidgetKit](https://sosumi.ai/documentation/widgetkit) | [ActivityKit](https://sosumi.ai/documentation/activitykit) | [Keeping a widget up to date](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)
+- Longer patterns: [advanced reference](references/widgetkit-advanced.md)
+- [WidgetKit](https://developer.apple.com/documentation/widgetkit)
+- [ActivityKit](https://developer.apple.com/documentation/activitykit)
+- [Keeping a widget up to date](https://developer.apple.com/documentation/widgetkit/keeping-a-widget-up-to-date)