useStreamGuests and useGuestSession
Authorized host controls and consent-first guest stage state.
Both hooks accept the stable StreamGuestOptions callbacks described by StreamGuestClient. Memoize callbacks when they depend on a selected stream/run, and supply a caller-owned guest-status endpoint to useGuestSession. An operator's paginated roster is not a substitute for that caller snapshot.
useStreamGuests returns roster, pending, error, client, refresh and command for host invitations, requests and moderation. useGuestSession adds joinStage and leaveStage and the room/activeGuestId snapshot. Effects connect polling and disconnect/leave RTC on unmount. Backend identity/role checks still apply when a button is hidden.
import { useGuestSession } from '@relayrtc/react'
export function GuestStage({ options }: { options: Parameters<typeof useGuestSession>[0] }) {
const guest = useGuestSession(options)
const own = guest.roster?.data.find(row => row.state === 'approved' || row.state === 'accepted')
return <section>
{own && !guest.room && <button disabled={!!guest.pending}
onClick={() => { void guest.joinStage(own.id) }}>Join stage with devices off</button>}
{guest.room && <button
onClick={() => { void guest.room?.microphone.enable().catch(console.error) }}>Enable microphone</button>}
{guest.room && <button onClick={() => { void guest.leaveStage() }}>Leave stage</button>}
{guest.error && <p role="alert">{guest.error.message}</p>}
</section>
}Use the returned guest Room for device controls and media snapshots. The guest client owns an independent room; ordinary provider hooks do not automatically observe it. Subscribe to that Room or its capture controls when building a preview. Invitation acceptance, RTC join and device enablement are separate choices. Show camera-denial errors while allowing a permitted microphone; moderator mute is a server permission fence, separate from local mute or device disable. Unmount delayed HLS/DVR players during stage participation and restore authorized viewer playback after leave/removal. See live guests.