agent-robot-avatar 0.2.0

package/docs/README.es.md

@@ -0,0 +1,217 @@
+# Agent Robot Avatar
+
+<p align="center">
+  <img src="../assets/readme/agent-robot-avatar-header.jpg" alt="Agent Robot Avatar">
+</p>
+
+[English](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/README.md) | [简体中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-CN.md) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md) | [日本語](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ja.md) | [한국어](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ko.md) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Português](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.pt.md) | [Deutsch](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.de.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.md)
+
+![Versión de desarrollo](https://img.shields.io/badge/version-v0.2.0-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
+
+![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=000) ![Web Component](https://img.shields.io/badge/Web-Native%20Component-5A67D8?style=flat-square) ![SVG](https://img.shields.io/badge/Rendering-SVG-FFB13B?style=flat-square&logo=svg&logoColor=000) ![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-2EA44F?style=flat-square) ![14 Agent States](https://img.shields.io/badge/Agent%20states-14-8B5CF6?style=flat-square) ![Pointer Following](https://img.shields.io/badge/Pointer-following-00A67E?style=flat-square) ![Jelly Drag](https://img.shields.io/badge/Drag-jelly%20physics-FF69B4?style=flat-square)
+
+Un Web Component ligero y expresivo de avatar robótico para agentes de IA y otras aplicaciones interactivas.
+
+Agent Robot Avatar está construido con SVG y JavaScript nativo, sin depender de frameworks de animación de terceros. Funciona como un Custom Element nativo y ofrece una API compacta para expresiones, estados de interacción, seguimiento del puntero, espera y forma de la cabeza.
+
+**Versión pública actual: v0.2.0**
+
+<p align="center">
+  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Demostración animada interactiva de Agent Robot Avatar" width="560">
+</p>
+
+## Características principales
+
+- SVG + JavaScript nativo
+- Web Component nativo
+- Sin dependencias de frameworks de animación
+- Parpadeo automático y mirada sutil
+- Seguimiento del puntero y movimiento de cabeza con inercia
+- Deformación local tipo gelatina al arrastrar y recuperación elástica
+- Estados y expresiones de Agent controlables por código
+- Semántica separada para espera, fallo, advertencia, revisión, bloqueo y error del sistema
+- Redondez de la cabeza ajustable
+- Antena flotante con parpadeo de estado opcional
+- Demo separado del componente reutilizable
+
+## Inicio rápido
+
+Si usas directamente el código del repositorio, conserva `agent-robot-avatar.js` junto con `src/` y carga la entrada pública:
+
+```html
+<script type="module" src="./agent-robot-avatar.js"></script>
+```
+
+```html
+<agent-robot-avatar id="avatar"></agent-robot-avatar>
+```
+
+El avatar entra automáticamente en el estado idle. Hay un ejemplo mínimo en [`examples/basic.html`](../examples/basic.html).
+
+## API básica
+
+```js
+const avatar = document.querySelector('#avatar');
+
+avatar.play('success');
+avatar.play('failure');
+avatar.play('warning');
+avatar.play('inspect');
+avatar.play('angry');
+avatar.play('error');
+
+avatar.reset();
+```
+
+## Estados y expresiones
+
+| Estado | API | Uso previsto |
+| --- | --- | --- |
+| Idle | `idle` | Estado normal de reposo |
+| Bored | `bored` | Periodos largos sin tarea activa |
+| Waiting | `waiting` | Solicitud enviada, esperando resultado |
+| Input | `input` | El usuario está escribiendo |
+| Send | `send` | Envío / gesto de asentir |
+| Success | `success` | Tarea completada correctamente |
+| Failure | `failure` | La tarea terminó sin éxito |
+| Warning | `warning` | Acción arriesgada o destructiva que requiere confirmación |
+| Inspect | `inspect` | Revisar, comprobar o verificar un resultado |
+| Blocked | `angry` | Solicitud bloqueada o que no puede continuar |
+| System error | `error` | Error de conexión, servicio o sistema |
+| Surprise | `surprise` | Resultado o evento inesperado |
+| Sleep | `sleep` | Entrar en reposo |
+| Wake | `wake` | Despertar |
+
+`failure` representa un fallo de la tarea; `error` se reserva para problemas de conexión, servicio o sistema. `waiting` indica una solicitud pendiente y `bored` indica inactividad.
+
+También hay alias semánticos:
+
+```js
+avatar.play('failed');
+avatar.play('fail');
+avatar.play('verify');
+avatar.play('review');
+avatar.play('blocked');
+avatar.play('policy-blocked');
+avatar.play('system-error');
+avatar.play('connection-error');
+```
+
+## Espera continua
+
+```js
+avatar.startWaiting();
+// Detener cuando llegue la respuesta o el resultado.
+avatar.stopWaiting();
+```
+
+Cualquier otra acción también interrumpe el estado waiting activo.
+
+## Seguimiento del puntero
+
+```js
+avatar.setPointerFollow(false);
+avatar.setPointerFollow(true);
+```
+
+## Redondez de la cabeza
+
+```js
+avatar.setHeadRoundness(0);   // más cuadrada
+avatar.setHeadRoundness(50);  // predeterminado
+avatar.setHeadRoundness(100); // más redonda
+
+console.log(avatar.getHeadRoundness());
+```
+
+Los valores se limitan a `0–100`. Al cambiar se emite `head-roundness-change`.
+
+```js
+avatar.addEventListener('head-roundness-change', (event) => {
+  console.log(event.detail.value);
+});
+```
+
+## Evento de estado
+
+Cada cambio visual emite `face-state`:
+
+```js
+avatar.addEventListener('face-state', (event) => {
+  console.log(event.detail.state);
+});
+```
+
+## Atributos
+
+```html
+<agent-robot-avatar
+  size="160"
+  color="#08090b"
+  auto-sleep="30000">
+</agent-robot-avatar>
+```
+
+| Atributo | Descripción |
+| --- | --- |
+| `size` | Tamaño del componente en píxeles |
+| `color` | Color principal del avatar |
+| `auto-sleep` | Tiempo de inactividad antes de dormir, en ms; `0` lo desactiva |
+
+## Comportamiento predeterminado
+
+Sin llamadas explícitas a la API, el avatar ya ofrece parpadeo aleatorio, movimiento sutil de la mirada, seguimiento del puntero cercano, movimiento inercial de la cabeza, retorno natural a idle y suspensión automática opcional.
+
+## Interacción de arrastre
+
+Al arrastrar, la cabeza se deforma localmente alrededor del punto de interacción en lugar de moverse como un objeto rígido.
+
+- Tirón fuerte hacia fuera: activa `angry` después de recuperarse
+- Empuje fuerte hacia el centro: activa `success` después de recuperarse
+- Arrastre pequeño: solo deformación
+
+## Demo interactiva
+
+`demo/index.html` incluye todos los estados públicos, seguimiento del puntero, arrastre tipo gelatina, ciclo de waiting, ajuste de redondez, controles de color y comportamiento y una simulación de conversación con Agent. El JavaScript exclusivo de la Demo está aislado en `demo/` y no forma parte del runtime reutilizable de npm.
+
+## Estructura del proyecto
+
+```text
+agent-robot-avatar.js     Entrada pública del componente
+src/                      Runtime reutilizable y módulos de expresiones
+demo/                     Demo interactiva y scripts exclusivos
+examples/                 Ejemplos mínimos de integración
+assets/support/           Recursos QR de apoyo / pago
+docs/                     Documentación multilingüe
+README.md                 Documento principal en inglés
+CHANGELOG.md              Historial público de versiones
+CONTRIBUTING.md           Guía de contribución
+package.json              Metadatos del paquete
+LICENSE                   Licencia MIT
+```
+
+## Distribución y compatibilidad
+
+El paquete está publicado en npm como `agent-robot-avatar` e incluye declaraciones TypeScript para acciones, eventos y métodos públicos. Está pensado para navegadores modernos compatibles con ES Modules, Custom Elements, SVG, Pointer Events y Web Animations API.
+
+## Contribuir
+
+Se aceptan Issues y Pull Requests. Consulta [`CONTRIBUTING.md`](../CONTRIBUTING.md) antes de enviar cambios.
+
+## Estado del proyecto
+
+v0.1.0 es la primera línea de versión pública. La API pública se mantiene deliberadamente pequeña para poder evolucionar con cuidado antes de un futuro compromiso de estabilidad `1.0.0`.
+
+Agent Robot Avatar es un proyecto independiente de código abierto y no está afiliado, respaldado ni representa a ninguna plataforma o marca de IA.
+
+## Licencia
+
+MIT License. Consulta [`LICENSE`](../LICENSE).
+
+## Invítame a un café
+
+Si el proyecto te resulta útil, puedes apoyarlo con el método que prefieras:
+
+| Ko-fi | Alipay | WeChat Pay |
+| --- | --- | --- |
+| <a href='https://ko-fi.com/P0E625WIOI' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> | <img src="../assets/support/alipay.png" alt="Código QR de Alipay" width="160"> | <img src="../assets/support/wechat-pay.png" alt="Código QR de WeChat Pay" width="160"> |

package/docs/README.fr.md

@@ -0,0 +1,215 @@
+# Agent Robot Avatar
+
+<p align="center">
+  <img src="../assets/readme/agent-robot-avatar-header.jpg" alt="Agent Robot Avatar">
+</p>
+
+[English](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/README.md) | [简体中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-CN.md) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md) | [日本語](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ja.md) | [한국어](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ko.md) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Português](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.pt.md) | [Deutsch](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.de.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.md)
+
+![Version](https://img.shields.io/badge/version-v0.2.0-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
+
+Un Web Component léger et expressif d’avatar robot pour les agents IA et d’autres applications interactives.
+
+Agent Robot Avatar est construit avec SVG et JavaScript natif, sans framework d’animation tiers. Il fonctionne comme un Custom Element natif et propose une API compacte pour les expressions, les états d’interaction, le suivi du pointeur, l’attente et la forme de la tête.
+
+**Version publique actuelle : v0.2.0**
+
+<p align="center">
+  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Démonstration animée interactive d’Agent Robot Avatar" width="560">
+</p>
+
+## Points forts
+
+- SVG + JavaScript natif
+- Web Component natif
+- Aucune dépendance à un framework d’animation
+- Clignement automatique et mouvements subtils du regard
+- Suivi du pointeur et mouvement de tête avec inertie
+- Déformation locale type gelée lors du glisser et retour élastique
+- États et expressions d’Agent pilotables par code
+- Sémantique distincte pour waiting, failure, warning, inspect, blocked et system error
+- Arrondi de la tête réglable
+- Antenne flottante avec clignotement d’état optionnel
+- Demo séparée du composant réutilisable
+
+## Démarrage rapide
+
+Si vous utilisez directement le code du dépôt, conservez `agent-robot-avatar.js` avec le dossier `src/`, puis chargez l’entrée publique :
+
+```html
+<script type="module" src="./agent-robot-avatar.js"></script>
+```
+
+```html
+<agent-robot-avatar id="avatar"></agent-robot-avatar>
+```
+
+L’avatar passe automatiquement à l’état idle. Un exemple minimal est disponible dans [`examples/basic.html`](../examples/basic.html).
+
+## API de base
+
+```js
+const avatar = document.querySelector('#avatar');
+
+avatar.play('success');
+avatar.play('failure');
+avatar.play('warning');
+avatar.play('inspect');
+avatar.play('angry');
+avatar.play('error');
+
+avatar.reset();
+```
+
+## États et expressions
+
+| État | API | Usage |
+| --- | --- | --- |
+| Idle | `idle` | État d’attente normal |
+| Bored | `bored` | Longue période sans tâche active |
+| Waiting | `waiting` | Requête envoyée, résultat en attente |
+| Input | `input` | L’utilisateur saisit du texte |
+| Send | `send` | Envoi / retour par hochement |
+| Success | `success` | Tâche terminée avec succès |
+| Failure | `failure` | Tâche terminée sans succès |
+| Warning | `warning` | Action importante nécessitant confirmation |
+| Inspect | `inspect` | Examiner, contrôler ou vérifier un résultat |
+| Blocked | `angry` | Requête bloquée ou impossible à poursuivre |
+| System error | `error` | Erreur de connexion, de service ou système |
+| Surprise | `surprise` | Événement ou résultat inattendu |
+| Sleep | `sleep` | Entrer en veille |
+| Wake | `wake` | Sortir de veille |
+
+`failure` correspond à l’échec de la tâche elle-même ; `error` est réservé aux problèmes de connexion, de service ou de système. `waiting` indique une requête en cours et `bored` une période d’inactivité.
+
+Des alias sémantiques sont également disponibles :
+
+```js
+avatar.play('failed');
+avatar.play('fail');
+avatar.play('verify');
+avatar.play('review');
+avatar.play('blocked');
+avatar.play('policy-blocked');
+avatar.play('system-error');
+avatar.play('connection-error');
+```
+
+## Attente continue
+
+```js
+avatar.startWaiting();
+// Arrêter lorsque la réponse ou le résultat arrive.
+avatar.stopWaiting();
+```
+
+Toute autre action interrompt aussi l’état waiting actif.
+
+## Suivi du pointeur
+
+```js
+avatar.setPointerFollow(false);
+avatar.setPointerFollow(true);
+```
+
+## Arrondi de la tête
+
+```js
+avatar.setHeadRoundness(0);   // plus carrée
+avatar.setHeadRoundness(50);  // valeur par défaut
+avatar.setHeadRoundness(100); // plus ronde
+
+console.log(avatar.getHeadRoundness());
+```
+
+Les valeurs sont limitées à `0–100`. Les changements déclenchent `head-roundness-change`.
+
+```js
+avatar.addEventListener('head-roundness-change', (event) => {
+  console.log(event.detail.value);
+});
+```
+
+## Événement d’état
+
+Chaque changement visuel déclenche `face-state` :
+
+```js
+avatar.addEventListener('face-state', (event) => {
+  console.log(event.detail.state);
+});
+```
+
+## Attributs
+
+```html
+<agent-robot-avatar
+  size="160"
+  color="#08090b"
+  auto-sleep="30000">
+</agent-robot-avatar>
+```
+
+| Attribut | Description |
+| --- | --- |
+| `size` | Taille du composant en pixels |
+| `color` | Couleur principale de l’avatar |
+| `auto-sleep` | Temps d’inactivité avant veille automatique, en ms ; `0` désactive la fonction |
+
+## Comportement par défaut
+
+Sans appel explicite à l’API, l’avatar propose déjà des clignements aléatoires, de petits mouvements du regard, le suivi du pointeur proche, une légère inertie de la tête, un retour naturel à idle et une veille automatique optionnelle.
+
+## Interaction par glisser
+
+Lors du glisser, la tête se déforme localement autour du point d’interaction au lieu de se déplacer comme un objet rigide.
+
+- Forte traction vers l’extérieur : déclenche `angry` après le retour
+- Forte poussée vers le centre : déclenche `success` après le retour
+- Petit glisser : déformation uniquement
+
+## Demo interactive
+
+`demo/index.html` contient tous les états publics, le suivi du pointeur, le glisser type gelée, le cycle waiting, le réglage de l’arrondi, les contrôles de couleur et de comportement et une simulation de conversation Agent. Le JavaScript propre à la Demo reste dans `demo/` et n’est pas inclus dans le runtime npm réutilisable.
+
+## Structure du projet
+
+```text
+agent-robot-avatar.js     Entrée publique du composant
+src/                      Runtime réutilisable et modules d’expression
+demo/                     Demo interactive et scripts dédiés
+examples/                 Exemples minimaux d’intégration
+assets/support/           Ressources QR de soutien / paiement
+docs/                     Documentation multilingue
+README.md                 Documentation principale en anglais
+CHANGELOG.md              Historique public des versions
+CONTRIBUTING.md           Guide de contribution
+package.json              Métadonnées du paquet
+LICENSE                   Licence MIT
+```
+
+## Distribution et compatibilité
+
+Le paquet est publié sur npm sous le nom `agent-robot-avatar` et inclut des déclarations TypeScript pour les actions, les événements et les méthodes publiques. Le composant cible les navigateurs modernes prenant en charge ES Modules, Custom Elements, SVG, Pointer Events et Web Animations API.
+
+## Contribuer
+
+Issues et Pull Requests sont les bienvenus. Consultez [`CONTRIBUTING.md`](../CONTRIBUTING.md) avant de proposer des changements.
+
+## État du projet
+
+v0.1.0 est la première ligne de version publique. L’API publique reste volontairement limitée afin d’évoluer avec prudence avant un futur engagement de stabilité `1.0.0`.
+
+Agent Robot Avatar est un projet open source développé indépendamment ; il n’est affilié, approuvé ni représentatif d’aucune plateforme ou marque d’IA.
+
+## Licence
+
+MIT License. Voir [`LICENSE`](../LICENSE).
+
+## Offrez-moi un café
+
+Si ce projet vous est utile, vous pouvez le soutenir avec la méthode qui vous convient :
+
+| Ko-fi | Alipay | WeChat Pay |
+| --- | --- | --- |
+| <a href='https://ko-fi.com/P0E625WIOI' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> | <img src="../assets/support/alipay.png" alt="QR code Alipay" width="160"> | <img src="../assets/support/wechat-pay.png" alt="QR code WeChat Pay" width="160"> |

package/docs/README.ja.md

@@ -0,0 +1,217 @@
+# Agent Robot Avatar
+
+<p align="center">
+  <img src="../assets/readme/agent-robot-avatar-header.jpg" alt="Agent Robot Avatar">
+</p>
+
+[English](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/README.md) | [简体中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-CN.md) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md) | [日本語](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ja.md) | [한국어](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ko.md) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Português](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.pt.md) | [Deutsch](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.de.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.md)
+
+![Version](https://img.shields.io/badge/version-v0.2.0-111111?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-0A7EA4?style=flat-square)](../LICENSE) [![CI](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/CX-ArtLab/agent-robot-avatar/actions/workflows/validate.yml) [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white)](https://ko-fi.com/P0E625WIOI)
+
+![Vanilla JavaScript](https://img.shields.io/badge/Vanilla-JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=000) ![Web Component](https://img.shields.io/badge/Web-Native%20Component-5A67D8?style=flat-square) ![SVG](https://img.shields.io/badge/Rendering-SVG-FFB13B?style=flat-square&logo=svg&logoColor=000) ![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-2EA44F?style=flat-square) ![14 Agent States](https://img.shields.io/badge/Agent%20states-14-8B5CF6?style=flat-square) ![Pointer Following](https://img.shields.io/badge/Pointer-following-00A67E?style=flat-square) ![Jelly Drag](https://img.shields.io/badge/Drag-jelly%20physics-FF69B4?style=flat-square)
+
+AI エージェントやその他のインタラクティブなアプリケーションで使える、軽量で表情豊かなロボットアバター Web Component です。
+
+Agent Robot Avatar は SVG と Vanilla JavaScript だけで構築され、サードパーティー製アニメーションフレームワークに依存しません。ネイティブ Custom Element として動作し、表情、状態、ポインター追従、待機フィードバック、頭部形状をシンプルな API で制御できます。
+
+**現在の公開バージョン：v0.2.0**
+
+<p align="center">
+  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar インタラクティブアニメーションデモ" width="560">
+</p>
+
+## 特長
+
+- SVG + Vanilla JavaScript
+- ネイティブ Web Component
+- 外部アニメーション依存なし
+- 自動まばたきと自然な視線移動
+- ポインター追従と慣性のある頭部モーション
+- 局所的なゼリー風ドラッグ変形と弾性復帰
+- Agent の状態や表情をプログラムから制御可能
+- waiting / failure / warning / inspect / blocked / system error を意味的に分離
+- 頭部の丸みを調整可能
+- オプションで点滅するフローティングアンテナ
+- Demo と再利用可能なコンポーネント本体を分離
+
+## クイックスタート
+
+リポジトリのソースを直接使う場合は、ルートの `agent-robot-avatar.js` と `src/` を同じ構成で保ち、公開エントリを読み込みます。
+
+```html
+<script type="module" src="./agent-robot-avatar.js"></script>
+```
+
+```html
+<agent-robot-avatar id="avatar"></agent-robot-avatar>
+```
+
+読み込み後は自動的に idle 状態になります。最小サンプルは [`examples/basic.html`](../examples/basic.html) にあります。
+
+## 基本 API
+
+```js
+const avatar = document.querySelector('#avatar');
+
+avatar.play('success');
+avatar.play('failure');
+avatar.play('warning');
+avatar.play('inspect');
+avatar.play('angry');
+avatar.play('error');
+
+avatar.reset();
+```
+
+## 状態と表情
+
+| 状態 | API 名 | 用途 |
+| --- | --- | --- |
+| Idle | `idle` | 通常の待機状態 |
+| Bored | `bored` | 長時間タスクがない状態 |
+| Waiting | `waiting` | リクエスト送信後、結果待ち |
+| Input | `input` | ユーザー入力中 |
+| Send | `send` | 送信 / うなずきフィードバック |
+| Success | `success` | タスク成功 |
+| Failure | `failure` | タスク自体が失敗 |
+| Warning | `warning` | 危険・破壊的な操作の確認 |
+| Inspect | `inspect` | 結果の確認・検証 |
+| Blocked | `angry` | リクエストが拒否・停止された状態 |
+| System error | `error` | 接続・サービス・システム障害 |
+| Surprise | `surprise` | 予期しない結果 |
+| Sleep | `sleep` | スリープへ移行 |
+| Wake | `wake` | スリープから復帰 |
+
+`failure` はタスク結果の失敗、`error` は接続・サービス・システム側の障害を表します。`waiting` は進行中の待機、`bored` はアクティブなタスクがない状態です。
+
+セマンティックエイリアスも利用できます。
+
+```js
+avatar.play('failed');
+avatar.play('fail');
+avatar.play('verify');
+avatar.play('review');
+avatar.play('blocked');
+avatar.play('policy-blocked');
+avatar.play('system-error');
+avatar.play('connection-error');
+```
+
+## 継続待機
+
+```js
+avatar.startWaiting();
+// 結果が返ったら停止します。
+avatar.stopWaiting();
+```
+
+別のアクションを再生した場合も waiting は解除されます。
+
+## ポインター追従
+
+```js
+avatar.setPointerFollow(false);
+avatar.setPointerFollow(true);
+```
+
+## 頭部の丸み
+
+```js
+avatar.setHeadRoundness(0);   // より角ばった形
+avatar.setHeadRoundness(50);  // デフォルト
+avatar.setHeadRoundness(100); // より丸い形
+
+console.log(avatar.getHeadRoundness());
+```
+
+値は `0–100` に制限されます。変更時には `head-roundness-change` イベントが発火します。
+
+```js
+avatar.addEventListener('head-roundness-change', (event) => {
+  console.log(event.detail.value);
+});
+```
+
+## 状態イベント
+
+表示状態が変化すると `face-state` イベントが発火します。
+
+```js
+avatar.addEventListener('face-state', (event) => {
+  console.log(event.detail.state);
+});
+```
+
+## 属性
+
+```html
+<agent-robot-avatar
+  size="160"
+  color="#08090b"
+  auto-sleep="30000">
+</agent-robot-avatar>
+```
+
+| 属性 | 説明 |
+| --- | --- |
+| `size` | コンポーネントのサイズ（px） |
+| `color` | アバターのメインカラー |
+| `auto-sleep` | 自動スリープまでのアイドル時間（ms）。`0` で無効 |
+
+## デフォルト動作
+
+API を呼ばなくても、ランダムなまばたき、視線移動、近くのポインターへの追従、軽い慣性モーション、自然な idle 復帰、オプションの自動スリープが動作します。
+
+## ドラッグ操作
+
+ドラッグ時は頭全体を剛体として動かすのではなく、操作点の周辺が局所的に変形します。
+
+- 強く外側へ引く：復帰後に `angry`
+- 強く中心へ押す：復帰後に `success`
+- 小さなドラッグ：変形のみ
+
+## インタラクティブ Demo
+
+`demo/index.html` には全公開状態、ポインター追従、ゼリー風ドラッグ、waiting ライフサイクル、頭部丸み調整、色・挙動設定、Agent 会話シミュレーションが含まれます。Demo 専用 JavaScript は `demo/` に分離され、再利用用 npm runtime には含まれません。
+
+## プロジェクト構成
+
+```text
+agent-robot-avatar.js     公開コンポーネントのエントリ
+src/                      再利用可能な runtime / 表情モジュール
+demo/                     インタラクティブ Demo と専用スクリプト
+examples/                 最小統合サンプル
+assets/support/           支援 / 決済 QR アセット
+docs/                     多言語ドキュメント
+README.md                 英語メインドキュメント
+CHANGELOG.md              公開リリース履歴
+CONTRIBUTING.md           コントリビューションガイド
+package.json              パッケージ情報
+LICENSE                   MIT License
+```
+
+## 配布と互換性
+
+パッケージは `agent-robot-avatar` として npm に公開され、アクション、イベント、公開メソッドの TypeScript 型定義を含みます。ES Modules、Custom Elements、SVG、Pointer Events、Web Animations API をサポートするモダンブラウザーを対象とします。
+
+## コントリビューション
+
+Issue と Pull Request を歓迎します。提出前に [`CONTRIBUTING.md`](../CONTRIBUTING.md) を確認してください。
+
+## プロジェクトの状態
+
+v0.1.0 は最初の公開リリースラインです。将来の `1.0.0` に向けて慎重に進化できるよう、公開 API は意図的に小さく保っています。
+
+Agent Robot Avatar は独立して開発されたオープンソースプロジェクトであり、特定の AI プラットフォームやブランドとは提携・公式承認関係にありません。
+
+## License
+
+MIT License。詳細は [`LICENSE`](../LICENSE) を参照してください。
+
+## コーヒーで支援
+
+このプロジェクトが役立った場合は、使いやすい方法で支援できます。
+
+| Ko-fi | Alipay | WeChat Pay |
+| --- | --- | --- |
+| <a href='https://ko-fi.com/P0E625WIOI' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> | <img src="../assets/support/alipay.png" alt="Alipay QR code" width="160"> | <img src="../assets/support/wechat-pay.png" alt="WeChat Pay QR code" width="160"> |