agent-robot-avatar 0.5.2 → 0.6.0

package/docs/README.zh-CN.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) | [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.5.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)
+![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)
 
@@ -24,6 +24,12 @@ Agent Robot Avatar 还可作为 AG-UI 风格 Agent 界面的视觉反馈层。
   <img src="../assets/demo/agent-robot-avatar-demo.gif" alt="Agent Robot Avatar 交互动画演示" width="560">
 </p>
 
+## 嵌入式眼睛版本（实验性）
+
+独立的 C++11 眼睛表情核心，在机器人和开发板的屏幕上画出同样的 18 种表情。固件示例覆盖 26 种开发板与屏幕组合（ESP32、ESP32-S3、RP2040；ST7789、ST7735、GC9A01 圆屏、ILI9341/9342/9488、CO5300 AMOLED、ST7701S RGB 屏、SSD1306/SH1106 OLED，含 LilyGO、M5Stack、微雪、Seeed、乐鑫等开发板）。所有示例都在 CI 中编译通过，尚未实机验证；如果你在实物上试过，欢迎提交实机验证报告。
+
+[查看硬件接入说明](https://github.com/CX-ArtLab/agent-robot-avatar/blob/main/embedded/README.zh-CN.md)。现有 Web 组件与 Demo 保持不变。
+
 ## 在线 Demo
 
 [打开交互 Demo](https://cx-artlab.github.io/agent-robot-avatar/?lang=zh-CN)
@@ -75,17 +81,19 @@ import 'agent-robot-avatar';
 const avatar = document.querySelector('#avatar');
 
 avatar.play('success');
-avatar.play('warning');
-avatar.play('error');
+avatar.play('wary');
+avatar.play('refuse');
 
 avatar.reset();
 ```
 
 可用动作：
 
-`idle` · `bored` · `waiting` · `waiting-wrap` · `input` · `send` · `success` · `failure` · `warning` · `inspect` · `blocked` · `error` · `surprise` · `love` · `random` · `sleep` · `wake`
+`idle` · `bored` · `waiting-spin` · `waiting-wrap` · `waiting-wave` · `input` · `affirm` · `success` · `failure` · `wary` · `inspect` · `angry` · `refuse` · `surprise` · `love` · `random` · `sleep` · `wake`
+
+`waiting-wave`（等待 · 波动）：双眼错开节奏上下起伏，每轮周期 1.1 秒、振幅 10 SVG 单位。`play('waiting-wave')` 连续播放三轮并回正；`startWaiting({ variant: 'wave' })` 持续循环，直到被其他动作替换或调用 `stopWaiting()`。支持减少动态效果设置，动作生命周期事件统一使用 `waiting`。
 
-`failure` 用于表示任务执行完成但结果失败；`error` 用于连接、服务或系统错误。
+动作名描述的是头像做出的样子：`refuse` 是摇头，用于 Agent 不能或不会执行某个请求；`failure` 用于任务或连接没有成功；`wary` 是侧头、上下打量的警惕眼神，用于需要用户确认的操作。0.5 版的旧名字（`send`、`warning`、`error`、`blocked` 等）在 1.0 之前仍可使用，但会在控制台提示改名，详见[升级对照表](../CHANGELOG.md#upgrading-from-05x)。
 
 `love` 用于表达喜欢或感谢：两只眼睛向中间靠拢合成一颗爱心，跳动三下后恢复。
 
@@ -99,11 +107,14 @@ avatar.startWaiting();
 // 第二种等待：眼睛从一侧转出，再从另一侧转入。
 avatar.startWaiting({ variant: 'wrap' });
 
+// 另一种等待动作：双眼错开节奏上下波动。
+avatar.startWaiting({ variant: 'wave' });
+
 try {
   const result = await runAgentRequest();
   await avatar.play(result.ok ? 'success' : 'failure');
 } catch (error) {
-  await avatar.play('error');
+  await avatar.play('failure');
 }
 ```
 
@@ -134,7 +145,6 @@ try {
 ```js
 avatar.setPointerFollow(false);
 avatar.setHeadRoundness(75);
-avatar.setAntennaFlash(true);
 avatar.setPressSqueeze(true);
 avatar.setAntennaDrag(true);
 ```
@@ -161,7 +171,7 @@ avatar.setAntennaDrag(true);
 
 ## 项目状态
 
-**当前公开版本：v0.5.2**
+**当前公开版本：v0.6.0**
 
 公开 API 会在未来 `1.0.0` 稳定性承诺前继续保持精简并谨慎演进。
 
@@ -188,3 +198,5 @@ MIT License。详见 [`LICENSE`](../LICENSE)。
 | Ko-fi | 支付宝 | 微信支付 |
 | --- | --- | --- |
 | <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="支付宝收款码" width="160"> | <img src="../assets/support/wechat-pay.png" alt="微信支付收款码" width="160"> |
+
+

package/docs/README.zh-TW.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) | [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.5.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)
+![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)
 
@@ -75,17 +75,17 @@ import 'agent-robot-avatar';
 const avatar = document.querySelector('#avatar');
 
 avatar.play('success');
-avatar.play('warning');
-avatar.play('error');
+avatar.play('wary');
+avatar.play('refuse');
 
 avatar.reset();
 ```
 
 可用動作：
 
-`idle` · `bored` · `waiting` · `waiting-wrap` · `input` · `send` · `success` · `failure` · `warning` · `inspect` · `blocked` · `error` · `surprise` · `love` · `random` · `sleep` · `wake`
+`idle` · `bored` · `waiting-spin` · `waiting-wrap` · `waiting-wave` · `input` · `affirm` · `success` · `failure` · `wary` · `inspect` · `angry` · `refuse` · `surprise` · `love` · `random` · `sleep` · `wake`
 
-`failure` 用於表示任務執行完成但結果失敗；`error` 用於連線、服務或系統錯誤。
+動作名描述的是頭像做出的樣子：`refuse` 是搖頭，用於 Agent 不能或不會執行某個請求；`failure` 用於任務或連線沒有成功；`wary` 是側頭、上下打量的警惕眼神，用於需要使用者確認的操作。0.5 版的舊名字（`send`、`warning`、`error`、`blocked` 等）在 1.0 之前仍可使用，但會在主控台提示改名，詳見[升級對照表](../CHANGELOG.md#upgrading-from-05x)。
 
 `love` 用於表達喜歡或感謝：兩隻眼睛向中間靠攏合成一顆愛心，跳動三下後恢復。
 
@@ -103,7 +103,7 @@ try {
   const result = await runAgentRequest();
   await avatar.play(result.ok ? 'success' : 'failure');
 } catch (error) {
-  await avatar.play('error');
+  await avatar.play('failure');
 }
 ```
 
@@ -134,7 +134,6 @@ try {
 ```js
 avatar.setPointerFollow(false);
 avatar.setHeadRoundness(75);
-avatar.setAntennaFlash(true);
 avatar.setPressSqueeze(true);
 avatar.setAntennaDrag(true);
 ```
@@ -161,7 +160,7 @@ avatar.setAntennaDrag(true);
 
 ## 專案狀態
 
-**目前公開版本：v0.5.2**
+**目前公開版本：v0.6.0**
 
 公開 API 會在未來 `1.0.0` 穩定性承諾前繼續保持精簡並謹慎演進。
 

package/index.d.ts

@@ -2,30 +2,42 @@ export type AgentRobotAvatarAction =
   | 'idle'
   | 'bored'
   | 'waiting'
-  | 'wait'
+  | 'waiting-spin'
   | 'waiting-wrap'
+  | 'waiting-wave'
   | 'input'
-  | 'send'
+  | 'affirm'
   | 'success'
   | 'failure'
+  | 'wary'
+  | 'inspect'
+  | 'angry'
+  | 'refuse'
+  | 'surprise'
+  | 'love'
+  | 'random'
+  | 'sleep'
+  | 'wake'
+  | AgentRobotAvatarDeprecatedAction;
+
+/**
+ * Older names that still play the same action but log a one-time deprecation
+ * notice. They are removed in 1.0.
+ */
+export type AgentRobotAvatarDeprecatedAction =
+  | 'wait'
+  | 'send'
   | 'failed'
   | 'fail'
   | 'warning'
-  | 'inspect'
   | 'verify'
   | 'review'
-  | 'angry'
   | 'blocked'
   | 'policy-blocked'
   | 'error'
   | 'system-error'
   | 'connection-error'
-  | 'surprise'
-  | 'love'
-  | 'random'
-  | 'slot'
-  | 'sleep'
-  | 'wake';
+  | 'slot';
 
 export type AgentRobotAvatarState =
   | 'idle'
@@ -39,8 +51,8 @@ export type AgentRobotAvatarState =
   | 'love'
   | 'random'
   | 'waiting'
-  | 'warning'
-  | 'error'
+  | 'wary'
+  | 'refuse'
   | 'inspect'
   | 'failure'
   | 'squeeze'
@@ -51,14 +63,13 @@ export type AgentRobotAvatarCanonicalAction =
   | 'bored'
   | 'waiting'
   | 'input'
-  | 'send'
+  | 'affirm'
   | 'success'
   | 'failure'
-  | 'warning'
+  | 'wary'
   | 'inspect'
   | 'angry'
-  | 'blocked'
-  | 'error'
+  | 'refuse'
   | 'surprise'
   | 'love'
   | 'random'
@@ -73,7 +84,7 @@ export type AgentRobotAvatarActionSource = 'api' | 'interaction' | 'automatic';
 export type AgentRobotAvatarWakeOn = 'activity' | 'interaction' | 'manual';
 export type AgentRobotAvatarMotion = 'auto' | 'reduce' | 'full';
 export interface AgentRobotAvatarWaitingOptions {
-  variant?: 'default' | 'wrap';
+  variant?: 'default' | 'spin' | 'wrap' | 'wave';
 }
 
 export interface AgentRobotAvatarActionStateDetail {
@@ -97,6 +108,7 @@ export declare class AgentRobotAvatar extends HTMLElement {
   startWaiting(options?: AgentRobotAvatarWaitingOptions): Promise<this>;
   stopWaiting(): this;
   setPointerFollow(enabled?: boolean): this;
+  /** @deprecated Removed in 0.6; does nothing and logs a one-time notice. Deleted in 1.0. */
   setAntennaFlash(enabled?: boolean): this;
   setPressSqueeze(enabled?: boolean): this;
   setAntennaDrag(enabled?: boolean): this;
@@ -126,3 +138,4 @@ declare global {
     'agent-robot-avatar': AgentRobotAvatar;
   }
 }
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-robot-avatar",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "A lightweight expressive robot avatar Web Component for AI agents and interactive applications.",
   "type": "module",
   "main": "./agent-robot-avatar.js",
@@ -21,12 +21,13 @@
     "dev": "node scripts/serve.mjs",
     "build:pages": "node scripts/build-pages.mjs",
     "check": "node scripts/check-source.mjs",
-    "test": "npm run check && npm run test:types && npm run test:release && npm run test:package && npm run test:browser && npm run build:pages",
+    "test": "npm run check && npm run test:types && npm run test:release && npm run test:package && npm run test:waiting && npm run test:browser && npm run build:pages",
     "release:check": "npm test && npm publish --dry-run --ignore-scripts --tag latest",
     "prepublishOnly": "npm test && node scripts/check-publish-tag.mjs",
     "test:types": "tsc -p tsconfig.types.json",
     "test:release": "node --test tests/release.test.mjs",
     "test:package": "node --test tests/package.test.mjs",
+    "test:waiting": "node --test tests/waiting-wave.test.mjs",
     "test:browser": "playwright test"
   },
   "files": [
@@ -75,3 +76,4 @@
     "typescript": "7.0.2"
   }
 }
+

package/src/agent-robot-avatar-actions.js

@@ -23,7 +23,7 @@ const WARNING_TIMING = Object.freeze({
   W5: 200,
   W5P: 300,
   W6: 200,
-  W6P: 300,
+  W6P: 500,
   W7: 100,
   W8: 800,
   W9: 227,
@@ -200,7 +200,7 @@ proto.error = async function() {
   const eyeDuration = 980;
   const headDuration = 1380;
   this._systemErrorShake = { start: performance.now(), duration: eyeDuration };
-  dispatchActionState(this, 'error');
+  dispatchActionState(this, 'refuse');
 
   centerHeadTransform(this);
   if (this._headMotion?.animate) {
@@ -234,7 +234,7 @@ proto.warning = async function() {
   const token = this._transitionToken;
   const duration = WARNING_PHASES.duration;
   this._warningFx = { start: performance.now(), duration };
-  dispatchActionState(this, 'warning');
+  dispatchActionState(this, 'wary');
 
   centerHeadTransform(this);
   if (this._headMotion?.animate) {
@@ -345,29 +345,32 @@ function drawWarning(now) {
     farDeepLidDrop = segment(elapsed, WARNING_PHASES.w6Start, WARNING_PHASES.w6End, 3.5, 0);
   }
 
-  const nearSX = lerp(1, 1.48, proximity);
+  const nearSX = lerp(1, 1.37, proximity);
   const nearSY = lerp(1, 1.40, proximity);
-  const farSX = lerp(1, 0.78, proximity);
-  const farSY = lerp(1, 0.97, proximity);
+  const farSX = lerp(1, 0.68, proximity);
+  const farSY = lerp(1, 0.99, proximity);
+
+  const nearTilt = lerp(0, -6.5, proximity);
+  const farTilt = lerp(0, 7.5, proximity);
 
   const nearX = lerp(86, 102.0, proximity);
-  const farX = lerp(154, 178.5, proximity);
+  const farX = lerp(154, 174.5, proximity);
   const nearY = lerp(126, 125.5, proximity);
-  const farY = lerp(126, 134.0, proximity) + farLowOffset;
+  const farY = lerp(126, 133.5, proximity) + farLowOffset;
 
   this._leftEye.setAttribute(
     'transform',
-    `translate(${nearX.toFixed(2)} ${nearY.toFixed(2)}) scale(${nearSX.toFixed(3)} ${nearSY.toFixed(3)})`
+    `translate(${nearX.toFixed(2)} ${nearY.toFixed(2)}) rotate(${nearTilt.toFixed(2)}) scale(${nearSX.toFixed(3)} ${nearSY.toFixed(3)})`
   );
   this._rightEye.setAttribute(
     'transform',
-    `translate(${farX.toFixed(2)} ${farY.toFixed(2)}) scale(${farSX.toFixed(3)} ${farSY.toFixed(3)})`
+    `translate(${farX.toFixed(2)} ${farY.toFixed(2)}) rotate(${farTilt.toFixed(2)}) scale(${farSX.toFixed(3)} ${farSY.toFixed(3)})`
   );
 
-  const nearTopY = lerp(-36, -10.0, lids) + lidShift;
-  const farTopY = lerp(-36, -18.0, lids) + lidShift * 0.95 + farDeepLidDrop;
-  const nearTopRot = lerp(0, 10.0, lids);
-  const farTopRot = lerp(0, -7.5, lids);
+  const nearTopY = lerp(-36, -8.0, lids) + lidShift;
+  const farTopY = lerp(-36, -10.0, lids) + lidShift * 0.95 + farDeepLidDrop;
+  const nearTopRot = lerp(0, 25.0, lids);
+  const farTopRot = lerp(0, -17.0, lids);
 
   this._leftTop.setAttribute('y', (nearTopY - 90).toFixed(2));
   this._leftTop.setAttribute('height', '90');

package/src/agent-robot-avatar-gestures.js

@@ -42,6 +42,15 @@ proto.setPressSqueeze=function(enabled=true){
   if(!enabled && this._gestureFx?.kind==='squeeze')this._cancelGesture();
   return this;
 };
+// Antenna blinking was removed in 0.6. The method stays so existing calls keep working.
+let warnedAntennaFlash=false;
+proto.setAntennaFlash=function(){
+  if(!warnedAntennaFlash){
+    warnedAntennaFlash=true;
+    console.warn('agent-robot-avatar: setAntennaFlash() was removed in 0.6 and does nothing. It will be deleted in 1.0.');
+  }
+  return this;
+};
 proto.setAntennaDrag=function(enabled=true){
   this.setAttribute('antenna-drag',String(Boolean(enabled)));
   if(!enabled && this._gestureFx?.kind==='antenna-drag')this._cancelGesture();

package/src/agent-robot-avatar-runtime.js

@@ -24,28 +24,36 @@ const baseStopWaiting = proto.stopWaiting;
 const baseDraw = proto._draw;
 
 const DEFAULT_SIZE = 112;
+// Canonical action names describe what the avatar does on screen. Older names that
+// described a situation (send, warning, blocked, error, ...) still resolve to the same
+// action, but print a one-time deprecation notice; they are removed in 1.0.
 const ACTION_ALIASES = Object.freeze({
   idle: 'idle',
   bored: 'bored',
   waiting: 'waiting',
+  'waiting-spin': 'waiting',
   wait: 'waiting',
   'waiting-wrap': 'waiting',
+  'waiting-wave': 'waiting',
   input: 'input',
-  send: 'send',
+  affirm: 'affirm',
+  send: 'affirm',
   success: 'success',
   failure: 'failure',
   failed: 'failure',
   fail: 'failure',
-  warning: 'warning',
+  wary: 'wary',
+  warning: 'wary',
   inspect: 'inspect',
   verify: 'inspect',
   review: 'inspect',
   angry: 'angry',
-  blocked: 'blocked',
-  'policy-blocked': 'blocked',
-  error: 'error',
-  'system-error': 'error',
-  'connection-error': 'error',
+  blocked: 'angry',
+  'policy-blocked': 'angry',
+  refuse: 'refuse',
+  error: 'refuse',
+  'system-error': 'refuse',
+  'connection-error': 'refuse',
   surprise: 'surprise',
   love: 'love',
   random: 'random',
@@ -54,10 +62,44 @@ const ACTION_ALIASES = Object.freeze({
   wake: 'wake',
 });
 
+const DEPRECATED_ACTIONS = Object.freeze({
+  wait: 'waiting-spin',
+  send: 'affirm',
+  failed: 'failure',
+  fail: 'failure',
+  warning: 'wary',
+  verify: 'inspect',
+  review: 'inspect',
+  blocked: 'angry',
+  'policy-blocked': 'angry',
+  error: 'refuse',
+  'system-error': 'refuse',
+  'connection-error': 'refuse',
+  slot: 'random',
+});
+
+// The renamed actions still run on the original implementations.
+const ACTION_IMPLEMENTATIONS = Object.freeze({
+  'waiting-spin': 'waiting',
+  affirm: 'send',
+  wary: 'warning',
+  refuse: 'error',
+});
+
+const warnedDeprecations = new Set();
+
+function warnDeprecatedAction(raw) {
+  const replacement = DEPRECATED_ACTIONS[raw];
+  if (!replacement || warnedDeprecations.has(raw)) return;
+  warnedDeprecations.add(raw);
+  console.warn(`agent-robot-avatar: action "${raw}" is deprecated, use "${replacement}". Old names stop working in 1.0.`);
+}
+
 function normalizeAction(name) {
   const raw = String(name || '').trim().toLowerCase();
   const canonical = Object.hasOwn(ACTION_ALIASES, raw) ? ACTION_ALIASES[raw] : null;
-  return { raw, canonical };
+  if (canonical) warnDeprecatedAction(raw);
+  return { raw, canonical, implementation: ACTION_IMPLEMENTATIONS[raw] ?? raw };
 }
 
 function wakePolicy(instance) {
@@ -717,17 +759,17 @@ function prepareReplacement(instance, canonical) {
 
 proto.play = function(name) {
   ensureRuntime(this);
-  const { raw, canonical } = normalizeAction(name);
+  const { canonical, implementation } = normalizeAction(name);
   if (!canonical) throw new Error(`Unknown Agent Robot Avatar action: ${name}`);
   if (playNoOp(this, canonical)) return this;
-  if (canonical === 'idle') return basePlay.call(this, raw);
+  if (canonical === 'idle') return basePlay.call(this, implementation);
 
   prepareReplacement(this, canonical);
 
   let result;
   this._runtimeInPlay = true;
   try {
-    result = basePlay.call(this, raw);
+    result = basePlay.call(this, implementation);
   } finally {
     this._runtimeInPlay = false;
   }
@@ -903,3 +945,4 @@ export {
   DEFAULT_SIZE,
 };
 export default AgentRobotAvatar;
+

package/src/agent-robot-avatar-version.js

@@ -1,3 +1,3 @@
-const VERSION = '0.5.2';
+const VERSION = '0.6.0';
 
 export { VERSION };

package/src/agent-robot-avatar-waiting.js

@@ -2,9 +2,13 @@ import AgentRobotAvatar, { registerAvatarExtension } from './agent-robot-avatar-
 import { WRAP_CYCLE, drawWrapWaiting } from './agent-robot-avatar-wrap.js';
 
 const WAITING_CYCLE = 3200;
+const WAVE_WAITING_CYCLE = 1100;
+const WAVE_WAITING_REPEATS = 3;
 const proto = AgentRobotAvatar.prototype;
 
 const clamp01 = value => Math.max(0, Math.min(1, value));
+const smooth = value => { const t = clamp01(value); return t * t * (3 - 2 * t); };
+const waitingDuration = variant => variant === 'wave' ? WAVE_WAITING_CYCLE * WAVE_WAITING_REPEATS : variant === 'wrap' ? WRAP_CYCLE : WAITING_CYCLE;
 
 function dispatchWaitingState(instance, state) {
   instance.dispatchEvent(new CustomEvent('face-state', {
@@ -28,8 +32,10 @@ function setEyeOrbitTransform(eye, x, scaleX, scaleY) {
 }
 
 async function enterWaiting(instance, continuous, source, options = {}) {
-  const variant = options?.variant ?? 'default';
-  if (variant !== 'default' && variant !== 'wrap') throw new TypeError(`Unknown waiting variant: ${variant}`);
+  // 'spin' names the default variant, matching the waiting-spin action.
+  const requested = options?.variant ?? 'default';
+  const variant = requested === 'spin' ? 'default' : requested;
+  if (variant !== 'default' && variant !== 'wrap' && variant !== 'wave') throw new TypeError(`Unknown waiting variant: ${requested}`);
   instance.noteActivity();
   instance._inputWanted = false;
 
@@ -44,7 +50,7 @@ async function enterWaiting(instance, continuous, source, options = {}) {
   instance._look.y = 0;
   instance._waitingFx = {
     start: performance.now(),
-    duration: variant === 'wrap' ? WRAP_CYCLE : WAITING_CYCLE,
+    duration: waitingDuration(variant),
     variant,
     continuous: continuous === true,
     source,
@@ -57,7 +63,7 @@ proto.waiting = async function(options = {}) {
   const token = await enterWaiting(this, false, 'play', options);
   if (token == null) return;
 
-  await this._wait(options?.variant === 'wrap' ? WRAP_CYCLE : WAITING_CYCLE);
+  await this._wait(waitingDuration(options?.variant));
   if (token !== this._transitionToken || !this._waitingRequested) return;
   this._waitingRequested = false;
   this._waitingFx = null;
@@ -89,6 +95,22 @@ function drawWaiting(now) {
     drawWrapWaiting(this, phaseMs);
     return;
   }
+  if (fx.variant === 'wave') {
+    // Restore the first embedded prototype's staggered vertical eye motion.
+    // Ease its entry/finite exit; continuous loops keep their phase at the seam.
+    let amplitude = 10 * smooth(elapsed / 140);
+    if (!fx.continuous) amplitude *= smooth((fx.duration - phaseMs) / 140);
+    const angle = (elapsed % WAVE_WAITING_CYCLE) / WAVE_WAITING_CYCLE * Math.PI * 2;
+    for (const [side, x, offset] of [['left', 86, 0], ['right', 154, 0.7]]) {
+      this[`_${side}Base`].setAttribute('cx', '0');
+      this[`_${side}Base`].setAttribute('cy', '0');
+      this[`_${side}Base`].setAttribute('rx', '27');
+      this[`_${side}Base`].setAttribute('ry', '29');
+      this[`_${side}Eye`].setAttribute('transform',
+        `translate(${x} ${(126 + Math.sin(angle + offset) * amplitude).toFixed(2)})`);
+    }
+    return;
+  }
 
   // Original R43 waiting-eye motion: two continuous horizontal orbits per 3.2 s cycle.
   const angle = t * Math.PI * 4;
@@ -113,9 +135,10 @@ registerAvatarExtension({
     waiting() { return this.waiting(); },
     wait() { return this.waiting(); },
     'waiting-wrap'() { return this.waiting({ variant: 'wrap' }); },
+    'waiting-wave'() { return this.waiting({ variant: 'wave' }); },
   },
   beforePlay(action) {
-    if (action === 'waiting' || action === 'wait' || action === 'waiting-wrap') return;
+    if (action === 'waiting' || action === 'wait' || action === 'waiting-wrap' || action === 'waiting-wave') return;
     this._waitingRequested = false;
     this._waitingFx = null;
   },
@@ -126,5 +149,6 @@ registerAvatarExtension({
   draw: drawWaiting,
 });
 
-export { AgentRobotAvatar, WAITING_CYCLE };
+export { AgentRobotAvatar, WAITING_CYCLE, WAVE_WAITING_CYCLE };
 export default AgentRobotAvatar;
+