Reference

The npm packages

ASMI ships two packages — a React package that's the main integration path for the ~95% of host sites that are React apps, and a framework-agnostic runtime for everything else.

React (recommended)

@avatar-state-machine-interface/react wraps the runtime with the correctness-critical UI surface — live mid-turn expression swaps via the runtime's onTrace hook, timer-loop animation playback, cosmetic gesture reactions, idle auto-return, a transparent face region split from the chat shell, auto-detected host theme, form-submit preventDefault so Send doesn't navigate away. The full integration is three imports and one JSX block:

bash

npm install @avatar-state-machine-interface/react \
            @avatar-state-machine-interface/runtime

tsx

"use client";
import { AsmiAvatar, type LlmProvider } from "@avatar-state-machine-interface/react";
import definition from "./my-avatar.json";    // fetched once via MCP get_avatar

const llmProvider: LlmProvider = {
  async generate({ systemPrompt, userPrompt, history, temperature, maxTokens }) {
    // Call OpenAI / Anthropic / Gemini / whatever your site already uses.
    return (await yourLlmClient.complete({ system: systemPrompt, user: userPrompt, history, temperature, maxTokens })).text;
  },
};

export default function Site() {
  return <AsmiAvatar definition={definition} llmProvider={llmProvider} debug />;
}

Drop debug once the expression trail paints the way you expect; the runtime will console.info every state transition, action, expression emission, and LLM call it fires while it's on.

Primitives are also exported for hand-rolled chat surfaces that need file uploads, paste handlers, voice input, or a radically different layout:

useAsmiSession(definition, llmProvider, options?) — the correctness-critical session hook. Returns state, history, metadata, sending, send, reset, setHistory, setExpression, bumpActivity.
<AsmiFace /> — transparent animated face primitive. Reads an expression prop; plays the configured animation triggers.
useHostTheme() / detectHostTheme() — apply the same auto-detected host palette to a custom wrapper.

Package source: packages/asmi-react/. Peer deps: react >=18, react-dom >=18. Runtime dep: @avatar-state-machine-interface/runtime.

Runtime (non-React escape hatch)

@avatar-state-machine-interface/runtime is the framework-agnostic core — a pure state-machine evaluator with zero external runtime dependencies and a single LlmProvider seam. Use this directly if you're on Vue, Svelte, Solid, vanilla JS, or you're evaluating the state machine on a server. React sites should use the React package above, which wraps this under the hood.

bash

npm install @avatar-state-machine-interface/runtime

import { processMessage } from "@avatar-state-machine-interface/runtime";

const result = await processMessage(
  definition,          // AvatarDefinition JSON from MCP get_avatar
  currentState,        // { conversation, expression }
  userMessage,
  { history },
  myLlmProvider,       // your own { generate: ... }
);
// result.response, result.newState.expression, result.outboundEvents

Your UI layer is responsible for rendering the face image, playing animation frames, and wiring user input to processMessage. The React package does all of this; on non-React stacks you do it once.

Package source: packages/asmi-runtime/.