first commit

docs/ui/react/react-audio-stream/src/hooks/use-stream-peers/use-stream-peers.md

@@ -0,0 +1,61 @@
+# 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.