LLM prompt — add the Web/React SDK

Use this prompt when you have an existing React or Next.js app and want to add a 2wai avatar screen using the full Web SDK (not the drop-in Web Component).

The prompt

Copy, paste, fill {PLACEHOLDERS}:

I'm adding a 2wai talking avatar to an existing React/Next.js app using the official @twai/* packages.

CONTEXT

2wai is a lip-synced talking-avatar platform. Transport 0 (LiveKit) is the only live transport. Integration pattern is MINT-PROXY: my server holds `sk_...` and mints a short-lived LiveKit participant token the client uses to join the avatar's room.

The SDK:
- `@twai/core` — engine + types (framework-free TypeScript)
- `@twai/player` — player facade over the engine
- `@twai/react` — React hooks + components

MY INPUTS

- sk_ key (server-only): {TWAI_SECRET_KEY}
- avatar_id: {AVATAR_ID}
- voice_id (optional): {VOICE_ID}
- framework: {NEXT_JS / VITE_REACT / CREATE_REACT_APP / OTHER}
- Next.js router: {APP_ROUTER / PAGES_ROUTER / NA}
- where I want the avatar: {ROUTE_PATH or COMPONENT_PATH}

WHAT I NEED YOU TO DO

1. **Install packages**:
   ```
   npm install @twai/core @twai/player @twai/react
   ```

2. **Add mint proxy route** (Next.js App Router example at `app/api/mint/route.ts`):
   ```ts
   export async function POST() {
     const r = await fetch('https://api.2wai.ai/v1/sessions', {
       method: 'POST',
       headers: {
         Authorization: `Bearer ${process.env.TWAI_SECRET_KEY}`,
         'Content-Type': 'application/json',
       },
       body: JSON.stringify({
         avatar_id: process.env.AVATAR_ID,
         voice_id: process.env.VOICE_ID,  // optional
         mode: 'video',
         transport: 'livekit',
       }),
     });
     const s = await r.json();
     if (!r.ok) return Response.json(s, { status: r.status });
     return Response.json({
       session_id: s.session_id,
       livekit_url: s.livekit_url,
       participant_token: s.participant_token,
       room_name: s.room_name,
     });
   }
   ```
   (If I'm on Pages Router, write `pages/api/mint.ts` with the equivalent default-export handler. If Vite/CRA, create a tiny Express/Fastify server beside the app and add `/api/mint` there.)

3. **Add env entries** to `.env.local` (gitignored):
   ```
   TWAI_SECRET_KEY=<sk_>
   AVATAR_ID=<avt_>
   VOICE_ID=<vc_>   # optional
   ```
   Add to `.env.example` with placeholders.

4. **Add the avatar screen** component:
   ```tsx
   'use client';  // Next App Router only
   import { useTwaiSession } from '@twai/react';

   export function AvatarScreen() {
     const { videoRef, send, state } = useTwaiSession({
       mintUrl: '/api/mint',
       avatarId: process.env.NEXT_PUBLIC_AVATAR_ID!,  // ok to expose; it's a public id
     });

     return (
       <div>
         <video ref={videoRef} autoPlay playsInline style={{ maxWidth: 480 }} />
         <button
           disabled={state !== 'ready'}
           onClick={() => send('Hi!')}
         >Say hi</button>
         <p>state: {state}</p>
       </div>
     );
   }
   ```
   Mount this at the route I specified above.

5. **Verify**:
   - Dev server starts clean.
   - Browser opens the route.
   - Avatar video appears within ~5s.
   - Click "Say hi" — the avatar talks.
   - DevTools Console — no errors.

GOTCHAS TO HONOR

- `TWAI_SECRET_KEY` is server-side only. Never prefix with `NEXT_PUBLIC_` or embed in client code.
- `NEXT_PUBLIC_AVATAR_ID` is fine to expose — avatar ids aren't credentials.
- `useTwaiSession` already configures the LiveKit room correctly (`adaptiveStream: false`, `dynacast: false`). Don't touch those.
- The hook's `state` values are: `idle | connecting | ready | rateLimited | failed | disconnected`. Gate your Send button on `state === 'ready'`.
- If the user types mid-reply, call `interrupt()` (also returned by `useTwaiSession`) before `send(newText)`.
- The old gateway MSE/WebSocket path is RETIRED. If you see `mse_url` or `websocket_url` in older docs, ignore them — the gateway returns `livekit_url` + `participant_token` + `room_name`.

DELIVERABLE

- One new mint-proxy route.
- One new React component mounted at my route.
- `.env.local` + `.env.example` entries.
- A one-line README note on how to run.

If you need anything I haven't given (my package manager, my env file location, whether the app has strict CSP that'll block the LiveKit WebRTC connections), ASK me.

Reference docs: https://developers.2wai.ai/sdks/web/
Reference app: https://github.com/2waiorg/2wai-toolkit-public/tree/main/samples/nextjs