# Rqmii React Agent SDK - Framework Recipes

This guide shows integration patterns for Vite, Next.js, and CRA.

## 1. Vite

### Install

```bash
npm install @rqmii_immersive/agent-react-sdk
```

### Env

`.env`:

```env
VITE_AGENT_API_URL=https://api.example.com
VITE_AGENT_WS_URL=wss://realtime.example.com
```

### App Example

```jsx
import {
  RqmiiAgentRoom,
  useRqmiiMessages,
} from "@rqmii_immersive/agent-react-sdk";

function UI() {
  const { sendTextMessage } = useRqmiiMessages();
  return <button onClick={() => sendTextMessage("Hi")}>Send</button>;
}

export default function App() {
  return (
    <RqmiiAgentRoom
      wsUrl={import.meta.env.VITE_AGENT_WS_URL}
      restUrl={import.meta.env.VITE_AGENT_API_URL}
      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
      connect
    >
      <UI />
    </RqmiiAgentRoom>
  );
}
```

## 2. Next.js (App Router)

Use client components for SDK usage.

### Install

```bash
npm install @rqmii_immersive/agent-react-sdk
```

### Env

`.env.local`:

```env
NEXT_PUBLIC_AGENT_API_URL=https://api.example.com
NEXT_PUBLIC_AGENT_WS_URL=wss://realtime.example.com
```

### Client Component

`app/agent/page.jsx`:

```jsx
"use client";

import {
  RqmiiAgentRoom,
  useRqmiiConnection,
  useRqmiiMessages,
} from "@rqmii_immersive/agent-react-sdk";

function UI() {
  const { connectionState } = useRqmiiConnection();
  const { messages, sendTextMessage } = useRqmiiMessages();

  return (
    <div>
      <div>{connectionState}</div>
      <button onClick={() => sendTextMessage("Hello")}>Send</button>
      <pre>{JSON.stringify(messages, null, 2)}</pre>
    </div>
  );
}

export default function AgentPage() {
  return (
    <RqmiiAgentRoom
      wsUrl={process.env.NEXT_PUBLIC_AGENT_WS_URL}
      restUrl={process.env.NEXT_PUBLIC_AGENT_API_URL}
      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
      connect
    >
      <UI />
    </RqmiiAgentRoom>
  );
}
```

### Next.js Notes

- Do not use SDK in server components.
- Keep all SDK consumers under `'use client'`.
- For cloud avatar player, render it only on client.

## 3. Create React App (CRA)

### Install

```bash
npm install @rqmii_immersive/agent-react-sdk
```

### Env

`.env`:

```env
REACT_APP_AGENT_API_URL=https://api.example.com
REACT_APP_AGENT_WS_URL=wss://realtime.example.com
```

### App Example

```jsx
import {
  RqmiiAgentRoom,
  useRqmiiMessages,
} from "@rqmii_immersive/agent-react-sdk";

function UI() {
  const { sendTextMessage } = useRqmiiMessages();
  return <button onClick={() => sendTextMessage("Hello")}>Send</button>;
}

export default function App() {
  return (
    <RqmiiAgentRoom
      wsUrl={process.env.REACT_APP_AGENT_WS_URL}
      restUrl={process.env.REACT_APP_AGENT_API_URL}
      session={{ mode: "initialize", apiKey: "YOUR_API_KEY", language: "en" }}
      connect
    >
      <UI />
    </RqmiiAgentRoom>
  );
}
```

## 4. Common Recipes

### Cloud Avatar

```jsx
import {
  RqmiiCloudAvatarPlayer,
  useRqmiiAvatar,
} from "@rqmii_immersive/agent-react-sdk";

function AvatarPanel() {
  const { cloudStreamState, isAvatarSpeaking } = useRqmiiAvatar();
  return (
    <>
      <div>stream: {cloudStreamState}</div>
      <div>speaking: {String(isAvatarSpeaking)}</div>
      <RqmiiCloudAvatarPlayer muted={false} />
    </>
  );
}
```

### Desktop Avatar Join

```jsx
<RqmiiAgentRoom
  wsUrl={WS_URL}
  restUrl={REST_URL}
  session={{ mode: "join_desktop", uniqueId: "A1B2C3" }}
  connect
>
  <UI />
</RqmiiAgentRoom>
```

### Manual Provider Control

```jsx
import {
  RqmiiAgentProvider,
  useRqmiiConnection,
} from "@rqmii_immersive/agent-react-sdk";

function Controls() {
  const { initializeSession, disconnect } = useRqmiiConnection();
  return (
    <>
      <button
        onClick={() => initializeSession({ apiKey: "KEY", language: "en" })}
      >
        Init
      </button>
      <button onClick={disconnect}>Disconnect</button>
    </>
  );
}

export default function App() {
  return (
    <RqmiiAgentProvider wsUrl={WS_URL} restUrl={REST_URL}>
      <Controls />
    </RqmiiAgentProvider>
  );
}
```

## 5. Troubleshooting by Framework

### Vite

- Ensure env keys start with `VITE_`.
- Restart dev server after env changes.

### Next.js

- Ensure page/component is client-side (`'use client'`).
- Use `NEXT_PUBLIC_` env keys.

### CRA

- Ensure env keys start with `REACT_APP_`.
- Restart `npm start` after env changes.

## 6. Where to Read More

- Full technical docs: `README.md`
- Quick docs: `README.simple.md`
