Add examples to documentation

docs/api/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "API",
-  "position": 6,
+  "position": 7,
   "link": {
     "type": "generated-index",
     "description": "API documentation for Client and Server SDKs.",

docs/examples/_category_.json

@@ -0,0 +1,10 @@
+{
+  "label": "Examples",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "title": "Examples",
+    "description": "Real-world code examples and use cases.",
+    "slug": "/examples"
+  }
+}

docs/examples/react-native.mdx

@@ -0,0 +1,180 @@
+---
+type: explanation
+sidebar_position: 0
+---
+
+# React Native Examples
+
+_Runnable reference apps demonstrating common Fishjam use cases in React Native_
+
+Each example is a standalone Expo application you can run locally and use as a starting point for your own project.
+All examples use `@fishjam-cloud/react-native-client` and require a Fishjam ID from the [Fishjam Dashboard](https://fishjam.io/app).
+
+| Example                                   | What it demonstrates                                               |
+| ----------------------------------------- | ------------------------------------------------------------------ |
+| [Minimal Video Room](#minimal-video-room) | Simplest possible video call — the baseline for all other examples |
+| [Fishjam Chat](#fishjam-chat)             | Full-featured video conferencing and livestreaming app             |
+| [Background Blur](#background-blur)       | Applying real-time video effects via camera track middleware       |
+| [Text Chat](#text-chat)                   | Peer-to-peer text messaging with WebRTC data channels              |
+| [Video Player](#video-player)             | Livestream broadcaster and viewer with separate UI modes           |
+
+---
+
+## Minimal Video Room
+
+The simplest way to get video calling working — joining a room, displaying your own camera feed, and showing remote participants. Start here if you're new to Fishjam.
+
+**Demonstrates:**
+
+- Wrapping your app in `FishjamProvider`
+- Connecting to a room with `useConnection`
+- Accessing local and remote peers with `usePeers`
+- Rendering video streams with `RTCView`
+
+### Running the example
+
+```bash
+cd minimal-react-native
+yarn install
+npx expo prebuild
+npx expo run:android  # or run:ios
+```
+
+:::important
+This won't work on the iOS Simulator — the Simulator can't access the camera. Test on a real device.
+:::
+
+The room screen uses `usePeers` to retrieve all participants and renders their camera streams in a two-column grid with `RTCView`.
+
+Browse the full source: [minimal-react-native on GitHub](https://github.com/fishjam-cloud/examples/tree/main/mobile-react-native/minimal-react-native)
+
+---
+
+## Fishjam Chat
+
+A full-featured application covering two distinct room types: a video conferencing room (conference call with multiple participants) and a livestream room (one broadcaster, many viewers). It is the most complete example and the best reference for production-like architecture.
+
+**Demonstrates:**
+
+- Tab-based navigation between VideoRoom and Livestream features
+- Pre-call room preview before joining
+- Environment switching between staging and production
+- Screen sharing from a livestream broadcaster
+- Permission handling with a reusable `useMediaPermissions` hook
+
+### Running the example
+
+```bash
+cd fishjam-chat
+yarn install
+npx expo prebuild
+npx expo run:android  # or run:ios
+```
+
+:::important
+Before prebuilding, replace the bundle identifier `io.fishjam.example.fishjamchat` with your own in `app.json` (both the Android package name and iOS bundle identifier fields).
+:::
+
+The app uses Expo Router with a bottom tab navigator. Each tab handles its own connection flow independently using `useConnection`.
+
+Browse the full source: [fishjam-chat on GitHub](https://github.com/fishjam-cloud/examples/tree/main/mobile-react-native/fishjam-chat)
+
+---
+
+## Background Blur
+
+Demonstrates how to apply real-time background blur to a local camera feed using camera track middleware. Blur can be toggled on and off during an active call without reconnecting.
+
+**Demonstrates:**
+
+- Installing and using `@fishjam-cloud/react-native-webrtc-background-blur`
+- Applying a video effect with `setCameraTrackMiddleware`
+- Removing an effect by passing `null` to `setCameraTrackMiddleware`
+
+### Running the example
+
+Install the additional blur package first:
+
+```bash npm2yarn
+npm install @fishjam-cloud/react-native-webrtc-background-blur
+```
+
+```bash
+cd blur-example
+yarn install
+npx expo prebuild
+npx expo run:android  # or run:ios
+```
+
+:::info
+Blur applies only to the local camera feed sent to other participants. Remote participants' video is unaffected.
+:::
+
+The blur hook from `useBackgroundBlur` provides a `middleware` function that is passed directly to `setCameraTrackMiddleware`. Passing `null` disables the effect.
+
+Browse the full source: [blur-example on GitHub](https://github.com/fishjam-cloud/examples/tree/main/mobile-react-native/blur-example)
+
+---
+
+## Text Chat
+
+Demonstrates peer-to-peer text messaging over WebRTC data channels — no separate messaging server required. Messages are sent directly between peers inside the Fishjam room.
+
+**Demonstrates:**
+
+- Initializing a data channel with `useDataChannel`
+- Publishing messages with `publishData`
+- Receiving incoming messages via the `onDataReceived` callback
+- Encoding and decoding message payloads with JSON
+
+### Running the example
+
+```bash
+cd text-chat
+yarn install
+npx expo prebuild
+npx expo run:android  # or run:ios
+```
+
+:::info
+Data channels use `reliable` mode by default, which guarantees message delivery and ordering — similar to TCP.
+:::
+
+Messages are `Uint8Array` payloads encoded and decoded with JSON and `TextEncoder`/`TextDecoder`. The `useDataChannel` hook wires together `publishData` for sending and `onDataReceived` for receiving.
+
+Browse the full source: [text-chat on GitHub](https://github.com/fishjam-cloud/examples/tree/main/mobile-react-native/text-chat)
+
+---
+
+## Video Player
+
+A focused livestreaming example with two separate modes: a streamer who broadcasts video and audio, and a viewer who watches the stream. Unlike Fishjam Chat, this example uses a single `App.tsx` entry point with a simple role selector screen.
+
+**Demonstrates:**
+
+- Broadcasting with `useLivestreamStreamer`
+- Watching a stream with `useLivestreamViewer`
+- Initializing camera and microphone with `useInitializeDevices`
+- Toggling camera and microphone tracks during an active stream
+
+### Running the example
+
+```bash
+cd video-player
+yarn install
+npx expo prebuild
+npx expo run:android  # or run:ios
+```
+
+The streamer side uses `useLivestreamStreamer` and `useInitializeDevices` to start broadcasting, while the viewer side uses `useLivestreamViewer` to connect and render the incoming stream with `RTCView`.
+
+Browse the full source: [video-player on GitHub](https://github.com/fishjam-cloud/examples/tree/main/mobile-react-native/video-player)
+
+---
+
+## Next steps
+
+- Follow the [React Native Quick Start](../tutorials/react-native-quick-start) if you haven't set up a project yet
+- Learn how to [handle screen sharing](../how-to/client/screensharing)
+- Learn how to [implement background streaming](../how-to/client/background-streaming)
+- Learn how to [work with data channels](../how-to/client/data-channels)

docs/examples/react.mdx

@@ -0,0 +1,192 @@
+---
+type: explanation
+sidebar_position: 1
+---
+
+# React Examples
+
+_Runnable reference apps demonstrating common Fishjam use cases in React_
+
+Each example is a standalone React application you can run locally and use as a starting point for your own project.
+All examples use `@fishjam-cloud/react-client` and require a Fishjam ID from the [Fishjam Dashboard](https://fishjam.io/app).
+
+| Example                             | What it demonstrates                                                   |
+| ----------------------------------- | ---------------------------------------------------------------------- |
+| [Minimal React](#minimal-react)     | Simplest video call — join a room, camera, mic, screen share           |
+| [Audio Only](#audio-only)           | Voice chat with no video and microphone device selection               |
+| [Text Chat](#text-chat)             | Peer-to-peer messaging over WebRTC data channels                       |
+| [Livestreaming](#livestreaming)     | One broadcaster, many viewers with separate streamer/viewer UIs        |
+| [Minimal Smelter](#minimal-smelter) | Custom video overlays using the Smelter rendering engine               |
+| [Fishjam Chat](#fishjam-chat)       | Full-featured conferencing app with background blur and screen sharing |
+
+---
+
+## Minimal React
+
+The simplest way to get a video call working in the browser — joining a room, displaying your own camera feed, and showing remote participants. Start here if you're new to Fishjam on the web.
+
+**Demonstrates:**
+
+- Wrapping your app in `FishjamProvider`
+- Connecting to a room with `useConnection`
+- Accessing local and remote peers with `usePeers`
+- Enabling camera and microphone with `useCamera` and `useMicrophone`
+- Starting screen sharing with `useScreenShare`
+- Rendering streams with `VideoPlayer` and `AudioPlayer` components
+
+### Running the example
+
+```bash
+cd minimal-react
+yarn install
+yarn dev
+```
+
+The room component uses `usePeers` to retrieve all participants and renders their video streams using `VideoPlayer` and audio with `AudioPlayer`.
+
+:::note
+This example requires a **peer token** to connect. You need to obtain one yourself — either via the [Sandbox API](../how-to/features/sandbox-api-testing#step-2-create-a-room-and-get-peer-tokens) for quick testing, or by setting up your own backend with the [Fishjam Server SDK](../tutorials/backend-quick-start).
+:::
+
+Browse the full source: [minimal-react on GitHub](https://github.com/fishjam-cloud/examples/tree/main/web-react/minimal-react)
+
+---
+
+## Audio Only
+
+A voice-only room with no video — demonstrates how to initialize Fishjam with audio exclusively and let users pick their microphone device before joining.
+
+**Demonstrates:**
+
+- Audio-only initialization with `useInitializeDevices` (`enableVideo: false`)
+- Microphone device selection from available inputs
+- Rendering a peer list with audio playback via `AudioPlayer`
+
+### Running the example
+
+```bash
+cd audio-only
+yarn install
+yarn dev
+```
+
+Setting `enableVideo: false` in `useInitializeDevices` skips camera initialization entirely, keeping the session lightweight for voice-only use cases.
+
+Browse the full source: [audio-only on GitHub](https://github.com/fishjam-cloud/examples/tree/main/web-react/audio-only)
+
+---
+
+## Text Chat
+
+Demonstrates peer-to-peer text messaging over WebRTC data channels — no separate messaging server required. Messages are sent directly between peers inside the Fishjam room.
+
+**Demonstrates:**
+
+- Initializing a data channel with `useDataChannel`
+- Publishing messages with `publishData`
+- Receiving incoming messages with `subscribeData`
+- Encoding and decoding message payloads with `TextEncoder` and `TextDecoder`
+
+### Running the example
+
+```bash
+cd text-chat
+yarn install
+yarn dev
+```
+
+Messages are `Uint8Array` payloads encoded and decoded with JSON and `TextEncoder`/`TextDecoder`. The `useDataChannel` hook wires together `publishData` for sending and `subscribeData` for receiving.
+
+Browse the full source: [text-chat on GitHub](https://github.com/fishjam-cloud/examples/tree/main/web-react/text-chat)
+
+---
+
+## Livestreaming
+
+A focused livestreaming example with two separate modes: a streamer who broadcasts video and audio, and a viewer who watches the stream. Token management is handled via the `useSandbox` hook.
+
+**Demonstrates:**
+
+- Broadcasting with `useLivestreamStreamer`
+- Watching a stream with `useLivestreamViewer`
+- Separate broadcaster and viewer UIs within one application
+- Obtaining peer tokens with `useSandbox`
+
+### Running the example
+
+```bash
+cd livestreaming
+yarn install
+yarn dev
+```
+
+The streamer side uses `useLivestreamStreamer` to publish camera and audio tracks, while the viewer side uses `useLivestreamViewer` to connect and render the incoming stream.
+
+Browse the full source: [livestreaming on GitHub](https://github.com/fishjam-cloud/examples/tree/main/web-react/livestreaming)
+
+---
+
+## Minimal Smelter
+
+Shows how to apply custom video overlays to a camera feed using the Smelter rendering engine — a text label composited directly onto the outgoing video stream.
+
+**Demonstrates:**
+
+- Creating a custom video source with `useCustomSource`
+- Initializing the Smelter engine with `useSmelter`
+- Registering inputs and outputs with `registerInput`/`registerOutput`
+- Compositing a text overlay on top of a live camera feed
+
+### Running the example
+
+```bash
+cd minimal-smelter
+yarn install
+yarn dev
+```
+
+:::important
+Smelter requires WebAssembly support — use a modern browser.
+:::
+
+The `useSmelter` hook manages the Smelter engine lifecycle. `registerInput` connects the local camera feed and `registerOutput` routes the composited result back into Fishjam as a custom track.
+
+:::note
+This example requires a **peer token** to connect. You need to obtain one yourself — either via the [Sandbox API](../how-to/features/sandbox-api-testing#step-2-create-a-room-and-get-peer-tokens) for quick testing, or by setting up your own backend with the [Fishjam Server SDK](../tutorials/backend-quick-start).
+:::
+
+Browse the full source: [minimal-smelter on GitHub](https://github.com/fishjam-cloud/examples/tree/main/web-react/minimal-smelter)
+
+---
+
+## Fishjam Chat
+
+A full-featured conferencing application covering camera, microphone, screen sharing, background blur via a camera track middleware, and a settings panel for device selection.
+
+**Demonstrates:**
+
+- Connecting to a room with `useConnection`
+- Managing camera and microphone with `useCamera` and `useMicrophone`
+- Screen sharing with `useScreenShare`
+- Applying real-time background blur using a MediaPipe camera track middleware
+- Device selection in a settings panel
+
+### Running the example
+
+```bash
+cd fishjam-chat
+yarn install
+yarn dev
+```
+
+Background blur is applied as a camera track middleware that processes each video frame with MediaPipe before the track is sent to other participants. Removing the middleware disables the effect without reconnecting.
+
+Browse the full source: [fishjam-chat on GitHub](https://github.com/fishjam-cloud/examples/tree/main/web-react/fishjam-chat)
+
+---
+
+## Next steps
+
+- Follow the [React Quick Start](../tutorials/react-quick-start) if you haven't set up a project yet
+- Learn how to [work with data channels](../how-to/client/data-channels)
+- Learn how to [implement screen sharing](../how-to/client/screensharing)