@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/shareplay-activities/references/shareplay-patterns.md

@@ -1,583 +1,443 @@
-# SharePlay Extended Patterns
+# SharePlay Patterns
 
-Overflow reference for the `shareplay-activities` skill. Contains advanced
-patterns that exceed the main skill file's scope.
+Longer examples for the `shareplay-activities` skill. SKILL.md covers setup,
+the session lifecycle and the messenger basics; this file builds on them.
 
 ## Contents
 
-- [Collaborative Drawing Canvas](#collaborative-drawing-canvas)
-- [Full SharePlay Manager](#full-shareplay-manager)
-- [SwiftUI SharePlay Integration](#swiftui-shareplay-integration)
-  - [ShareLink and AirDrop](#sharelink-and-airdrop)
-- [Custom Activity with State Sync](#custom-activity-with-state-sync)
-- [Participant Tracking](#participant-tracking)
+- [A shared sticky-note board](#a-shared-sticky-note-board)
+- [A reusable manager](#a-reusable-manager)
+- [SwiftUI entry points](#swiftui-entry-points)
+- [Syncing game state, including late joiners](#syncing-game-state-including-late-joiners)
+- [Tracking who joins and leaves](#tracking-who-joins-and-leaves)
+- [Nearby participants on visionOS](#nearby-participants-on-visionos)
 
-## Collaborative Drawing Canvas
+## A shared sticky-note board
 
-### Activity Definition
+Several people drag notes around one board. Positions change constantly, while
+clearing the board must never be lost.
 
 ```swift
 import GroupActivities
+import Observation
+import SwiftUI
 
-struct DrawTogetherActivity: GroupActivity {
-    static let activityIdentifier = "com.example.draw-together"
+struct NoteBoard: GroupActivity, Sendable {
+    static let activityIdentifier = "org.sample.board.notes"
 
     var metadata: GroupActivityMetadata {
-        var meta = GroupActivityMetadata()
-        meta.title = "Draw Together"
-        meta.type = .createTogether
-        return meta
+        var info = GroupActivityMetadata()
+        info.title = "Plan on one board"
+        info.type = .createTogether
+        return info
     }
 }
-```
 
-### Stroke Message
-
-```swift
-import Foundation
+struct Spot: Codable, Sendable, Hashable { var x: Double; var y: Double }
+struct Tint: Codable, Sendable, Hashable { var red: Double; var green: Double; var blue: Double }
 
-struct StrokeMessage: Codable, Sendable {
+struct NoteMoved: Codable, Sendable, Identifiable {
     let id: UUID
-    let points: [CGPointCodable]
-    let color: ColorCodable
-    let lineWidth: Double
-
-    struct CGPointCodable: Codable, Sendable {
-        let x: Double
-        let y: Double
-    }
-
-    struct ColorCodable: Codable, Sendable {
-        let red: Double
-        let green: Double
-        let blue: Double
-        let alpha: Double
-    }
+    var trail: [Spot]
+    var tint: Tint
+    var size: Double
 }
 
-struct ClearCanvasMessage: Codable, Sendable {
-    let timestamp: Date
-}
+struct BoardCleared: Codable, Sendable {}
 ```
 
-### Drawing Manager
+`CGPoint` and `Color` are not `Codable`, so the message uses small codable
+stand-ins for points and colours.
 
 ```swift
-import GroupActivities
-
-@Observable
-@MainActor
-final class DrawingManager {
-    private var session: GroupSession<DrawTogetherActivity>?
-    private var reliableMessenger: GroupSessionMessenger?
-    private var unreliableMessenger: GroupSessionMessenger?
-    private var tasks: [Task<Void, Never>] = []
-
-    var strokes: [StrokeMessage] = []
-    var isConnected = false
-
-    func startObserving() {
-        Task {
-            for await session in DrawTogetherActivity.sessions() {
-                configureSession(session)
-            }
-        }
-    }
-
-    private func configureSession(
-        _ session: GroupSession<DrawTogetherActivity>
-    ) {
-        // Clean up previous session
-        cleanUp()
-
-        self.session = session
-        self.reliableMessenger = GroupSessionMessenger(
-            session: session,
-            deliveryMode: .reliable
-        )
-        self.unreliableMessenger = GroupSessionMessenger(
-            session: session,
-            deliveryMode: .unreliable
-        )
-
-        // Observe state
-        let stateTask = Task {
-            for await state in session.$state.values {
-                switch state {
-                case .joined:
-                    isConnected = true
-                case .invalidated:
-                    isConnected = false
-                    cleanUp()
-                default:
-                    break
+@Observable @MainActor
+final class BoardSync {
+    private(set) var notes: [UUID: NoteMoved] = [:]
+    private(set) var connected = false
+    private var session: GroupSession<NoteBoard>?
+    private var fast: GroupSessionMessenger?
+    private var safe: GroupSessionMessenger?
+    private var jobs: [Task<Void, Never>] = []
+
+    func configure(_ incoming: GroupSession<NoteBoard>) {
+        cleanup()
+        session = incoming
+        let quick = GroupSessionMessenger(session: incoming, deliveryMode: .unreliable)
+        let sure = GroupSessionMessenger(session: incoming, deliveryMode: .reliable)
+        fast = quick
+        safe = sure
+
+        jobs.append(Task { @MainActor [weak self] in
+            for await state in incoming.$state.values {
+                if case .invalidated = state {
+                    self?.cleanup()
+                } else if case .joined = state {
+                    self?.connected = true
                 }
             }
-        }
-        tasks.append(stateTask)
-
-        // Observe strokes (unreliable for speed)
-        let strokeTask = Task {
-            guard let messenger = unreliableMessenger else { return }
-            for await (stroke, _) in messenger.messages(of: StrokeMessage.self) {
-                strokes.append(stroke)
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            for await (note, _) in quick.messages(of: NoteMoved.self) {
+                self?.notes[note.id] = note
             }
-        }
-        tasks.append(strokeTask)
-
-        // Observe clear messages (reliable for correctness)
-        let clearTask = Task {
-            guard let messenger = reliableMessenger else { return }
-            for await (_, _) in messenger.messages(of: ClearCanvasMessage.self) {
-                strokes.removeAll()
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            for await _ in sure.messages(of: BoardCleared.self) {
+                self?.notes.removeAll()
             }
-        }
-        tasks.append(clearTask)
-
-        session.join()
+        })
+        incoming.join()
     }
 
-    func sendStroke(_ stroke: StrokeMessage) async {
-        strokes.append(stroke)
-        try? await unreliableMessenger?.send(stroke, to: .all)
+    func move(_ note: NoteMoved) {
+        notes[note.id] = note
+        guard let fast else { return }
+        Task { try? await fast.send(note, to: .all) }
     }
 
-    func clearCanvas() async {
-        strokes.removeAll()
-        try? await reliableMessenger?.send(
-            ClearCanvasMessage(timestamp: Date()),
-            to: .all
-        )
+    func clearBoard() {
+        notes.removeAll()
+        guard let safe else { return }
+        Task { try? await safe.send(BoardCleared(), to: .all) }
     }
 
     func leave() {
+        defer { cleanup() }
         session?.leave()
-        cleanUp()
     }
 
-    private func cleanUp() {
-        tasks.forEach { $0.cancel() }
-        tasks.removeAll()
+    private func cleanup() {
+        for job in jobs { job.cancel() }
+        jobs = []
+        fast = nil
+        safe = nil
         session = nil
-        reliableMessenger = nil
-        unreliableMessenger = nil
-        isConnected = false
+        connected = false
     }
 }
 ```
 
-## Full SharePlay Manager
+Two messengers share one session: note moves go over the unreliable one for
+speed, and clearing goes over the reliable one so nobody misses it. Local
+changes apply on this device first and are then sent to everyone.
+`configure` starts by cleaning up any earlier session.
 
-### Generic Activity Manager
+## A reusable manager
+
+A generic manager that any activity can use.
 
 ```swift
 import GroupActivities
+import Observation
 
-@Observable
-@MainActor
+enum SharePlayError: Error { case notConnected }
+
+@MainActor @Observable
 final class SharePlayManager<Activity: GroupActivity> {
+    private(set) var participants: Set<Participant> = []
+    private(set) var journal: GroupSessionJournal?
     private(set) var session: GroupSession<Activity>?
     private(set) var messenger: GroupSessionMessenger?
-    private(set) var journal: GroupSessionJournal?
+    private var jobs: [Task<Void, Never>] = []
 
-    private(set) var activeParticipants: Set<Participant> = []
-    private(set) var localParticipant: Participant?
-    private(set) var isJoined = false
-
-    private var tasks: [Task<Void, Never>] = []
-
-    // GroupSessionJournal requires iOS/iPadOS/tvOS 17+, macOS 14+,
-    // or visionOS 1+. Gate this property if your deployment target is older.
+    var localParticipant: Participant? { session?.localParticipant }
+    var isJoined: Bool {
+        if case .joined? = session?.state { return true }
+        return false
+    }
 
-    func startObserving() {
-        Task {
-            for await session in Activity.sessions() {
-                configure(session)
-            }
+    func startObserving() async {
+        for await incoming in Activity.sessions() {
+            adopt(incoming)
         }
     }
 
-    private func configure(_ session: GroupSession<Activity>) {
+    private func adopt(_ incoming: GroupSession<Activity>) {
         reset()
-
-        self.session = session
-        self.messenger = GroupSessionMessenger(session: session)
-        self.journal = GroupSessionJournal(session: session)
-        self.localParticipant = session.localParticipant
-
-        let stateTask = Task {
-            for await state in session.$state.values {
-                switch state {
-                case .joined:
-                    isJoined = true
-                case .invalidated:
-                    isJoined = false
-                    reset()
-                default:
-                    break
-                }
+        session = incoming
+        messenger = GroupSessionMessenger(session: incoming)
+        journal = GroupSessionJournal(session: incoming)
+        jobs.append(Task { @MainActor [weak self] in
+            for await current in incoming.$activeParticipants.values {
+                self?.participants = current
             }
-        }
-        tasks.append(stateTask)
-
-        let participantTask = Task {
-            for await participants in session.$activeParticipants.values {
-                activeParticipants = participants
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            for await state in incoming.$state.values {
+                if case .invalidated = state { self?.reset() }
             }
-        }
-        tasks.append(participantTask)
-
-        session.join()
-    }
-
-    func leave() {
-        session?.leave()
-        reset()
+        })
+        incoming.join()
     }
 
     func end() {
+        defer { reset() }
         session?.end()
-        reset()
     }
 
-    private func reset() {
-        tasks.forEach { $0.cancel() }
-        tasks.removeAll()
-        session = nil
-        messenger = nil
-        journal = nil
-        isJoined = false
-        activeParticipants = []
+    func leave() {
+        defer { reset() }
+        session?.leave()
     }
-}
-```
 
-### Type-Safe Message Handling
+    private func connectedMessenger() throws -> GroupSessionMessenger {
+        guard let messenger else { throw SharePlayError.notConnected }
+        return messenger
+    }
 
-```swift
-extension SharePlayManager {
-    func send<T: Codable>(_ message: T) async throws {
-        guard let messenger else {
-            throw SharePlayError.notConnected
-        }
-        try await messenger.send(message, to: .all)
+    func broadcast<Payload: Codable & Sendable>(_ payload: Payload) async throws {
+        try await connectedMessenger().send(payload, to: .all)
     }
 
-    func send<T: Codable>(_ message: T, to participant: Participant) async throws {
-        guard let messenger else {
-            throw SharePlayError.notConnected
-        }
-        try await messenger.send(message, to: .only(participant))
+    func send<Payload: Codable & Sendable>(_ payload: Payload, to person: Participant) async throws {
+        try await connectedMessenger().send(payload, to: .only(person))
     }
 
-    func messages<T: Codable>(of type: T.Type) -> AsyncThrowingStream<(T, Participant), Error> {
-        AsyncThrowingStream { continuation in
-            let task = Task {
-                guard let messenger else {
-                    continuation.finish()
-                    return
-                }
-                for await (message, context) in messenger.messages(of: type) {
-                    continuation.yield((message, context.source))
+    func messages<Payload: Codable & Sendable>(of kind: Payload.Type) -> AsyncThrowingStream<(Payload, Participant), Error> {
+        let source = messenger
+        return AsyncThrowingStream { sink in
+            guard let source else {
+                sink.finish(throwing: SharePlayError.notConnected)
+                return
+            }
+            let pump = Task {
+                for await (payload, ctx) in source.messages(of: kind) {
+                    sink.yield((payload, ctx.source))
                 }
-                continuation.finish()
+                sink.finish()
             }
-            continuation.onTermination = { _ in task.cancel() }
+            sink.onTermination = { _ in pump.cancel() }
         }
     }
-}
 
-enum SharePlayError: Error {
-    case notConnected
+    private func reset() {
+        for job in jobs { job.cancel() }
+        jobs = []
+        participants = []
+        journal = nil
+        messenger = nil
+        session = nil
+    }
 }
 ```
 
-## SwiftUI SharePlay Integration
+The `journal` property requires the 17 releases of iOS, iPadOS and tvOS, macOS
+14, or the first visionOS.
+With an older deployment target, gate it with `@available` or `#available`.
+`leave()` leaves and resets; `end()` ends the session for everyone and resets.
+The typed send helpers throw `notConnected` when no messenger exists yet.
+
+## SwiftUI entry points
 
-Use this section when surfacing activities through SwiftUI controls. A custom
-button works best when a FaceTime call or Messages conversation is already
-active. Use `ShareLink`, UIKit/AppKit share sheets, or
-`GroupActivitySharingController` when the user needs to choose participants.
+A custom SharePlay button only makes sense while the person is already on a
+FaceTime call or in a Messages chat. When the person still has to choose who to
+share with, use `ShareLink`, a share sheet or `GroupActivitySharingController`.
 
 ### ShareLink and AirDrop
 
-SwiftUI `ShareLink`, SharePlay over AirDrop, and system share sheets require
-the shared item or activity to conform to `Transferable`. Keep the transferable
-payload small; share IDs and URLs, then load heavy content after joining.
+`ShareLink`, SharePlay over AirDrop and the system share sheets all need the
+activity to be `Transferable`. Keep what it carries small, such as an ID or a
+URL, and load the heavy content after joining. `Transferable` requires
+`Sendable`, and a struct only gets that implicitly inside its own file, which is
+why `NoteBoard` above declares `Sendable` explicitly.
 
 ```swift
-import CoreTransferable
-import GroupActivities
 import SwiftUI
+import GroupActivities
+import CoreTransferable
 
-extension WatchTogetherActivity: Transferable {
+extension NoteBoard: Transferable {
     static var transferRepresentation: some TransferRepresentation {
-        GroupActivityTransferRepresentation { activity in
-            activity
-        }
+        GroupActivityTransferRepresentation { $0 }
     }
 }
 
-ShareLink(
-    item: WatchTogetherActivity(movieID: movieID, movieTitle: movieTitle),
-    preview: SharePreview(movieTitle)
-)
+struct InviteButton: View {
+    var body: some View {
+        ShareLink(item: NoteBoard(), preview: SharePreview("Plan on one board"))
+    }
+}
 ```
 
-### SharePlay Button
+### A SharePlay button
 
-```swift
-import GroupActivities
-import SwiftUI
+`GroupActivity` does not require `Sendable`, so the generic parameter adds it:
+the button's `Task` hands the activity to the nonisolated
+`prepareForActivation()` and `activate()`.
 
-struct SharePlayButton<Activity: GroupActivity>: View {
+```swift
+struct SharePlayButton<Activity: GroupActivity & Sendable>: View {
+    @State private var groupState = GroupStateObserver()
     let activity: Activity
 
-    @State private var observer = GroupStateObserver()
-
     var body: some View {
-        if observer.isEligibleForGroupSession {
+        if groupState.isEligibleForGroupSession {
             Button {
                 Task {
-                    try await startActivity()
+                    guard case .activationPreferred = await activity.prepareForActivation() else { return }
+                    _ = try? await activity.activate()
                 }
             } label: {
                 Label("SharePlay", systemImage: "shareplay")
             }
         }
     }
-
-    private func startActivity() async throws {
-        switch await activity.prepareForActivation() {
-        case .activationPreferred:
-            _ = try await activity.activate()
-        case .activationDisabled:
-            break
-        case .cancelled:
-            break
-        @unknown default:
-            break
-        }
-    }
 }
 ```
 
-### SharePlay Status Indicator
+### A status badge
 
 ```swift
-struct SharePlayStatusView: View {
-    let participantCount: Int
-    let isConnected: Bool
+struct SharePlayBadge: View {
+    let connected: Bool
+    let count: Int
 
     var body: some View {
-        if isConnected {
-            HStack {
-                Image(systemName: "shareplay")
-                    .foregroundStyle(.green)
-                Text("\(participantCount) connected")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-            }
+        if connected {
+            Label("\(count)", systemImage: "shareplay")
+                .font(.caption)
+                .padding(6)
+                .background(.thinMaterial, in: Capsule())
         }
     }
 }
 ```
 
-### Full Activity View
+### Putting it in a screen
 
-Create the session manager at an app, scene, or feature coordinator boundary and
-inject it into SwiftUI. The content view should use the manager, not own the
-`sessions()` observation lifecycle.
+Create the manager at the app, scene or feature-coordinator level and inject
+it. The screen reads it from the environment and never owns the `sessions()`
+lifecycle itself.
 
 ```swift
-struct SharedMovieView: View {
-    @Environment(SharePlayManager<WatchTogetherActivity>.self) private var manager
-
-    let movieID: String
-    let movieTitle: String
+struct BoardScreen: View {
+    @Environment(SharePlayManager<NoteBoard>.self) private var shared
 
     var body: some View {
-        VStack {
-            // Movie content here
-
-            HStack {
-                SharePlayButton(
-                    activity: WatchTogetherActivity(
-                        movieID: movieID,
-                        movieTitle: movieTitle
-                    )
-                )
-
-                if manager.isJoined {
-                    SharePlayStatusView(
-                        participantCount: manager.activeParticipants.count,
-                        isConnected: true
-                    )
-                }
+        BoardCanvas()
+            .overlay(alignment: .topTrailing) {
+                SharePlayBadge(connected: shared.isJoined, count: shared.participants.count)
             }
-        }
-        .task { manager.startObserving() }
-        .onDisappear { manager.leave() }
+            .toolbar { SharePlayButton(activity: NoteBoard()) }
+            .task { await shared.startObserving() }
+            .onDisappear { shared.leave() }
     }
 }
 ```
 
-## Custom Activity with State Sync
+## Syncing game state, including late joiners
 
-### Quiz Game Example
+A shared word puzzle. Whoever started the session hosts it and brings each
+newcomer up to date.
 
 ```swift
-import GroupActivities
-
-struct QuizActivity: GroupActivity {
-    let quizID: String
-
+struct WordRace: GroupActivity {
+    let puzzleID: UUID
     var metadata: GroupActivityMetadata {
-        var meta = GroupActivityMetadata()
-        meta.title = "Quiz Time"
-        meta.type = .generic
-        return meta
+        var info = GroupActivityMetadata()
+        info.title = "Word race"
+        info.type = .generic
+        return info
     }
 }
 
-// Messages
-struct QuizQuestion: Codable, Sendable {
-    let questionID: String
-    let text: String
-    let options: [String]
-}
-
-struct QuizAnswer: Codable, Sendable {
-    let questionID: String
-    let selectedOption: Int
-}
-
-struct QuizState: Codable, Sendable {
-    let currentQuestionIndex: Int
-    let scores: [String: Int]  // participant ID -> score
-}
-```
-
-### Quiz Manager
-
-```swift
-@Observable
-@MainActor
-final class QuizManager {
-    private var session: GroupSession<QuizActivity>?
-    private var messenger: GroupSessionMessenger?
-    private var tasks: [Task<Void, Never>] = []
-
-    var currentQuestion: QuizQuestion?
-    var scores: [String: Int] = [:]
-    var isHost = false
-
-    func configureSession(_ session: GroupSession<QuizActivity>) {
-        self.session = session
-        self.messenger = GroupSessionMessenger(session: session)
-        self.isHost = session.isLocallyInitiated
-
-        let questionTask = Task {
-            guard let messenger else { return }
-            for await (question, _) in messenger.messages(of: QuizQuestion.self) {
-                currentQuestion = question
+struct NewClue: Codable, Sendable { let number: Int; let clue: String }
+struct Guess: Codable, Sendable { let number: Int; let word: String }
+struct RaceSnapshot: Codable, Sendable { let clue: NewClue?; let points: [String: Int] }
+
+@Observable @MainActor
+final class WordRaceHost {
+    private(set) var clue: NewClue?
+    private(set) var points: [String: Int] = [:]
+    private var jobs: [Task<Void, Never>] = []
+
+    func run(_ session: GroupSession<WordRace>) {
+        let messenger = GroupSessionMessenger(session: session)
+        let hosting = session.isLocallyInitiated
+
+        jobs.append(Task { @MainActor [weak self] in
+            for await (next, _) in messenger.messages(of: NewClue.self) { self?.clue = next }
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            for await (guess, context) in messenger.messages(of: Guess.self) {
+                self?.score(guess, from: context.source)
             }
-        }
-        tasks.append(questionTask)
-
-        let answerTask = Task {
-            guard let messenger else { return }
-            for await (answer, context) in messenger.messages(of: QuizAnswer.self) {
-                processAnswer(answer, from: context.source)
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            for await (snapshot, _) in messenger.messages(of: RaceSnapshot.self) {
+                self?.clue = snapshot.clue
+                self?.points = snapshot.points
             }
-        }
-        tasks.append(answerTask)
-
-        // Send current state to late joiners
-        let participantTask = Task {
-            var known: Set<Participant> = []
-            for await participants in session.$activeParticipants.values {
-                let newJoiners = participants.subtracting(known)
-                for joiner in newJoiners {
-                    if isHost, let question = currentQuestion {
-                        try? await messenger?.send(question, to: .only(joiner))
+        })
+        jobs.append(Task { @MainActor [weak self] in
+            var seen = Set<Participant>()
+            for await present in session.$activeParticipants.values {
+                let arrivals = present.subtracting(seen)
+                seen = present
+                guard hosting, let self else { continue }
+                for newcomer in arrivals {
+                    if let clue = self.clue {
+                        try? await messenger.send(clue, to: .only(newcomer))
                     }
-                    let state = QuizState(
-                        currentQuestionIndex: 0,
-                        scores: scores
-                    )
-                    try? await messenger?.send(state, to: .only(joiner))
+                    let snapshot = RaceSnapshot(clue: self.clue, points: self.points)
+                    try? await messenger.send(snapshot, to: .only(newcomer))
                 }
-                known = participants
             }
-        }
-        tasks.append(participantTask)
-
+        })
         session.join()
     }
 
-    func submitAnswer(option: Int) async {
-        guard let question = currentQuestion else { return }
-        let answer = QuizAnswer(
-            questionID: question.questionID,
-            selectedOption: option
-        )
-        try? await messenger?.send(answer, to: .all)
-    }
-
-    private func processAnswer(_ answer: QuizAnswer, from participant: Participant) {
-        // Score the answer and update scores
-        let key = participant.id.uuidString
-        scores[key, default: 0] += 1
+    private func score(_ guess: Guess, from player: Participant) {
+        guard guess.number == clue?.number else { return }
+        points[player.id.uuidString, default: 0] += 1
     }
 }
 ```
 
-## Participant Tracking
+- `session.isLocallyInitiated` marks the device that started the session, which
+  acts as host.
+- Each message type gets its own task over `messages(of:)`; the guess handler
+  reads the sender from `context.source`.
+- The participant task remembers who it has seen, and for every new arrival
+  the host sends the current clue and then a full snapshot `to: .only(...)`.
+- Points are keyed by `participant.id.uuidString`.
 
-### Tracking Who Has Seen What
+## Tracking who joins and leaves
 
 ```swift
-@Observable
 @MainActor
-final class ParticipantTracker {
-    private var knownParticipants: Set<Participant> = []
-
-    func handleParticipantUpdate(
-        _ activeParticipants: Set<Participant>,
-        sendStateTo: (Participant) async throws -> Void
-    ) async {
-        let joined = activeParticipants.subtracting(knownParticipants)
-        let left = knownParticipants.subtracting(activeParticipants)
-
-        for participant in joined {
-            print("Participant joined: \(participant.id)")
-            try? await sendStateTo(participant)
-        }
+final class RosterTracker {
+    private var known: Set<Participant> = []
+    private let welcome: (Participant) async -> Void
 
-        for participant in left {
-            print("Participant left: \(participant.id)")
-        }
+    init(welcome: @escaping (Participant) async -> Void) {
+        self.welcome = welcome
+    }
 
-        knownParticipants = activeParticipants
+    func update(with active: Set<Participant>) async {
+        let joined = active.subtracting(known)
+        let departed = known.subtracting(active)
+        for person in joined { await welcome(person) }
+        if !departed.isEmpty { Log.share.info("\(departed.count) left") }
+        known = active
     }
 }
 ```
 
-### Nearby Participant Detection
+## Nearby participants on visionOS
 
-On visionOS 26+, nearby Apple Vision Pro participants can join the same group
-activity. The core session, messenger, and journal APIs treat nearby and
-FaceTime participants the same; use `isNearbyWithLocalParticipant` only when UI
-or spatial placement needs to distinguish them:
+On visionOS 26 and later, people wearing Vision Pro headsets in the same room can
+join the same activity. Sessions, messengers and journals treat them exactly
+like FaceTime participants. `participant.isNearbyWithLocalParticipant` tells you
+who is physically present; check it only when the interface or spatial
+placement really depends on it.
 
 ```swift
-for participant in session.activeParticipants {
-    if participant.isNearbyWithLocalParticipant {
-        print("\(participant.id) is nearby")
+func seat(_ person: Participant, in layout: inout RoomLayout) {
+    if person.isNearbyWithLocalParticipant {
+        layout.placeBesideLocalUser(person.id)
+    } else {
+        layout.placeAsSpatialPersona(person.id)
     }
 }
 ```
-
-This is useful for visionOS spatial activities where you want to offer
-different experiences for co-located vs. remote participants.