# Buddy widget

> Animated companion with stage, coins, equipped items, and live event effects.

Source: https://docs.hatched.live/docs/reference/widgets/buddy

## Mount

```html
<script src="https://cdn.hatched.live/widget.js" data-session-token="SESSION_TOKEN" defer></script>

<div data-hatched-mount="buddy"></div>
```

Use `data-embed-token` on the script instead of `data-session-token` for a
read-only buddy.

For client-rendered routes, call `window.__HATCHED_WIDGET__?.init({ token })`
after the mount element exists. The global is `window.__HATCHED_WIDGET__`; the
init payload uses `token`, not `embedToken`.

## Script attributes

| Attribute            | Values                 | Default                           |
| -------------------- | ---------------------- | --------------------------------- |
| `data-session-token` | widget session token   | interactive mode                  |
| `data-embed-token`   | embed token            | read-only mode                    |
| `data-theme`         | `light` `dark`         | `light`                           |
| `data-api-base-url`  | API origin + `/api/v1` | `https://api.hatched.live/api/v1` |

## Required scopes

- `read` renders buddy state.
- `events:track` enables `window.__HATCHED_WIDGET__.track(...)`.

## Appearance and pending operations

The buddy widget displays `buddy.appearance` from `/widget/state`. When an
equip or evolve operation is still rendering marketplace items, the widget keeps
the latest safe `image_url` visible and shows a small status banner:

- `pending` while an appearance job is running.
- `awaiting_credits` while Hatched waits for image credits before retrying.
- `failed` when recovery or rerender is needed.

`/widget/state` also includes `pending_operations` and an `ETag`; the loader
uses both to poll efficiently and refresh every mounted widget on the page.

## Host API

```ts
await window.__HATCHED_WIDGET__.track('lesson_completed', {
  lessonId: 'lesson_1',
});
```

The loader reconciles effects into every mounted widget on the page.