first commit

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

@@ -0,0 +1,54 @@
+# use-stream-levels
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`useStreamLevels` projects realtime peak/RMS samples out of the session. Called without
+an argument it returns the local-microphone level; called with a peer id it returns the
+named peer's level. The level numbers come from chunks A/B's analyzer slot (which lives
+on each peer's plugin chain alongside the `StreamSourcePlugin`), and this hook is a
+zero-state projection — it does not compute anything itself.
+
+The reading is intentionally synchronous: the provider's render-bump version is what
+schedules re-renders, and the session is responsible for batching analyzer ticks into
+the `levels-changed` event channel at a sane cadence (typically 60 Hz).
+
+## Features
+
+- Same hook for local and per-peer levels — the `peerId?` argument selects.
+- Re-renders on every `levels-changed` event via the provider's version counter.
+- Throws `REACT_AUDIO_STREAM.NO_PROVIDER` when used outside a `<StreamProvider>`.
+
+## Usage: Basic
+
+```tsx
+const { peak, rms } = useStreamLevels();
+return <LevelMeter peak={peak} rms={rms} />;
+```
+
+## Usage: Advanced
+
+```tsx
+const peers = useStreamPeers();
+return peers.map((p) => {
+    const { peak } = useStreamLevels(p.id);
+    return <PeerLevelBar key={p.id} peerId={p.id} peak={peak} />;
+});
+```
+
+(Real apps should hoist the per-peer call into a child component to keep the hook count
+stable across renders.)
+
+## API Reference
+
+- `useStreamLevels(peerId?: string): LevelSample` — `LevelSample` is `{ peak: number; rms: number }`.
+
+## Implementation Notes
+
+The hook does not pull from `@suaveplan/audio-analysis-spectrum` directly — that module
+runs inside the audio engine (browser tier, owned by chunks A/B). The React boundary
+only ever sees the peak/RMS scalars produced by the engine's analyzer. Keeping the
+hook this thin guarantees zero DSP work happens during React rendering.