# @bible-strong/avatar-react

React 19 renderer for a validated Bible Strong `AvatarDefinition`. React and React DOM 19 are peer
dependencies; `@bible-strong/avatar-core` is installed as a normal dependency.

## Install

```sh
pnpm add @bible-strong/avatar-react react react-dom
```

Import the package stylesheet once in the application entry point:

```tsx
import { Avatar, type AvatarController } from '@bible-strong/avatar-react'
import type { AvatarDefinition } from '@bible-strong/avatar-core'
import '@bible-strong/avatar-react/styles.css'
import { useRef } from 'react'

export function Assistant({ definition }: { definition: AvatarDefinition }) {
  const avatar = useRef<AvatarController>(null)
  return (
    <>
      <Avatar ref={avatar} definition={definition} defaultAnimation="idle" />
      <button onClick={() => avatar.current?.play('happy')}>Play happy</button>
      <button onClick={() => avatar.current?.setExpression('neutral')}>Neutral</button>
    </>
  )
}
```

For a reusable component tied to one JSON definition, use `createAvatar`. It validates the
definition once and, when the JSON is statically typed, narrows `animation`, `defaultAnimation`,
`expression` and `defaultExpression` to the semantic keys present in that definition:

```tsx
import { createAvatar } from '@bible-strong/avatar-react'
import avatarJson from './strobi.avatar.json'

const StrobiAvatar = createAvatar(avatarJson)

export function Strobi() {
  return <StrobiAvatar defaultAnimation="idle" />
}
```

Definitions fetched at runtime are validated by the same factory, but their keys are necessarily
checked at runtime rather than inferred by TypeScript.

`play` and `setExpression` return `{ ok: true }` or a typed error with one of
`unknown_animation`, `unknown_expression` or `controlled_by_props`. `pause` freezes the exact
timeline position, calling `play` with the paused key resumes it, and `stop` returns an
uncontrolled avatar to `neutral`.

## Props reference

`Avatar` exposes typed props for the definition, playback state and presentation. `AnimationKey`
and `ExpressionKey` are semantic string keys from the supplied definition.

### Definition and playback

| Prop                | Type                                 | Default  | Behavior                                                                                                                   |
| ------------------- | ------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `definition`        | `AvatarDefinition`                   | required | Validated JSON definition containing the expressions and animations to render.                                             |
| `animation`         | `AnimationKey \| undefined`          | —        | Controlled timeline. Each step chooses the displayed expression. Mutually exclusive with `expression`.                     |
| `expression`        | `ExpressionKey \| undefined`         | —        | Controlled direct expression. Mutually exclusive with `animation`.                                                         |
| `defaultAnimation`  | `AnimationKey \| undefined`          | —        | Initial uncontrolled timeline, read on mount. Autoplay is enabled by default. Mutually exclusive with `defaultExpression`. |
| `defaultExpression` | `ExpressionKey \| undefined`         | —        | Initial uncontrolled expression, read on mount without starting a timeline. Mutually exclusive with `defaultAnimation`.    |
| `autoplay`          | `boolean \| undefined`               | `true`   | Starts `defaultAnimation` automatically. It has no effect without `defaultAnimation`.                                      |
| `ref`               | `Ref<AvatarController> \| undefined` | —        | Exposes the imperative API described below.                                                                                |

`animation` and `expression` are two alternative sources of truth. Passing both throws an error;
the component never silently overrides one with the other. A controlled target takes priority over
an uncontrolled default when they are intentionally mixed.

### Presentation

| Prop        | Type                            | Default             | Behavior                                                                    |
| ----------- | ------------------------------- | ------------------- | --------------------------------------------------------------------------- |
| `size`      | `number \| string \| undefined` | `240`               | Number or CSS value applied to the wrapper width and height.                |
| `className` | `string \| undefined`           | —                   | CSS class added to the outer wrapper.                                       |
| `style`     | `CSSProperties \| undefined`    | —                   | Inline styles for the outer wrapper. `width` and `height` come from `size`. |
| `ariaLabel` | `string \| undefined`           | `Procedural avatar` | Accessible name announced to screen readers.                                |

### Playback callbacks

| Prop                 | Type                                  | Receives                                                               |
| -------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| `onAnimationEnd`     | `(animation: AnimationKey) => void`   | The key of a `once` animation when it completes naturally.             |
| `onExpressionChange` | `(expression: ExpressionKey) => void` | The semantic expression key whenever the displayed expression changes. |
| `onError`            | `(error: AvatarRuntimeError) => void` | An unknown animation or expression key supplied through props.         |

Unknown keys passed through `animation`, `expression`, `defaultAnimation` or `defaultExpression`
are reported to `onError`. Without an error handler, the component writes the typed runtime error
to the developer console instead of failing silently.

## Imperative API

Pass a `ref` to receive an `AvatarController`. Use it when buttons, events or another imperative
source need to drive an uncontrolled avatar:

| Method                      | Type                                                 | Behavior                                                       |
| --------------------------- | ---------------------------------------------------- | -------------------------------------------------------------- |
| `play(animation)`           | `(animation: AnimationKey) => AvatarCommandResult`   | Starts an animation or resumes it from its paused position.    |
| `pause()`                   | `() => void`                                         | Freezes the exact timeline position.                           |
| `stop()`                    | `() => void`                                         | Stops playback and resets an uncontrolled avatar to `neutral`. |
| `setExpression(expression)` | `(expression: ExpressionKey) => AvatarCommandResult` | Shows one expression directly.                                 |
| `getState()`                | `() => AvatarPlaybackState`                          | Returns `activeAnimation?`, `activeExpression` and `status`.   |

`play` and `setExpression` return `{ ok: true }` or `{ ok: false, error }`. Errors include
`unknown_animation`, `unknown_expression` and `controlled_by_props`. When `animation` or
`expression` is controlled by props, use those props to change the target; imperative target
commands cannot replace the parent value.

The definition is validated once per immutable object reference and revalidated/reinitialized when
that reference changes.

## Styling hooks

The stylesheet exposes `.bs-avatar` and `.bs-avatar__svg`. Consumer `className` and `style` are
applied to the outer wrapper.

The public component never exposes Studio IDs or document types. The package follows Semantic
Versioning. While it remains below `1.0.0`, breaking API changes increment the minor version and
fixes increment the patch version.