@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/shareplay-activities/SKILL.md

@@ -1,500 +1,329 @@
 ---
 name: shareplay-activities
-description: "Build shared real-time experiences using GroupActivities and SharePlay. Use when implementing shared media playback, collaborative app features, synchronized game state, or any FaceTime, Messages, AirDrop, or nearby visionOS group activity on iOS, macOS, tvOS, or visionOS."
+description: "GroupActivities and SharePlay on iOS, macOS, tvOS and visionOS: GroupActivity, GroupSession lifecycle, messengers, playback sync, file transfer, late joiners. Use for shared media, collaboration or synced game state over FaceTime, Messages, AirDrop or nearby sharing."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
-# GroupActivities / SharePlay
-Build shared real-time experiences using the GroupActivities framework. SharePlay
-connects people over FaceTime, Messages, AirDrop, and nearby visionOS sharing,
-synchronizing media playback, app state, or custom data. Targets Swift 6.3 / iOS 26+.
-
-## Contents
-
-- [Setup](#setup)
-- [Defining a GroupActivity](#defining-a-groupactivity)
-- [Session Lifecycle](#session-lifecycle)
-- [Sending and Receiving Messages](#sending-and-receiving-messages)
-- [Coordinated Media Playback](#coordinated-media-playback)
-- [Starting SharePlay from Your App](#starting-shareplay-from-your-app)
-- [GroupSessionJournal: File Transfer](#groupsessionjournal-file-transfer)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+
+# SharePlay and Group Activities
+
+SharePlay joins people in a FaceTime call, a Messages conversation, an AirDrop
+exchange or, on visionOS, a room of nearby headsets, and keeps media, app state
+or custom data in step between them. Code here is written for Swift 6.3 on
+iOS 26 and newer.
 
 ## Setup
 
 ### Capability
 
-Add the **Group Activities** capability to the app target in Xcode. Xcode adds
-the required entitlement and updates the provisioning profile:
+Add **Group Activities** to the app target under Signing & Capabilities. Xcode
+then sets `com.apple.developer.group-session` to `true` in the entitlements
+file and refreshes provisioning.
 
-```xml
-<key>com.apple.developer.group-session</key>
-<true/>
-```
+Only app targets get it. Group Activities does not run in widgets, other
+extensions or App Clips.
 
-Configure this only for app targets. Group Activities are not available in
-widgets, extensions, or App Clips.
+### Eligibility
 
-### Checking Eligibility
+`GroupStateObserver` reports whether a FaceTime call, or a Messages chat, is
+currently able to host an activity. Use it to decide whether a
+SharePlay button appears.
 
 ```swift
 import GroupActivities
 
-let observer = GroupStateObserver()
-
-// Check if a FaceTime call or Messages conversation is active
-if observer.isEligibleForGroupSession {
-    showSharePlayButton()
-}
-```
-
-Observe changes reactively:
-
-```swift
-for await isEligible in observer.$isEligibleForGroupSession.values {
-    showSharePlayButton(isEligible)
+@MainActor
+func watchEligibility(update: @escaping @MainActor (Bool) -> Void) async {
+    let observer = GroupStateObserver()
+    update(observer.isEligibleForGroupSession)
+    for await eligible in observer.$isEligibleForGroupSession.values {
+        update(eligible)
+    }
 }
 ```
 
-## Defining a GroupActivity
-
-Conform to `GroupActivity` and provide metadata:
+## Defining an activity
 
 ```swift
-import GroupActivities
-
-struct WatchTogetherActivity: GroupActivity {
-    let movieID: String
-    let movieTitle: String
+struct CookAlong: GroupActivity {
+    let recipeID: String
 
     var metadata: GroupActivityMetadata {
-        var meta = GroupActivityMetadata()
-        meta.title = movieTitle
-        meta.type = .watchTogether
-        meta.fallbackURL = URL(string: "https://example.com/movie/\(movieID)")
-        return meta
+        var info = GroupActivityMetadata()
+        info.title = "Cook together"
+        info.type = .exploreTogether
+        info.fallbackURL = URL(string: "https://recipes.example/r/\(recipeID)")
+        return info
     }
 }
 ```
 
-### Activity Types
+### Activity types
 
-| Type | Use Case |
-|---|---|
-| `.generic` | Default for custom activities |
-| `.watchTogether` | Video playback |
-| `.listenTogether` | Audio playback |
-| `.createTogether` | Collaborative creation (drawing, editing) |
-| `.exploreTogether` | Shared browsing, planning, or exploration |
-| `.learnTogether` | Shared learning or studying |
-| `.readTogether` | Shared reading |
-| `.shopTogether` | Shared shopping |
-| `.workoutTogether` | Shared fitness sessions |
+| Type | Fits |
+| --- | --- |
+| `.generic` | The default for anything custom |
+| `.watchTogether` | Video |
+| `.listenTogether` | Audio |
+| `.createTogether` | Drawing, editing, building something together |
+| `.exploreTogether` | Browsing, planning, exploring |
+| `.learnTogether` | Study sessions |
+| `.readTogether` | Reading |
+| `.shopTogether` | Shopping |
+| `.workoutTogether` | Fitness |
 
-`GroupActivity` is `Codable`; stored activity data must be codable. Add
-`Transferable` only for SwiftUI `ShareLink`, SharePlay over AirDrop, or
-AppKit/UIKit share sheets. Keep payloads minimal: use identifiers or URLs
-instead of large data.
+`GroupActivity` inherits `Codable`, so every stored property must be codable.
+Keep the payload tiny: an identifier or a URL, never the content itself. Add
+`Transferable` only when the activity is offered through a SwiftUI `ShareLink`,
+an AirDrop hand-off, or a UIKit or AppKit share sheet.
 
-## Session Lifecycle
+## Session lifecycle
 
-### Listening for Sessions
+### Receiving sessions
 
-Set up a long-lived task to receive sessions when another participant starts
-the activity:
+Sessions started by anyone arrive through `Activity.sessions()`. Iterate it in
+a task owned by a long-lived object.
 
 ```swift
-@Observable
-@MainActor
-final class SharePlayManager {
-    private var session: GroupSession<WatchTogetherActivity>?
+import GroupActivities
+import Observation
+
+@MainActor @Observable
+final class KitchenSession {
+    private(set) var people: Set<Participant> = []
+    private(set) var session: GroupSession<CookAlong>?
+    private var jobs: [Task<Void, Never>] = []
     private var messenger: GroupSessionMessenger?
-    private var sessionTasks: [Task<Void, Never>] = []
 
-    func observeSessions() {
-        Task {
-            for await session in WatchTogetherActivity.sessions() {
-                self.configureSession(session)
-            }
+    init() {
+        Task { @MainActor [weak self] in
+            for await incoming in CookAlong.sessions() { self?.attach(incoming) }
         }
     }
 
-    private func configureSession(
-        _ session: GroupSession<WatchTogetherActivity>
-    ) {
-        self.session = session
-        self.messenger = GroupSessionMessenger(session: session)
-
-        // Observe session state changes
-        let stateTask = Task {
-            for await state in session.$state.values {
-                handleState(state)
-            }
-        }
-        sessionTasks.append(stateTask)
+    private func attach(_ incoming: GroupSession<CookAlong>) {
+        session = incoming
+        messenger = GroupSessionMessenger(session: incoming)
+        let states = incoming.$state.values
+        let rosters = incoming.$activeParticipants.values
+        jobs.append(Task { @MainActor [weak self] in
+            for await phase in states { self?.handle(phase) }
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            for await roster in rosters { self?.people = roster }
+        })
+        incoming.join()
+    }
 
-        // Observe participant changes
-        let participantTask = Task {
-            for await participants in session.$activeParticipants.values {
-                handleParticipants(participants)
-            }
+    private func handle(_ state: GroupSession<CookAlong>.State) {
+        switch state {
+        case .waiting:
+            break
+        case .joined:
+            if let recipe = session?.activity.recipeID { RecipeStore.shared.open(recipe) }
+        case .invalidated:
+            teardown()
+        @unknown default:
+            break
         }
-        sessionTasks.append(participantTask)
-
-        // Join the session
-        session.join()
     }
 
-    private func cleanUp() {
-        sessionTasks.forEach { $0.cancel() }
-        sessionTasks.removeAll()
+    func teardown() {
+        for job in jobs { job.cancel() }
+        jobs = []
         session = nil
         messenger = nil
     }
 }
 ```
 
-### Session States
-
-| State | Description |
-|---|---|
-| `.waiting` | Session exists but local participant has not joined |
-| `.joined` | Local participant is actively in the session |
-| `.invalidated(reason:)` | Session ended (check reason for details) |
-
-### Handling State Changes
-
-```swift
-private func handleState(_ state: GroupSession<WatchTogetherActivity>.State) {
-    switch state {
-    case .waiting:
-        print("Waiting to join")
-    case .joined:
-        print("Joined session")
-        loadActivity(session?.activity)
-    case .invalidated(let reason):
-        print("Session ended: \(reason)")
-        cleanUp()
-    @unknown default:
-        break
-    }
-}
-
-private func handleParticipants(_ participants: Set<Participant>) {
-    print("Active participants: \(participants.count)")
-}
-```
-
-### Leaving and Ending
+### States
 
-```swift
-// Leave the session (other participants continue)
-session?.leave()
+| State | Meaning |
+| --- | --- |
+| `.waiting` | The session exists; the local person has not joined |
+| `.joined` | The local person is in the session |
+| `.invalidated(reason:)` | The session is over; the reason says why |
 
-// End the session for all participants
-session?.end()
-```
+Participants come as a `Set<Participant>`.
 
-## Sending and Receiving Messages
+### Leaving and ending
 
-Use `GroupSessionMessenger` to sync small, time-sensitive app state between
-participants.
+- `session?.leave()`: only this device leaves; everyone else carries on.
+- `session?.end()`: the session ends for all participants.
 
-### Defining Messages
+## Messages
 
-Messages must be `Codable`; keep each message under 256 KB.
+`GroupSessionMessenger` carries small, time-sensitive app state. Each message
+is `Codable` and must stay under 256 KB.
 
 ```swift
-struct SyncMessage: Codable {
-    let action: String
-    let timestamp: Date
-    let data: [String: String]
+struct StepChanged: Codable, Sendable {
+    let stepIndex: Int
 }
-```
-
-### Sending
-
-```swift
-func sendSync(_ message: SyncMessage) async throws {
-    guard let messenger else { return }
 
-    try await messenger.send(message, to: .all)
+func announce(step: Int, via messenger: GroupSessionMessenger) async throws {
+    try await messenger.send(StepChanged(stepIndex: step), to: .all)
 }
 
-// Send to specific participants
-try await messenger.send(message, to: .only(participant))
-```
-
-### Receiving
-
-```swift
-func observeMessages() {
-    guard let messenger else { return }
-
-    Task {
-        for await (message, context) in messenger.messages(of: SyncMessage.self) {
-            let sender = context.source
-            handleReceivedMessage(message, from: sender)
-        }
+func listen(on messenger: GroupSessionMessenger) async {
+    for await (change, context) in messenger.messages(of: StepChanged.self) {
+        RecipeStore.shared.show(step: change.stepIndex, from: context.source)
     }
 }
 ```
 
-### Delivery Modes
+Send to one person with `to: .only(participant)`; the sender of a received
+message is `context.source`.
 
-```swift
-// Reliable (default) -- checked and retried for crucial state
-let reliableMessenger = GroupSessionMessenger(
-    session: session,
-    deliveryMode: .reliable
-)
-
-// Unreliable -- lower latency, no delivery guarantee
-let unreliableMessenger = GroupSessionMessenger(
-    session: session,
-    deliveryMode: .unreliable
-)
-```
+Pick a delivery mode with `GroupSessionMessenger(session:deliveryMode:)`:
 
-Use `.reliable` for state-changing actions such as selections or turns. Use
-`.unreliable` for high-frequency ephemeral data such as cursor positions,
-drawing strokes, and reactions.
+| Mode | Behaviour | Use for |
+| --- | --- | --- |
+| `.reliable` (default) | Delivery checked and retried | State changes: selections, turns |
+| `.unreliable` | Lower latency, may drop | Frequent throwaway data: cursors, strokes, reactions |
 
-## Coordinated Media Playback
+## Coordinated media playback
 
-For video/audio, use `AVPlaybackCoordinator` with `AVPlayer`:
+For `AVPlayer` content, hand the session to the player's coordinator:
 
 ```swift
 import AVFoundation
-import GroupActivities
 
-func configurePlayback(
-    session: GroupSession<WatchTogetherActivity>,
-    player: AVPlayer
-) {
-    // Connect the player's coordinator to the session
-    let coordinator = player.playbackCoordinator
-    coordinator.coordinateWithSession(session)
+func syncPlayback(_ player: AVPlayer, with session: GroupSession<MovieNight>) {
+    player.playbackCoordinator.coordinateWithSession(session)
 }
 ```
 
-Once connected, AVFoundation synchronizes play/pause, seeking, rate, playback speed,
-and time. Do not put AVPlayer transport fields in messenger messages or snapshots,
-including late-joiner snapshots; use custom messages only for state outside playback.
+`AVPlaybackCoordinator` then keeps play, pause, seeks, rate and position in
+step for everyone. Play state, position and rate never belong in your own
+messages or state snapshots, late-joiner snapshots included. Custom messages are
+for state that playback does not cover.
 
-## Starting SharePlay from Your App
-
-### Using GroupActivitySharingController (UIKit)
+## Starting SharePlay from the app
 
 ```swift
-import GroupActivities
-import UIKit
-
-func startSharePlay() async throws {
-    let activity = WatchTogetherActivity(
-        movieID: "123",
-        movieTitle: "Great Movie"
-    )
-
-    switch await activity.prepareForActivation() {
-    case .activationPreferred:
-        // A conversation is active and the user chose to share.
-        _ = try await activity.activate()
-
+func startCooking(_ activity: CookAlong) async {
+    let choice = await activity.prepareForActivation()
+    switch choice {
     case .activationDisabled:
-        // The user chose local playback, or sharing is unavailable.
-        startLocalExperience()
-
+        RecipeStore.shared.open(activity.recipeID)
+    case .activationPreferred:
+        do { _ = try await activity.activate() } catch { Log.share.error("\(error)") }
     case .cancelled:
-        break
-
+        return
     @unknown default:
-        break
+        return
     }
 }
 ```
 
-When no conversation is active (i.e., `isEligibleForGroupSession` is false),
-use `GroupActivitySharingController` to let the user pick contacts first:
-
-```swift
-let controller = try GroupActivitySharingController(activity)
-present(controller, animated: true)
-```
-
-Use the `shareplay` SF Symbol for custom controls. Treat `GroupActivityMetadata`
-as discovery copy: concise title, subtitle, image, and type aligned with the
-entry point. Keep sibling domains out: GameKit owns auth, matchmaking,
-leaderboards, achievements, and voice/chat; TabletopKit owns seats, board
-equipment, spatial placement, turns, rules, and authoritative tabletop state;
-AVKit owns playback UI. SharePlay owns invitations, lifecycle, participants, and
-coordination handoffs. See [references/shareplay-patterns.md](references/shareplay-patterns.md) for SwiftUI `ShareLink`, AirDrop, and direct activation patterns.
-
-## GroupSessionJournal: File Transfer
-
-For larger, non-time-sensitive attachments, use `GroupSessionJournal` instead
-of `GroupSessionMessenger`. Journal items must conform to `Transferable`, are
-available to late joiners, and are limited to 100 MB. It requires iOS/iPadOS/tvOS
-17+, macOS 14+, or visionOS 1+. For larger/protected assets, share a pointer or manifest and use server storage or app-managed file transfer.
-
-```swift
-import GroupActivities
-
-let journal = GroupSessionJournal(session: session)
-
-// Upload a Transferable file or data item
-let attachment = try await journal.add(sharedImageItem)
-
-// Observe incoming attachments
-Task {
-    for await attachments in journal.attachments {
-        for attachment in attachments {
-            let data = try await attachment.load(Data.self)
-            handleReceivedFile(data)
-        }
-    }
-}
-```
-
-## Common Mistakes
-
-### DON'T: Forget to call session.join()
-
-```swift
-// WRONG -- session is received but never joined
-for await session in MyActivity.sessions() {
-    self.session = session
-    // Session stays in .waiting state forever
-}
-
-// CORRECT -- join after configuring
-for await session in MyActivity.sessions() {
-    self.session = session
-    self.messenger = GroupSessionMessenger(session: session)
-    session.join()
-}
-```
-
-### DON'T: Forget to leave or end sessions
+- `.activationPreferred`: there is a live conversation and sharing was
+  chosen; call `activate()`.
+- `.activationDisabled`: they chose to stay local, or sharing is not possible;
+  start the local experience.
+- `.cancelled`: do nothing.
 
-```swift
-// WRONG -- session stays alive after the user navigates away
-func viewDidDisappear() {
-    // Nothing -- session leaks
-}
-
-// CORRECT -- leave when the view is dismissed
-func viewDidDisappear() {
-    session?.leave()
-    session = nil
-    messenger = nil
-}
-```
-
-### DON'T: Assume all participants have the same state
+With no conversation in progress (`isEligibleForGroupSession == false`),
+present `GroupActivitySharingController` in UIKit so the person can pick
+contacts:
 
 ```swift
-// WRONG -- broadcasting state without handling late joiners
-func onJoin() {
-    // New participant has no idea what the current state is
-}
-
-// CORRECT -- send full state to new participants
-func handleParticipants(_ participants: Set<Participant>) {
-    let newParticipants = participants.subtracting(knownParticipants)
-    for participant in newParticipants {
-        Task {
-            try await messenger?.send(currentState, to: .only(participant))
-        }
-    }
-    knownParticipants = participants
-}
+let picker = try GroupActivitySharingController(CookAlong(recipeID: recipe.id))
+hostViewController.present(picker, animated: true)
 ```
 
-### DON'T: Use SharePlay transports for large/protected assets
-
-```swift
-// WRONG -- messenger is small/time-sensitive; journal is Transferable and <=100 MB
-let imageData = try Data(contentsOf: imageURL)     // 300 KB
-try await messenger.send(imageData, to: .all)      // Too large
-// CORRECT -- journal attachments up to 100 MB; otherwise share a pointer/manifest
-let journal = GroupSessionJournal(session: session)
-try await journal.add(sharedImageItem)
-// Larger/protected assets: server storage or app-managed file transfer
-```
+Custom controls use the `shareplay` SF Symbol. Write
+`GroupActivityMetadata` as discovery copy: a short title, a subtitle and image
+where the surface shows them, and a type that matches where the activity was
+started. SwiftUI buttons, `ShareLink` and AirDrop are covered in
+[the patterns file](references/shareplay-patterns.md).
 
-### DON'T: Send redundant messages for media playback
+Boundaries with neighbouring frameworks:
 
-```swift
-// WRONG -- manually syncing play/pause when using AVPlayer
-func play() {
-    player.play()
-    try await messenger.send(PlayMessage(), to: .all)
-}
+- GameKit: sign-in, matchmaking, leaderboards, achievements, voice chat.
+- TabletopKit: seating, pieces on the board, where things sit in space, turn
+  order, game rules, and which device holds the true table state.
+- AVKit: playback UI.
+- SharePlay (this skill): invitations, session lifecycle, participants and the
+  hand-off points to the others.
 
-// CORRECT -- let AVPlaybackCoordinator handle it
-player.playbackCoordinator.coordinateWithSession(session)
-player.play()  // Automatically synced to all participants
-```
+## GroupSessionJournal: sharing files
 
-### DON'T: Observe sessions in a view that gets recreated
+For bigger attachments that are not time-critical, use `GroupSessionJournal`
+instead of the messenger. Items must be `Transferable`, attachments stay
+available to people who join later, and each attachment may be up to 100 MB.
+Available on iOS, iPadOS and tvOS 17+, macOS 14+ and visionOS 1+.
 
 ```swift
-// WRONG -- each time the view appears, a new listener is created
-struct MyView: View {
-    var body: some View {
-        Text("Hello")
-            .task {
-                for await session in MyActivity.sessions() { }
-            }
-    }
+func sharePhoto(_ photo: DishPhoto, in session: GroupSession<CookAlong>) async throws {
+    let shelf = GroupSessionJournal(session: session)
+    _ = try await shelf.add(photo)
 }
 
-// CORRECT -- observe sessions in a long-lived manager
-@Observable
-final class ActivityManager {
-    init() {
-        Task {
-            for await session in MyActivity.sessions() {
-                configureSession(session)
-            }
+func collectPhotos(from shelf: GroupSessionJournal) async {
+    for await batch in shelf.attachments {
+        for item in batch {
+            guard let bytes = try? await item.load(Data.self) else { continue }
+            Gallery.shared.insert(bytes, id: item.id)
         }
     }
 }
 ```
 
-## Review Checklist
-
-- [ ] Group Activities capability added to the app target only
-- [ ] `GroupActivity` struct is `Codable` with meaningful metadata
-- [ ] `Transferable` conformance added when using `ShareLink`, AirDrop, or share sheets
-- [ ] `sessions()` observed in a long-lived object (not a SwiftUI view body)
-- [ ] `session.join()` called after receiving and configuring the session
-- [ ] `session.leave()` called when the user navigates away or dismisses
-- [ ] `GroupSessionMessenger` messages stay under 256 KB with appropriate `deliveryMode`
-- [ ] Late-joining participants receive current state on connection
-- [ ] `$state` and `$activeParticipants` publishers observed for lifecycle changes
-- [ ] `GroupSessionJournal` used for non-time-sensitive `Transferable` attachments
-- [ ] `AVPlaybackCoordinator` used for media sync (not manual messages)
-- [ ] `GroupStateObserver.isEligibleForGroupSession` checked before showing SharePlay UI
-- [ ] `GroupActivitySharingController` used when no conversation is active
-- [ ] Session invalidation handled with cleanup of messenger, journal, and tasks
+Anything larger, or anything that needs access control, goes to server storage
+or an app-managed transfer; share only a pointer or manifest through SharePlay.
+
+## Common mistakes
+
+- **No `join()`.** The session sits in `.waiting` forever. Join once the
+  messenger and observers are set up.
+- **Never leaving.** Navigating away without `session?.leave()` leaks the
+  session. Leave on disappear and drop the session and messenger.
+- **Assuming everyone has the same state.** A late joiner knows nothing.
+  Compare `activeParticipants` with the set you already know and send the full
+  state `to: .only(participant)` to each newcomer.
+- **Pushing big payloads through the messenger.** A 300 KB `Data` blob already
+  exceeds its limit. Use the journal up to 100 MB, and server storage or your
+  own transfer beyond that.
+- **Duplicating playback commands.** With `AVPlaybackCoordinator` in charge,
+  `player.play()` is already shared; extra play or pause messages fight it.
+- **Listening to `sessions()` in a view's `.task`.** Each appearance starts
+  another listener. Observe from a long-lived manager, for example from its
+  `init`.
+
+## Review checklist
+
+- [ ] Only the app target carries the capability
+- [ ] `GroupActivity` is `Codable` and its metadata is meaningful
+- [ ] `Transferable` added where `ShareLink`, AirDrop or share sheets are used
+- [ ] A long-lived object, never a view body, iterates `sessions()`
+- [ ] `join()` called after the session is received and configured
+- [ ] `leave()` called when the person navigates away or dismisses
+- [ ] Messenger payloads under 256 KB, with a suitable `deliveryMode`
+- [ ] Late joiners receive the current state
+- [ ] Both `$state` and `$activeParticipants` are observed
+- [ ] Journal used for `Transferable` attachments that are not time-sensitive
+- [ ] `AVPlaybackCoordinator` handles media sync
+- [ ] `isEligibleForGroupSession` checked before SharePlay UI is shown
+- [ ] `GroupActivitySharingController` offered when no conversation is active
+- [ ] Invalidation tears down messenger, journal and tasks
 
 ## References
 
-- Extended patterns (SwiftUI sharing, collaborative canvas, spatial Personas): [references/shareplay-patterns.md](references/shareplay-patterns.md)
-- [Configuring Group Activities](https://sosumi.ai/documentation/xcode/configuring-group-activities)
-- [GroupActivities framework](https://sosumi.ai/documentation/groupactivities)
-- [GroupActivity protocol](https://sosumi.ai/documentation/groupactivities/groupactivity)
-- [GroupSession](https://sosumi.ai/documentation/groupactivities/groupsession)
-- [GroupSessionMessenger](https://sosumi.ai/documentation/groupactivities/groupsessionmessenger)
-- [GroupSessionJournal](https://sosumi.ai/documentation/groupactivities/groupsessionjournal)
-- [GroupStateObserver](https://sosumi.ai/documentation/groupactivities/groupstateobserver)
-- [GroupActivitySharingController](https://sosumi.ai/documentation/groupactivities/groupactivitysharingcontroller-ybcy)
-- [Defining your app's SharePlay activities](https://sosumi.ai/documentation/groupactivities/defining-your-apps-shareplay-activities)
-- [Presenting SharePlay activities from your app's UI](https://sosumi.ai/documentation/groupactivities/promoting-shareplay-activities-from-your-apps-ui)
-- [Synchronizing data during a SharePlay activity](https://sosumi.ai/documentation/groupactivities/synchronizing-data-during-a-shareplay-activity)
-- [Supporting coordinated media playback](https://sosumi.ai/documentation/avfoundation/supporting-coordinated-media-playback)
-- [SharePlay HIG](https://sosumi.ai/design/human-interface-guidelines/shareplay)
+- [Pattern catalogue](references/shareplay-patterns.md): shared canvas,
+  generic manager, SwiftUI buttons and ShareLink, state sync for late joiners,
+  participant tracking, visionOS nearby
+- Capability setup: [Group Activities in Xcode](https://developer.apple.com/documentation/xcode/configuring-group-activities)
+- [GroupActivities](https://developer.apple.com/documentation/groupactivities)
+- [GroupActivity](https://developer.apple.com/documentation/groupactivities/groupactivity)
+- [GroupSession](https://developer.apple.com/documentation/groupactivities/groupsession)
+- [GroupSessionMessenger](https://developer.apple.com/documentation/groupactivities/groupsessionmessenger)
+- [GroupSessionJournal](https://developer.apple.com/documentation/groupactivities/groupsessionjournal)
+- [GroupStateObserver](https://developer.apple.com/documentation/groupactivities/groupstateobserver)
+- [GroupActivitySharingController](https://developer.apple.com/documentation/groupactivities/groupactivitysharingcontroller-ybcy)
+- Article, activity definitions: [link](https://developer.apple.com/documentation/groupactivities/defining-your-apps-shareplay-activities)
+- Article, starting activities from app UI: [link](https://developer.apple.com/documentation/groupactivities/promoting-shareplay-activities-from-your-apps-ui)
+- Article, keeping data in sync: [link](https://developer.apple.com/documentation/groupactivities/synchronizing-data-during-a-shareplay-activity)
+- Article, coordinated playback: [link](https://developer.apple.com/documentation/avfoundation/supporting-coordinated-media-playback)
+- Design guidance: [SharePlay HIG page](https://developer.apple.com/design/human-interface-guidelines/shareplay)