CamilleScholtz/swmpc / .agents/skills/app-intents-whats-new-27
app-intents-whats-new-27
VerifiedNew App Intents APIs and behaviors for iOS 27 and macOS 27: SnippetIntent, LongRunningIntent, execution modes, and interactive snippets.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.8 KB |
| references/convenience-properties.md | markdown | 6.6 KB |
| references/cross-device-and-ownership.md | markdown | 7.8 KB |
| references/entity-collection.md | markdown | 8.7 KB |
| references/execution-modes.md | markdown | 10.6 KB |
| references/interactive-snippets.md | markdown | 13.9 KB |
| references/onscreen-entities.md | markdown | 6.4 KB |
| references/relevance-and-context.md | markdown | 6.8 KB |
| references/requestchoice.md | markdown | 5.3 KB |
| references/schema-adoption.md | markdown | 14.9 KB |
| references/spotlight-indexing.md | markdown | 7.1 KB |
| references/system-shortcuts.md | markdown | 3.1 KB |
| references/testing.md | markdown | 14.9 KB |
| references/union-values.md | markdown | 10.0 KB |
| references/visual-intelligence.md | markdown | 6.1 KB |
references/cross-device-and-ownership.md
View on GitHub# 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`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |