agent-robot-avatar 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,43 @@ The project follows Semantic Versioning for public releases. Internal developmen
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-10
+
+### Added
+
+- Added `wake-on="activity|interaction|manual"` to control automatic wake behavior while preserving `activity` as the default.
+- Added `motion="auto|reduce|full"`; `auto` follows `prefers-reduced-motion` and updates when the system preference changes.
+- Added the semantic `action-state` event with `{ action, phase, source }` lifecycle data for host integrations and accessible status messaging.
+- Added explicit `px` support for `size`, alongside existing numeric pixel values.
+- Added Chromium, Firefox, and WebKit browser validation, including trusted Chromium touch-cancellation coverage.
+
+### Changed
+
+- Unified program-action and drag cancellation so reset, replacement actions, disconnect, and pointer cancellation cannot leave delayed drag reactions behind.
+- Program-controlled actions such as waiting and input now keep ownership of their expression while drag deformation remains available; suppressed drag reactions are discarded rather than replayed.
+- Invalid/no-op actions are validated before destructive extension cleanup, so an invalid `wake` or unknown action cannot tear down a running action.
+- Touch interaction uses `touch-action: pinch-zoom` on the avatar interaction region so single-pointer dragging remains available while page scrolling outside the avatar is unaffected and two-finger zoom remains possible.
+- Reduced-motion mode removes continuous decorative motion while preserving distinct static states and semantic action lifecycles.
+- Avatars pause sustained frame rendering when hidden, without layout, or outside the viewport, then resume the current state when visible again.
+- High-frequency pointer updates are coalesced to the latest update per animation frame.
+- Shared the head-flattening geometry used by the antenna and roundness modules.
+
+### Fixed
+
+- Preserved valid `window.AgentRobotAvatarInspectConfig` values supplied before module loading and normalized missing, invalid, and out-of-range values deterministically.
+- Distinguished `pointercancel` from a normal release so cancelled touch gestures recover without success/angry feedback.
+- Tightened `size` parsing so unsupported units, malformed values, zero, negative, and non-finite input use the default size instead of being partially parsed as pixels.
+
+## [0.2.1] - 2026-09-05
+
+### Fixed
+
+- Fixed dynamic custom-element creation failing because the constructor added a host style attribute; preserved default and explicit sizing.
+- Prevented interrupted expression continuations and animation callbacks from overriding resets or newer actions.
+- Fixed automatic sleep repeatedly restarting its own preparation instead of reaching sleep.
+- Synchronized dynamic head colors with the eye masks and antenna, including while sleep rendering is paused.
+- Cancelled pending timers, animations, waiting, and drag feedback on disconnect; reattached avatars start idle with their settings preserved.
+
 ## [0.2.0] - 2026-09-04
 
 First stable release of the backward-compatible 0.2 series.
@@ -56,5 +93,7 @@ First public release.
 - npm-compatible package metadata for later package publication
 - Contribution guide, issue templates, pull request template, MIT License, and Ko-fi funding metadata
 
+[0.3.0]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.3.0
+[0.2.1]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.2.1
 [0.2.0]: https://github.com/CX-ARTLab/agent-robot-avatar/releases/tag/v0.2.0
 [0.1.0]: https://github.com/CX-ARTLab/agent-robot-avatar/releases/tag/v0.1.0

package/README.md

@@ -6,20 +6,30 @@
 
 [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)
