Buddy widget

Mount

<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

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

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

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