# use-stream-peers

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`useStreamPeers` returns the live remote-peer roster as a stable `readonly Peer[]`. Each
peer entry carries the participant id, display name, transport connection state, and
the latest measured round-trip time in milliseconds. The hook is the canonical source
of peer data for any UI that renders a participant list, a per-peer mixer strip, or a
per-peer level meter, and it re-evaluates whenever the provider's render-bump version
ticks.

The hook is intentionally a thin projection — it does not own selection, sorting, or
filtering. Consumers compose their own derived state on top with `useMemo`.

## Features

- Stable array identity across renders when peers have not changed.
- Re-renders on `peers-changed`, `state-changed`, and every other session event channel
  via the provider's render-bump counter.
- Throws `REACT_AUDIO_STREAM.NO_PROVIDER` when used without a `<StreamProvider>`.

## Usage: Basic

```tsx
const peers = useStreamPeers();
return (
    <ul>
        {peers.map((p) => (
            <li key={p.id}>{p.displayName} ({p.rttMs} ms)</li>
        ))}
    </ul>
);
```

## Usage: Advanced

```tsx
const peers = useStreamPeers();
const sorted = useMemo(
    () => [...peers].sort((a, b) => a.displayName.localeCompare(b.displayName)),
    [peers]
);
const slow = sorted.filter((p) => p.rttMs > 150);
```

## API Reference

- `useStreamPeers(): readonly Peer[]` — see `Peer` in `session/session-shape/session-shape.types.ts`.

## Implementation Notes

The implementation memoises against the provider's `version` counter, which is the
only legitimate invalidation signal — components must not depend on the peer array's
internal identity for invalidation because the session is free to reuse the same array
across mutations (for example when only RTT changed). The version-counter approach is
intentionally over-eager: re-deriving an array reference is O(1) and matches the
package-wide pattern.