avatars-sdk-react: Instructions file for Codex

Agent Guidelines

Context for AI agents working with the Runway Avatar SDK monorepo.

Repository Structure

packages/
  core/    → @runwayml/avatars (framework-agnostic)
  react/   → @runwayml/avatars-react (React bindings)
examples/
  vanilla-js/          Pure JS demo
  nextjs-simple/       Minimal Next.js
  nextjs/              Full Next.js with presets
  nextjs-client-events/  Client event tools
  express/             Express + Vite
  ...
docs/                  Reference docs (holding files)

Package Architecture

Core (packages/core/) — No React, no framework dependency. LiveKit is the only runtime dep but fully abstracted from the public API.

src/
├── client.ts              # AvatarSession class + streamTo/connect entry points
├── emitter.ts             # Tiny typed event emitter
├── transcript-accumulator.ts
├── types.ts               # All shared types + AvatarEvent enum
├── tools.ts               # clientTool / Standard Schema
├── standard-schema.ts
├── api/
│   ├── consume.ts         # consumeSession HTTP call
│   ├── config.ts          # DEFAULT_BASE_URL
│   ├── page-actions.ts    # Page action tool definitions
│   └── index.ts           # /api subpath entry
└── utils/
    ├── parseClientEvent.ts
    ├── parseTranscription.ts
    └── flatDeltaAccumulator.ts

React (packages/react/) — Components and hooks. Depends on @runwayml/avatars as a regular dependency. No direct LiveKit imports.

src/
├── components/            # AvatarCall, AvatarProvider, AvatarSession, AvatarVideo, etc.
├── hooks/                 # useAvatarSession, useAvatar, useLocalMedia, useTranscript, etc.
├── api/index.ts           # Re-exports from core /api for backwards compat
├── types.ts               # React-specific types (props, context values)
├── styles.css
└── index.ts

Key Patterns

Core SDK API:

const session = await streamTo({ credentials, target: videoEl });
session.mic.toggle();
session.on(AvatarEvent.AvatarVideoReady, (track) => { ... });
session.end();