# Convenience Property Macros
**SDK Version:** iOS 26.0 and later

If the user's deployment target is below iOS 26 / macOS 26 / watchOS 26 / tvOS 26 / visionOS 26, the new APIs in this reference (`@ComputedProperty` and `@DeferredProperty`, including their `title:`, `indexingKey:`, and `customIndexingKey:` overloads) require availability gating. The base `@ComputedProperty()` / `@ComputedProperty(title:)` and `@DeferredProperty()` / `@DeferredProperty(title:)` macros floor at 26.0 across iOS, macOS, watchOS, tvOS, and visionOS; the CoreSpotlight `indexingKey:` / `customIndexingKey:` overloads are iOS 26.0 / macOS 26.0 / visionOS 26.0 only (no watchOS/tvOS). See "Deployment target below SDK 26" below for the gating shape to use.

`@ComputedProperty` and `@DeferredProperty` are peer/accessor macros for `AppEntity` properties that project a value from the entity's source of truth at access time instead of snapshotting a stale copy into a stored `@Property`. `@ComputedProperty` reads synchronously and cheaply; `@DeferredProperty` backs an `get async throws` accessor for expensive or lazy values. Both are read-only projections: apply them only to derived, non-writable values — never to `id` or to any user-editable state, which stays a stored `@Property`. Because these run against the backing model, the store is threaded into the entity through its `init` (from its `EntityQuery`), not injected onto the entity.

## @ComputedProperty

`@ComputedProperty` attaches `get`/`set` accessors to an `AppEntity` property that reads **synchronously** from the entity's backing model on every access, so the value is always current with no manual refresh path. Use it when the value is always in memory and computing it is cheap (a field lookup or trivial format). The bare `@ComputedProperty()` and `@ComputedProperty(title:)` forms carry the value; the getter body must be non-async and non-throwing.

```swift
@available(iOS 26.0, *)
struct LandmarkEntity: AppEntity {
    let id: UUID
    private let store: ModelData

    init(id: UUID, store: ModelData) {
        self.id = id
        self.store = store
    }

    @ComputedProperty
    var isFavorite: Bool { store.landmark(id)?.isFavorite ?? false }

    static var defaultQuery = LandmarkEntityQuery()
}
```

**Availability:** `@ComputedProperty()` and `@ComputedProperty(title:)` are iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0.

## @ComputedProperty with Spotlight indexing

`@ComputedProperty(indexingKey:)` and `@ComputedProperty(title:indexingKey:)` take a `PartialKeyPath<CSSearchableItemAttributeSet>`, and `@ComputedProperty(customIndexingKey:)` / `@ComputedProperty(title:customIndexingKey:)` take a `CSCustomAttributeKey`, mapping the computed value into a Spotlight attribute in one declaration. These overloads map the computed value into CoreSpotlight's `CSSearchableItemAttributeSet`, and AppIntents gates them off watchOS/tvOS, so they are narrower than the base macro.

```swift
@available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
@available(watchOS, unavailable) @available(tvOS, unavailable)
extension LandmarkEntity {
    @ComputedProperty(title: "Name", indexingKey: \.displayName)
    var indexedName: String { store.landmark(id)?.name ?? "" }
}
```

**Availability:** the `indexingKey:` and `customIndexingKey:` overloads are iOS 26.0, macOS 26.0, visionOS 26.0 (no watchOS/tvOS).

## @DeferredProperty

`@DeferredProperty` has the same shape as `@ComputedProperty` (attaches `get`/`set`), but the backing getter is declared `get async throws` — the system evaluates it lazily, only when the value is actually needed, and it can await and throw. Use it for values that require I/O, network, decoding, or a slow computation you don't want to pay on every entity materialization. The bare `@DeferredProperty()` and `@DeferredProperty(title:)` forms carry the value.

```swift
@available(iOS 26.0, *)
struct LandmarkEntity: AppEntity {
    let id: UUID
    private let store: ModelData

    init(id: UUID, store: ModelData) {
        self.id = id
        self.store = store
    }

    @DeferredProperty(title: "Conditions")
    var conditions: String {
        get async throws {
            try await store.fetchWeather(id).summary
        }
    }

    static var defaultQuery = LandmarkEntityQuery()
}
```

**Availability:** `@DeferredProperty()` and `@DeferredProperty(title:)` are iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0.

## @DeferredProperty with Spotlight indexing

`@DeferredProperty(indexingKey:)` and `@DeferredProperty(title:indexingKey:)` take a `PartialKeyPath<CSSearchableItemAttributeSet>`, mapping the deferred value into a Spotlight attribute. As with `@ComputedProperty`, these bridge to CoreSpotlight and are unavailable on watchOS/tvOS. `@DeferredProperty` has no `customIndexingKey:` overload.

```swift
// Gate the enclosing type/extension, never the property.
@available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
@available(watchOS, unavailable) @available(tvOS, unavailable)
extension LandmarkEntity {
    @DeferredProperty(title: "Conditions", indexingKey: \.contentDescription)
    var conditions: String {
        get async throws {
            try await store.fetchWeather(id).summary
        }
    }
}
```

**Availability:** the `indexingKey:` overloads are iOS 26.0, macOS 26.0, visionOS 26.0 (no watchOS/tvOS).

## Read-only projections only

Both macros produce read-only projections of the entity's source of truth. Never apply `@ComputedProperty` or `@DeferredProperty` to `id` or to any writable, user-editable value — identity and intent-input state stay a stored `let` or `@Property`. Keep the `@ComputedProperty` body synchronous, non-throwing, and free of I/O; if the value needs to await or throw, it belongs in `@DeferredProperty`'s `get async throws` accessor instead.

## Deployment target below SDK 26

When the user's deployment target is below SDK 26 and the answer needs any of the macros above, gate the **enclosing type or extension** behind an availability check and provide a fallback for older OS versions:

```swift
@available(iOS 26.0, *)
extension LandmarkEntity {
    @ComputedProperty
    var isFavorite: Bool { store.landmark(id)?.isFavorite ?? false }
}
```

Gate to the macro's real floor: the base `@ComputedProperty()` / `@DeferredProperty()` (and their `title:` forms) at iOS 26.0 / macOS 26.0 / watchOS 26.0 / tvOS 26.0 / visionOS 26.0, and the `indexingKey:` / `customIndexingKey:` overloads at iOS 26.0 / macOS 26.0 / visionOS 26.0 only (no watchOS/tvOS). For deployment targets below 26, keep a stored `@Property` fallback populated in `init` for the older path. Don't emit unconditional uses of these macros; the typecheck will fail with `'ComputedProperty' is only available in iOS 26.0 or newer`.

# Cross-Device Entities & Ownership
**SDK Version:** iOS 27.0 and later

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the APIs in this reference (`SyncableEntity`, `SyncableEntityIdentifier`, `EntityOwnership`, and `OwnershipProvidingEntity`) require availability gating. All four are `anyAppleOS 27.0` and have no earlier back-deployment. See "Deployment target below SDK 27" below for the gating shape to use.

The same logical entity often lives on more than one of a person's devices — a landmark synced through CloudKit shows up on their iPhone, iPad, and Mac — and it may be private to them, shared into a collaborative plan, or shared publicly. The 2027 SDKs add `SyncableEntity` (with `SyncableEntityIdentifier`) so an entity keeps a stable identity as it moves between devices, and `OwnershipProvidingEntity` (with `EntityOwnership`) so the system can tell whether an entity is the person's own, shared, or public before acting on it. In the examples below, `LandmarkEntity` is a landmark synced across a person's devices and `TravelPhotoEntity` is a photo from a trip that the person may keep private, share into a group album, or share publicly.

## SyncableEntity

`SyncableEntity` refines `AppEntity` for an entity whose identity must survive travelling between a person's devices. A per-device local id (for example a SwiftData `persistentID`) is not enough: a shortcut created on iPhone must still resolve on iPad, where that local id was never minted. The protocol itself adds no requirements beyond `AppEntity`; its purpose is to pair the entity with a `SyncableEntityIdentifier` for its `ID`.

```swift
@available(iOS 27.0, *)
struct LandmarkEntity: SyncableEntity {
    // LocalID = the local store UUID; StableID = the CloudKit record name.
    let id: SyncableEntityIdentifier<UUID, String>

    @Property(title: "Name") var name: String

    static let typeDisplayRepresentation = TypeDisplayRepresentation(name: "Landmark")
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(name)") }

    static let defaultQuery = LandmarkEntityQuery()

    init(local: UUID, cloudKitID: String, name: String) {
        self.id = SyncableEntityIdentifier(local: local, stable: cloudKitID)
        self.name = name
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## SyncableEntityIdentifier

`SyncableEntityIdentifier<LocalID, StableID>` is the identifier a `SyncableEntity` uses for its `ID`. It carries an optional `local` id (a fast lookup key on the device that owns the local store) and an optional `stable` id (the cross-device key). Both `LocalID` and `StableID` must be `EntityIdentifierConvertible & Sendable`. The identifier is itself `Sendable`, `Equatable`, `Hashable`, `CustomStringConvertible`, and `EntityIdentifierConvertible`, so the framework can round-trip it through a string the way it does any entity id.

The designated initializer, `init(local:stable:)`, takes both keys as non-optional — you construct one when you hold both. The stored `local` and `stable` properties are optional because the framework can hand you back an identifier that has lost one side of the pair (for example an id round-tripped from a device that never saw the local store), so an `EntityQuery` must branch on whichever key survived.

```swift
@available(iOS 27.0, *)
struct LandmarkEntityQuery: EntityQuery {
    func entities(for identifiers: [LandmarkEntity.ID]) async throws -> [LandmarkEntity] {
        var results: [LandmarkEntity] = []
        for id in identifiers {
            if let local = id.local, let hit = try await ModelData.shared.landmark(localID: local) {
                results.append(LandmarkEntity(hit))          // fast path, same device
            } else if let stable = id.stable, let hit = try await ModelData.shared.landmark(cloudKitID: stable) {
                results.append(LandmarkEntity(hit))          // cross-device fallback
            }
        }
        return results
    }
}
```

When the local and stable ids are the same type and value, `init(id:)` is available where `LocalID == StableID`:

```swift
@available(iOS 27.0, *)
let sharedID = SyncableEntityIdentifier(id: recordName)   // LocalID == StableID == String
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## EntityOwnership

`EntityOwnership` is an `OptionSet` (also `Sendable`) that describes how a person relates to an entity. It has three static members: `.unknown`, `.shared`, and `.public`. There is no `.private` or `.owned` case, and crucially **`.unknown` is the empty set** (`EntityOwnership.unknown == []`, rawValue 0): an entity that is neither shared nor public — *including the person's own* — has neither bit set, which is the same value as `.unknown`. You therefore cannot distinguish "owned" from "unknown." Because it is an `OptionSet`, you construct values with set-literal syntax and combine bits where an entity is genuinely more than one thing.

```swift
let ownedOrUnknown: EntityOwnership = []   // == .unknown (the framework's "unknown or unspecified"); also what you return for the person's own/private data
let shared: EntityOwnership = .shared      // the person shares it with specific collaborators
let published: EntityOwnership = .public   // the person shares this data publicly
```

Because `.unknown == []`, there is no separate "ownership is undetermined" value to return — don't write logic that tries to tell `.unknown` apart from an owned/empty set. Set the `.shared` and/or `.public` bits when they apply; leave the set empty (`[]`) otherwise.

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## OwnershipProvidingEntity

`OwnershipProvidingEntity` refines `AppEntity` with a single requirement, `var ownership: EntityOwnership { get }`. Conform to it when an entity type spans private, shared, and public data, so the system knows the ownership of a given value before it acts on, surfaces, or forwards it. In particular, the system uses this to gate confirmation: acting on a `.shared` or `.public` entity can prompt the person to confirm — because the action reaches beyond their own data — where an owned entity would proceed without that extra step.

```swift
@available(iOS 27.0, *)
struct TravelPhotoEntity: OwnershipProvidingEntity {
    let id: UUID
    @Property(title: "Caption") var caption: String
    let source: PhotoSource   // .mine / .sharedWithMe / .sharedPublicly

    var ownership: EntityOwnership {
        switch source {
        case .mine:            return []          // own/private data — no shared/public bits
        case .sharedWithMe:    return .shared
        case .sharedPublicly:  return .public
        }
    }

    static let typeDisplayRepresentation = TypeDisplayRepresentation(name: "Travel Photo")
    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(caption)") }
    static let defaultQuery = TravelPhotoQuery()
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Deployment target below SDK 27

When the user's deployment target is below SDK 27 and the answer needs any of the APIs above, gate every use with `@available(iOS 27.0, *)` (or the matching `anyAppleOS 27.0` platforms) on the enclosing declaration, and keep an entity that still works on older systems as the fallback:

```swift
@available(iOS 27.0, *)
struct LandmarkEntity: SyncableEntity {
    let id: SyncableEntityIdentifier<UUID, String>
    // …
}

// Fallback for deployment targets below iOS 27: a plain AppEntity keyed on the local id.
struct LegacyLandmarkEntity: AppEntity {
    let id: UUID
    // …
}
```

Guard runtime paths that read `ownership` or construct a `SyncableEntityIdentifier` with `if #available(iOS 27.0, *)`. Don't emit unconditional calls to these APIs; the typecheck will fail with `'<API>' is only available in iOS 27.0 or newer`.

# EntityCollection
**SDK Version:** iOS 27.0 and later

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the `EntityCollection<Entity>` type in this reference requires availability gating. It floors uniformly at 27.0 across iOS, macOS, watchOS, tvOS, and visionOS (declared `@available(anyAppleOS 27.0, *)`).

`EntityCollection<Entity>` is a value type that stores an ordered list of entity **identifiers** (`[Entity.ID]`) up front and defers materializing the full `AppEntity` instances until you explicitly ask for them. Use it anywhere you would otherwise hold a large `[Entity]` but only need the identifiers for most of the work — a Shortcuts action operating on hundreds of selected items, a batch mutation keyed by id, or an `@Property` on an entity that references many others. The win is at parameter-resolution time: a `@Parameter var items: [Entity]` forces the system to resolve every id into a fully hydrated entity before your `perform()` runs; `@Parameter var items: EntityCollection<Entity>` hands you the ids cheaply and lets you resolve on demand.

## `[Entity]` vs `EntityCollection<Entity>` as a parameter

The core adoption decision. With `[Entity]`, the system resolves and hydrates every identifier into a full entity during parameter resolution — for hundreds of entities that is expensive memory and time at a critical moment. With `EntityCollection<Entity>`, resolution only carries the identifiers; you hydrate later (or never, if you only need ids).