+![Version](https://img.shields.io/badge/version-v0.3.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)
 
 A lightweight, expressive robot avatar Web Component for AI agents and other interactive applications.
 
+Suitable for AI assistant and agent interfaces, including products and experiences similar to ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI, and OpenCode.
+
+It can also be used for desktop pets, virtual pets, desktop companions, digital mascots, chatbot avatars, and other interactive character experiences.
+
+Agent Robot Avatar can also be used as a visual feedback layer for AG-UI-style agent interfaces.
+
 Agent Robot Avatar is built with SVG and vanilla JavaScript. It has no third-party animation framework dependency, works as a native custom element, and exposes a compact API for expressions, interaction states, pointer behavior, waiting feedback, and head-shape customization.
 
-**Current public version: v0.2.0**
+**Current public version: v0.3.0**
 
 <p align="center">
   <img src="./assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar interactive animation demo" width="560">
 </p>
 
+## Live Demo
+
+Try the interactive demo: [Open Agent Robot Avatar](https://cx-artlab.github.io/agent-robot-avatar/?lang=en)
+
 ## Highlights
 
 - Pure SVG + vanilla JavaScript
@@ -30,6 +40,9 @@ Agent Robot Avatar is built with SVG and vanilla JavaScript. It has no third-par
 - Jelly-style local drag deformation with elastic recovery
 - Programmatically controlled Agent states and expressions
 - Distinct waiting, failure, warning, review, blocked-content, and system-error semantics
+- Semantic `action-state` lifecycle events for host integrations
+- Reduced-motion support and visibility-aware frame pausing
+- Configurable sleep wake policy
 - Adjustable head roundness
 - Floating antenna with optional status flashing
 - Demo UI kept separate from the reusable component
@@ -50,7 +63,7 @@ Add the custom element:
 
 The avatar enters its default idle behavior automatically. No initialization code is required.
 
-A minimal runnable example is available at [`examples/basic.html`](./examples/basic.html).
+A minimal runnable example is available at [`examples/basic.html`](./examples/basic.html). An accessibility-oriented integration example is available at [`examples/accessibility.html`](./examples/accessibility.html).
 
 Bundler-based projects can install and use the component from npm with:
 
@@ -75,7 +88,7 @@ avatar.play('success');
 avatar.play('failure');
 avatar.play('warning');
 avatar.play('inspect');
-avatar.play('angry');
+avatar.play('blocked');
 avatar.play('error');
 ```
 
@@ -85,6 +98,10 @@ Return to the default idle state:
 avatar.reset();
 ```
 
+`reset()` cancels the current program action, pending waits, head animations, drag/rebound state, and delayed drag reactions, then returns to idle. Cancelled animation promises continue to resolve normally rather than rejecting. Removing the element performs the same internal cleanup without emitting cleanup-only `face-state` or `action-state` notifications. Reattaching starts from idle and preserves appearance and behavior attributes/settings.
+
+A valid new action replaces the previous active action. The old semantic action receives `cancel`; it cannot resume later and overwrite the replacement. An unknown action throws before destructive cleanup. A no-op action such as `wake` while already awake leaves the current action unchanged.
+
 ## Actions and states
 
 | State | API name | Intended use |
@@ -98,13 +115,13 @@ avatar.reset();
 | Failure | `failure` | A task completed unsuccessfully |
 | Warning | `warning` | A risky or destructive action needs confirmation |
 | Inspect | `inspect` | Reviewing, checking, or verifying a result |
-| Blocked | `angry` | A request is blocked, disallowed, or cannot proceed |
+| Blocked | `blocked` | A request is blocked, disallowed, or cannot proceed |
 | System error | `error` | Connection, service, or system failure |
 | Surprise | `surprise` | An unexpected event or result |
-| Sleep | `sleep` | Enter the sleep state |
-| Wake | `wake` | Wake from sleep |
+| Sleep | `sleep` | Enter the component sleep state |
+| Wake | `wake` | Wake the component from sleep |
 
-The state names intentionally distinguish task results from system conditions. For example, `failure` means the requested task finished unsuccessfully, while `error` is reserved for connection, service, or system failures. `waiting` represents an active pending request; `bored` represents inactivity.
+The state names intentionally distinguish task results from system conditions. For example, `failure` means the requested task finished unsuccessfully, while `error` is reserved for connection, service, or system failures. `waiting` represents an active pending request; `bored` represents inactivity. `sleep` describes the avatar component state only and does not imply that the real Agent is offline.
 
 Semantic aliases are also available:
 
@@ -113,8 +130,8 @@ avatar.play('failed');           // same as failure
 avatar.play('fail');             // same as failure
 avatar.play('verify');           // same as inspect
 avatar.play('review');           // same as inspect
-avatar.play('blocked');          // same as angry
-avatar.play('policy-blocked');   // same as angry
+avatar.play('angry');            // same visual expression as blocked
+avatar.play('policy-blocked');   // same as blocked
 avatar.play('system-error');     // same as error
 avatar.play('connection-error'); // same as error
 ```
@@ -126,11 +143,114 @@ For real Agent workflows, use the dedicated waiting lifecycle when a request is
 ```js
 avatar.startWaiting();
 
-// Stop when a response or result arrives.
+// Stop when the request ends without replacing it with another action.
 avatar.stopWaiting();
 ```
 
-Calling another action also interrupts the active waiting state.
+`startWaiting()` remains active until `stopWaiting()`, `reset()`, or another program action replaces it. A replacement reports `cancel`; `stopWaiting()` reports a normal `end`. Drag deformation remains available while waiting, but decorative drag expressions are suppressed and discarded rather than replayed after waiting ends.
+
+A typical request lifecycle can be written as:
+
+```js
+avatar.startWaiting();
+try {
+  const result = await runAgentRequest();
+  await avatar.play(result.ok ? 'success' : 'failure');
+} catch (error) {
+  await avatar.play('error');
+}
+```
+
+The visual `error` action eventually returns to idle. That visual completion does not mean the underlying request, connection, or business error has been resolved; the host application remains the source of truth.
+
+## Semantic action event
+
+`face-state` remains available for backward compatibility and describes visual face states. It may contain visual terms such as `happy` or `sad`, so it should not be treated as a reliable business-result event.
+
+For semantic integration, listen to `action-state`:
+
+```js
+avatar.addEventListener('action-state', (event) => {
+  const { action, phase, source } = event.detail;
+  console.log(action, phase, source);
+});
+```
+
+`action-state` uses this contract:
+
+- `action`: normalized action name. Aliases such as `failed`/`fail` become `failure`; `verify`/`review` become `inspect`.
+- `phase`: `start`, followed by exactly one `end` or `cancel` for each action that actually starts.
+- `source`: `api`, `interaction`, or `automatic`.
+- Continuous actions such as `startWaiting()` and active input do not emit `end` just because one animation cycle completes.
+- Replacement or `reset()` emits `cancel`; `stopWaiting()` emits `end` for waiting.
+- No-op calls emit no lifecycle event.
+- Decorative drag feedback uses `action: "reaction"` and `source: "interaction"`, so it cannot be confused with an API-level task success/failure.
+- The event bubbles and is `composed`, so it can be observed above the custom element/Shadow DOM boundary.
+- Disconnect cleanup is silent and does not manufacture host-facing status notifications.
+
+The event describes avatar actions, not real request outcomes. The host must decide what the underlying Agent state actually means.
+
+## Accessibility integration
+
+For accessible status text, map program actions to localized host text rather than announcing every visual change:
+
+```html
+<div id="agent-status" role="status" aria-live="polite"></div>
+```
+
+```js
+const status = document.querySelector('#agent-status');
+const messages = {
+  waiting: 'Processing…',
+  failure: 'Task failed.',
+  error: 'Connection problem.',
+};
+
+avatar.addEventListener('action-state', ({ detail }) => {
+  if (detail.source === 'interaction') return;
+  if (detail.phase === 'start' && messages[detail.action]) {
+    status.textContent = messages[detail.action];
+  }
+});
+```
+
+Use a normal `role="status"` for routine updates. Do not announce blinking, gaze changes, or decorative drag reactions, and do not automatically make every error an interruptive alert. If the host already announces the same status elsewhere, the avatar can remain decorative to avoid duplicate screen-reader output.
+
+See [`examples/accessibility.html`](./examples/accessibility.html) for a runnable example.
+
+## Wake policy
+
+The `wake-on` attribute controls automatic wake behavior:
+
+```html
+<agent-robot-avatar wake-on="manual"></agent-robot-avatar>
+```
+
+| Value | Behavior |
+| --- | --- |
+| `activity` | Default. Page pointer/keyboard activity can wake a sleeping avatar, preserving previous behavior. |
+| `interaction` | Only direct interaction with this avatar wakes it automatically. Activity elsewhere does not. |
+| `manual` | Environment activity, including direct avatar interaction, does not automatically wake it. |
+
+Explicit API intent remains explicit: `avatar.play('wake')` wakes the avatar in every mode, and `avatar.noteActivity()` keeps its existing behavior of recording activity and waking by default. Pass `false` to `noteActivity(false)` to record activity without waking. Other program actions may leave sleep when their action semantics require a new visible state. `reset()` always returns to idle.
+
+Different avatar instances may use different `wake-on` values.
+
+## Reduced motion
+
+Use the `motion` attribute to control animation intensity:
+
+```html
+<agent-robot-avatar motion="auto"></agent-robot-avatar>
+```
+
+| Value | Behavior |
+| --- | --- |
+| `auto` | Default. Follows `prefers-reduced-motion` and responds to preference changes at runtime. |
+| `reduce` | Keeps recognizable static states while suppressing continuous or elastic decorative motion. |
+| `full` | Uses the normal animation style regardless of the system reduced-motion preference. |
+
+Reduced mode suppresses continuous waiting orbits, idle wandering/blinking motion, head-follow inertia, elastic rebound, antenna spring motion, and status flashing where appropriate. Waiting/input lifecycles remain active until the host ends or replaces them, even when their visual state is static. Switching modes does not revive cancelled work or change `action-state` lifecycle semantics.
 
 ## Pointer following
 
@@ -141,6 +261,8 @@ avatar.setPointerFollow(false);
 avatar.setPointerFollow(true);
 ```
 
+High-frequency pointer positions are coalesced to the latest update per animation frame. Pointer following remains active in normal mode when the avatar is not being dragged or owned by another expression.
+
 ## Antenna flashing
 
 Antenna status flashing is disabled by default and can be enabled per avatar:
@@ -150,6 +272,24 @@ avatar.setAntennaFlash(true);
 avatar.setAntennaFlash(false);
 ```
 
+## Inspect configuration
+
+Inspect/review timing and geometry can be customized before loading the component:
+
+```html
+<script>
+  window.AgentRobotAvatarInspectConfig = {
+    aperture: 24,
+    scanOffset: 12,
+  };
+</script>
+<script type="module" src="./agent-robot-avatar.js"></script>
+```
+
+The existing configuration object is preserved. Values are converted with `Number(...)`, must be finite, and are clamped to supported ranges; missing or invalid values receive defaults. `aperture` is clamped to `6–40`, `scanOffset` to `0–24`, and timing values to their supported `0/40–2400 ms` ranges. The same `window.AgentRobotAvatarInspectConfig` object can still be modified after loading; values are normalized again when an inspect action begins. Invalid input cannot enter the animation calculations as `NaN`.
+
+Default configuration keeps the existing v0.2.1 visual timing.
+
 ## Head roundness
 
 The head shape can be adjusted from a squarer form to a rounder form without changing the eye clipping or drag-deformation system:
@@ -172,9 +312,9 @@ avatar.addEventListener('head-roundness-change', (event) => {
 });
 ```
 
-## State event
+## Visual state event
 
-The component emits a `face-state` event whenever its visual state changes:
+The component continues to emit `face-state` whenever its visual state changes:
 
 ```js
 avatar.addEventListener('face-state', (event) => {
@@ -182,25 +322,29 @@ avatar.addEventListener('face-state', (event) => {
 });
 ```
 
-Host applications can use this event to synchronize interface state, logs, Agent workflows, or accessibility feedback.
+Use this event for visual synchronization or legacy integrations. Prefer `action-state` for business/Agent lifecycle logic and accessibility status text.
 
 ## Attributes
 
 ```html
 <agent-robot-avatar
-  size="160"
+  size="160px"
   color="#08090b"
-  auto-sleep="30000">
+  auto-sleep="30000"
+  wake-on="activity"
+  motion="auto">
 </agent-robot-avatar>
 ```
 
 | Attribute | Description |
 | --- | --- |
-| `size` | Component size in pixels |
-| `color` | Main avatar color |
-| `auto-sleep` | Idle time before automatic sleep, in milliseconds; `0` disables automatic sleep |
+| `size` | Positive pixel size. Accepts plain numbers such as `140` and explicit pixels such as `140px`. Unsupported units, malformed strings, zero, negative, and non-finite values fall back to `112px`. |
+| `color` | Main avatar color. |
+| `auto-sleep` | Idle time before automatic sleep, in milliseconds; `0` disables automatic sleep. |
+| `wake-on` | Automatic wake policy: `activity` (default), `interaction`, or `manual`. |
+| `motion` | Motion policy: `auto` (default), `reduce`, or `full`. |
 
-All attributes are optional.
+All attributes are optional. Dynamic size changes are supported; drag coordinates and pointer following use the element's current layout size.
 
 ## Default behavior
 
@@ -213,15 +357,25 @@ Without explicit API calls, the avatar already provides subtle ambient behavior:
 - Natural return to idle
 - Optional automatic sleep
 
+`motion="reduce"` or an active system reduced-motion preference simplifies these decorative behaviors.
+
 ## Drag interaction
 
-The avatar supports direct pointer dragging. The head deforms locally around the interaction point instead of moving as a rigid object.
+The avatar supports direct mouse, pen, and touch pointer dragging. The head deforms locally around the interaction point instead of moving as a rigid object.
 
-- Strong outward pull: triggers `angry` after recovery
-- Strong inward push toward the center: triggers `success` after recovery
+- Strong outward pull while idle: triggers an `angry` visual reaction after recovery
+- Strong inward push toward the center while idle: triggers a `success` visual reaction after recovery
 - Small drag: deformation only, with no expression trigger
+- Active program actions such as waiting/input keep expression ownership; drag deformation remains available but its decorative reaction is discarded
+- `pointercancel`, lost capture, reset, replacement actions, and disconnect restore drag geometry without delayed reaction
+
+The avatar interaction region uses `touch-action: pinch-zoom`: single-pointer movement remains available to the custom drag gesture, while two-pointer pinch zoom remains allowed. Page scrolling initiated outside the avatar keeps the page's normal touch behavior. Desktop mouse interaction is unchanged.
+
+## Rendering and visibility
 
-When released, the shape returns with an elastic rebound.
+The component pauses sustained frame rendering when it has no visible layout area or is outside the viewport. Parent-container hiding is covered through layout/intersection observation. When it becomes visible again, the avatar resumes the current valid state rather than replaying stale actions.
+
+Finite action timers continue to settle while visual drawing is paused, so action promises do not depend on continuous rendering. The existing hidden-page and settled-sleep pause behavior remains in place. Observers and per-instance media-query listeners are cleaned up when an avatar is disconnected.
 
 ## Interactive Demo
 
@@ -257,11 +411,13 @@ LICENSE                   MIT License
 
 The package is published on npm as `agent-robot-avatar`. It includes the public entry, TypeScript declarations, runtime modules, documentation, and support assets.
 
-The npm package intentionally includes only the public entry, TypeScript declarations, `src/` runtime, documentation, and support assets; Demo-only files are excluded.
+The npm package intentionally includes only the public entry, TypeScript declarations, `src/` runtime, documentation, and support assets; Demo-only files and test files are excluded.
 
 ## Compatibility
 
-Agent Robot Avatar is designed for modern browsers with support for ES modules, Custom Elements, SVG, Pointer Events, and the Web Animations API.
+Agent Robot Avatar is designed for modern browsers with support for ES modules, Custom Elements, SVG, Pointer Events, the Web Animations API, `IntersectionObserver`, `ResizeObserver`, and `matchMedia`.
+
+The automated browser suite covers Chromium, Firefox, and WebKit. Trusted touch-drag cancellation is additionally exercised through Chromium's touch emulation; see the PR/release validation notes for any real-device coverage.
 
 ## Contributing
 
@@ -269,18 +425,22 @@ Issues and pull requests are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md)
 
 ## Project status
 
-v0.1.0 is the first public release line. The public API is intentionally small so it can evolve carefully before a future `1.0.0` stability commitment.
+v0.3.0 is the current public release. v0.1.0 remains available as the first public version. The public API is intentionally small so it can evolve carefully before a future `1.0.0` stability commitment.
 
 Agent Robot Avatar is independently developed and is not affiliated with, endorsed by, or representative of any AI platform or brand.
 
+## Character design and visual identity
+
+The Agent Robot Avatar character, including its robot appearance and visual identity, is an original design by CX ArtLab.
+
+The MIT License applies to the software and source code. It permits use, modification, and distribution of the software, including use of the avatar within applications, but it does not transfer ownership of the Agent Robot Avatar name, character identity, or visual identity, and does not grant the right to present them as another party's original character, trademark, or standalone brand.
+
+References to third-party AI products describe possible use cases or product inspiration only and do not indicate affiliation, endorsement, or ownership of the character design.
+
 ## License
 
 MIT License. See [`LICENSE`](./LICENSE).
 
 ## Buy me a coffee
 
-If this project is useful to you, you can buy me a coffee. Use whichever option is most convenient:
-
-| 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"> |
+<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/agent-robot-avatar.js

@@ -6,11 +6,21 @@ import './src/agent-robot-avatar-antenna-flash.js';
 import './src/agent-robot-avatar-inspect.js';
 import './src/agent-robot-avatar-failure.js';
 import './src/agent-robot-avatar-head-roundness.js';
+import './src/agent-robot-avatar-runtime.js';
+import './src/agent-robot-avatar-runtime-fixes.js';
 import { VERSION } from './src/agent-robot-avatar-version.js';
 
+// Elements already present in markup can upgrade while the core module is
+// loading, before runtime extensions finish installing their prototype hooks.
+// Initialize those existing instances once the full public entry is ready so
+// runtime policies (including touch-action) are applied synchronously.
+if (typeof document !== 'undefined') {
+  document.querySelectorAll('agent-robot-avatar').forEach(avatar => avatar._resumeFrames?.());
+}
+
 if (typeof window !== 'undefined') {
   window.AgentRobotAvatarVersion = VERSION;
 }
 
 export { AgentRobotAvatar, VERSION };
-export default AgentRobotAvatar;
+export default AgentRobotAvatar;

package/docs/README.de.md

@@ -6,18 +6,30 @@
 
 [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)
 
-![Entwicklungsversion](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)
+![Version](https://img.shields.io/badge/version-v0.3.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)
 
 Eine leichte, ausdrucksstarke Roboter-Avatar-Web-Component für KI-Agenten und andere interaktive Anwendungen.
 
+Geeignet für KI-Assistenten- und Agent-Oberflächen, einschließlich Produkten und Erlebnissen ähnlich wie ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI und OpenCode.
+
+Sie kann außerdem für Desktop Pets, virtuelle Haustiere, Desktop-Begleiter, digitale Maskottchen, Chatbot-Avatare und andere interaktive Charaktererlebnisse verwendet werden.
+
+Agent Robot Avatar kann außerdem als visuelle Feedback-Ebene für Agent-Oberflächen im AG-UI-Stil eingesetzt werden.
+
 Agent Robot Avatar basiert auf SVG und Vanilla JavaScript und benötigt kein externes Animationsframework. Die Komponente funktioniert als natives Custom Element und stellt eine kompakte API für Ausdrücke, Interaktionszustände, Pointer-Following, Wartefeedback und Kopfform bereit.
 
-**Aktuelle öffentliche Version: v0.2.0**
+**Aktuelle öffentliche Version: v0.3.0**
 
 <p align="center">
   <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Interaktive animierte Demo von Agent Robot Avatar" width="560">
 </p>
 
+## Live-Demo
+
+Interaktive Demo ausprobieren: [Agent Robot Avatar öffnen](https://cx-artlab.github.io/agent-robot-avatar/?lang=de)
+
 ## Highlights
 
 - SVG + Vanilla JavaScript
@@ -49,7 +61,7 @@ avatar.play('success');
 avatar.play('failure');
 avatar.play('warning');
 avatar.play('inspect');
-avatar.play('angry');
+avatar.play('blocked');
 avatar.play('error');
 avatar.reset();
 ```
@@ -67,7 +79,7 @@ avatar.reset();
 | Failure | `failure` | Aufgabe wurde erfolglos abgeschlossen |
 | Warning | `warning` | Eine wichtige Aktion benötigt Bestätigung |
 | Inspect | `inspect` | Ergebnis prüfen oder verifizieren |
-| Blocked | `angry` | Anfrage blockiert oder kann nicht fortgesetzt werden |
+| Blocked | `blocked` | Anfrage blockiert oder kann nicht fortgesetzt werden |
 | System error | `error` | Verbindungs-, Dienst- oder Systemfehler |
 | Surprise | `surprise` | Unerwartetes Ereignis oder Ergebnis |
 | Sleep | `sleep` | Schlafzustand aktivieren |
@@ -75,6 +87,8 @@ avatar.reset();
 
 `failure` beschreibt einen Fehlschlag der Aufgabe selbst; `error` ist für Verbindungs-, Dienst- oder Systemprobleme reserviert. `waiting` bezeichnet eine laufende Anfrage, `bored` dagegen Inaktivität.
 
+`angry` bleibt als kompatibler Name für denselben visuellen Ausdruck wie `blocked` verfügbar.
+
 ```js
 avatar.startWaiting();
 avatar.stopWaiting();
@@ -107,6 +121,8 @@ Ohne explizite API-Aufrufe bietet der Avatar zufälliges Blinzeln, subtile Blick
 - Stark zur Mitte drücken: nach der Rückkehr `success`
 - Kleine Bewegung: nur Verformung
 
+Diese Drag-Ausdrücke gelten nur im idle-Zustand, wenn keine programmatisch gesteuerte Aktion den Avatar belegt. Während `waiting`, `input`, `inspect` und anderer aktiver Aktionen bleibt die Verformung erhalten, die Drag-Reaktion wird jedoch unterdrückt und später nicht nachgeholt. `pointercancel` stellt nur die Form wieder her und löst weder success noch angry aus.
+
 ## Interaktive Demo
 
 `demo/index.html` enthält alle öffentlichen Zustände, Pointer-Following, Jelly-Drag, den waiting-Lebenszyklus, Kopfrundung, Farb- und Verhaltenssteuerung sowie eine simulierte Agent-Unterhaltung. Demo-spezifisches JavaScript liegt unter `demo/` und ist nicht Teil des wiederverwendbaren npm-Runtimes.
@@ -137,7 +153,7 @@ Issues und Pull Requests sind willkommen. Bitte vor Änderungen [`CONTRIBUTING.m
 
 ## Projektstatus
 
-v0.1.0 ist die erste öffentliche Release-Linie. Die öffentliche API bleibt bewusst klein, damit sie vor einer späteren Stabilitätszusage mit `1.0.0` sorgfältig weiterentwickelt werden kann.
+v0.3.0 ist die aktuelle öffentliche Version. v0.1.0 bleibt als erste öffentliche Version verfügbar. Die öffentliche API bleibt bewusst klein, damit sie vor einer späteren Stabilitätszusage mit `1.0.0` sorgfältig weiterentwickelt werden kann.
 
 Agent Robot Avatar ist ein unabhängig entwickeltes Open-Source-Projekt und steht in keiner offiziellen Verbindung zu einer KI-Plattform oder Marke.
 
@@ -147,6 +163,4 @@ MIT License. Siehe [`LICENSE`](../LICENSE).
 
 ## Unterstütze mich mit einem Kaffee
 
-| 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"> |
+<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.es.md

@@ -6,20 +6,30 @@
 
 [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)
+![Versión](https://img.shields.io/badge/version-v0.3.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.
 
+Es adecuado para interfaces de asistentes y agentes de IA, incluidos productos y experiencias similares a ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI y OpenCode.
+
+También puede utilizarse para desktop pets, mascotas virtuales, compañeros de escritorio, mascotas digitales, avatares de chatbots y otras experiencias con personajes interactivos.
+
+Agent Robot Avatar también puede funcionar como una capa de feedback visual para interfaces de agentes de estilo AG-UI.
+
 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**
+**Versión pública actual: v0.3.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>
 
+## Demo en vivo
+
+Prueba la demo interactiva: [Abrir Agent Robot Avatar](https://cx-artlab.github.io/agent-robot-avatar/?lang=es)
+
 ## Características principales
 
 - SVG + JavaScript nativo
@@ -57,7 +67,7 @@ avatar.play('success');
 avatar.play('failure');
 avatar.play('warning');
 avatar.play('inspect');
-avatar.play('angry');
+avatar.play('blocked');
 avatar.play('error');
 
 avatar.reset();
@@ -76,7 +86,7 @@ avatar.reset();
 | 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 |
+| Blocked | `blocked` | 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 |
@@ -91,7 +101,7 @@ avatar.play('failed');
 avatar.play('fail');
 avatar.play('verify');
 avatar.play('review');
-avatar.play('blocked');
+avatar.play('angry'); // misma expresión visual que blocked
 avatar.play('policy-blocked');
 avatar.play('system-error');
 avatar.play('connection-error');
@@ -170,6 +180,8 @@ Al arrastrar, la cabeza se deforma localmente alrededor del punto de interacció
 - Empuje fuerte hacia el centro: activa `success` después de recuperarse
 - Arrastre pequeño: solo deformación
 
+Estas expresiones de arrastre solo se aplican en idle cuando ninguna acción programática controla el avatar. Durante `waiting`, `input`, `inspect` y otras acciones activas se conserva la deformación, pero la expresión de arrastre se suprime y no se reproduce después. `pointercancel` restaura la forma sin activar success ni angry.
+
 ## 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.
@@ -200,7 +212,7 @@ Se aceptan Issues y Pull Requests. Consulta [`CONTRIBUTING.md`](../CONTRIBUTING.
 
 ## 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`.
+v0.3.0 es la versión pública actual. v0.1.0 continúa disponible como la primera 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.
 
@@ -210,8 +222,4 @@ 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"> |
+<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>