agent-robot-avatar 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -4,27 +4,72 @@ All notable user-facing changes to Agent Robot Avatar are documented here.
 
 The project follows Semantic Versioning for public releases. Internal development build numbers are not part of the public version history.
 
-## [Unreleased]
+## [0.7.0] - 2026-10-29
 
-## [0.5.2] - 2026-10-06
+### Added
 
-### Fixed
+- 188 skins in 17 series. Pick one by number with `skin="301"` or `setSkin(301)`; `setSkin(null)` goes back to the flat color.
+- Skin numbers are permanent: the series number plus two digits, so 305 is the fifth skin of series 3. New skins take the next free number, and numbers are never reused.
+- Every skin works with every expression and gesture, and its light follows the pointer.
+- `SKINS`, `SKIN_SERIES` and `SKIN_NAMES` list the skins, for building a skin picker.
+- Skin code loads only when a page uses a skin. `loadSkins()` loads it in advance.
+- `agent-robot-avatar/lite`: the same avatar without any skin code.
+- The demo has a Skin Gallery and a page with every skin.
+
+## [0.6.0] - 2026-10-23
+
+### Upgrading from 0.5.x
+
+Several actions are renamed after what the avatar does on screen, instead of the situation they were first written for. The old names keep working in 0.6 and print a one-time notice in the browser console; they stop working in 1.0. To upgrade, replace the old names in `play()` calls and in `action-state` or `face-state` listeners:
+
+| Old name | New name | What it looks like |
+| --- | --- | --- |
+| `send` | `affirm` | A nod |
+| `warning` | `wary` | Head turned, one eye close, a guarded up-and-down look |
+| `error`, `system-error`, `connection-error` | `refuse` | A head shake |
+| `blocked`, `policy-blocked` | `angry` | Lowered, glaring eyes |
+| `wait` | `waiting-spin` (or `waiting`) | The default waiting spin |
+| `failed`, `fail` | `failure` | |
+| `verify`, `review` | `inspect` | |
+| `slot` | `random` | |
+
+`action-state` now reports `affirm`, `wary`, `angry` and `refuse`, and `face-state` reports `wary` and `refuse`. A shake reads as "no", so use `refuse` when the Agent cannot or will not do something, and `failure` when a task or connection fails. Antenna blinking is removed: `setAntennaFlash()` now does nothing and prints a one-time notice, and it is deleted in 1.0. Packages that depend on `^0.5.x` do not pick up 0.6 automatically.
+
+### Added
+
+- Added the `waiting-wave` action: both eyes bob in staggered waves. `startWaiting({ variant: 'wave' })` loops it continuously.
+- Added `waiting-spin` as the explicit name of the default waiting motion, and `startWaiting({ variant: 'spin' })`.
+- Added brand-inspired color palettes to the demo. Colors apply to a stage card around the avatar; hovering a swatch previews it, a dice button picks a random palette, a swap button exchanges the background and head colors, and a reset button appears on the stage while the colors differ from the default. The page opens by rolling the stage through the palettes in step with the eyes' reel spin, ending with a faint rainbow ripple.
+
+### Changed
+
+- Renamed actions as listed above.
+- Demo labels now describe the expression: Waiting · Spin, Waiting · Scroll, Affirm, Wary, Angry and Refuse. The toolbar row is one card as wide as the actions, with Head shape and a random-colors button.
+- Refined the wary expression with independently tilted eyes, adjusted eye proportions and eyelids.
+
+### Also in this release
 
-- Corrected the repository URL case in `package.json` so npm provenance publishing succeeds.
+- The embedded eyes engine for robot and dev-board screens is still in development. It will get its own version number and release; progress is tracked in [embedded/CHANGELOG.md](embedded/CHANGELOG.md).
 
-## [0.5.1] - 2026-10-05
+### Removed
+
+- Removed antenna blinking (`setAntennaFlash()`), which added little and is no longer shown in the demo.
 
 ### Fixed
 
-- `love` now shows the full heart under reduced motion, and `love` and `random` follow motion preference changes while they play.
+- The demo no longer shows intermediate layouts while loading, keeps its action rows even and stable on phones and under browser page translators, and keeps an open panel on screen.
 
-## [0.5.0] - 2026-10-05
+## [0.5.2] - 2026-10-06
 
 ### Added
 
 - Added the `love` action: the eyes lean together into a heart, beat three times, then return.
 - Added the `random` action (alias `slot`): the eyes roll like slot-machine reels, then settle with a bounce.
 
+### Fixed
+
+- `love` now shows the full heart under reduced motion, and `love` and `random` follow motion preference changes while they play.
+
 ## [0.4.3] - 2026-09-22
 
 ### Fixed