```swift
// AVOID: forces the system to hydrate every entity during parameter resolution.
struct DisableAlarmsIntent: AppIntent {
    static var title: LocalizedStringResource = "Disable Alarms"

    @Parameter(title: "Alarms")
    var alarms: [AlarmEntity]   // hundreds of full entities materialized up front

    func perform() async throws -> some IntentResult {
        try await AlarmService.disable(alarms.map(\.id))
        return .result()
    }
}

// PREFER: identifiers carried cheaply; no forced hydration.
@available(iOS 27.0, *)
struct DisableAlarmsIntent: AppIntent {
    static var title: LocalizedStringResource = "Disable Alarms"

    @Parameter(title: "Alarms")
    var alarms: EntityCollection<AlarmEntity>

    func perform() async throws -> some IntentResult {
        // Only ids are needed, so nothing is hydrated.
        try await AlarmService.disable(alarms.identifiers)
        return .result()
    }
}
```

**Availability:** `EntityCollection<Entity>` is iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Constructing a collection

`init(identifiers:)` is the cheap path — it stores the ids and nothing else (the `identifiers:` argument defaults to `[]`, so `EntityCollection()` gives an empty collection). `init(entities:)` maps each entity to its id **and** pre-caches the entity instances, so a later `resolvedEntities()` returns them without a query. `EntityCollection` also conforms to `ExpressibleByArrayLiteral` over `Entity.ID`, so an array literal of ids is sugar for `init(identifiers:)`.

```swift
@available(iOS 27.0, *)
func makeCollections(ids: [AlarmEntity.ID], entities: [AlarmEntity]) {
    let cheap = EntityCollection<AlarmEntity>(identifiers: ids)   // ids only
    let cached = EntityCollection(entities: entities)            // pre-caches entities
    let literal: EntityCollection<AlarmEntity> = [ids[0], ids[1]] // array-literal sugar
    _ = (cheap, cached, literal)
}
```

**Availability:** `init(identifiers:)`, `init(entities:)`, and the `ExpressibleByArrayLiteral` conformance are iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Hydrating with `resolvedEntities()`

When you need the full entities, call `resolvedEntities() async throws -> [Entity]`. If the collection was built with `init(entities:)` (or has already been resolved once), it returns the cached instances; otherwise it uses `Entity.defaultQuery` to fetch them and caches the result, so the second call is free. Hydrate once and reuse — do not call it inside a hot loop.

```swift
@available(iOS 27.0, *)
func perform(alarms: EntityCollection<AlarmEntity>) async throws {
    // AVOID: re-resolving per iteration (each call may run the default query).
    for id in alarms.identifiers {
        let all = try await alarms.resolvedEntities()   // wasteful in a loop
        _ = all.first { $0.id == id }
    }

    // PREFER: hydrate once, then work against the array.
    let entities = try await alarms.resolvedEntities()
    for entity in entities {
        await process(entity)
    }
}
```

**Availability:** `resolvedEntities()` is iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Working with the identifiers

The `identifiers` property is public and directly accessible. `count` and `isEmpty` report on the identifiers without hydrating. `EntityCollection` conforms to `Collection` with `Element == Entity.ID`, so iterating it yields **identifiers, not entities**. Mutating helpers `append(_:)` (by id or by entity), `append(contentsOf:)`, and `remove(_:)` (by id or entity, requires `Entity.ID: Equatable`) let you edit the id list in place, and `contains(_:)` (by id or entity, `Entity.ID: Equatable`) checks membership — all without touching the hydration cache.

```swift
@available(iOS 27.0, *)
func editCollection(_ alarms: inout EntityCollection<AlarmEntity>, extra: AlarmEntity) {
    guard !alarms.isEmpty else { return }
    for id in alarms {                 // Collection iteration yields Entity.ID
        print(id)
    }
    alarms.append(extra)               // appends extra.id
    if alarms.contains(extra) {        // membership by entity (Entity.ID: Equatable)
        alarms.remove(extra)
    }
    print(alarms.count)
}
```

**Availability:** `identifiers`, `count`, `isEmpty`, the `Collection` conformance, and the `append`/`remove`/`contains` helpers are iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Using it as `@Parameter` and `@Property`

`EntityCollection` is usable both as an app intent `@Parameter` and as an `@Property` on an `AppEntity` — the same deferred-hydration behavior applies in both roles. As a property it lets an entity reference many related entities by id without forcing those references to hydrate whenever the owning entity is materialized.

```swift
@available(iOS 27.0, *)
struct PlaylistEntity: AppEntity {
    let id: UUID

    @Property(title: "Songs")
    var songs: EntityCollection<SongEntity>   // ids stored; hydrate on demand

    static var defaultQuery = PlaylistQuery()
}
```

**Availability:** usage as `@Parameter` and `@Property` follows the type's floor — iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Traps

`Equatable` on `EntityCollection` compares **identifiers only** — the hydration cache is ignored, so a freshly-built `init(identifiers:)` collection and an `init(entities:)` collection with the same ids compare equal even though one has cached entities and the other doesn't. Don't rely on `==` to tell you whether entities have been hydrated. And because `resolvedEntities()` runs the default query on a cold collection, calling it repeatedly (e.g. once per loop iteration) defeats the whole point of deferring hydration — resolve once, then iterate the returned `[Entity]`.

## Deployment target below SDK 27

When the user's deployment target is below SDK 27 and the answer needs `EntityCollection`, gate the parameter, property, or enclosing declaration behind an availability check and provide a fallback for older OS versions:

```swift
@available(iOS 27.0, *)
struct DisableAlarmsIntent: AppIntent {
    static var title: LocalizedStringResource = "Disable Alarms"

    @Parameter(title: "Alarms")
    var alarms: EntityCollection<AlarmEntity>

    func perform() async throws -> some IntentResult {
        try await AlarmService.disable(alarms.identifiers)
        return .result()
    }
}
```

Gate to the type's real floor: iOS 27.0 / macOS 27.0 / watchOS 27.0 / tvOS 27.0 / visionOS 27.0. For deployment targets below 27, keep a `[Entity]` (or `[Entity.ID]`) parameter as the fallback path. Don't emit unconditional uses of `EntityCollection`; the typecheck will fail with `'EntityCollection' is only available in iOS 27.0 or newer`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|-----|-----|-------|---------|------|----------|
| `EntityCollection<Entity>` (type) | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `init(identifiers:)` / `init(entities:)` / array-literal | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `identifiers` / `count` / `isEmpty` | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `resolvedEntities()` | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `Collection` conformance (yields `Entity.ID`) | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `append` / `remove` / `contains` | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| Use as `@Parameter` / `@Property` | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |

# Execution Modes, Foreground Continuation & Long-Running Intents
**SDK Version:** iOS 26.0 and later

If the user's deployment target is below iOS 26 / macOS 26 / watchOS 26 / tvOS 26 / visionOS 26, the new APIs in this reference (`supportedModes` / `IntentModes`, `continueInForeground(_:alwaysConfirm:)`, `needsToContinueInForegroundError(_:alwaysConfirm:)`, `UndoableIntent`) require availability gating; `CancellableIntent` / `IntentCancellationReason` are iOS 26.4 and later, and `LongRunningIntent` / `performBackgroundTask(options:operation:)` / `LongRunningTaskOptions` / `IntentExecutionTargets` / `allowedExecutionTargets` are iOS 27.0 and later.

iOS 26 replaces the boolean `openAppWhenRun` flag with a declarative `IntentModes` option set, so an intent states where it runs (background, foreground, or a runtime-decided mix) and only escalates to the foreground when its code actually asks. The same releases add first-class cancellation and undo, and iOS 27 adds system-managed background execution that can outlive the caller plus control over which process runs the intent. The examples use the WWDC TravelTracking sample, with `LandmarkEntity`, `GetCrowdStatusIntent`, and `TagPhotosIntent`.

## Supported modes

`supportedModes: IntentModes` declares where an intent runs. Use `.background` for headless work; `.foreground` (equivalent to `.foreground(.immediate)`) to switch to the app **before** `perform()` runs; or `.foreground(_:)` with a `ForegroundMode` — `.immediate` (switch before `perform()` runs), `.deferred` (start work first, switch when content is ready), or `.dynamic` (decide at runtime). `IntentModes` is an `OptionSet`, so combine them: `[.background, .foreground(.dynamic)]` starts in the background and escalates on demand. Omitting the property defaults to `.background` for a plain intent — the system derives the default (a legacy `openAppWhenRun = true` maps to `.foreground`; a URL-representable `OpenIntent` maps to `.background`). The old `static var openAppWhenRun: Bool` is deprecated in 26.0; declare `supportedModes` and delete the flag.

```swift
@available(iOS 26.0, *)
struct TagPhotosIntent: AppIntent {
    static let title: LocalizedStringResource = "Tag Photos"
    // Try to tag headlessly; escalate to the app only when needed.
    static var supportedModes: IntentModes { [.background, .foreground(.dynamic)] }

    func perform() async throws -> some IntentResult {
        // ...
        return .result()
    }
}
```

**Availability:** iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0.

## Foreground continuation

An intent declared `[.background, .foreground(.dynamic)]` starts in the background and can pull itself into the foreground only when it needs to. Call `continueInForeground(_:alwaysConfirm:)` to escalate inline and keep running after the switch, or `throw needsToContinueInForegroundError(_:alwaysConfirm:)` when the intent cannot proceed at all without the app and you want the system to prompt. Pass `alwaysConfirm: false` to skip the confirmation dialog when the surface already implies intent. Some contexts (voice-only, certain widgets) cannot bring the app forward, so guard on `systemContext.currentMode.canContinueInForeground` first; calling `continueInForeground` in a context that cannot foreground throws.

```swift
@available(iOS 26.0, *)
struct GetCrowdStatusIntent: AppIntent {
    static let title: LocalizedStringResource = "Get Crowd Status"
    static var supportedModes: IntentModes { [.background, .foreground(.dynamic)] }

    @Parameter var landmark: LandmarkEntity

    func perform() async throws -> some IntentResult {
        guard try await needsFullEditor(for: landmark) else {
            return .result()   // finished in the background, never touched UI
        }
        guard systemContext.currentMode.canContinueInForeground else {
            throw needsToContinueInForegroundError("Open \(landmark.name) to review crowd status")
        }
        try await continueInForeground("Continue in the app?", alwaysConfirm: false)
        await presentCrowdStatus(for: landmark)   // now foreground — safe to present UI
        return .result()
    }
}
```

**Availability:** iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0. (`systemContext.currentMode` and `IntentModes.Current.canContinueInForeground` share the same availability.)

## Undoable intents

`UndoableIntent` refines `SystemIntent` and exposes a `@MainActor` `undoManager: UndoManager?`. Register an undo action against it so the system can offer Undo for the intent's effect. Because `undoManager` is `@MainActor`, touch it only from a main-actor context — mark `perform()` `@MainActor` or hop explicitly.

```swift
@available(iOS 26.0, *)
struct DeleteLandmarkIntent: AppIntent, UndoableIntent {
    static let title: LocalizedStringResource = "Delete Landmark"
    @Parameter var landmark: LandmarkEntity

    @MainActor
    func perform() async throws -> some IntentResult {
        let snapshot = try await ModelData.shared.delete(landmark)
        undoManager?.registerUndo(withTarget: ModelData.shared) { $0.restore(snapshot) }
        return .result()
    }
}
```

**Availability:** iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0.

## Cancellable intents

`CancellableIntent` lets an intent observe cancellation with a reason. Wrap the cancellable work in `withIntentCancellationHandler(operation:onCancel:)`; the `onCancel` handler receives an `IntentCancellationReason`, which is either `.timeout` or `.userCancelled`, so you can distinguish a system timeout from an explicit user cancel.

```swift
@available(iOS 26.4, *)
struct GetCrowdStatusIntent: AppIntent, CancellableIntent {
    static let title: LocalizedStringResource = "Get Crowd Status"
    @Parameter var landmark: LandmarkEntity

    func perform() async throws -> some IntentResult {
        try await withIntentCancellationHandler {
            try await ModelData.shared.fetchCrowdStatus(for: landmark)
        } onCancel: { reason in
            ModelData.shared.stopFetch(dueTo: reason)   // .timeout or .userCancelled
        }
        return .result()
    }
}
```

**Availability:** iOS 26.4, macOS 26.4, watchOS 26.4, tvOS 26.4, visionOS 26.4.

## Long-running intents

On iOS, iPadOS, watchOS, tvOS, and visionOS a background App Intent gets only about 30 seconds to finish before the system ends it (macOS has no such limit). So before iOS 27, work that ran longer than that risked being terminated when the window closed or the initiating surface went away. `LongRunningIntent` hands the work to a system-managed background task (BGContinuedProcessingTask) via `performBackgroundTask(options:operation:)`, which extends runtime past that limit and survives the initiating surface disappearing.

`LongRunningIntent` refines `ProgressReportingIntent`, so a Foundation `progress` object drives determinate progress, and the system's Live Activity displays that progress automatically with no presentation code of your own: `progress.localizedDescription` / `localizedAdditionalDescription` become the title and subtitle, and `completedUnitCount` / `totalUnitCount` drive the progress bar. Pass `options: .requiresGPU` (a `LongRunningTaskOptions` value) to tell the system the task needs GPU resources so it schedules accordingly. A second overload, `performBackgroundTask(options:operation:onCancel:)`, is available only when the intent also conforms to `CancellableIntent`, and its `onCancel` closure receives an `IntentCancellationReason`.

```swift
@available(iOS 27.0, *)
struct TagPhotosIntent: AppIntent, LongRunningIntent, CancellableIntent {
    static let title: LocalizedStringResource = "Tag Photos"
    static var supportedModes: IntentModes { .background }

    func perform() async throws -> some IntentResult {
        // The system observes self.progress via KVO and mirrors it to the Live Activity.
        progress.localizedDescription = "Tagging photos…"   // becomes the Live Activity title
        let tagged = try await performBackgroundTask(options: .requiresGPU) {
            try await ModelData.shared.tagPhotos { done, total in
                self.progress.totalUnitCount = Int64(total)
                self.progress.completedUnitCount = Int64(done)  // drives the progress bar
            }
        } onCancel: { reason in
            ModelData.shared.abortTagging(reason: reason)   // .timeout or .userCancelled
        }
        return .result(dialog: "Tagged \(tagged) photos")
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0. (`LongRunningTaskOptions.requiresGPU` and the `onCancel:` overload share the same availability; the `onCancel:` overload additionally requires `Self: CancellableIntent`, iOS 26.4.)

## Execution targets

`allowedExecutionTargets: IntentExecutionTargets` pins which process runs an intent. `IntentExecutionTargets` is an `OptionSet` with `.default` (the system chooses — the default value), `.main` (the main app, for in-memory caches or live navigator state), `.appIntentsExtension` (the App Intents extension), and `.widgetKitExtension` (the WidgetKit extension, for latency-sensitive widget-driven runs). Prefer `.default` unless the code genuinely needs a specific process, since forcing `.main` defeats extension-based execution and adds launch latency.

```swift
@available(iOS 27.0, *)
struct AdvanceNavigationIntent: AppIntent {
    static let title: LocalizedStringResource = "Advance Navigation"
    static var supportedModes: IntentModes { .background }
    // Needs the main app's live navigator singleton.
    static var allowedExecutionTargets: IntentExecutionTargets { .main }

