agent-robot-avatar 0.3.2 → 0.6.0

package/docs/README.pt.md

@@ -1,225 +1,185 @@
-# 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)
-
-![Versão](https://img.shields.io/badge/version-v0.3.2-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)
-
-Um Web Component leve e expressivo de avatar robótico para agentes de IA e outras aplicações interativas.
-
-É adequado para interfaces de assistentes e agentes de IA, incluindo produtos e experiências semelhantes a ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI e OpenCode.
-
-Também pode ser usado em desktop pets, pets virtuais, companheiros de desktop, mascotes digitais, avatares de chatbot e outras experiências com personagens interativos.
-
-Agent Robot Avatar também pode funcionar como uma camada de feedback visual para interfaces de agentes no estilo AG-UI.
-
-Agent Robot Avatar é construído com SVG e JavaScript puro, sem dependência de frameworks de animação de terceiros. Funciona como um Custom Element nativo e oferece uma API compacta para expressões, estados de interação, seguimento do ponteiro, feedback de espera e formato da cabeça.
-
-**Versão pública atual: v0.3.2**
-
-<p align="center">
-  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Demonstração animada interativa do Agent Robot Avatar" width="560">
-</p>
-
-## Demo ao vivo
-
-Experimente a demo interativa: [Abrir Agent Robot Avatar](https://cx-artlab.github.io/agent-robot-avatar/?lang=pt)
-
-## Principais recursos
-
-- SVG + JavaScript puro
-- Web Component nativo
-- Sem dependências de frameworks de animação
-- Piscar automático e movimento sutil do olhar
-- Seguimento do ponteiro e movimento da cabeça com inércia
-- Deformação local tipo gelatina ao arrastar e retorno elástico
-- Estados e expressões de Agent controláveis por código
-- Semântica separada para espera, falha, aviso, inspeção, bloqueio e erro de sistema
-- Arredondamento da cabeça ajustável
-- Antena flutuante com indicação piscante opcional
-- Demo separado do componente reutilizável
-
-## Início rápido
-
-Ao usar diretamente o código do repositório, mantenha `agent-robot-avatar.js` junto com `src/` e carregue a entrada pública:
-
-```html
-<script type="module" src="./agent-robot-avatar.js"></script>
-```
-
-```html
-<agent-robot-avatar id="avatar"></agent-robot-avatar>
-```
-
-O avatar entra automaticamente no estado idle. Um exemplo mínimo está em [`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('blocked');
-avatar.play('error');
-
-avatar.reset();
-```
-
-## Estados e expressões
-
-| Estado | API | Uso |
-| --- | --- | --- |
-| Idle | `idle` | Estado normal de espera |
-| Bored | `bored` | Longos períodos sem tarefa ativa |
-| Waiting | `waiting` | Solicitação enviada, aguardando resultado |
-| Input | `input` | Usuário digitando |
-| Send | `send` | Envio / feedback de aceno |
-| Success | `success` | Tarefa concluída com sucesso |
-| Failure | `failure` | Tarefa concluída sem sucesso |
-| Warning | `warning` | Ação arriscada ou destrutiva exige confirmação |
-| Inspect | `inspect` | Revisar, conferir ou verificar um resultado |
-| Blocked | `blocked` | Solicitação bloqueada ou impossibilitada de continuar |
-| System error | `error` | Falha de conexão, serviço ou sistema |
-| Surprise | `surprise` | Evento ou resultado inesperado |
-| Sleep | `sleep` | Entrar em repouso |
-| Wake | `wake` | Sair do repouso |
-
-`failure` representa falha da própria tarefa; `error` é reservado para problemas de conexão, serviço ou sistema. `waiting` indica uma solicitação pendente e `bored` representa inatividade.
-
-Aliases semânticos também estão disponíveis:
-
-```js
-avatar.play('failed');
-avatar.play('fail');
-avatar.play('verify');
-avatar.play('review');
-avatar.play('angry'); // mesma expressão visual de blocked
-avatar.play('policy-blocked');
-avatar.play('system-error');
-avatar.play('connection-error');
-```
-
-## Espera contínua
-
-```js
-avatar.startWaiting();
-// Pare quando a resposta ou resultado chegar.
-avatar.stopWaiting();
-```
-
-Qualquer outra ação também interrompe o estado waiting ativo.
-
-## Seguimento do ponteiro
-
-```js
-avatar.setPointerFollow(false);
-avatar.setPointerFollow(true);
-```
-
-## Arredondamento da cabeça
-
-```js
-avatar.setHeadRoundness(0);   // mais quadrada
-avatar.setHeadRoundness(50);  // padrão
-avatar.setHeadRoundness(100); // mais arredondada
-
-console.log(avatar.getHeadRoundness());
-```
-
-Os valores são limitados a `0–100`. Alterações emitem `head-roundness-change`.
-
-```js
-avatar.addEventListener('head-roundness-change', (event) => {
-  console.log(event.detail.value);
-});
-```
-
-## Evento de estado
-
-Cada mudança 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 | Descrição |
-| --- | --- |
-| `size` | Tamanho do componente em pixels |
-| `color` | Cor principal do avatar |
-| `auto-sleep` | Tempo de inatividade antes de dormir, em ms; `0` desativa |
-
-## Comportamento padrão
-
-Sem chamadas explícitas à API, o avatar já oferece piscadas aleatórias, movimento sutil do olhar, seguimento do ponteiro próximo, movimento inercial da cabeça, retorno natural a idle e suspensão automática opcional.
-
-## Interação por arraste
-
-Ao arrastar, a cabeça se deforma localmente ao redor do ponto de interação, em vez de se mover como um corpo rígido.
-
-- Puxão forte para fora: ativa `angry` após retornar
-- Empurrão forte para o centro: ativa `success` após retornar
-- Arraste pequeno: apenas deformação
-
-Essas expressões de arraste só se aplicam em idle quando nenhuma ação programática controla o avatar. Durante `waiting`, `input`, `inspect` e outras ações ativas, a deformação é preservada, mas a expressão de arraste é suprimida e não é reproduzida depois. `pointercancel` restaura apenas a forma, sem acionar success ou angry.
-
-## Demo interativo
-
-`demo/index.html` inclui todos os estados públicos, seguimento do ponteiro, arraste tipo gelatina, ciclo de waiting, ajuste do arredondamento, controles de cor e comportamento e simulação de conversa com Agent. O JavaScript exclusivo do Demo fica isolado em `demo/` e não faz parte do runtime reutilizável do npm.
-
-## Estrutura do projeto
-
-```text
-agent-robot-avatar.js     Entrada pública do componente
-src/                      Runtime reutilizável e módulos de expressão
-demo/                     Demo interativo e scripts exclusivos
-examples/                 Exemplos mínimos de integração
-assets/support/           Recursos QR de apoio / pagamento
-docs/                     Documentação multilíngue
-README.md                 Documento principal em inglês
-CHANGELOG.md              Histórico público de versões
-CONTRIBUTING.md           Guia de contribuição
-package.json              Metadados do pacote
-LICENSE                   Licença MIT
-```
-
-## Distribuição e compatibilidade
-
-O pacote está publicado no npm como `agent-robot-avatar` e inclui declarações TypeScript para ações, eventos e métodos públicos. Destina-se a navegadores modernos com suporte a ES Modules, Custom Elements, SVG, Pointer Events e Web Animations API.
-
-## Contribuição
-
-Issues e Pull Requests são bem-vindos. Leia [`CONTRIBUTING.md`](../CONTRIBUTING.md) antes de enviar alterações.
-
-## Status do projeto
-
-v0.3.2 é a versão pública atual. v0.1.0 continua disponível como a primeira versão pública. A API pública é mantida deliberadamente pequena para evoluir com cuidado antes de um futuro compromisso de estabilidade `1.0.0`.
-
-Agent Robot Avatar é um projeto independente de código aberto e não é afiliado, endossado nem representa nenhuma plataforma ou marca de IA.
-
-## Licença
-
-MIT License. Consulte [`LICENSE`](../LICENSE).
-
-## Pague-me um café
-
-<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>
+# 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) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Русский](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ru.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.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) | [日本語](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) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md)
+
+![Version](https://img.shields.io/badge/version-v0.6.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)
+
+Um Web Component leve e expressivo de avatar robô para agentes de IA e aplicações interativas.
+
+Pode ser usado em assistentes de IA, interfaces de agentes, companheiros de desktop, pets virtuais, mascotes digitais, avatares de chatbot e outras experiências com personagens interativos.
+
+É adequado para interfaces de assistentes de IA e agentes, incluindo produtos e experiências semelhantes ao ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI e OpenCode.
+
+Construído com SVG e JavaScript nativo, funciona como um Custom Element e não possui dependências em tempo de execução.
+
+O Agent Robot Avatar também pode ser usado como camada de feedback visual para interfaces de agentes no estilo AG-UI.
+
+<p align="center">
+  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Demonstração animada interativa do Agent Robot Avatar" width="560">
+</p>
+
+## Demo ao vivo
+
+[Abrir a demo interativa](https://cx-artlab.github.io/agent-robot-avatar/?lang=pt)
+
+## Destaques
+
+- Web Component nativo
+- Renderização SVG + JavaScript nativo
+- Zero dependências em tempo de execução
+- Piscar automático e comportamento idle sutil
+- Olhos que seguem o ponteiro e movimento inercial da cabeça
+- Deformação local tipo gelatina ao arrastar, com recuperação elástica
+- Compressão ao manter pressionado e antena elástica arrastável
+- Estados e expressões do Agent controláveis por código
+- Feedback para waiting, success, failure, warning, review, blocked e system error
+- Suporte a movimento reduzido
+- Comportamento de sono configurável
+- Arredondamento da cabeça ajustável
+- Pisca de status opcional na antena
+- Declarações TypeScript incluídas
+
+## Instalação
+
+```bash
+npm install agent-robot-avatar
+```
+
+```js
+import 'agent-robot-avatar';
+```
+
+Também é possível carregar diretamente o código-fonte do repositório:
+
+```html
+<script type="module" src="./agent-robot-avatar.js"></script>
+```
+
+Depois, adicione o componente:
+
+```html
+<agent-robot-avatar id="avatar"></agent-robot-avatar>
+```
+
+Nenhum código de inicialização é necessário. O avatar entra automaticamente no estado idle padrão.
+
+## Uso básico
+
+```js
+const avatar = document.querySelector('#avatar');
+
+avatar.play('success');
+avatar.play('wary');
+avatar.play('refuse');
+
+avatar.reset();
+```
+
+Ações disponíveis:
+
+`idle` · `bored` · `waiting-spin` · `waiting-wrap` · `waiting-wave` · `input` · `affirm` · `success` · `failure` · `wary` · `inspect` · `angry` · `refuse` · `surprise` · `love` · `random` · `sleep` · `wake`
+
+Os nomes das ações descrevem o que o avatar faz. `refuse` balança a cabeça, para um pedido que o Agent não pode ou não vai realizar; `failure` é para uma tarefa ou conexão que não deu certo; `wary` vira a cabeça e olha de cima a baixo com desconfiança, para uma ação que exige confirmação. Os nomes da 0.5 (`send`, `warning`, `error`, `blocked` e outros) continuam funcionando com um aviso no console até a 1.0; veja a [tabela de atualização](../CHANGELOG.md#upgrading-from-05x).
+
+`love` expressa carinho ou gratidão: os dois olhos se inclinam até formar um único coração, batem três vezes e depois voltam ao normal.
+
+`random` reproduz um giro de caça-níqueis: cada olho rola sobre um tambor; depois o olho esquerdo desacelera, quica e para, seguido do direito. `slot` é um alias.
+
+Um fluxo típico de solicitação de Agent:
+
+```js
+avatar.startWaiting();
+
+// Segunda espera: os olhos saem por um lado e voltam pelo outro.
+avatar.startWaiting({ variant: 'wrap' });
+
+try {
+  const result = await runAgentRequest();
+  await avatar.play(result.ok ? 'success' : 'failure');
+} catch (error) {
+  await avatar.play('failure');
+}
+```
+
+## Opções comuns
+
+```html
+<agent-robot-avatar
+  size="160"
+  color="#08090b"
+  auto-sleep="30000"
+  wake-on="activity"
+  motion="auto">
+</agent-robot-avatar>
+```
+
+| Atributo | Uso |
+| --- | --- |
+| `size` | Tamanho do avatar em pixels |
+| `color` | Cor principal do avatar |
+| `auto-sleep` | Tempo de inatividade antes do sono automático; `0` desativa |
+| `wake-on` | Política de despertar automático: `activity`, `interaction` ou `manual` |
+| `motion` | Política de movimento: `auto`, `reduce` ou `full` |
+| `press-squeeze` | Pressione o centro para comprimir; `false` desativa |
+| `antenna-drag` | Arraste e retorno elástico da antena com reação de raiva; `false` desativa |
+
+Controles comuns em tempo de execução:
+
+```js
+avatar.setPointerFollow(false);
+avatar.setHeadRoundness(75);
+avatar.setPressSqueeze(true);
+avatar.setAntennaDrag(true);
+```
+
+Manter o centro pressionado inicia a compressão. Ao mover mais de 4 pixels CSS, o mesmo gesto passa ao arraste de cabeça existente. A antena usa o mesmo limite de distância e termina com a reação de raiva existente.
+
+## Eventos e integração
+
+O componente emite `face-state` para mudanças de estado visual e `action-state` para mudanças semânticas no ciclo de vida das ações.
+
+Para integrações com a aplicação host e textos de status acessíveis, prefira `action-state`. Veja [`examples/accessibility.html`](../examples/accessibility.html) para um exemplo executável do ciclo de vida de uma solicitação.
+
+Um exemplo mínimo de integração está disponível em [`examples/basic.html`](../examples/basic.html).
+
+## Compatibilidade
+
+Projetado para navegadores modernos com suporte a ES Modules, Custom Elements, SVG, Pointer Events, Web Animations API, `IntersectionObserver`, `ResizeObserver` e `matchMedia`.
+
+Os testes automatizados cobrem Chromium, Firefox e WebKit.
+
+## Contribuindo
+
+Issues e Pull Requests são bem-vindos. Consulte [`CONTRIBUTING.md`](../CONTRIBUTING.md) antes de enviar alterações.
+
+## Status do projeto
+
+**Versão pública atual: v0.6.0**
+
+A API pública é mantida deliberadamente compacta enquanto o projeto evolui em direção a um futuro compromisso de estabilidade `1.0.0`.
+
+Agent Robot Avatar é desenvolvido de forma independente e não é afiliado, endossado nem representa qualquer plataforma ou marca de IA.
+
+## Design do personagem e identidade visual
+
+O personagem Agent Robot Avatar, incluindo sua aparência robótica e identidade visual, é um design original da CX ArtLab.
+
+A licença MIT se aplica ao software e ao código-fonte. Ela permite usar, modificar e distribuir o avatar como parte de aplicações, mas não transfere a propriedade do nome Agent Robot Avatar, da identidade do personagem ou de sua identidade visual, nem concede o direito de apresentá-los como personagem original ou marca independente de outra parte.
+
+Os nomes de produtos de terceiros mencionados neste projeto servem apenas para descrever possíveis casos de uso e não indicam afiliação ou endosso.
+
+## Licença
+
+MIT License. Consulte [`LICENSE`](../LICENSE).
+
+---
+
+Se este projeto for útil para você, você pode me pagar um café.
+
+<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>

package/docs/README.ru.md

@@ -0,0 +1,185 @@
+# 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) | [Español](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.es.md) | [Русский](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.ru.md) | [Français](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.fr.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) | [日本語](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) | [繁體中文](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/docs/README.zh-TW.md)
+
+![Version](https://img.shields.io/badge/version-v0.6.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)
+
+Лёгкий и выразительный Web Component с роботом-аватаром для AI-агентов и интерактивных приложений.
+
+Его можно использовать в AI-ассистентах, интерфейсах агентов, настольных компаньонах, виртуальных питомцах, цифровых маскотах, аватарах чат-ботов и других интерактивных персонажах.
+
+Подходит для интерфейсов AI-ассистентов и агентов, включая продукты и сценарии, похожие на ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI и OpenCode.
+
+Компонент построен на SVG и vanilla JavaScript, работает как нативный Custom Element и не имеет runtime-зависимостей.
+
+Agent Robot Avatar также можно использовать как слой визуальной обратной связи для интерфейсов агентов в стиле AG-UI.
+
+<p align="center">
+  <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Интерактивная анимационная демонстрация Agent Robot Avatar" width="560">
+</p>
+
+## Демонстрация в реальном времени
+
+[Открыть интерактивную демонстрацию](https://cx-artlab.github.io/agent-robot-avatar/?lang=ru)
+
+## Основные возможности
+
+- Нативный Web Component
+- SVG-рендеринг + vanilla JavaScript
+- Ноль runtime-зависимостей
+- Автоматическое моргание и лёгкое idle-поведение
+- Следование глазами за указателем и инерционное движение головы
+- Локальная jelly-деформация при перетаскивании с упругим возвратом
+- Сжатие при удержании и перетаскиваемая пружинящая антенна
+- Программное управление состояниями и выражениями Agent
+- Обратная связь для waiting, success, failure, warning, review, blocked и system error
+- Поддержка reduced motion
+- Настраиваемое поведение сна
+- Регулируемое скругление головы
+- Опциональное мигание антенны для статуса
+- TypeScript-декларации включены
+
+## Установка
+
+```bash
+npm install agent-robot-avatar
+```
+
+```js
+import 'agent-robot-avatar';
+```
+
+Также можно напрямую загрузить исходный код из репозитория:
+
+```html
+<script type="module" src="./agent-robot-avatar.js"></script>
+```
+
+Затем добавьте компонент:
+
+```html
+<agent-robot-avatar id="avatar"></agent-robot-avatar>
+```
+
+Инициализация не требуется. Аватар автоматически переходит в стандартное состояние idle.
+
+## Базовое использование
+
+```js
+const avatar = document.querySelector('#avatar');
+
+avatar.play('success');
+avatar.play('wary');
+avatar.play('refuse');
+
+avatar.reset();
+```
+
+Доступные действия:
+
+`idle` · `bored` · `waiting-spin` · `waiting-wrap` · `waiting-wave` · `input` · `affirm` · `success` · `failure` · `wary` · `inspect` · `angry` · `refuse` · `surprise` · `love` · `random` · `sleep` · `wake`
+
+Названия действий описывают, что делает аватар. `refuse` качает головой — для запроса, который Agent не может или не будет выполнять; `failure` — для задачи или соединения, которые не удались; `wary` поворачивает голову и настороженно оглядывает сверху вниз — для действия, требующего подтверждения. Названия из 0.5 (`send`, `warning`, `error`, `blocked` и другие) работают до 1.0 с уведомлением в консоли; см. [таблицу обновления](../CHANGELOG.md#upgrading-from-05x).
+
+`love` выражает симпатию или благодарность: два глаза наклоняются друг к другу и образуют одно сердце, трижды бьются и возвращаются в исходное состояние.
+
+`random` проигрывает вращение игрового автомата: каждый глаз катится по барабану, затем левый глаз замедляется, подпрыгивает и останавливается, следом правый. `slot` — псевдоним.
+
+Типичный жизненный цикл запроса Agent:
+
+```js
+avatar.startWaiting();
+
+// Второй вариант ожидания: глаза уходят с одной стороны и возвращаются с другой.
+avatar.startWaiting({ variant: 'wrap' });
+
+try {
+  const result = await runAgentRequest();
+  await avatar.play(result.ok ? 'success' : 'failure');
+} catch (error) {
+  await avatar.play('failure');
+}
+```
+
+## Часто используемые параметры
+
+```html
+<agent-robot-avatar
+  size="160"
+  color="#08090b"
+  auto-sleep="30000"
+  wake-on="activity"
+  motion="auto">
+</agent-robot-avatar>
+```
+
+| Атрибут | Назначение |
+| --- | --- |
+| `size` | Размер аватара в пикселях |
+| `color` | Основной цвет аватара |
+| `auto-sleep` | Время бездействия до автоматического сна; `0` отключает его |
+| `wake-on` | Политика автоматического пробуждения: `activity`, `interaction` или `manual` |
+| `motion` | Политика движения: `auto`, `reduce` или `full` |
+| `press-squeeze` | Удержание центра для сжатия; `false` отключает жест |
+| `antenna-drag` | Перетаскивание и пружинящий возврат антенны с сердитой реакцией; `false` отключает жест |
+
+Часто используемые runtime-настройки:
+
+```js
+avatar.setPointerFollow(false);
+avatar.setHeadRoundness(75);
+avatar.setPressSqueeze(true);
+avatar.setAntennaDrag(true);
+```
+
+Удержание центра запускает сжатие. После перемещения более чем на 4 CSS-пикселя тот же жест переходит в существующее перетаскивание головы. Для антенны действует тот же предел расстояния, а после возврата запускается существующая сердитая реакция.
+
+## События и интеграция
+
+Компонент отправляет `face-state` при изменениях визуального состояния и `action-state` при семантических изменениях жизненного цикла действий.
+
+Для интеграции с host-приложением и доступного статусного текста предпочтительнее `action-state`. Рабочий пример жизненного цикла запроса находится в [`examples/accessibility.html`](../examples/accessibility.html).
+
+Минимальный пример интеграции доступен в [`examples/basic.html`](../examples/basic.html).
+
+## Совместимость
+
+Рассчитан на современные браузеры с поддержкой ES Modules, Custom Elements, SVG, Pointer Events, Web Animations API, `IntersectionObserver`, `ResizeObserver` и `matchMedia`.
+
+Автоматизированные тесты покрывают Chromium, Firefox и WebKit.
+
+## Участие в разработке
+
+Issues и Pull Requests приветствуются. Перед отправкой изменений прочитайте [`CONTRIBUTING.md`](../CONTRIBUTING.md).
+
+## Статус проекта
+
+**Текущая публичная версия: v0.6.0**
+
+Публичный API намеренно остаётся компактным, пока проект развивается к будущему обязательству стабильности `1.0.0`.
+
+Agent Robot Avatar разрабатывается независимо и не аффилирован, не одобрен и не представляет какую-либо AI-платформу или бренд.
+
+## Дизайн персонажа и визуальная идентичность
+
+Персонаж Agent Robot Avatar, включая внешний вид робота и визуальную идентичность, является оригинальной разработкой CX ArtLab.
+
+MIT License применяется к программному обеспечению и исходному коду. Она разрешает использовать, изменять и распространять аватар как часть приложений, но не передаёт права собственности на название Agent Robot Avatar, идентичность персонажа или визуальную идентичность и не даёт права представлять их как оригинального персонажа или самостоятельный бренд другой стороны.
+
+Названия сторонних продуктов, упомянутые в проекте, используются только для описания возможных сценариев применения и не означают аффилированность или одобрение.
+
+## Лицензия
+
+MIT License. См. [`LICENSE`](../LICENSE).
+
+---
+
+Если этот проект оказался полезен, вы можете угостить меня кофе.
+
+<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>