## Summary - Add Siri and Shortcuts actions for music playback, queue management, playlists, favorites, and transport controls. - Bridge native App Intents to the mobile app’s playback and library data. ## Testing - Not run Reviewed-on: #40
2.9 KiB
Siri and Shortcuts
This integration uses Expo 58 inline modules and expo-app-intents. Rebuild the native app after changing Swift declarations or registrations. An OTA JavaScript update cannot add these capabilities.
Playback and library changes open oTunes because they need its authenticated React runtime. Swift dispatches a request and waits for an app-owned completion acknowledgment. Playback waits for the native audio player to load the requested track; warmup waits for it to load while paused. Errors reach Siri, and requests that have expired are discarded before starting a side effect. Native catalog reads do not open the app.
The full entity catalog lives in Application Support. The backend supplies pages of 200 records. Expo's UserDefaults catalog holds at most 100 suggestions per kind, with favorites first, and mirrors those suggestions into Spotlight. Siri's native queries search the full disk catalog. Catalogs refresh on launch, foreground entry, favorite changes, and every five minutes while foregrounded.
Songs, albums, artists, and playlists have Spotlight open intents and on-screen entity associations. Associations require iOS 18.4 and Xcode 27; Spotlight indexing requires iOS 18. Playback donations are made after the player starts, preserve shuffle, and resolve real catalog entities. Removed records trigger donation cleanup. Sign-out clears catalogs, Spotlight entries, donations, and pending invocations. On iOS 27, the query types also handle system requests to rebuild Spotlight indexes.
Audio schema intents require Xcode 27 and iOS 27. Custom intents remain available on earlier supported versions and remain visible on iOS 27 because intent discovery metadata must be a compile-time constant.
Backend rollout
Deploy the companion Convex changes before installing the new mobile build:
library.intentCatalogPagesupplies authenticated, paginated entity records.appIntentPlaylistsrecords playlist-creation request IDs in the same transaction as creation. Replaying a request returns the original playlist ID.playlists.createPlaylistaccepts an optionalinvocationId; existing callers can omit it.
Verification
Run from the repository root:
pnpm --filter @otunes/mobile typecheck
pnpm --filter @otunes/convex typecheck
node --test apps/mobile/lib/app-intents.test.cjs packages/convex/convex/app-intent-playlists.test.cjs
Build iOS with Xcode and verify the app target's ExtractAppIntentsMetadata phase. TypeScript checks alone do not validate Swift declarations or Apple's schema contracts.
On a suitable device, verify cold and warm playback, paused warmup followed by playback, offline errors, request expiry, playlist replay, and a saved shortcut after upgrading. Check entity resolution after rename/delete and sign-out. Verify Spotlight opening, on-screen requests, and donations separately; metadata extraction does not establish system discovery or successful runtime execution.