    @Parameter var meters: Double

    func perform() async throws -> some IntentResult {
        Navigator.shared.advance(by: meters)   // only valid in the main process
        return .result()
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `supportedModes` / `IntentModes` (`.background`, `.foreground`, `.foreground(.immediate/.deferred/.dynamic)`) | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |
| `continueInForeground(_:alwaysConfirm:)` / `needsToContinueInForegroundError(_:alwaysConfirm:)` | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |
| `systemContext.currentMode.canContinueInForeground` | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |
| `UndoableIntent` (`@MainActor undoManager`) | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |
| `CancellableIntent` / `IntentCancellationReason` / `withIntentCancellationHandler` | 26.4 | 26.4 | 26.4 | 26.4 | 26.4 |
| `LongRunningIntent` / `performBackgroundTask(options:operation:)` / `LongRunningTaskOptions` | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `IntentExecutionTargets` / `allowedExecutionTargets` | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |

# Interactive Snippets
**SDK Version:** iOS 26.0 and later

If the user's deployment target is below iOS 26, the new APIs in this reference (the `SnippetIntent` protocol, the `ShowsSnippetIntent` capability and its `result(snippetIntent:)` factories, `requestConfirmation(actionName:snippetIntent:)`, `EmptySnippetIntent`, and `SnippetIntent.reload()`) require availability gating. The static `ShowsSnippetView` snippet (`result(view:)` / `result { }`, iOS 16.0) and the `Button(intent:)` / `Toggle(isOn:intent:)` controls (iOS 17.0) back-deploy further and do not need iOS 26 gating on their own — it is the *live-snippet refresh* behavior that is new. See "Deployment target below SDK 26" below for the gating shape to use.

Before iOS 26 an App Intent could only show a static snapshot from `result(view:)`, so any control inside it was dead — its taps ran no code. iOS 26 adds interactive snippets: model the snippet as a `SnippetIntent`, return it from the main intent with `result(snippetIntent:)`, and host `Button(intent:)` / `Toggle(isOn:intent:)` controls whose taps run real intents. Those control intents can re-present the same snippet (or call `reload()`) to refresh it in place. The running example is Apple's **Landmarks** sample (the `AppIntentsTravelTracker` app): `ClosestLandmarkIntent` returns a `LandmarkSnippetIntent` that renders a `LandmarkView`, whose `Button(intent:)` controls favorite the landmark (`UpdateFavoritesIntent`) or find tickets (`FindTicketsIntent`).

## SnippetIntent and ShowsSnippetIntent

`SnippetIntent` is an `AppIntent` whose `PerformResult` is constrained to `ShowsSnippetView` — its `perform()` returns `some IntentResult & ShowsSnippetView` (a `result(view:)` snippet from the SwiftUI overlay). The *main* intent hands the system a live snippet by composing `ShowsSnippetIntent` into its return type and calling `.result(snippetIntent:)`; the system can re-run that `SnippetIntent` to redraw. `EmptySnippetIntent` is the factory's default argument when there is no snippet to show.

```swift
@available(iOS 26.0, *)
struct ClosestLandmarkIntent: AppIntent {
    static let title: LocalizedStringResource = "Find Closest Landmark"
    @Dependency var modelData: ModelData

    func perform() async throws -> some ReturnsValue<LandmarkEntity> & ShowsSnippetIntent & ProvidesDialog {
        let landmark = await findClosestLandmark()
        return .result(
            value: landmark,
            dialog: IntentDialog(
                full: "The closest landmark is \(landmark.name).",
                supporting: "\(landmark.name) is located in \(landmark.continent)."
            ),
            snippetIntent: LandmarkSnippetIntent(landmark: landmark)
        )
    }
}

@available(iOS 26.0, *)
struct LandmarkSnippetIntent: SnippetIntent {
    static let title: LocalizedStringResource = "Landmark Snippet"

    @Parameter var landmark: LandmarkEntity
    @Dependency var modelData: ModelData

    init() {}
    init(landmark: LandmarkEntity) { self.landmark = landmark }

    func perform() async throws -> some IntentResult & ShowsSnippetView {
        let isFavorite = await modelData.isFavorite(landmark)   // READ only
        return .result(view: LandmarkView(landmark: landmark, isFavorite: isFavorite))
    }
}
```

An intent you **construct with parameter values** — to pass as `snippetIntent:`, wire to `Button(intent:)`, or hand to `requestConfirmation` — needs a **custom `init` that assigns its `@Parameter`s**, plus the required no-argument `init()`. (Every snippet/control intent shown below does the same.)

**Availability:** the `SnippetIntent` protocol, `ShowsSnippetIntent`, `EmptySnippetIntent`, and the `result(snippetIntent:)` factories are iOS 26.0 (base AppIntents module). The `ShowsSnippetView` capability and the overlay `result(view:)` / `result { }` factories the snippet's own `perform()` returns are iOS 16.0.

## result(snippetIntent:) vs result(view:)

The two live at different layers. The **main** intent calls `result(snippetIntent:)` (iOS 26.0) to hand the system a `SnippetIntent` it can re-run to redraw — use it whenever the card has controls that act or state that changes. A `SnippetIntent` (or any display-only intent) renders its card with `result(view:)` (iOS 16.0, SwiftUI overlay), which bakes a one-time SwiftUI snapshot from the values captured at return time and never re-runs code. `result(snippetIntent:)` comes in `value:` / `dialog:` / `opensIntent:` combinations (as in `ClosestLandmarkIntent` above).

```swift
// Main intent: hand over a live snippet the system can re-run.
return .result(value: landmark, dialog: dialog,
               snippetIntent: LandmarkSnippetIntent(landmark: landmark))

// Inside the SnippetIntent (or a display-only intent): render a one-time snapshot.
return .result(view: LandmarkView(landmark: landmark, isFavorite: isFavorite))
```

**Availability:** `result(snippetIntent:)` and its `value:` / `dialog:` / `opensIntent:` combinations are iOS 26.0. `result(view:)` / `result { }` and their combinations are iOS 16.0 (active when the target imports both AppIntents and SwiftUI).

## Interactive controls with Button(intent:) and Toggle(isOn:intent:)

Inside a snippet view, wire controls to intents — `Button(intent:)` and `Toggle(isOn:intent:)` — never to closures. A tapped control runs the intent; `Button(action:)` / `.onTapGesture` closures inside a snippet run no code. `LandmarkView` wires a favorite button and a find-tickets button to their control intents:

```swift
struct LandmarkView: View {
    let landmark: LandmarkEntity
    let isFavorite: Bool

    var body: some View {
        // ...
        Button(intent: UpdateFavoritesIntent(landmark: landmark, isFavorite: !isFavorite)) {
            Label(isFavorite ? "Remove Favorite" : "Add Favorite", systemImage: "star")
        }
        Button(intent: FindTicketsIntent(landmark: landmark)) {
            Text("Find Tickets")
        }
        // ...
    }
}
```

For boolean state you can pair a `Toggle(isOn:intent:)` instead of a button — note `isOn:` takes a plain `Bool`, not a `Binding<Bool>`: the toggle doesn't own the state, the control intent does.

**Availability:** `Button(intent:)` and `Toggle(isOn:intent:)` are iOS 17.0 (SwiftUI cross-import overlay). They compile in any SwiftUI view; their *refresh-a-live-snippet* behavior requires the iOS 26.0 `SnippetIntent` host.

## Confirmation snippets with requestConfirmation(snippetIntent:)

A control intent can present its own snippet mid-run to confirm an action. `requestConfirmation(actionName:snippetIntent:)` (iOS 26.0) shows a `SnippetIntent` and suspends until the person confirms. `FindTicketsIntent` confirms a ticket search with a `TicketRequestSnippetIntent`:

```swift
@available(iOS 26.0, *)
struct FindTicketsIntent: AppIntent {
    static let title: LocalizedStringResource = "Find Tickets"

    @Parameter var landmark: LandmarkEntity
    @Dependency var searchEngine: SearchEngine

    init() {}
    init(landmark: LandmarkEntity) { self.landmark = landmark }

    func perform() async throws -> some IntentResult {
        let searchRequest = await searchEngine.createRequest(landmarkEntity: landmark)
        // Present a snippet that lets people adjust the request, then confirm.
        try await requestConfirmation(
            actionName: .search,
            snippetIntent: TicketRequestSnippetIntent(searchRequest: searchRequest)
        )
        // ...resume searching once confirmed...
        return .result()
    }
}

@available(iOS 26.0, *)
struct TicketRequestSnippetIntent: SnippetIntent {
    static let title: LocalizedStringResource = "Ticket Request Snippet"

    @Parameter var searchRequest: SearchRequestEntity

    init() {}
    init(searchRequest: SearchRequestEntity) { self.searchRequest = searchRequest }

    func perform() async throws -> some IntentResult & ShowsSnippetView {
        .result(view: TicketRequestView(searchRequest: searchRequest))
    }
}
```

**Availability:** `requestConfirmation(actionName:snippetIntent:)` is iOS 26.0.

## Refresh in place

The refresh paths are distinct — don't conflate them:

- **A control intent (a `Button` / `Toggle` tap) just returns `.result()`.** After it completes, the system **automatically re-runs the hosting `SnippetIntent.perform()`** and redraws with fresh state — you do *not* re-present the snippet from the control intent.
- **`.result(snippetIntent:)`** is for the *originating* or *transition* intent — the one that first shows a snippet, or switches to a *different* one.
- **`SnippetIntent.reload()`** refreshes the snippet from *outside* a tap — an out-of-band / `async` update completing elsewhere. Call it from that async context; it is not a substitute for the automatic re-run after a tap.

Put every mutation in the *control* intent, never in the snippet's `perform()` — and never point `Button(intent:)` / `Toggle(isOn:intent:)` at the `SnippetIntent` itself; always target a separate action intent.

```swift
// Control intent invoked by a snippet button: do the work, then just return .result().
// The system re-runs LandmarkSnippetIntent.perform() and redraws automatically.
@available(iOS 26.0, *)
struct UpdateFavoritesIntent: AppIntent {
    static let title: LocalizedStringResource = "Update Favorites"

    @Parameter var landmark: LandmarkEntity
    @Parameter var isFavorite: Bool
    @Dependency var modelData: ModelData

    init() {}
    init(landmark: LandmarkEntity, isFavorite: Bool) {
        self.landmark = landmark
        self.isFavorite = isFavorite
    }

    func perform() async throws -> some IntentResult {
        await modelData.setFavorite(landmark, isFavorite: isFavorite)   // the mutation
        return .result()                                               // no re-present needed
    }
}

// Out-of-band refresh (not a tap): re-run the snippet's perform() as async work completes.
@available(iOS 26.0, *)
func performRequest(_ request: SearchRequestEntity) async throws {
    // set a pending status...
    TicketResultSnippetIntent.reload()   // redraw: pending

    // ...await the search...
    TicketResultSnippetIntent.reload()   // redraw: results
}
```

**Availability:** `result(snippetIntent:)` and the static `SnippetIntent.reload()` are iOS 26.0.

## Side-effect-free SnippetIntent.perform()

`SnippetIntent.perform()` must be idempotent and side-effect-free: the system may re-run it on any redraw (state restoration, `reload()`, live refresh), so it must be a pure read that renders current state. `LandmarkSnippetIntent` only reads (`modelData.isFavorite(landmark)`); the mutation lives in `UpdateFavoritesIntent`, which the snippet's button invokes.

```swift
@available(iOS 26.0, *)
struct LandmarkSnippetIntent: SnippetIntent {
    static let title: LocalizedStringResource = "Landmark Snippet"

    @Parameter var landmark: LandmarkEntity
    @Dependency var modelData: ModelData

    init() {}
    init(landmark: LandmarkEntity) { self.landmark = landmark }

    func perform() async throws -> some IntentResult & ShowsSnippetView {
        // READ current state only — safe to run repeatedly.
        let isFavorite = await modelData.isFavorite(landmark)
        return .result(view: LandmarkView(landmark: landmark, isFavorite: isFavorite))
    }
}
```

**Availability:** iOS 26.0.

## Deployment target below SDK 26

When the user's deployment target is below SDK 26 and the answer needs interactive snippets, don't try to branch the two snippet styles inside one `perform()`: a single opaque `some IntentResult` return can't yield `.result(snippetIntent:)` on one path and the static `.result(view:)` overlay on another, because those are two different concrete result types and an opaque return must resolve to exactly one (the build fails with "do not have matching underlying types"). Instead gate at the *declaration* level — mark the interactive intent `@available(iOS 26.0, *)` and provide a separate, independently-typed fallback intent that returns a static result for earlier OSes.

```swift
// New: interactive-snippet intent, gated at the declaration.
@available(iOS 26.0, *)
struct ClosestLandmarkIntent: AppIntent {
    static let title: LocalizedStringResource = "Find Closest Landmark"
    @Dependency var modelData: ModelData

    func perform() async throws -> some ReturnsValue<LandmarkEntity> & ShowsSnippetIntent & ProvidesDialog {
        let landmark = await findClosestLandmark()
        return .result(value: landmark,
                       dialog: "The closest landmark is \(landmark.name).",
                       snippetIntent: LandmarkSnippetIntent(landmark: landmark))
    }
}

// Older targets: a separate intent returning a static, display-only result.
struct ClosestLandmarkLegacyIntent: AppIntent {
    static let title: LocalizedStringResource = "Find Closest Landmark"
    @Dependency var modelData: ModelData

    func perform() async throws -> some ReturnsValue<LandmarkEntity> & ProvidesDialog {
        let landmark = await findClosestLandmark()
        return .result(value: landmark,
                       dialog: "The closest landmark is \(landmark.name).")
    }
}
```

The `Button(intent:)` / `Toggle(isOn:intent:)` controls (iOS 17.0) and `result(view:)` (iOS 16.0) don't themselves need iOS 26 gating — only their use to refresh a live snippet does. Don't emit unconditional calls to `result(snippetIntent:)`, `requestConfirmation(actionName:snippetIntent:)`, the `SnippetIntent` protocol, or `SnippetIntent.reload()` on a sub-26 target; the typecheck will fail with `'<API>' is only available in iOS 26.0 or newer`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `SnippetIntent` protocol | 26 | 26 | 26 | 26 | 26 |
| `ShowsSnippetIntent`, `result(snippetIntent:)` | 26 | 26 | 26 | 26 | 26 |
| `requestConfirmation(actionName:snippetIntent:)` | 26 | 26 | 26 | 26 | 26 |
| `EmptySnippetIntent` | 26 | 26 | 26 | 26 | 26 |
| `SnippetIntent.reload()` | 26 | 26 | 26 | 26 | 26 |
| `ShowsSnippetView`, `result(view:)` / `result { }` | 16 | 13 | 9 | 16 | 1 |
| `Button(intent:)` / `Toggle(isOn:intent:)` | 17 | 14 | 10 | 17 | 1 |

# Onscreen Entities
**SDK Version:** iOS 18.2 and later

If the user's deployment target is below the availability listed for a given API in this reference (`NSUserActivity.appEntityIdentifier` / `AppEntityAnnotatable` are iOS 18.2; `EntityIdentifier(for:identifier:)` back-deploys to iOS 16.0, `EntityIdentifier(activityIdentifier:)` is iOS 18.0; the SwiftUI `.appEntityIdentifier(_:)` / `.appEntityIdentifier(forSelectionType:_:)` modifiers and `AppEntityUIElement` / `AppEntityUIElementsContext` are iOS 18.4), the usage requires availability gating. 

Onscreen entities let Siri and Apple Intelligence resolve "this" on the current screen to a concrete `AppEntity` — so a request like "add this to my list" binds to the entity the person is looking at. You do it by annotating the foreground `NSUserActivity` with the identifier of the entity being shown. This is a different surface from **visual-intelligence search** (matching camera/screenshot content — see `visual-intelligence.md`) and from **proactively surfacing** entities (`RelevantEntities` / `AppEntityContext` — see `relevance-and-context.md`). The running example is **CometCal, **a calendar app whose `EventEntity` is an `IndexedEntity` with `var id: UUID` and `var title: String`.

## Annotate NSUserActivity with the onscreen entity

For Siri or Apple Intelligence to resolve "this" while a detail screen is up, the foreground `NSUserActivity` must carry the identifier of the entity being shown. `NSUserActivity` conforms to `AppEntityAnnotatable`, which adds `var appEntityIdentifier: EntityIdentifier? { get set }`. Build the identifier with `EntityIdentifier(for:identifier:)` from the entity's type and id, and keep it in sync as the displayed entity changes.

In SwiftUI, the `.userActivity(_:element:_:)` modifier both keeps the activity current for the view and gives you a closure to populate it. CometCal's `EventDetailView` annotates the activity with the event being shown:

```swift
import AppIntents
import SwiftUI

// EventDetailView body, trailing modifiers
.userActivity("com.example.cometcal.viewEvent") { activity in
    activity.appEntityIdentifier = EntityIdentifier(
        for: EventEntity.self,
        identifier: event.id
    )   // the link that resolves "this"
}
```

Building the same identifier outside SwiftUI (e.g. when constructing an `NSUserActivity` by hand) follows the same shape — set `title`, assign `appEntityIdentifier`, and call `becomeCurrent()` on appearance:

```swift
import AppIntents

@available(iOS 18.2, *)
func makeActivity(for event: EventEntity) -> NSUserActivity {
    let activity = NSUserActivity(activityType: "com.example.cometcal.viewEvent")
    activity.title = event.title
    activity.appEntityIdentifier = EntityIdentifier(for: EventEntity.self, identifier: event.id)
    activity.becomeCurrent()
    return activity
}
```

When you already hold the entity value (not just its id), the single-argument `EntityIdentifier(for:)` builds the same identifier — `EntityIdentifier(for: event)` is equivalent to `EntityIdentifier(for: EventEntity.self, identifier: event.id)`. Reach for the two-argument form when you have only the type and id (as in the list-selection closure below).

**Availability:** `AppEntityAnnotatable` and the `NSUserActivity` conformance are `@available(macOS 15.2, iOS 18.2, watchOS 11.2, tvOS 18.2, visionOS 2.2, *)` — this surface ships from iOS 18.2. `EntityIdentifier(for:)` back-deploys to iOS 16.0; `EntityIdentifier(activityIdentifier:)` is iOS 18.0.

## Annotate list rows with a selection type

When a screen shows a list rather than a single detail view, annotate the rows so Siri can resolve "this" against whichever row is visible or selected. SwiftUI's `.appEntityIdentifier(forSelectionType:_:)` modifier takes the row's selection type (here `EventEntity.ID`, i.e. `UUID`) and a closure that maps each selected value back to an `EntityIdentifier`. CometCal's `CalendarListView` applies it to its event list:

```swift
// CalendarListView body, on the event list
.appEntityIdentifier(forSelectionType: EventEntity.ID.self) { eventID in
    EntityIdentifier(for: EventEntity.self, identifier: eventID)
}
```

This uses the same `EntityIdentifier(for:identifier:)` form as the detail view, driven off the selection value instead of a fixed entity. The SwiftUI `.appEntityIdentifier(forSelectionType:_:)` modifier (and the single-entity `.appEntityIdentifier(_:)` modifier) are **iOS 18.4** (macOS 15.4 / watchOS 11.4 / tvOS 18.4 / visionOS 2.4) — newer than the iOS 18.2 `NSUserActivity` property — so gate a view that uses them at 18.4.

**Which surface to use.** Match the annotation to what's on screen:
- **One primary item** (a detail view, a single full-screen photo): annotate the whole screen — either the foreground `NSUserActivity`'s `appEntityIdentifier` (iOS 18.2) or the single-entity `.appEntityIdentifier(_:)` SwiftUI modifier (iOS 18.4). Siri resolves "this" to that one entity.
- **Several meaningful items at once** (rows in a list, cards in a grid, messages in a thread): annotate each with `.appEntityIdentifier(forSelectionType:_:)` so a request like "the 2nd one" maps to the right row's entity. Don't collapse a multi-item screen to a single activity-level entity.

For either to resolve, the annotated type must be a real `AppEntity` with a working `defaultQuery` (the system looks the entity up by the identifier you supply) — see `entities-and-queries` in the specialist skill.

## Finer-grained onscreen elements

For reporting individual entities visible on screen (rather than a single `NSUserActivity`-level entity), `AppEntityUIElement` / `AppEntityUIElementsContext` provide finer-grained onscreen-element association. Both are iOS 18.4. Consult their current declarations in your SDK before adopting — this reference does not enumerate their members.

**Availability:** `AppEntityUIElement` / `AppEntityUIElementsContext` are `@available(macOS 15.4, iOS 18.4, watchOS 11.4, tvOS 18.4, visionOS 2.4, *)`.
## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `AppEntityAnnotatable` / `NSUserActivity.appEntityIdentifier` | 18.2 | 15.2 | 11.2 | 18.2 | 2.2 |
| `EntityIdentifier(for:)` | 16.0 | 13.0 | 9.0 | 16.0 | 1.0* |
| `EntityIdentifier(activityIdentifier:)` | 18.0 | 15.0 | 11.0 | 18.0 | 2.0 |
| `.appEntityIdentifier(_:)` / `.appEntityIdentifier(forSelectionType:_:)` (SwiftUI) | 18.4 | 15.4 | 11.4 | 18.4 | 2.4 |
| `AppEntityUIElement` / `AppEntityUIElementsContext` | 18.4 | 15.4 | 11.4 | 18.4 | 2.4 |

# Proactively Surfacing Relevant Entities
**SDK Version:** iOS 27.0 and later

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the new APIs in this reference (`RelevantEntities` and its `.shared` singleton, `updateEntities(_:for:)`, `removeEntities(_:)`, `removeAllEntities()`, `removeEntities(_:from:)`, `removeAllEntities(for:)`, `AppEntityContext`, and the `AudioContext` factories `.nowPlaying` / `.workout` / `.workout(activityType:)` / `.workout(intensityLevel:)`) require availability gating. `RelevantIntent` and `RelevantIntentManager` are older (iOS 17.0) and do not need iOS 27 gating.

`RelevantEntities` is a **narrow, media-focused** API: your app **donates the playable media items it owns — songs, albums, artists, playlists, radio stations, podcasts, and the like — so the system can suggest something to *play* (including items the person hasn't searched for or played before) in an audio scenario such as a workout or Now Playing.** It is **not** a general-purpose relevance or discovery mechanism, and it does **not** surface arbitrary entities: the only shipping contexts are audio (`AudioContext`), and your donations are candidates for the system's *media-playback* suggestions. (Making content *searchable* is Spotlight indexing; teaching the system *patterns from actions people took* is interaction donation via `IntentDonationManager` — different surfaces for different purposes. Don't reach for `RelevantEntities` for either.) You donate the full current set with `updateEntities(_:for:)` — each call replaces the previous set for that context — and retract it when it no longer applies; if the person doesn't open your app, the system expires the donations after roughly four weeks. The shipping contexts are **Now Playing** (`.audio(.nowPlaying)`) and **workout** (`.audio(.workout)` and its activity-type / intensity variants) — for example, surfacing a running playlist the moment someone starts a run. The running example is **TravelTracking**, whose travel-podcast feature donates the `EpisodeEntity` a person is currently listening to.

## Relevant entities

`RelevantEntities` is a `Sendable` struct reached through its `static let shared` singleton. `updateEntities(_:for:)` registers an array of `any AppEntity` as relevant for a given `AppEntityContext`; the call *replaces* the entities previously registered for that context, so pass the full current set each time rather than appending. Register when the context genuinely applies — when the person is listening to something, or has started a workout — so the set reflects what's relevant now.

```swift
import AppIntents

@available(iOS 27.0, *)
func updateNowPlaying(_ episode: EpisodeEntity) async throws {
    // Replaces whatever was previously published for the now-playing context.
    try await RelevantEntities.shared.updateEntities([episode], for: .audio(.nowPlaying))
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27 (`anyAppleOS 27.0`).

## Removing relevant entities

`RelevantEntities` offers four retraction calls so nothing lingers in system surfaces once it is no longer relevant. `removeEntities(_:from:)` retracts specific entities from one context; `removeAllEntities(for:)` clears an entire context; `removeEntities(_:)` and `removeAllEntities()` operate across every context your app published. Pair every publish with a matching removal.

```swift
import AppIntents

@available(iOS 27.0, *)
func retireNowPlaying(_ episode: EpisodeEntity) async throws {
    // Retract a specific entity from one context...
    try await RelevantEntities.shared.removeEntities([episode], from: .audio(.nowPlaying))
    // ...clear the whole context...
    try await RelevantEntities.shared.removeAllEntities(for: .audio(.nowPlaying))
    // ...or clear everything TravelTracking published, across all contexts.
    try await RelevantEntities.shared.removeAllEntities()
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27 (`anyAppleOS 27.0`).

## App entity context

`AppEntityContext` names the situation an entity is relevant to. It is a `Hashable`, `Sendable` value type, so you can store it, compare it, and key collections on it. It's produced by `AppEntityContext.audio(_:)`, which takes an `AudioContext`; the shipping `AudioContext` values are `.nowPlaying` (the system's Now Playing control or complication) and — from the HealthKit overlay — `.workout` (a workout of any type), `.workout(activityType:)` for a specific `HKWorkoutActivityType`, and `.workout(intensityLevel:)` for a `.low` / `.medium` / `.high` intensity. A more specific workout context is a stronger hint than the broad one, and you can register entities for several contexts at once.

```swift
import AppIntents

@available(iOS 27.0, *)
func nowPlayingContext() -> AppEntityContext {
    .audio(.nowPlaying)                    // the system's Now Playing control / complication
}

// Workout contexts need the HealthKit overlay.
import HealthKit

@available(iOS 27.0, *)
func runningContext() -> AppEntityContext {
    .audio(.workout(activityType: .running))   // e.g. surface a running playlist when a run starts
}
```

**Availability:** iOS 27, macOS 27, watchOS 27, tvOS 27, visionOS 27 (`anyAppleOS 27.0`). `.nowPlaying` is in AppIntents; the `.workout` factories and `WorkoutIntensityLevel` come from the HealthKit overlay (`import HealthKit`), same availability.

## Relevant intents (widget configuration)

`RelevantIntent` is the adjacent, older surface for marking a *widget-configuration* intent as relevant — it dates to iOS 17.0, so don't describe it as new in iOS 27 or conflate it with the iOS 27 `RelevantEntities` entity API (the two are easy to mix up by name). Its initializer `init(_:widgetKind:relevance:)` takes a `WidgetConfigurationIntent`, a `widgetKind` string, and a `relevance` of type `RelevantContext`, which originates in the **RelevanceKit** framework but is re-exported by AppIntents, so `import AppIntents` resolves it — an explicit `import RelevanceKit` is optional. You submit the results through `RelevantIntentManager.shared.updateRelevantIntents(_:)`. Use it only for widget-configuration intents, not for arbitrary intents.

```swift
import AppIntents
import RelevanceKit                  // optional — RelevantContext is re-exported by AppIntents

@available(iOS 17.0, *)
@available(tvOS, unavailable)
func publishRelevantWidgets(_ intents: [TravelGalleryWidgetIntent],
                            relevance: RelevantContext) async throws {
    let relevant = intents.map {
        RelevantIntent($0, widgetKind: "TravelGallery", relevance: relevance)
    }
    try await RelevantIntentManager.shared.updateRelevantIntents(relevant)
}
```

**Availability:** `RelevantIntent` / `RelevantIntentManager`: iOS 17.0, macOS 14.0, watchOS 10.0, tvOS 17.0. The `init(_:widgetKind:relevance:)` initializer is iOS 17.0 / macOS 14.0 / watchOS 10.0 and is **unavailable on tvOS**.

# Requesting a Choice Mid-Perform

**SDK Version:** iOS 26.0 and later

If the user's deployment target is below iOS 26 / macOS 26 / watchOS 26 / tvOS 26 / visionOS 26, the APIs in this reference (`requestChoice(between:dialog:)`, `IntentChoiceOption`, and `IntentChoiceOption.Style`) require availability gating. See "Deployment target below SDK 26" below for the gating shape to use.

Before iOS 26 an intent that needed the person to pick between a few options had to model that as a parameter and lean on disambiguation, or bounce into the app. iOS 26 adds `requestChoice(between:dialog:)`, which pauses `perform()` inline, shows a system prompt with a small set of options, and resumes with the option the person chose — no parameter, no app launch. It is the multi-option sibling of `requestConfirmation` (see `execution-modes.md` for continuation, and the specialist skill's `execution-model` for the general "confirm before destructive work" rule). Running example: the WWDC **TravelTracking** sample, whose `FindTicketsIntent` asks the person to pick a visit window before buying a ticket.

## requestChoice(between:dialog:)

`requestChoice(between:dialog:)` is an `async throws` method on `AppIntent`. Call it from `perform()` with an array of `IntentChoiceOption` and an optional `IntentDialog`; it returns the chosen `IntentChoiceOption`. Because `IntentChoiceOption` is `Equatable`, compare the return value against the options you built to branch. Reach for it when the choice is a small, fixed set decided *during* execution — not for open-ended entity selection (model that as a `@Parameter` and let resolution/disambiguation handle it).

```swift
@available(iOS 26.0, *)
struct FindTicketsIntent: AppIntent {
    static let title: LocalizedStringResource = "Find Tickets"
    @Parameter var landmark: LandmarkEntity

    func perform() async throws -> some IntentResult & ProvidesDialog {
        let morning = IntentChoiceOption(title: "Morning visit")
        let evening = IntentChoiceOption(title: "Evening visit")

        let choice = try await requestChoice(
            between: [morning, evening],
            dialog: "When should the visit be?"
        )

        let window: VisitWindow = (choice == morning) ? .morning : .evening
        try await ModelData.shared.bookTicket(landmark, window: window)
        return .result(dialog: "Booked the \(window) visit.")
    }
}
```

**Availability:** iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0.

## IntentChoiceOption and styling

`IntentChoiceOption(title:style:)` builds an option from a `LocalizedStringResource` title and an optional `Style` (default `.default`). Use `.destructive` for an option that deletes or is otherwise hard to undo — the system renders it accordingly. Include `IntentChoiceOption.cancel`, a system-provided option, when the person should be able to back out: **selecting `.cancel` makes `requestChoice` throw** (a cancellation error), so a cancel aborts `perform()` rather than returning — don't try to handle it as a returned value. (`Option` is a convenience type alias for `IntentChoiceOption`, declared on `AppIntent` — reference it as `Option` inside an intent, not `IntentChoiceOption.Option`.)

```swift
@available(iOS 26.0, *)
func perform() async throws -> some IntentResult {
    let keep   = IntentChoiceOption(title: "Keep both")
    let replace = IntentChoiceOption(title: "Replace existing", style: .destructive)

    // Selecting .cancel throws — it does not come back as a return value.
    let choice = try await requestChoice(between: [keep, replace, .cancel],
                                         dialog: "This landmark already exists.")
    if choice == replace {
        try await ModelData.shared.overwrite()
    }
    return .result()
}
```

**Availability:** iOS 26.0, macOS 26.0, watchOS 26.0, tvOS 26.0, visionOS 26.0. `IntentChoiceOption`, `IntentChoiceOption.Style` (`.default` / `.destructive` / `.cancel`), and the static `IntentChoiceOption.cancel` share the same availability.

## Deployment target below SDK 26

When the user's deployment target is below SDK 26 and the answer needs a mid-perform choice, gate the `requestChoice` path behind `@available` / `if #available` and fall back to the pre-26 approach (a `@Parameter` the person fills, or `requestConfirmation` for a binary choice):

```swift
func perform() async throws -> some IntentResult & ProvidesDialog {
    if #available(iOS 26.0, *) {
        let a = IntentChoiceOption(title: "Morning visit")
        let b = IntentChoiceOption(title: "Evening visit")
        let choice = try await requestChoice(between: [a, b], dialog: "When?")
        // ...branch on `choice`...
    } else {
        // Older fallback: resolve a parameter, or use requestConfirmation for a binary choice.
    }
    return .result(dialog: "Booked.")
}
```

Use this shape (or `@available(iOS 26.0, *)` on the enclosing declaration) whenever the prompt names a deployment target below SDK 26. Don't emit unconditional calls to `requestChoice` / `IntentChoiceOption`; the typecheck will fail with `'<API>' is only available in iOS 26.0 or newer`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `requestChoice(between:dialog:)` | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |
| `IntentChoiceOption` / `.Style` / `.cancel` | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |

# Adopting App Intent Schemas
**SDK Version:** iOS 18.0 and later (the schema-adoption macros)

The schema-adoption macros (`@AppIntent(schema:)`, `@AppEntity(schema:)`, `@AppEnum(schema:)`) are available from iOS 18.0 (macOS 15.0, tvOS 18.0, watchOS 11.0, visionOS 2.0). If the user's deployment target is below that, gate the type with `@available(iOS 18.0, *)`. **An individual domain can carry its own, later availability than the macro** — the running example here, the `calendar` domain, is exactly such a case: it is **iOS 27.0** (macOS 27.0, visionOS 27.0; unavailable on watchOS/tvOS), newer than the iOS 18.0 macros, so the calendar types below are gated `@available(iOS 27.0, *)`. Always check a `domain.schema`'s declaration in your SDK and gate to its floor, not the macro's.

A schema mandates a fixed shape for an intent, entity, or enum: a specific set of typed, sometimes-required parameters and a specific result type, so that Apple Intelligence and Siri can invoke your code through a standardized contract. When you adopt a schema, you are promising the system that your type matches that contract. You attach the schema with the macro — `@AppIntent(schema: .<domain>.<action>)` for an intent, `@AppEntity(schema: .<domain>.<type>)` for an entity, `@AppEnum(schema: .<domain>.<type>)` for an enum — and the framework generates the schema conformance (e.g. `AssistantSchemaIntent`) plus the member scaffolding the schema requires. A build tool validates that your type actually satisfies the schema after compilation. Confirm what is available in your SDK before naming one. In the running example, the CometCal calendar sample adopts the public `calendar` domain to let a user create and manage calendar events, and the `system` domain to open one in the app.

## Which domains reach which surface

Pick a domain by the surface you want to light up. The domains below are the **public** schema catalog documented by Apple ([App schema domains](https://developer.apple.com/documentation/appintents/app-schema-domains)); an individual domain can be gated in a given SDK, so confirm a `domain.schema` identifier at its declaration before emitting it. 

| Surface | Domains | What adoption does |
|---|---|---|
| **Apple Intelligence + Siri** (primary) | `audio`, `calendar`, `camera`, `clock`, `files`, `mail`, `maps`, `messages`, `notes`, `phone`, `photos`, `reminders`, `system` (system & in-app search) | Conforming types become discoverable by Apple Intelligence and Siri, and also appear in the Shortcuts app. |
| **Visual Intelligence** (single-purpose) | `visualIntelligence` | Surfaces the app's results when a person points the camera at / selects on-screen content (pairs with `IntentValueQuery` — see `visual-intelligence.md`). |
| **Side-button conversational launch** (single-purpose) | `assistant` | Lets people in Japan launch a voice-based conversational app from the iPhone side button. |
| **Shortcuts app only**  | `books`, `browser`, `journal` (journaling), `presentation`, `reader`, `spreadsheet`, `whiteboard`, `wordProcessor` | Schemas usable in the Shortcuts app; they do **not** make the conforming type discoverable by Apple Intelligence or Siri. |

CometCal's `calendar` domain is an **Apple Intelligence + Siri primary** domain: adopting `.calendar.createEvent`, `.calendar.event`, and friends makes those types discoverable by Apple Intelligence and Siri and surfaces them in the Shortcuts app. An app can adopt schemas from several domains (CometCal uses `calendar` for its create/update/delete actions plus `system` for opening an event). Adopt a domain only when your action genuinely matches its purpose — a forced fit degrades Siri's behavior.

### All-or-nothing domains

Three domains require you to adopt **every** schema in the group if you adopt any of them: **`mail`, `clock`, `messages`**. Xcode flags the missing schemas at build time, so partial adoption won't ship. Don't reach for a single schema from these expecting partial support. 

## The `@Assistant*` → `@App*` rename (the central trap)

The macros are named `@AppIntent(schema:)`, `@AppEntity(schema:)`, and `@AppEnum(schema:)`. The older `@AssistantIntent(schema:)`, `@AssistantEntity(schema:)`, and `@AssistantEnum(schema:)` macros — and the `AssistantSchema` type / `AssistantSchemas.Intent` etc. — are **deprecated and renamed** to the `@App*` forms. Reach for the `@App*` spelling; do not emit `@Assistant*`. CometCal uses only the modern `@App*(schema:)` forms.

The deprecated spelling still compiles, so this is easy to get wrong. If you write it, the compiler emits a deprecation warning that names the replacement, e.g. `'AssistantIntent' is deprecated: renamed to 'AppIntent'`. Migrate by swapping the macro name and leaving the `schema:` argument as-is. (This example uses `.mail.createDraft` rather than a calendar schema: the `calendar` domain is new in iOS 27 and exists only under the modern `@App*` spelling, so it can't illustrate the deprecated form; `mail` is an iOS 18.0 domain present under both spellings.)

```swift
// Deprecated (do not use):
@available(iOS 18.0, *)
@AssistantIntent(schema: .mail.createDraft)
struct ComposeDraft { /* ... */ }

// Current spelling:
@available(iOS 18.0, *)
@AppIntent(schema: .mail.createDraft)
struct ComposeDraft {
    func perform() async throws -> some IntentResult { /* ... */ }
}
```

The schema accessors (`.mail.createDraft`, `.calendar.createEvent`, etc.) are unchanged by the rename — only the macro name and the `AssistantSchema`/`AssistantSchemas.*` type names moved to `AppSchema`/`AppIntentSchema`/`AppEntitySchema`/`AppEnumSchema`.

**Availability:** `@AppIntent(schema:)` / `@AppEntity(schema:)` / `@AppEnum(schema:)` are iOS 18.0+. The `@Assistant*` forms are deprecated.

## Adopting an intent schema

A schema-conforming intent is a normal `AppIntent` — it still has a `perform()` and can be surfaced as an `AppShortcut` — with the extra constraint that its parameters and result must match the schema's contract. Attaching `@AppIntent(schema:)` generates the schema conformance for you; you supply the properties the schema defines. Note that the struct itself declares **no** `: AppIntent` conformance — the macro adds the `AppIntent` conformance and the schema-required shape. Depending on the schema, the macro also confers the capability protocol the schema implies — e.g. `OpenIntent`, `DeleteIntent`, `ShowInAppSearchResultsIntent`, or `AudioPlaybackIntent` — so you implement that protocol's requirements too. Apple Intelligence reads only the properties the schema defines; any extra property you add must be optional and is seen only by the Shortcuts app.

Use a concrete schema only when you can confirm it exists in your SDK. The `calendar` domain is available in (iOS 27.0). For example, `.calendar.createEvent` creates a calendar event and returns it:

```swift
@available(iOS 27.0, *)
@AppIntent(schema: .calendar.createEvent)
struct CreateEventIntent {
    var title: String
    var startDate: Date
    var endDate: Date?
    var location: EventLocation?
    var calendar: CalendarEntity
    var isAllDay: Bool
    var attendees: [AttendeeEntity]

    @Dependency
    var calendarManager: CalendarManager

    func perform() async throws -> some ReturnsValue<EventEntity> {
        // Create the event from the schema-provided values and return the entity.
        let event = try calendarManager.createEvent(/* ... */)
        return .result(value: event.entity)
    }
}
```

The required and optional properties are dictated by the schema, not by you — you can't drop a property the schema requires or change its type. You *may* add optional extras, but they're Shortcuts-only (Siri and Apple Intelligence never fill them — see the traps below). If your functionality doesn't map onto a schema in a domain, write a plain `AppIntent` instead; schema adoption is only for actions that match a published contract. CometCal also adopts `.calendar.updateEvent` and `.calendar.deleteEvent` the same way, and `.system.open` for `OpenEventIntent` (which takes an `EventEntity` and opens it in the app).

If you don't know which domains your SDK exposes, don't guess. Check the current SDK for the domains and schemas available to you rather than naming one that may not be present.

**Availability:** the schema macros are iOS 18.0+, but the `calendar` domain and `.calendar.createEvent` are **iOS 27.0** (macOS 27.0, visionOS 27.0; unavailable on watchOS/tvOS) — a domain can carry a later floor than the macro, so check its declaration in your SDK and gate accordingly.

## Adopting entity and enum schemas

Schemas also standardize the app entities an intent returns or takes as parameters, and the enums used for constrained parameter values. Adopt them the same way, with `@AppEntity(schema:)` and `@AppEnum(schema:)`. The schema decides the required shape, but you may add extra protocol conformances on top of it — CometCal's `EventEntity` also conforms to `IndexedEntity` (for Spotlight) and `OwnershipProvidingEntity`:

```swift
@available(iOS 27.0, *)
@AppEntity(schema: .calendar.event)
struct EventEntity: IndexedEntity, OwnershipProvidingEntity {
    static let defaultQuery = EventEntityQuery()

    var id: UUID
    var calendar: CalendarEntity
    var title: String
    var startDate: Date
    var endDate: Date
    var status: EventEntityStatus?
    // ... the other properties the schema defines ...

    var displayRepresentation: DisplayRepresentation { DisplayRepresentation(title: "\(title)") }

    struct EventEntityQuery: EntityQuery {
        func entities(for identifiers: [UUID]) async throws -> [EventEntity] { [] }
    }
}
```

Entities that never persist can adopt `TransientAppEntity` — CometCal's attendee entity does, since an attendee only exists in the context of an event — and a lookup entity like the calendar itself is a plain `IndexedEntity`:

```swift
@available(iOS 27.0, *)
@AppEntity(schema: .calendar.attendee)
struct AttendeeEntity: TransientAppEntity {
    var person: IntentPerson
    var status: ParticipantStatus?
    // ... the properties the schema defines ...
}

@available(iOS 27.0, *)
@AppEntity(schema: .calendar.calendar)
struct CalendarEntity: IndexedEntity {
    static let defaultQuery = CalendarEntityQuery()
    let id: UUID
    var title: String
    // ...
}
```

An `@AppEnum(schema:)` constrains a parameter to a fixed set of cases. CometCal's event status maps onto `.calendar.eventStatus`:

```swift
@available(iOS 27.0, *)
@AppEnum(schema: .calendar.eventStatus)
enum EventEntityStatus: String {
    case confirmed
    case tentative
    case cancelled

    static let caseDisplayRepresentations: [Self: DisplayRepresentation] = [
        .confirmed: "Confirmed",
        .tentative: "Tentative",
        .cancelled: "Cancelled",
    ]
}
```

CometCal adopts several more calendar enums the same way — `.calendar.eventSpan`, `.calendar.attendeeStatus`, and `.calendar.attendeeType`. As with intents, the schema decides the required shape; the macro generates the conformance and validation happens at build time.

**Availability:** the `calendar` entity and enum schemas shown are **iOS 27.0** (macOS 27.0, visionOS 27.0; unavailable on watchOS/tvOS), like the rest of the `calendar` domain.

## How schema conformance is validated

Adopting a schema is a build-time contract, enforced in two places. The macro attaches the schema conformance protocol (e.g. `AssistantSchemaIntent`) and injects the member attributes the schema needs, so a type that isn't shaped like the schema fails to compile. Then, after compilation, the `appintentsmetadataprocessor` build tool extracts your intent's metadata and checks it against the schema definition from the `AppIntentSchemas` package — verifying the required properties are present and correctly typed. A schema-conforming intent flows through the same metadata pipeline as any other `AppIntent`; the schema is what lets Apple Intelligence match a request to your intent through the standardized contract, and it can still be surfaced through `AppShortcut` for Siri and Shortcuts.

## Migrating an existing intent (`isAssistantOnly`)

If an existing intent's properties already match a schema, just add the macro — no other change. If adopting the schema would change the intent's properties in a way that breaks saved shortcuts, don't mutate the old intent: add a **new** schema-conforming intent alongside it and mark the new one Apple-Intelligence-only during the transition.

```swift
@available(iOS 27.0, *)
@AppIntent(schema: .calendar.createEvent)
struct CreateEventIntentAI {
    static let isAssistantOnly: Bool = true   // hidden from Shortcuts; serves Siri / Apple Intelligence only
    var title: String
    var startDate: Date
    func perform() async throws -> some ReturnsValue<EventEntity> { /* ... */ }
}
```

`isAssistantOnly = true` hides the new intent from the Shortcuts app so users don't see a duplicate pair, while the old intent keeps serving existing shortcuts. Remove `isAssistantOnly` once you retire the old intent. Never rename or remove an intent while saved shortcuts or donations depend on it (see the specialist skill's identifiers-are-a-contract guardrail).

## Traps

- **Reaching for the deprecated `@Assistant*` spelling.** Training data over-represents `@AssistantIntent` / `@AssistantEntity` / `@AssistantEnum` and `AssistantSchema`. These are deprecated (renamed to `@AppIntent` / `@AppEntity` / `@AppEnum` and `AppSchema`). Always emit the `@App*` forms.
- **Omitting or mistyping a schema-required property.** The schema fixes the *required* parameter/result shape: omit a required property, or give one the wrong type, and the build fails validation. You *can* add extras beyond the schema — **optional** extra parameters on an intent, or extra properties on an entity — but they surface only in the Shortcuts app; Siri and Apple Intelligence never fill or render them.
- **Assuming a domain exists.** Never emit a domain unless verified in the SDK. When in doubt, use a generic placeholder (`.<domain>.<action>`) and tell the user to check the current SDK for the domains available to them.

## Deployment target below SDK 18

When the user's deployment target is below a schema's floor, gate the type. The schema macros and schema accessors do not exist on older OSes, so an unconditional adoption won't type-check. Gate to the *domain's* floor, which may be newer than the iOS 18.0 macros — the `calendar` domain, for instance, is iOS 27.0:

```swift
@available(iOS 27.0, *)
@AppIntent(schema: .calendar.createEvent)
struct CreateEventIntent {
    var title: String
    var startDate: Date
    func perform() async throws -> some ReturnsValue<EventEntity> { /* ... */ }
}
```

If the same action must also ship on older targets, provide a plain (non-schema) `AppIntent` on the fallback path and register the schema-conforming variant only under the domain's `@available` floor. Don't emit an unconditional `@AppIntent(schema:)`; the typecheck fails with `'AppIntent(schema:)' is only available in iOS 18.0 or newer` (or the schema's own later floor, e.g. `'calendar' is only available in iOS 27.0 or newer`).

# Spotlight Indexing Enhancements
**SDK Version:** iOS 26.0 and later

If the user's deployment target is below iOS 26 / macOS 26 / visionOS 26 (or iOS 27 / macOS 27 / visionOS 27 for the query and cross-link APIs), the new APIs in this reference (`@ComputedProperty(indexingKey:)` and `@DeferredProperty(indexingKey:)`, `IndexedEntityQuery` with `reindexEntities(for:indexDescription:)` / `reindexAllEntities(indexDescription:)`, and `CSSearchableItem.relatedAppEntityIdentifier` / `CSSearchableItemAttributeSet.relatedAppEntityIdentifier`) require availability gating. The baseline `IndexedEntity` conformance and `indexAppEntities`/`deleteAppEntities` are older (iOS 18) and are noted here only for context. See "Deployment target below SDK 27" below for the gating shape to use.

`IndexedEntity` (iOS 18.0) already lets an `AppEntity` project itself into a `CSSearchableItemAttributeSet` so it appears in Spotlight, and `CSSearchableIndex.indexAppEntities(_:priority:)` / `deleteAppEntities(...)` (also iOS 18.0) push and remove those entities. This reference covers what is *new* on top of that baseline: computed and deferred property indexing keys (iOS 26), a query protocol that lets the system drive reindexing (iOS 27), and a way to cross-link an independently indexed searchable item back to an app entity (iOS 27). Running example: a travel app, **TravelTracking**, whose library entity is `LandmarkEntity: IndexedEntity`.

These surfaces attach to *any* `IndexedEntity` — including a **schema-conforming** one, since a schema entity is still an `AppEntity`. CometCal's calendar entity combines both (`@AppEntity(schema: .calendar.event) struct EventEntity: IndexedEntity`), and a music library's `@AppEntity(schema: .audio.song)` entity is pushed to Spotlight the same way (`CSSearchableIndex.indexAppEntities([song])`). Schema adoption and Spotlight indexing are orthogonal — an entity can do both.

## Computed and deferred indexing keys

`@ComputedProperty(indexingKey:)` and `@DeferredProperty(indexingKey:)` map an entity value to a `CSSearchableItemAttributeSet` key path without stored backing, extending the older `@Property(indexingKey:)` (iOS 18.4) to derived values. Use `@ComputedProperty(indexingKey:)` when the value is computed synchronously from other fields, and `@DeferredProperty(indexingKey:)` when producing it is expensive or `async` (network, disk, decode) so it is fetched lazily rather than on every materialization. The key is a `PartialKeyPath<CSSearchableItemAttributeSet>`; both macros also offer a `title:`-prefixed overload. `@ComputedProperty` additionally has a `customIndexingKey:` overload taking a `CSCustomAttributeKey`; `@DeferredProperty` does not.

```swift
@available(iOS 26.0, macOS 26.0, visionOS 26.0, *)
struct LandmarkEntity: AppEntity, IndexedEntity {
    let id: UUID

    // Synchronous, derived from other fields.
    @ComputedProperty(indexingKey: \.title)
    var name: String { "\(number). \(rawName)" }

    // Expensive / async: fetched lazily, only when indexing needs it.
    @DeferredProperty(indexingKey: \.textContent)
    var notes: String { get async throws { try await ModelData.notes(for: id) } }
    // ...
}
```

**Availability:** `@ComputedProperty(indexingKey:)` / `(title:indexingKey:)` / `(customIndexingKey:)` and `@DeferredProperty(indexingKey:)` / `(title:indexingKey:)` are iOS 26.0, macOS 26.0, visionOS 26.0 (no watchOS/tvOS). The baseline `@Property(indexingKey:)` / `(title:indexingKey:)` is iOS 18.4, macOS 15.4, visionOS 2.4, and is `@available(watchOS, unavailable)` / `@available(tvOS, unavailable)`.

## System-driven reindexing from the query

`IndexedEntityQuery` refines `EntityQuery` (requiring `Self.Entity: IndexedEntity`) and adds `reindexEntities(for:indexDescription:)` and `reindexAllEntities(indexDescription:)`, letting the system ask your query to refresh Spotlight when the backing store changes. Both receive a `CSSearchableIndexDescription` and typically re-push entities through `CSSearchableIndex.indexAppEntities(_:)`.

```swift
@available(iOS 27.0, macOS 27.0, visionOS 27.0, *)
struct LandmarkEntityQuery: IndexedEntityQuery {
    func entities(for identifiers: [LandmarkEntity.ID]) async throws -> [LandmarkEntity] {
        try await ModelData.landmarks(ids: identifiers)
    }

    func reindexEntities(
        for identifiers: [LandmarkEntity.ID],
        indexDescription: CSSearchableIndexDescription
    ) async throws {
        try await CSSearchableIndex.default().indexAppEntities(entities(for: identifiers))
    }

    func reindexAllEntities(
        indexDescription: CSSearchableIndexDescription
    ) async throws {
        try await CSSearchableIndex.default().indexAppEntities(ModelData.all())
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, visionOS 27.0 (no watchOS/tvOS).

## Cross-link a searchable item to an app entity

`relatedAppEntityIdentifier` is a settable `EntityIdentifier?` on both `CSSearchableItem` and `CSSearchableItemAttributeSet`. Set it on an item you index directly (content *not* built from an `IndexedEntity`) to associate it with an existing app entity, so Spotlight's own UI can cross-link the two. This is distinct from the older iOS 18.0 `CSSearchableItem(appEntity:)` / `associateAppEntity(_:priority:)`, which build an item *from* an entity; `relatedAppEntityIdentifier` points an *independently* indexed item *at* an entity by identifier.

```swift
@available(iOS 27.0, macOS 27.0, visionOS 27.0, *)
func indexRoutePage(for landmark: LandmarkEntity, html: URL) async throws {
    let item = CSSearchableItem(
        uniqueIdentifier: "route-\(landmark.id.uuidString)",
        domainIdentifier: "routes",
        attributeSet: CSSearchableItemAttributeSet(contentType: .html))
    item.relatedAppEntityIdentifier = EntityIdentifier(for: landmark)
    try await CSSearchableIndex.default().indexSearchableItems([item])
}
```

**Availability:** iOS 27.0, macOS 27.0, visionOS 27.0 (no watchOS/tvOS) on both `CSSearchableItem` and `CSSearchableItemAttributeSet`.

## Deployment target below SDK 27

When the user's deployment target is below the version an API requires, gate the new surface behind `@available`/`if #available` and keep a fallback that uses the baseline iOS 18 indexing path (a plain `@Property(indexingKey:)` and manual `indexAppEntities`), or skip the enhancement on older OS versions:

```swift
if #available(iOS 27, macOS 27, visionOS 27, *) {
    item.relatedAppEntityIdentifier = EntityIdentifier(for: landmark)   // iOS 27 API
}
try await CSSearchableIndex.default().indexSearchableItems([item])   // iOS 18 baseline
```

Gate the property macros at iOS 26 (`@ComputedProperty`/`@DeferredProperty(indexingKey:)`), and the query protocol and `relatedAppEntityIdentifier` at iOS 27, either with `if #available` around the use or `@available(iOS 26, *)` / `@available(iOS 27, *)` on an enclosing declaration. Do not emit these APIs on watchOS or tvOS — the property indexing keys, `IndexedEntityQuery`, and `relatedAppEntityIdentifier` are unavailable there at every OS version; branch to a plain property or skip indexing on those platforms. Don't emit unconditional calls; the typecheck will fail with `'<API>' is only available in iOS 26.0 or newer` (or 27.0).

# Running System Shortcuts
**SDK Version:** iOS 27.0 and later

If the user's deployment target is below iOS 27, the APIs in this reference (`SystemShortcut` and `RunSystemShortcutIntent`) require availability gating. Both types are iOS-only — they are `@available(macOS, unavailable)`, `@available(tvOS, unavailable)`, `@available(watchOS, unavailable)`, and `@available(visionOS, unavailable)` — so any use also needs a fallback on non-iOS targets.
iOS 27 adds a way to run a system-provided shortcut from an interactive widget. `RunSystemShortcutIntent` is a `SystemIntent` that runs a `SystemShortcut`, and its only supported use is to back a SwiftUI `Button(intent:)` inside a widget configuration. In the running example, a "TravelTracking" widget exposes a button that runs a system shortcut. Outside a widget button, `RunSystemShortcutIntent` has no functionality — do not surface it as an App Shortcut, invoke it from `perform()`, or wire it anywhere else.

## SystemShortcut

`SystemShortcut` is an opaque value that identifies a system-provided shortcut. It conforms to `Equatable` and `Sendable`. It exposes no public initializer and no public static factory in the SDK, so app code cannot construct or enumerate `SystemShortcut` values directly — treat any specific value as system-resolved. Because of this, a `SystemShortcut` is only ever something you receive from a system-provided context and pass straight through; do not store your own or model it as a custom property on a widget timeline entry.

```swift
// A SystemShortcut you were handed by a system-provided context.
// You compare or pass it through — you never construct it yourself.
@available(iOS 27.0, *)
func makeRunIntent(for shortcut: SystemShortcut) -> RunSystemShortcutIntent {
    RunSystemShortcutIntent(shortcut: shortcut)
}
```

**Availability:** iOS 27.0. Unavailable on macOS, tvOS, watchOS, and visionOS.

## RunSystemShortcutIntent

`RunSystemShortcutIntent` is a `SystemIntent` that runs a system shortcut. It has two initializers: the parameterless `init()`, and `init(shortcut:)` which takes a system-resolved `SystemShortcut`. Use it only to back a SwiftUI `Button(intent:)` inside a widget configuration; it has no functionality in any other context.

```swift
// In a WidgetKit view body for a "TravelTracking" widget configuration.
// `entry.configuration.shortcut` is a SystemShortcut carried on the widget's
// configuration entry (a value the system resolved — not one the app built).
@available(iOS 27.0, *)
private var runShortcutButton: some View {
    Button(intent: RunSystemShortcutIntent(shortcut: entry.configuration.shortcut)) {
        Label("Run Shortcut", systemImage: "bolt")
    }
}
```

If you do not have a specific `SystemShortcut` in hand, use the parameterless initializer and let the system resolve which shortcut runs:

```swift
@available(iOS 27.0, *)
private var runShortcutButton: some View {
    Button(intent: RunSystemShortcutIntent()) {
        Label("Run Shortcut", systemImage: "bolt")
    }
}
```

**Availability:** iOS 27.0. Unavailable on macOS, tvOS, watchOS, and visionOS.

# Testing App Intents with AppIntentsTesting

**SDK Version:** iOS 27.0 and later

`AppIntentsTesting` (`import AppIntentsTesting`; a developer-tools framework that links only from test targets) runs your app intents, entities, enums, and queries **out-of-process against your installed app — the same way Siri or Shortcuts invoke them** — and lets you assert on the results through type-erased wrappers, without linking your app target into the test. Because execution is out-of-process, you don't inject test doubles in the test process; you arrange deterministic data by driving the app itself (e.g. a seed intent), and assert against what its real queries and `perform()` return.

The examples use **XCTest** and are drawn from Apple's published **CometCal** calendar sample, which has `EventEntity` / `CalendarEntity` (both `IndexedEntity`), their string/enumerable queries, intents like `CreateEventIntent` / `OpenEventIntent` / `FetchEventIntent`, and debug-only seed intents (`SeedSampleEventsIntent`, `ResetTestDataIntent`).

The entire `AppIntentsTesting` module is `@available(iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0)`; the simplest setup is a test target that deploys to iOS 27+ — see "Deployment target below SDK 27" if it deploys lower.

## A shared base test case

Hold one `IntentDefinitions(bundleIdentifier:)` (the bundle id of your app under test, **not** the test bundle) and expose per-type accessors — addressing intents/entities by their **type/intent name**. The subscripts (`.intents["…"]`, `.entities["…"]`, plus `.enums`, `.transientEntities`, `.valueQueries`) return the definition directly (non-optional). Arrange deterministic data in `setUp` by running the app's seed intent, so every test starts from known events:

```swift
import XCTest
import AppIntentsTesting

@available(iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0, *)
class CalendarTestCase: XCTestCase {
    let app = XCUIApplication()
    let definitions = IntentDefinitions(bundleIdentifier: "com.example.CometCal")   // your app's bundle id

    var eventEntity: AppEntityDefinition { definitions.entities["EventEntity"] }
    var calendarEntity: AppEntityDefinition { definitions.entities["CalendarEntity"] }
    var createEvent: AppIntentDefinition { definitions.intents["CreateEventIntent"] }
    var openEvent: AppIntentDefinition { definitions.intents["OpenEventIntent"] }
    var seedSampleEvents: AppIntentDefinition { definitions.intents["SeedSampleEventsIntent"] }

    override func setUp() async throws {
        try await super.setUp()
        try await seedSampleEvents.makeIntent().run()   // out-of-process seed → known data
    }
}
```

`makeReference(identifier:)` / `makeIntent(…)` build a type-erased `AnyAppEntity` / `AnyAppIntent`; `makeIntent` is a callable wrapper (`IntentValuePropertiesCallable`), so you invoke it like a function and pass parameters by their **real `@Parameter` label**. A `makeReference(identifier:)` reference is non-throwing and carries the **id only** — the entity's other properties read as nil until the app resolves it through a query.

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Executing an intent and reading the result

`AnyAppIntent.run()` is `@discardableResult func run() async throws -> ResolvedIntentResult`; it runs the full resolve-then-`perform()` pipeline out-of-process. For an entity-returning intent, read a property off the result with the **throwing** `result.value` accessor (`try` required). Note `result.value` passed straight into another `makeIntent(…)` needs no `try` — in a parameter position the compiler selects a non-throwing overload of the `.value` lookup; only a *typed read* like `result.value.title` throws:

```swift
final class IntentExecutionTests: CalendarTestCase {
    func testCreateEventReturnsEntity() async throws {
        let result = try await createEvent.makeIntent(
            title: "Asteroid Dodgeball Practice",
            startDate: Date(),
            isAllDay: false,
            calendar: "Deep Space"
        ).run()
        XCTAssertEqual(try result.value.title, "Asteroid Dodgeball Practice")   // typed read → try
    }

    func testUpdateTakesTheReturnedEntity() async throws {
        let created = try await createEvent.makeIntent(
            title: "Temp Event", startDate: Date(), isAllDay: false, calendar: "Mission Control"
        ).run()
        let updated = try await definitions.intents["UpdateEventIntent"].makeIntent(
            event: created.value,                    // returned entity as a parameter — no `try`
            title: "Temp Event (Revised)"
        ).run()
        XCTAssertEqual(try updated.value.title, "Temp Event (Revised)")
    }
}
```

CometCal's intents return entities, but if an intent returns a scalar, another value, or an enum, read `result.value` (a throwing typed read) accordingly. `.as(_:)` lives on the value path you get from `result.value`, and an enum result comes back as `AnyAppEnum`:

```swift
// Primitive result — bind the expected type (Double / String / … conform to IntentValueConvertible):
let miles: Double = try result.value

// Convert the value path to another IntentValueConvertible type with .as(_:):
let name = try result.value.as(String.self)

// An enum result comes back as AnyAppEnum — read rawValue (or .as(_:) for a LosslessStringConvertible type):
let status: AnyAppEnum = try result.value
XCTAssertEqual(status.rawValue, "confirmed")
```

For a `perform()` that throws (CometCal's `FetchEventIntent` throws when no event matches), assert the error path with `do / try / XCTFail / catch` — XCTest has no async throw-assert, and confirmation is handled automatically (you don't supply a confirmation handler):

```swift
func testFetchMissingEventThrows() async {
    do {
        _ = try await definitions.intents["FetchEventIntent"].makeIntent(title: "No Such Event").run()
        XCTFail("Expected FetchEventIntent to throw when no event matches")
    } catch {
        // expected — the intent throws eventNotFound
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Asserting entity queries

Exercise an entity's query through its `AppEntityDefinition`; the call dispatches to the app under test, so you assert against its seeded data. `AnyAppEntity` is `@dynamicMemberLookup` with **throwing** typed reads; its `identifier` is an `AttributedEntityIdentifier` (get the string id from `entity.identifier.instanceIdentifier`). The surfaces are `entities(matching:)` (string query), `entities(identifiers:)`, `allEntities()`, and `suggestedEntities()` — each returning `[AnyAppEntity]`, plus a `…Query()` variant returning `AnyEntityQuery`.

```swift
final class EntityQueryTests: CalendarTestCase {
    func testStringQueryMatchesSeededEvent() async throws {
        // "Cosmic Ray Calibration" is one of the seeded events.
        let results = try await eventEntity.entities(matching: "Cosmic Ray")
        XCTAssertEqual(results.count, 1)
        XCTAssertEqual(try results[0].title, "Cosmic Ray Calibration")
    }

    func testAllAndSuggested() async throws {
        let all = try await eventEntity.allEntities()
        XCTAssertFalse(all.isEmpty)
        let suggested = try await eventEntity.suggestedEntities()
        XCTAssertFalse(suggested.isEmpty)
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Value queries: values(for:)

`values(for:)` is the only `AppIntentsTesting` entry point for an `IntentValueQuery` — the query Visual Intelligence uses to turn a search input into candidate values (see `visual-intelligence.md` for authoring one). CometCal ships no `IntentValueQuery`, but the `valueQueries` registry tests one the moment your app exposes it. Suppose CometCal added an `EventValueQuery` returning events for a search input: reach it through `definitions.valueQueries["…"]`, call `values(for:)` with the input (in a test you pass a plain value such as a `String`, not a `SemanticContentDescriptor`), and read `result.items`. `items` is a `DynamicPropertyPathCollection` — not an array — so read a property off an item by binding the item as a `DynamicPropertyPath`, then a throwing typed read:

```swift
final class EventValueQueryTests: CalendarTestCase {
    func testValueQueryReturnsItems() async throws {
        // Illustrative: assumes CometCal exposes an EventValueQuery. "Cosmic Ray Calibration" is seeded.
        let result = try await definitions.valueQueries["EventValueQuery"].values(for: "Cosmic Ray")
        XCTAssertEqual(result.items.count, 1)

        let first: DynamicPropertyPath = result.items[0]        // element → path (non-throwing)
        XCTAssertEqual(try first.title, "Cosmic Ray Calibration")   // typed read → try

        let empty = try await definitions.valueQueries["EventValueQuery"].values(for: "nope")
        XCTAssertTrue(empty.items.isEmpty)
    }
}
```

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## View annotations: viewAnnotations()

`viewAnnotations()` reports the entities the app annotates on the **currently visible screen** — the read-back side of the onscreen annotations the app authors with `.appEntityIdentifier(...)` / `NSUserActivity.appEntityIdentifier` (see `onscreen-entities.md`). So drive the real app UI with `XCUIApplication` (open the detail screen via an intent, wait for it to appear), then read them. `ViewAnnotation` exposes `isSelected: Bool` and `entity: AnyAppEntity`:

```swift
final class ViewAnnotationTests: CalendarTestCase {
    @MainActor
    func testEventDetailIsAnnotated() async throws {
        let events = try await eventEntity.entities(matching: "Crew Lunch at the Nebula Cafe")
        let event = try XCTUnwrap(events.first)

        try await openEvent.makeIntent(target: event).run()          // navigate the UI

        XCTAssertTrue(app.staticTexts["Crew Lunch at the Nebula Cafe"].waitForExistence(timeout: 5))

        let annotations = try await eventEntity.viewAnnotations()
        XCTAssertEqual(annotations.count, 1)
        let annotation = try XCTUnwrap(annotations.first)
        XCTAssertEqual(try annotation.entity.title, "Crew Lunch at the Nebula Cafe")
        XCTAssertTrue(annotation.isSelected)   // the detail screen selects the event it shows
    }
}
```

`ViewAnnotation.entity` is the annotated `AnyAppEntity` and `isSelected` reports whether the app marked that entity as the selected one on screen — a detail view that presents a single event annotates it as selected, as above. For a list screen, expect multiple annotations and assert on membership/count.

**Availability:** iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0.

## Spotlight matching: spotlightQuery(_:)

`spotlightQuery(_:)` matches entities the app has indexed. Rather than indexing by hand, drive the app's normal flow — create the entity through an intent (`EventEntity` conforms to `IndexedEntity`, so the app indexes it as a side effect), give the index a moment to settle, then query:

```swift
final class SpotlightTests: CalendarTestCase {
    func testNewEventIsIndexed() async throws {
        let before = try await eventEntity.spotlightQuery("Supernova Viewing Party")
        XCTAssertTrue(before.isEmpty)

        _ = try await createEvent.makeIntent(
            title: "Supernova Viewing Party", startDate: Date(), isAllDay: false, calendar: "Deep Space"
        ).run()
        try await Task.sleep(for: .seconds(1))    // Spotlight indexing is asynchronous

        let hits = try await eventEntity.spotlightQuery("Supernova Viewing Party")
        XCTAssertEqual(hits.count, 1)
        XCTAssertEqual(try hits[0].title, "Supernova Viewing Party")
    }
}
```

`spotlightQuery(_:)` is `@available(tvOS, unavailable)` / `@available(watchOS, unavailable)` — gate cross-platform files accordingly.

**Availability:** iOS 27.0, macOS 27.0, visionOS 27.0. Unavailable on tvOS and watchOS.

## Arranging deterministic data

Because everything runs **out-of-process against the installed app**, you can't inject test doubles or seed `AppDependencyManager.shared` from the test process — the intent resolves its `@Dependency` values inside the app, and `AppIntentsTesting` exposes no test-scoped injection API. Instead, drive the app to set up known state: CometCal ships debug-only **seed/reset intents** (`SeedSampleEventsIntent`, `ResetTestDataIntent`, `ClearSpotlightIntent`) that populate a known store, and the base case runs one in `setUp`. Then assert against those known values:

```swift
final class DataSeedingTests: CalendarTestCase {
    func testResetProducesKnownCalendars() async throws {
        try await definitions.intents["ResetTestDataIntent"].makeIntent().run()

        let calendars = try await calendarEntity.allEntities()
        let titles: [String] = try calendars.map { try $0.title }
        XCTAssertTrue(titles.contains("Mission Control"))
        XCTAssertTrue(titles.contains("Deep Space"))
    }
}
```

If your app has no such seed intent, add a debug-only one (as CometCal does) — it's the out-of-process equivalent of arranging a test fixture.

## Deployment target below SDK 27

`AppIntentsTesting` is entirely iOS 27.0+, and a test that drives it only runs on iOS 27 — so the simplest path is to make the test target deploy to iOS 27+, and nothing needs gating. If the test target deploys lower, two things matter: you **cannot** gate the `import` itself (`@available` isn't allowed on an `import`, and there is no compile-time `#if available`) — the `import` weak-links and compiles fine on older targets; instead gate the **usage** by putting `@available(iOS 27.0, …, *)` on the enclosing test case. An ungated reference then fails to compile with `'IntentDefinitions' is only available in iOS 27.0 or newer`.

```swift
import XCTest
import AppIntentsTesting

@available(iOS 27.0, macOS 27.0, watchOS 27.0, tvOS 27.0, visionOS 27.0, *)
final class GatedTests: XCTestCase {
    let definitions = IntentDefinitions(bundleIdentifier: "com.example.CometCal")   // your app's bundle id

    func testRunsUnderGate() async throws {
        let result = try await definitions.intents["CreateCalendarIntent"].makeIntent(
            name: "Occupy Saturn", color: "red"
        ).run()
        XCTAssertEqual(try result.value.title, "Occupy Saturn")
    }
}
```

For `spotlightQuery(_:)`, additionally carry `@available(tvOS, unavailable)` / `@available(watchOS, unavailable)`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `IntentDefinitions`, `makeIntent`, `makeReference(identifier:)` | 27 | 27 | 27 | 27 | 27 |
| `AnyAppIntent.run()` / `ResolvedIntentResult.value` | 27 | 27 | 27 | 27 | 27 |
| entity queries / `AnyEntityQuery` / `AnyAppEntity` (`AttributedEntityIdentifier`) | 27 | 27 | 27 | 27 | 27 |
| `valueQueries` / `values(for:)` / `.items` (`DynamicPropertyPathCollection`) | 27 | 27 | 27 | 27 | 27 |
| `viewAnnotations()` / `ViewAnnotation` | 27 | 27 | 27 | 27 | 27 |
| `spotlightQuery(_:)` | 27 | 27 | n/a | n/a | 27 |

# Union Values as Shortcuts Parameters
**SDK Version:** iOS 27.0 and later

If the user's deployment target is below iOS 27 / macOS 27 / watchOS 27 / tvOS 27 / visionOS 27, the parameter behavior in this reference requires availability gating. The `@UnionValue` macro itself is older and back-deploys (`@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)`), but the `AppUnionValue` / `AppUnionValueCasesProviding` conformances that let a union type act as a Shortcuts parameter — and the parameter-summary interpolation for its components — are `@available(anyAppleOS 27.0, *)`. In practice a `@UnionValue` type is only usable as a `@Parameter` once the deployment target is 27.0, so gate at **27.0** wherever the parameter behavior is what you need. See "Deployment target below SDK 27" below for the gating shape.

`@UnionValue` lets one value be any of several unrelated types — `case place(PlaceDescriptor)` or `case address(String)`. The sibling `visual-intelligence.md` covers `@UnionValue` for multi-type visual-query **results** (returning `[LandmarkResult]` from an `IntentValueQuery`). This reference is about the other direction: using a `@UnionValue` type as **parameter input** in a Shortcuts action, where the new-in-27 `AppUnionValue` / `AppUnionValueCasesProviding` conformances give the union the nominal identity and per-case metadata the editor needs to render a case picker and a parameter summary.

The running example is drawn from Apple's published **CometCal** calendar sample, whose `EventLocation` union lets a calendar event's location be either a structured place or a free-text address.

## What `@UnionValue` produces

Applying `@UnionValue` to an `enum` whose cases each wrap a single type generates an extension conforming the enum to `AppUnionValue` (plus the supporting App Intents value conformance the macro adds). That conformance is what carries the union into App Intents: `AppUnionValue` refines `TypeDisplayRepresentable` and declares an associated `Cases` type (`associatedtype Cases: AppUnionValueCasesProviding where Cases.UnionValue == Self`). The macro also synthesizes the nested `Cases` enum — one bare case per union case — and conforms it to `AppUnionValueCasesProviding`, which itself refines `AppEnum`. That `AppEnum`-backed `Cases` enum is the nominal, metadata-bearing type Shortcuts uses to offer the user a "which kind?" picker before it collects the associated value.

Without `AppUnionValue`/`AppUnionValueCasesProviding` (iOS 27.0) the macro would still expand, but the union would lack the case metadata and nominal identity required to surface it as a selectable parameter — these two conformances are the new-in-27 piece that makes a union a first-class Shortcuts input.

**Availability:** `AppUnionValue` and `AppUnionValueCasesProviding` are both `@available(anyAppleOS 27.0, *)`. The `@UnionValue` macro is `@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)`.

## A `@UnionValue` enum as a `@Parameter`

Declare the union with `@UnionValue`, then use it directly as the `Value` type of a `@Parameter`. Each case's wrapped type (`PlaceDescriptor`, `String`, …) must itself be a valid App Intents value — an `AppEntity`, `AppEnum`, or a built-in like `String`. Because the parameter behavior depends on the 27.0 conformances, gate the union type and the intent at iOS 27.0.

```swift
import AppIntents
import GeoToolbox

@available(iOS 27.0, *)
@UnionValue
enum EventLocation {
    case place(PlaceDescriptor)    // PlaceDescriptor from GeoToolbox
    case address(String)
}

@available(iOS 27.0, *)
@AppIntent(schema: .calendar.createEvent)
struct CreateEventIntent {

    // Shortcuts renders a case picker (Place vs. Address) then collects the value.
    var location: EventLocation?

    @MainActor
    func perform() async throws -> some ReturnsValue<EventEntity> {
        // switch over the selected case
        if case .address(let str) = location {
            // use the free-text address
        } else if case .place(let place) = location {
            // use the structured PlaceDescriptor
        }
        // ...
    }
}
```

CometCal reaches `EventLocation` through the `.calendar.createEvent` schema, so the union arrives as a schema-provided property rather than an explicit `@Parameter`. Most apps adopt `@UnionValue` on their **own** intents, where you declare the same union type directly as a `@Parameter` — this is the shape you'll write most often:

```swift
@available(iOS 27.0, *)
struct SetEventLocationIntent: AppIntent {
    static let title: LocalizedStringResource = "Set Event Location"

    // Shortcuts renders a case picker (Place vs. Address), then collects the value.
    @Parameter(title: "Location")
    var location: EventLocation

    func perform() async throws -> some IntentResult {
        switch location {
        case .place(let place):    _ = place    // structured PlaceDescriptor
        case .address(let text):   _ = text     // free-text address
        }
        return .result()
    }
}
```

**Availability:** the union type is usable as a `@Parameter` only from iOS 27.0 (the `AppUnionValue` conformance floor). Gate the `@UnionValue` type and the enclosing intent with `@available(iOS 27.0, *)`.

## Custom case metadata and type display

Let the macro synthesize the `Cases` enum; do not hand-roll it. Provide user-facing strings by implementing the `AppUnionValue` requirements in an extension: `typeDisplayRepresentation` names the union in the editor, and `caseDisplayRepresentations` maps each `Cases` value to the label shown in the picker. Both have empty default implementations, so an un-customized union shows blank strings — supply real ones for anything user-visible. (CometCal's `EventLocation` leaves these at their defaults; the extension below shows the shape you'd add.)

```swift
@available(iOS 27.0, *)
extension EventLocation {
    static var typeDisplayRepresentation: TypeDisplayRepresentation { "Event Location" }

    static let caseDisplayRepresentations: [Cases: DisplayRepresentation] = [
        .place: "Place",
        .address: "Address",
    ]
}
```

`AppUnionValueCasesProviding` inherits both `typeDisplayRepresentation` and `caseDisplayRepresentations` from the associated `UnionValue`, so you write the metadata once on the union and the generated `Cases` enum picks it up automatically.

**Availability:** `AppUnionValue.typeDisplayRepresentation` / `caseDisplayRepresentations` and the `AppUnionValueCasesProviding` inheriting defaults are `@available(anyAppleOS 27.0, *)`.

## Union components in parameter summaries

A union parameter exposes two components for `Summary` interpolation: `\.$parameter.type` (the case name of the selected value) and `\.$parameter.value` (the associated value of that case). These are surfaced by `IntentParameter.AppUnionValueComponent` (`.type` / `.value`) and are available only when `Value.ValueType: AppUnionValue`. 

```swift
@available(iOS 27.0, *)
@AppIntent(schema: .calendar.createEvent)
struct CreateEventIntent {
    static var parameterSummary: some ParameterSummary {
        Summary("Create event at \(\.$location.type): \(\.$location.value)")
    }
    // ...
}
```

**Availability:** the `ParameterSummaryString.StringInterpolation` overload for union components and `IntentParameter.AppUnionValueComponent` are `@available(anyAppleOS 27.0, *)`.

## Don't hand-roll the Cases enum

Never define the `Cases` enum or its conformance yourself — the macro generates it and wires `Cases.UnionValue == Self`; a hand-written one will not satisfy the `where` clauses. Put customization in an extension on the union, not on `Cases`.

Also mind the availability split: the `@UnionValue` macro attribute reads as iOS 18.0, but that floor is a red herring for parameter use. The parameter picker, custom metadata, and summary interpolation all depend on the 27.0 conformances, so gate at iOS 27.0 whenever the union is a Shortcuts parameter — matching the RESULTS guidance in `visual-intelligence.md`.

## Deployment target below SDK 27

When the user's deployment target is below SDK 27 and the answer needs a `@UnionValue` type as a parameter, gate the union and its intent behind an availability check and provide a fallback path for older OS versions:

```swift
@available(iOS 27.0, *)
@UnionValue
enum EventLocation {
    case place(PlaceDescriptor)
    case address(String)
}

@available(iOS 27.0, *)
@AppIntent(schema: .calendar.createEvent)
struct CreateEventIntent {
    var location: EventLocation?
    // ...
}
```

Gate to the conformance floor — iOS 27.0 / macOS 27.0 / watchOS 27.0 / tvOS 27.0 / visionOS 27.0 — even though the `@UnionValue` macro attribute itself back-deploys to iOS 18.0; the parameter behavior is what pins it to 27.0. For deployment targets below 27, provide separate scalar parameters (e.g. one for the structured place, one for the address string) or split into two intents rather than a union. Don't emit an unconditional `@UnionValue` parameter; the typecheck will fail with `'AppUnionValue' is only available in iOS 27.0 or newer`.

## Availability summary

| Symbol | Availability | Notes |
|---|---|---|
| `@UnionValue` (macro) | iOS 18.0, macOS 15.0, watchOS 11.0, tvOS 18.0, visionOS 2.0 | Older floor; expands to the `AppUnionValue` conformance (plus the macro's supporting value conformance) |
| `AppUnionValue` | anyAppleOS 27.0 | Public protocol; refines `TypeDisplayRepresentable`; nominal identity + `Cases` |
| `AppUnionValueCasesProviding` | anyAppleOS 27.0 | Public protocol; refines `AppEnum`; the generated `Cases` enum conforms |
| `AppUnionValue.typeDisplayRepresentation` / `caseDisplayRepresentations` | anyAppleOS 27.0 | Empty defaults; override in an extension on the union |
| `IntentParameter.AppUnionValueComponent` (`.type` / `.value`) | anyAppleOS 27.0 | Union components for parameter summaries |
| `ParameterSummaryString.StringInterpolation` union overload | anyAppleOS 27.0 | Enables `\.$param.type` / `\.$param.value` in `Summary` |
| Effective gate for a `@UnionValue` **parameter** | iOS 27.0 | Parameter/picker/summary behavior requires the 27.0 conformances |

# Visual Intelligence
**SDK Version:** iOS 26.0 and later

If the user's deployment target is below the availability listed for a given API in this reference (`IntentValueQuery` and `SemanticContentDescriptor` are iOS 26.0; `@UnionValue` / `AppUnionValue` are effectively iOS 27.0; `OpenIntent` back-deploys to iOS 16.0), the new usage requires availability gating. See "Deployment target below the API's floor" below for the gating shape to use.

Visual intelligence lets the system hand your app what the camera or a screenshot sees and ask which of your entities match: you supply the query, the result types, and the "open" intents that make each result actionable. The running example is **TravelTracking**, a travel app with a `LandmarkEntity` and a `LandmarkCollectionEntity`. Associating the entity on the *current screen* with "this" is a separate surface — see `onscreen-entities.md`; proactively surfacing entities (`RelevantEntities`, `AppEntityContext`) lives in `relevance-and-context.md`.

## IntentValueQuery for visual intelligence

`IntentValueQuery` answers a visual-intelligence search: the system hands you a `SemanticContentDescriptor` and you return the matching entities. Conform a type to `IntentValueQuery`, set `Input` to `SemanticContentDescriptor`, and implement `func values(for:) async throws`. `SemanticContentDescriptor` lives in the **VisualIntelligence** framework, not AppIntents — you must `import VisualIntelligence` or the `Input` type will not resolve. It exposes `public let labels: [String]` and `public var pixelBuffer: CVReadOnlyPixelBuffer?`, both read-only; you consume the descriptor, you never construct one. There is no separate "register this query" call — the system discovers the conformance through App Intents metadata extraction, the same way it finds `AppIntent` and `EntityQuery` types.

```swift
import AppIntents
import VisualIntelligence            // SemanticContentDescriptor lives here.

@available(iOS 26.0, *)
struct LandmarkIntentValueQuery: IntentValueQuery {
    // Input is the system-provided descriptor, not a String or your own type.
    func values(for input: SemanticContentDescriptor) async throws -> [LandmarkEntity] {
        let hints = input.labels                       // e.g. ["mountain", "peak"]
        return try await ModelData.shared.match(labels: hints,
                                                pixelBuffer: input.pixelBuffer)
    }
}
```

**Availability:** `IntentValueQuery` is `@available(anyAppleOS 26.0, *)`. `SemanticContentDescriptor` is `@available(iOS 26.0, macOS 27.0, macCatalyst 27.0, *)` (VisualIntelligence). Gate the query with `@available(iOS 26.0, *)`.

## @UnionValue for multiple result types

When one visual query can return more than one entity type — a `LandmarkEntity` or a `LandmarkCollectionEntity` — do not erase to `[any AppEntity]`, which loses per-type "open" targeting and display. Instead define a `@UnionValue` enum with one `case` per concrete type and return an array of it. (How `@UnionValue` expands and why the union type is gated at iOS 27.0 rather than the macro's own 18.0 floor is covered in `union-values.md`; here it's just the result type of the query.)

```swift
import AppIntents
import VisualIntelligence

@available(iOS 27.0, *)
@UnionValue
enum LandmarkResult {
    case landmark(LandmarkEntity)
    case collection(LandmarkCollectionEntity)
}

@available(iOS 27.0, *)
struct LandmarkIntentValueQuery: IntentValueQuery {
    func values(for input: SemanticContentDescriptor) async throws -> [LandmarkResult] {
        var results: [LandmarkResult] = []
        results += try await ModelData.shared.matchLandmarks(input).map(LandmarkResult.landmark)
        results += try await ModelData.shared.matchCollections(input).map(LandmarkResult.collection)
        return results
    }
}
```

**Availability:** gate a `@UnionValue` result type at `@available(iOS 27.0, *)` (the `AppUnionValue` conformance the union relies on is iOS 27.0, even though the `@UnionValue` macro itself back-deploys). Using a `@UnionValue` type as a Shortcuts *parameter* is covered in `union-values.md`.

## One OpenIntent per result type

A visual result is inert until tapping it opens something, so give each result type an `OpenIntent` and the system offers "open" on it. The VI-specific rule: an `OpenIntent`'s `Value` must be a **single concrete** `AppEntity`/`AppValue`, never the `@UnionValue` — so with a multi-type (`@UnionValue`) result you write **one `OpenIntent` per case type**. (`OpenIntent` itself — the `target`, `openAppWhenRun`, the default `perform()` — is covered in the specialist skill's `url-representation`.)

```swift
import AppIntents

@available(iOS 16.0, *)
struct OpenLandmarkIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Landmark"

    @Parameter(title: "Landmark")
    var target: LandmarkEntity             // OpenIntent.Value == LandmarkEntity
}

@available(iOS 16.0, *)
struct OpenLandmarkCollectionIntent: OpenIntent {
    static let title: LocalizedStringResource = "Open Landmark Collection"

    @Parameter(title: "Landmark Collection")
    var target: LandmarkCollectionEntity
}
```

**Availability:** `OpenIntent` is `@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)`.

## Availability summary

| API | iOS | macOS | watchOS | tvOS | visionOS |
|---|---|---|---|---|---|
| `IntentValueQuery` | 26.0 | 26.0 | 26.0 | 26.0 | 26.0 |
| `SemanticContentDescriptor`¹ | 26.0 | 27.0 | — | — | — |
| `@UnionValue` result type² | 27.0 | 27.0 | 27.0 | 27.0 | 27.0 |
| `OpenIntent` | 16.0 | 13.0 | 9.0 | 16.0 | 1.0³ |

¹ Ships from the **VisualIntelligence** framework (`import VisualIntelligence`), declared `@available(iOS 26.0, macOS 27.0, macCatalyst 27.0, *)` — note the mixed floor (iOS 26 but macOS 27); it is not part of AppIntents.
² The `@UnionValue` macro attribute is iOS 18.0, but a union usable as a result here conforms to `AppUnionValue` (iOS 27.0) — gate union *types* at iOS 27.0.
³ The interface declares `OpenIntent` as `@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)` — no explicit visionOS floor; visionOS availability (1.0) is implied by the trailing `*`, not enumerated.