@@ -160,6 +205,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.6.0]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.6.0
+[0.5.2]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.5.2
 [0.4.3]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.4.3
 [0.4.2]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.4.2
 [0.3.2]: https://github.com/CX-ArtLab/agent-robot-avatar/releases/tag/v0.3.2
@@ -168,3 +215,5 @@ First public release.
 [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) | [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)
 
@@ -26,7 +26,7 @@ Built with SVG and vanilla JavaScript, it works as a native custom element with
 
 ## Live Demo
 
-[Open the interactive demo](https://cx-artlab.github.io/agent-robot-avatar/)
+[Open the interactive demo](https://cx-artlab.github.io/agent-robot-avatar/) · [Visit the Skin Gallery](https://cx-artlab.github.io/agent-robot-avatar/skins.html)
 
 ## Highlights
 
@@ -38,11 +38,12 @@ Built with SVG and vanilla JavaScript, it works as a native custom element with
 - Jelly-style drag deformation with elastic recovery
 - Press-and-hold squeeze and draggable spring antenna interactions
 - Programmatically controlled Agent states and expressions
-- Waiting, success, failure, warning, review, blocked, and system-error feedback
+- Expressions for waiting, success, failure, affirm, wary, inspect, angry, refuse, love and more
 - Reduced-motion support
 - Configurable sleep behavior
 - Adjustable head roundness
-- Optional antenna status flashing
+- 188 numbered skins in 17 series, with light that follows the pointer
+- A lite build without skins for the smallest pages
 - TypeScript declarations included
 
 ## Install
@@ -69,27 +70,54 @@ Then add the component:
 
 No initialization code is required. The avatar enters its default idle behavior automatically.
 
+### Lite build
+
+For pages that never use skins, `agent-robot-avatar/lite` is the same avatar without any skin code:
+
+```js
+import 'agent-robot-avatar/lite';
+```
+
+In the lite build the `skin` attribute is ignored, and the console notes that skins need the full build.
+
 ## Basic usage
 
 ```js
 const avatar = document.querySelector('#avatar');
 
 avatar.play('success');
-avatar.play('warning');
-avatar.play('error');
+avatar.play('wary');
+avatar.play('refuse');
 
 avatar.reset();
 ```
 
 Available actions:
 
-`idle` · `bored` · `waiting` · `waiting-wrap` · `input` · `send` · `success` · `failure` · `warning` · `inspect` · `blocked` · `error` · `surprise` · `love` · `random` · `sleep` · `wake`
-
-`failure` is intended for a task that completed unsuccessfully, while `error` is intended for connection, service, or system failures.
-
-`love` expresses affection or thanks: the two eyes lean together into a single heart, beat three times, then return.
-
-`random` plays a slot-machine spin: each eye rolls over a drum, then the left eye slows, bounces and settles, followed by the right. `slot` is an alias.
+| Action | Looks like | Use when |
+| --- | --- | --- |
+| `idle` | Blinks and glances around | Default state |
+| `bored` | Glances slowly from side to side | Nothing has happened for a while |
+| `waiting-spin` | Eyes circle from side to side | Waiting for a reply (default) |
+| `waiting-wrap` | Eyes slide out one side and back in the other | Waiting for a reply |
+| `waiting-wave` | Eyes bob up and down in turn | Waiting for a reply |
+| `input` | Eyes become blinking text cursors | The user is typing |
+| `affirm` | Nods | Got it, confirmed |
+| `success` | Happy, smiling eyes | Task completed |
+| `failure` | Head and eyes droop | Task or connection failed |
+| `wary` | Turns its head and gives a guarded up-and-down look | An action needs confirmation |
+| `inspect` | Narrows its eyes and scans up and down | Checking or reviewing something |
+| `angry` | Lowered, glaring eyes | Content blocked |
+| `refuse` | Shakes its head | Cannot or will not do the request |
+| `surprise` | Wide-open eyes | Something unexpected |
+| `love` | Eyes merge into a beating heart | Thanks, affection |
+| `random` | Eyes spin like slot-machine reels | Random pick, playful moment |
+| `sleep` | Closes its eyes and sleeps | No activity for a long time |
+| `wake` | Opens its eyes and wakes up | Activity resumes |
+
+Waiting actions play one round with `play()`. `startWaiting({ variant: 'spin' | 'wrap' | 'wave' })` loops until another action starts or `stopWaiting()` is called.
+
+Names from 0.5 (`send`, `warning`, `error`, `blocked`, `slot` and others) still work with a console notice until 1.0; see the [upgrade table](CHANGELOG.md#upgrading-from-05x).
 
 For a real Agent request lifecycle:
 
@@ -99,11 +127,14 @@ avatar.startWaiting();
 // Alternative waiting motion: eyes turn out through one side and return through the other.
 avatar.startWaiting({ variant: 'wrap' });
 
+// Alternative waiting motion: staggered vertical eye waves.
+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');
 }
 ```
 
@@ -128,19 +159,60 @@ try {
 | `motion` | Motion policy: `auto`, `reduce`, or `full` |
 | `press-squeeze` | Center press-and-hold squeeze; set to `false` to disable |
 | `antenna-drag` | Antenna drag, spring return, and angry reaction; set to `false` to disable |
+| `skin` | Skin number, such as `301`; leave it out for the flat color |
 
 Common runtime controls:
 
 ```js
 avatar.setPointerFollow(false);
 avatar.setHeadRoundness(75);
-avatar.setAntennaFlash(true);
 avatar.setPressSqueeze(true);
 avatar.setAntennaDrag(true);
 ```
 
 The avatar center begins the squeeze interaction. Moving more than 4 CSS pixels transfers the same pointer gesture to the existing head drag. Dragging the antenna uses the same pull limit as head dragging and ends with the existing angry reaction.
 
+## Skins · New in 0.7
+
+188 skins in 17 series, with light that follows the pointer. Every skin has a permanent number: the series number followed by two digits, so 305 is the fifth skin of series 3. Titles may be reworded later; numbers never change and are never reused.
+
+<img src="./assets/readme/skin-gallery.jpg" alt="Skin Gallery: featured skins, filters and search" width="100%">
+
+```html
+<agent-robot-avatar skin="301"></agent-robot-avatar>
+```
+
+```js
+avatar.setSkin(102);  // or '102'
+avatar.setSkin(null); // back to the flat color
+```
+
+See every skin with its number on the [all skins page](https://cx-artlab.github.io/agent-robot-avatar/materials/).
+
+| Series | Numbers |
+| --- | --- |
+| Glaze | 101–106 |
+| Ice glass | 201–206 |
+| Gummy | 301–312 |
+| Candy glass | 401–406 |
+| Acrylic | 501–512 |
+| Jelly | 601–612 |
+| Gradient | 701–712 |
+| Frosted glass | 801–806 |
+| Metal | 901–930 |
+| Gems and ceramics | 1001–1012 |
+| Wood | 1101–1106 |
+| Balls | 1201–1210 |
+| Clear and shimmer | 1301–1305 |
+| Fabric and leather | 1401–1412 |
+| Sweets and fruit | 1501–1512 |
+| Nature | 1601–1612 |
+| Patterns and tech | 1701–1717 |
+
+Skin painters download the first time a skin is used, so a page without skins never loads them. `await loadSkins()` loads them in advance. `SKINS` holds each skin’s Chinese and English titles and colors, `SKIN_SERIES` the series, and `SKIN_NAMES` every number.
+
+Every expression and gesture works with a skin. When the skin is removed, the `color` attribute applies again.
+
 ## Events and integration
 
 The component emits `face-state` for visual state changes and `action-state` for semantic action lifecycle changes.
@@ -155,13 +227,17 @@ Designed for modern browsers with support for ES Modules, Custom Elements, SVG,
 
 Automated browser tests cover Chromium, Firefox, and WebKit.
 
+## Hardware version (in development)
+
+A C++ version that shows the avatar's expressions on robot and dev-board screens (it draws only the eyes) is in development and not released yet. See the [hardware guide](https://github.com/CX-ArtLab/agent-robot-avatar/tree/main/embedded).
+
 ## Contributing
 
 Issues and pull requests are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) before submitting changes.
 
 ## Project status
 
-**Current public version: v0.5.2**
+**Current public version: v0.6.0**
 
 The public API is intentionally kept compact while the project evolves toward a future `1.0.0` stability commitment.
 
@@ -184,3 +260,4 @@ MIT License. See [`LICENSE`](./LICENSE).
 If this project is useful to you, you can buy me a coffee.
 
 <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-lite.js

@@ -0,0 +1,44 @@
+// The smallest build: every expression and gesture, without skins. The skin
+// attribute and setSkin() only explain where skins live, so a page written for
+// the full build keeps working with the plain avatar.
+import AgentRobotAvatar from './src/agent-robot-avatar-extension-host.js';
+import './src/agent-robot-avatar-actions.js';
+import './src/agent-robot-avatar-antenna.js';
+import './src/agent-robot-avatar-waiting.js';
+import './src/agent-robot-avatar-inspect.js';
+import './src/agent-robot-avatar-failure.js';
+import './src/agent-robot-avatar-love.js';
+import './src/agent-robot-avatar-random.js';
+import './src/agent-robot-avatar-head-roundness.js';
+import './src/agent-robot-avatar-gestures.js';
+import './src/agent-robot-avatar-runtime.js';
+import { VERSION } from './src/agent-robot-avatar-version.js';
+
+const proto = AgentRobotAvatar.prototype;
+let warned = false;
+function explain() {
+  if (warned) return;
+  warned = true;
+  console.warn('agent-robot-avatar: skins are not part of the lite build; import "agent-robot-avatar" instead of "agent-robot-avatar/lite" to use them.');
+}
+if (!proto.setSkin) {
+  proto._applySkinAttribute = function() { if (this.getAttribute('skin')) explain(); };
+  proto.setSkin = function(value = null) {
+    if (value !== null && value !== 'none') explain();
+    return this;
+  };
+  proto.getSkin = () => null;
+}
+
+// Elements already present in markup can upgrade while the core module is
+// loading, before runtime extensions finish installing their prototype hooks.
+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;

package/agent-robot-avatar.js

@@ -2,13 +2,13 @@ import AgentRobotAvatar from './src/agent-robot-avatar-extension-host.js';
 import './src/agent-robot-avatar-actions.js';
 import './src/agent-robot-avatar-antenna.js';
 import './src/agent-robot-avatar-waiting.js';
-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-love.js';
 import './src/agent-robot-avatar-random.js';
 import './src/agent-robot-avatar-head-roundness.js';
 import './src/agent-robot-avatar-gestures.js';
+import { SKIN_NAMES, SKINS, SKIN_SERIES, loadSkins } from './src/agent-robot-avatar-skins.js';
 import './src/agent-robot-avatar-runtime.js';
 import { VERSION } from './src/agent-robot-avatar-version.js';
 
@@ -24,5 +24,5 @@ if (typeof window !== 'undefined') {
   window.AgentRobotAvatarVersion = VERSION;
 }
 
-export { AgentRobotAvatar, VERSION };
+export { AgentRobotAvatar, SKIN_NAMES, SKINS, SKIN_SERIES, VERSION, loadSkins };
 export default AgentRobotAvatar;

package/index.d.ts

@@ -2,30 +2,99 @@ 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';
+
+/**
+ * Skin numbers for the `skin` attribute and `setSkin()`: the series number
+ * followed by two digits, so `305` is the fifth skin of series 3. A number is
+ * permanent; titles may be reworded, numbers never change and are never reused.
+ */
+export type AgentRobotAvatarSkin =
+  | '101' | '102' | '103' | '104' | '105' | '106' | '201' | '202' | '203' | '204' | '205' | '206'
+  | '301' | '302' | '303' | '304' | '305' | '306' | '307' | '308' | '309' | '310' | '311' | '312'
+  | '401' | '402' | '403' | '404' | '405' | '406' | '501' | '502' | '503' | '504' | '505' | '506'
+  | '507' | '508' | '509' | '510' | '511' | '512' | '601' | '602' | '603' | '604' | '605' | '606'
+  | '607' | '608' | '609' | '610' | '611' | '612' | '701' | '702' | '703' | '704' | '705' | '706'
+  | '707' | '708' | '709' | '710' | '711' | '712' | '801' | '802' | '803' | '804' | '805' | '806'
+  | '901' | '902' | '903' | '904' | '905' | '906' | '907' | '908' | '909' | '910' | '911' | '912'
+  | '913' | '914' | '915' | '916' | '917' | '918' | '919' | '920' | '921' | '922' | '923' | '924'
+  | '925' | '926' | '927' | '928' | '929' | '930' | '1001' | '1002' | '1003' | '1004' | '1005' | '1006'
+  | '1007' | '1008' | '1009' | '1010' | '1011' | '1012' | '1101' | '1102' | '1103' | '1104' | '1105' | '1106'
+  | '1201' | '1202' | '1203' | '1204' | '1205' | '1206' | '1207' | '1208' | '1209' | '1210' | '1301' | '1302'
+  | '1303' | '1304' | '1305' | '1401' | '1402' | '1403' | '1404' | '1405' | '1406' | '1407' | '1408' | '1409'
+  | '1410' | '1411' | '1412' | '1501' | '1502' | '1503' | '1504' | '1505' | '1506' | '1507' | '1508' | '1509'
+  | '1510' | '1511' | '1512' | '1601' | '1602' | '1603' | '1604' | '1605' | '1606' | '1607' | '1608' | '1609'
+  | '1610' | '1611' | '1612' | '1701' | '1702' | '1703' | '1704' | '1705' | '1706' | '1707' | '1708' | '1709'
+  | '1710' | '1711' | '1712' | '1713' | '1714' | '1715' | '1716' | '1717';
+
+/** Display information for one skin. */
+export interface AgentRobotAvatarSkinInfo {
+  /** The series id, such as `'glaze'` or `'metal'`. */
+  readonly series: string;
+  /** Chinese title. */
+  readonly title: string;
+  /** English title. */
+  readonly titleEn: string;
+  /** Representative colors, light to dark. */
+  readonly base: readonly string[];
+}
+
+/** A group of related skins, in gallery order. */
+export interface AgentRobotAvatarSkinSeries {
+  readonly id: string;
+  /** The first digits of every skin number in the series. */
+  readonly number: number;
+  readonly title: string;
+  readonly titleEn: string;
+  readonly skins: readonly AgentRobotAvatarSkin[];
+}
+
+/** Every skin number, in gallery order. */
+export declare const SKIN_NAMES: readonly AgentRobotAvatarSkin[];
+/** Titles and colors for every skin, by number. */
+export declare const SKINS: Readonly<Record<AgentRobotAvatarSkin, AgentRobotAvatarSkinInfo>>;
+/** The skin series, in gallery order. */
+export declare const SKIN_SERIES: readonly AgentRobotAvatarSkinSeries[];
+/**
+ * Skin painters download the first time a skin is used, so the first skin shows
+ * a moment after it is set. Await this to load them in advance.
+ */
+export declare function loadSkins(): Promise<void>;
 
 export type AgentRobotAvatarState =
   | 'idle'
@@ -39,8 +108,8 @@ export type AgentRobotAvatarState =
   | 'love'
   | 'random'
   | 'waiting'
-  | 'warning'
-  | 'error'
+  | 'wary'
+  | 'refuse'
   | 'inspect'
   | 'failure'
   | 'squeeze'
@@ -51,14 +120,13 @@ export type AgentRobotAvatarCanonicalAction =
   | 'bored'
   | 'waiting'
   | 'input'
-  | 'send'
+  | 'affirm'
   | 'success'
   | 'failure'
-  | 'warning'
+  | 'wary'
   | 'inspect'
   | 'angry'
-  | 'blocked'
-  | 'error'
+  | 'refuse'
   | 'surprise'
   | 'love'
   | 'random'
@@ -73,7 +141,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,11 +165,19 @@ 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;
   setHeadRoundness(value?: number): this;
   getHeadRoundness(): number;
+  /**
+   * Dresses the head in a numbered skin with light that follows the pointer.
+   * Same as the `skin` attribute; `null` or `'none'` returns to the flat color.
+   * Throws for an unknown number.
+   */
+  setSkin(skin?: AgentRobotAvatarSkin | number | 'none' | null): this;
+  getSkin(): AgentRobotAvatarSkin | null;
   noteActivity(wake?: boolean): void;
 
   addEventListener<K extends keyof AgentRobotAvatarEventMap>(
@@ -126,3 +202,4 @@ declare global {
     'agent-robot-avatar': AgentRobotAvatar;
   }
 }
+

package/lite.d.ts

@@ -0,0 +1,5 @@
+// The lite build: the same avatar without skins. setSkin() keeps its type so a
+// page can switch builds, but it only logs that skins need the full build.
+export { AgentRobotAvatar, VERSION } from './index.js';
+export { default } from './index.js';
+export type * from './index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-robot-avatar",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "A lightweight expressive robot avatar Web Component for AI agents and interactive applications.",
   "type": "module",
   "main": "./agent-robot-avatar.js",
@@ -14,6 +14,11 @@
       "types": "./index.d.ts",
       "import": "./agent-robot-avatar.js",
       "default": "./agent-robot-avatar.js"
+    },
+    "./lite": {
+      "types": "./lite.d.ts",
+      "import": "./agent-robot-avatar-lite.js",
+      "default": "./agent-robot-avatar-lite.js"
     }
   },
   "sideEffects": true,
@@ -21,20 +26,22 @@
     "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 test: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:browser": "playwright test"
+    "test:waiting": "node --test tests/waiting-wave.test.mjs",
+    "test:browser": "playwright test",
+    "test:pages": "node --test tests/pages-public.test.mjs"
   },
   "files": [
     "agent-robot-avatar.js",
+    "agent-robot-avatar-lite.js",
     "index.d.ts",
+    "lite.d.ts",
     "src/",
-    "assets/support/",
-    "docs/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

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');