agent-robot-avatar 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,44 @@ The project follows Semantic Versioning for public releases. Internal developmen
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-10
+
+### Fixed
+
+- Prevented disconnect cleanup from recreating per-instance media-query listeners and observers; reattaching now initializes connected runtime resources once without emitting cleanup-only lifecycle events.
+- Decoupled automatic sleep timing from frame rendering so `motion="reduce"` can pause continuous drawing without disabling `auto-sleep`, while active waiting/input continue to take priority.
+- Ensured reduced-motion state changes commit their final static SVG before rendering pauses, including the fully closed sleep pose.
+- Made `stopWaiting()` terminate the action it actually resets: waiting ends normally, other active program actions are cancelled once, and idle calls emit no false terminal event.
+- Separated explicit `noteActivity()` calls from ambient DOM activity so host calls inside real event handlers keep API semantics while automatic wakeups continue to obey `wake-on`.
+- Restricted action alias lookup to declared keys so prototype-like names such as `constructor` and `__proto__` fail before changing waiting/action state.
+
+## [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
@@ -66,6 +104,8 @@ 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.1]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.3.1
+[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,7 +6,7 @@
 
 [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.1-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.1-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)
 
@@ -20,7 +20,7 @@ Agent Robot Avatar can also be used as a visual feedback layer for AG-UI-style a
 
 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.1**
+**Current public version: v0.3.1**
 
 <p align="center">
   <img src="./assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar interactive animation demo" width="560">
@@ -40,6 +40,9 @@ Try the interactive demo: [Open Agent Robot Avatar](https://cx-artlab.github.io/
 - 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
@@ -60,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:
 
@@ -95,7 +98,9 @@ Return to the default idle state:
 avatar.reset();
 ```
 
-`reset()` cancels pending animations and returns to idle. Removing the element also cancels timers, animations, waiting, and drag feedback, without emitting a `face-state` event for cleanup. Reattaching starts from idle and preserves appearance and behavior settings. Cancelled animation promises resolve normally.
+`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, and also tears down its per-instance media-query listener and observers without restarting rendering as a cleanup side effect. Reattaching starts from idle, preserves appearance and behavior attributes/settings, and installs connected runtime resources once.
+
+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
 
@@ -113,10 +118,10 @@ avatar.reset();
 | 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:
 
@@ -138,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` when waiting is active. For backward compatibility, calling `stopWaiting()` during another active program action still returns the avatar to idle; that action now receives exactly one `cancel`. Calling it with no active action does not manufacture a lifecycle event. 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 active waiting, or `cancel` for a different active action that it resets to idle.
+- 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 request-lifecycle example covering waiting, success, failure, connection errors, host cancellation, request replacement, and stale-result protection. Its live-region text follows host request state rather than low-level face changes.
+
+## 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()` records activity and wakes by default even when the host calls it from inside a real `keydown`, `pointerdown`, or `click` handler. Pass `false` to `noteActivity(false)` to record activity without waking. Automatic page/direct-interaction wakeups are handled separately and still obey `wake-on`; their `action-state` source is `automatic`, while an explicit host wake remains `api`. 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. Automatic sleep uses an independent cancellable timer rather than the draw loop, so it still works while reduced motion has paused continuous rendering; activity and runtime `auto-sleep` changes reschedule it, and active waiting/input are not overwritten. Static state changes are committed before reduced rendering pauses, including the final closed-eye sleep pose. Switching modes does not revive cancelled work or change `action-state` lifecycle semantics.
 
 ## Pointer following
 
@@ -153,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:
@@ -162,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:
@@ -184,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) => {
@@ -194,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
 
@@ -225,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
 
@@ -269,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
 
@@ -281,18 +425,22 @@ Issues and pull requests are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md)
 
 ## Project status
 
-v0.2.1 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.
+v0.3.1 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,20 @@ 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 { 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,7 +6,9 @@
 
 [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.1-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.1-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.
 
@@ -18,7 +20,7 @@ Agent Robot Avatar kann außerdem als visuelle Feedback-Ebene für Agent-Oberfl
 
 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.1**
+**Aktuelle öffentliche Version: v0.3.1**
 
 <p align="center">
   <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Interaktive animierte Demo von Agent Robot Avatar" width="560">
@@ -119,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.
@@ -149,7 +153,7 @@ Issues und Pull Requests sind willkommen. Bitte vor Änderungen [`CONTRIBUTING.m
 
 ## Projektstatus
 
-v0.2.1 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.
+v0.3.1 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.
 
@@ -159,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,7 +6,7 @@
 
 [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](https://img.shields.io/badge/version-v0.2.1-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.1-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)
 
@@ -20,7 +20,7 @@ Agent Robot Avatar también puede funcionar como una capa de feedback visual par
 
 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.1**
+**Versión pública actual: v0.3.1**
 
 <p align="center">
   <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Demostración animada interactiva de Agent Robot Avatar" width="560">
@@ -180,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.
@@ -210,7 +212,7 @@ Se aceptan Issues y Pull Requests. Consulta [`CONTRIBUTING.md`](../CONTRIBUTING.
 
 ## Estado del proyecto
 
-v0.2.1 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`.
+v0.3.1 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.
 
@@ -220,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>

package/docs/README.fr.md

@@ -6,7 +6,9 @@
 
 [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.1-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.1-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 léger et expressif d’avatar robot pour les agents IA et d’autres applications interactives.
 
@@ -18,7 +20,7 @@ Agent Robot Avatar peut également servir de couche de retour visuel pour les in
 
 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.1**
+**Version publique actuelle : v0.3.1**
 
 <p align="center">
   <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Démonstration animée interactive d’Agent Robot Avatar" width="560">
@@ -178,6 +180,8 @@ Lors du glisser, la tête se déforme localement autour du point d’interaction
 - Forte poussée vers le centre : déclenche `success` après le retour
 - Petit glisser : déformation uniquement
 
+Ces expressions de glisser ne s’appliquent à l’état idle que lorsqu’aucune action programmée ne contrôle l’avatar. Pendant `waiting`, `input`, `inspect` et les autres actions actives, la déformation reste visible mais l’expression de glisser est supprimée et n’est pas rejouée ensuite. `pointercancel` restaure uniquement la forme sans déclencher success ni angry.
+
 ## 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.
@@ -208,7 +212,7 @@ Issues et Pull Requests sont les bienvenus. Consultez [`CONTRIBUTING.md`](../CON
 
 ## État du projet
 
-v0.2.1 est la version publique actuelle. v0.1.0 reste disponible comme première version publique. L’API publique reste volontairement limitée afin d’évoluer avec prudence avant un futur engagement de stabilité `1.0.0`.
+v0.3.1 est la version publique actuelle. v0.1.0 reste disponible comme première 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.
 
@@ -218,8 +222,4 @@ 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"> |
+<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.ja.md

@@ -6,7 +6,7 @@
 
 [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.1-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.1-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)
 
@@ -20,7 +20,7 @@ Agent Robot Avatar は、AG-UI スタイルの Agent インターフェースに
 
 Agent Robot Avatar は SVG と Vanilla JavaScript だけで構築され、サードパーティー製アニメーションフレームワークに依存しません。ネイティブ Custom Element として動作し、表情、状態、ポインター追従、待機フィードバック、頭部形状をシンプルな API で制御できます。
 
-**現在の公開バージョン：v0.2.1**
+**現在の公開バージョン：v0.3.1**
 
 <p align="center">
   <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar インタラクティブアニメーションデモ" width="560">
@@ -180,6 +180,8 @@ API を呼ばなくても、ランダムなまばたき、視線移動、近く
 - 強く中心へ押す：復帰後に `success`
 - 小さなドラッグ：変形のみ
 
+これらのドラッグ表情は、プログラム制御のアクションがアバターを使用していない idle 時にのみ適用されます。`waiting`、`input`、`inspect` などの実行中は変形だけを残し、ドラッグ表情は抑制して後から再生しません。`pointercancel` では形状だけを復元し、成功・怒りの表情は発生しません。
+
 ## インタラクティブ Demo
 
 `demo/index.html` には全公開状態、ポインター追従、ゼリー風ドラッグ、waiting ライフサイクル、頭部丸み調整、色・挙動設定、Agent 会話シミュレーションが含まれます。Demo 専用 JavaScript は `demo/` に分離され、再利用用 npm runtime には含まれません。
@@ -210,7 +212,7 @@ Issue と Pull Request を歓迎します。提出前に [`CONTRIBUTING.md`](../
 
 ## プロジェクトの状態
 
-v0.2.1 は現在の公開バージョンです。v0.1.0 は最初の公開バージョンとして引き続き利用できます。将来の `1.0.0` に向けて慎重に進化できるよう、公開 API は意図的に小さく保っています。
+v0.3.1 は現在の公開バージョンです。v0.1.0 は最初の公開バージョンとして引き続き利用できます。将来の `1.0.0` に向けて慎重に進化できるよう、公開 API は意図的に小さく保っています。
 
 Agent Robot Avatar は独立して開発されたオープンソースプロジェクトであり、特定の AI プラットフォームやブランドとは提携・公式承認関係にありません。
 
@@ -220,8 +222,4 @@ 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"> |
+<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>