aaavatars 2.1.0 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 # aaavatars
 
-Deterministic 2D character avatars for AI agents. Same name, same character. A `status` prop drives looping states and `play()` triggers one-shot reactions.
+Deterministic 2D character avatars for AI agents. Same name, same character. Its state is four [layers](#layers): `activity`, `expression` and `gaze` drive looping states, expressed through the eyes, and `play()` triggers one-shot reactions.
 
 [Live demo](https://rsmdt.github.io/aaavatars/)
 
@@ -11,13 +11,13 @@ npm install aaavatars
 ```
 
 ```tsx
-import { Avatar, AvatarGroup, type AvatarHandle, parseAvatarValue } from "aaavatars";
+import { Avatar, AvatarGroup, type AvatarHandle } from "aaavatars";
 
 const avatar = useRef<AvatarHandle>(null);
 
-<Avatar ref={avatar} name="Chief of Staff" size={36} status="working" label="Searching the web" />;
+<Avatar ref={avatar} name="Chief of Staff" size={36} activity="coding" label="Writing code" />;
 
-await avatar.current?.play("done");
+await avatar.current?.play("success");
 ```
 
 ## Avatar
@@ -26,23 +26,122 @@ await avatar.current?.play("done");
 |---|---|
 | `name` | seed string |
 | `frame` | `false` (no background), `0` (square) to `0.5` (circle) |
-| `status` | `idle`, `thinking`, `working`, `waiting`, `error`, `sleeping` |
+| `activity` | `idle`, `thinking`, `working`, `reading`, `searching`, `reviewing`, `coding`, `writing`, `waiting`, `asking`, `listening`, `speaking`, `stuck`, `sleeping` |
+| `expression` | `neutral`, `happy`, `sad`, `angry`, `confused`, `curious`, `tired`, `love` |
+| `gaze` | `follow` (pointer), `ponder`, `scan`, `read`, `wander`, `ahead`, `down`, `away`; defaults per activity |
 | `shape` | `circle`, `squircle`, `pill`, `hex`, `triangle`, `drop`, `cloud`, `blob` |
 | `eyes` | `round`, `dot`, `tall`, `wide` |
 | `mouth` | `none`, `smile`, `flat`, `open`, or `renderMouth={(slot) => <svg element />}` |
 | `accessory` | `none`, `antenna`, `sprout`, `hat`, `glasses`, `bowtie` |
 | `content` | `face` or `initial` |
 | `colors` / `body` / `background` | palette to pick from, or explicit hex colours |
-| `fill` / `shading` | `solid` or `gradient`; `0` to `1` |
+| `fill` / `shading` | `solid` or `gradient`; soft-clay depth from `0` (flat, the default) to `1` |
 | `src` | image URL, falls back to the character when it fails to load |
 | `badge` | node pinned to the bottom-right corner |
 | `label` | tooltip and accessible description of the current action |
-| `blink` / `look` / `motion` | turn blinking, pointer following or looping off |
+| `blink` / `motion` | turn blinking or looping off |
 | `interactive` | click, double-click, drag-to-squish and press-and-hold reactions |
+| `onChange` | called with the event when one starts playing, from `play()` or an interactive reaction, and with `null` when it ends |
 
-Unset `shape`, `eyes` and colours come from the name. `mouth` and `accessory` stay off until you set them. Each name blinks, drifts and loops at its own slightly different tempo and phase, in CSS only. With `look`, eyes follow a mouse or pen anywhere on the page through one shared listener, updated once per frame.
+Unset `shape`, `eyes` and colours come from the name. `mouth` and `accessory` stay off until you set them.
 
-`play(event)` accepts `acknowledge`, `handoff`, `done`, `success`, `failure`, `surprise`, `wake` and resolves when the animation ends. Under `prefers-reduced-motion`, or while the page is hidden, it resolves immediately.
+With `shading` above `0`, the head is shaded like soft clay: a darker rim, a sheen that rolls with the gaze, and a soft contact shadow that stays put while the body bobs.
+
+## Layers
+
+A character's state is four independent layers. Each answers one question, and each can change without touching the others.
+
+| Layer | Answers | Lasts | Set with |
+|---|---|---|---|
+| Activity | what is the agent doing? | until changed | `activity` prop |
+| Expression | how does it feel? | until changed | `expression` prop |
+| Gaze | where is it looking? | until changed | `gaze` prop, defaults per activity |
+| Event | what just happened? | about 1 to 3 seconds, then back to rest | `play(event)` |
+
+The eyes carry every layer, so a face without a mouth still reads. Each eye has a top and bottom lid, and its outline can morph into a glyph.
+
+When two layers want the same part of the face, the more specific one wins:
+
+1. An event owns the whole face while it plays. Glyph eyes morph back to round eyes for it, except `error`, which morphs them into `x x`, and return when it ends.
+2. A non-`neutral` expression owns the eyes, the blinking and, when a mouth is set, the mouth.
+3. The activity owns the body motion, the accessory motion and, while the expression is `neutral`, the eye pose and the mouth.
+4. The gaze moves where the eyes point. It never changes their shape.
+
+`sleeping` is the one exception: it keeps the eyes closed whatever the expression.
+
+### Activity
+
+An activity is the body language of a task. It is not a combination of an expression and a gaze. It sets the body's motion, picks a default gaze, and, only while the expression is `neutral`, may give the eyes their own pose: a glyph, a lid shape or a loop. It never sets an emotion, so `activity="coding" expression="happy"` is a happy coder, with the happy eyes replacing the `>_` until the expression returns to `neutral`.
+
+| Activity | Body | Eyes, with a `neutral` expression | Default gaze |
+|---|---|---|---|
+| `idle` | slow drift | | `follow` |
+| `thinking` | sway | | `ponder` |
+| `working` | quick bob | | `scan` |
+| `reading` | still | | `read` |
+| `searching` | leans in | dart in short jumps and hold, looking for something | `ahead` |
+| `reviewing` | head dips with the eyes | narrow to a slit, look down, up, back, then down once more; a 6s loop | `ahead` |
+| `coding` | bob | morph into a sharp `>_` prompt with a blinking cursor | `ahead` |
+| `writing` | slow bob | | `read` |
+| `waiting` | still | settle to the centre, then circle around each other twice every 3.2s | `ahead` |
+| `asking` | head tilted | still, one eye wider: the person's turn to answer or approve | `ahead` |
+| `listening` | nod | slide together into one tall blinking cursor | `ahead` |
+| `speaking` | bob, mouth talks | | `follow` |
+| `stuck` | tilted | sweep side to side once, then morph into sharp `x x` crosses | `ahead` |
+| `sleeping` | breathe, sunk | droop, catch themselves once, droop again and close. Leaving it wakes them: half-open, wide, back to rest | `ahead` |
+
+### Expression
+
+An expression is a mood that can last for minutes, shown through the lids and, when set, the mouth. A feeling that only makes sense for a moment, like surprise, is an event instead, so no value belongs to both layers.
+
+| Expression | Eyes |
+|---|---|
+| `neutral` | the activity's eyes |
+| `happy` | bottom lids raised |
+| `sad` | top lids down, tilted outward |
+| `angry` | top lids down, tilted inward |
+| `confused` | one lid lowered |
+| `love` | both eyes tilt together into one beating heart |
+| `tired` | heavy top lids, drooping outward |
+| `curious` | both eyes slightly wider |
+
+### Gaze
+
+A gaze is a pattern of where to look. It works with any activity and any eye shape, and only moves the eyes. A loop that also needs the lids or the head, like `reviewing` or `waiting`, belongs to the activity instead.
+
+| Gaze | Eyes |
+|---|---|
+| `follow` | follow a mouse or pen anywhere on the page while it moves, then return to glancing 0.9s after it stops |
+| `wander` | glance around and hold, ignoring the pointer |
+| `ponder` | look up-left, then up-right, then back |
+| `scan` | sweep across: slow right, quick jump back |
+| `read` | read line by line: three short hops right, jump back and down a line, three lines, then back to the top |
+| `ahead` | look straight out |
+| `down` | look down at the work, drifting a little side to side |
+| `away` | look off to the side, with a brief check-in straight ahead |
+
+### Event
+
+An event is a one-off reaction. `play(event)` resolves when the animation ends. Each reaction first centres the eyes and settles for half a second, except when triggered by a click or press.
+
+An event does not change the `activity`, `expression` or `gaze` props. `EVENT_LAYERS[event]` names the expression and gaze it shows while it plays, for example `success` shows `happy` eyes looking `ahead`. Pair it with `onChange` to mirror the face in your own UI.
+
+| Event | Reaction |
+|---|---|
+| `acknowledge` | a double nod of the eyes |
+| `handoff` | eyes and body lean to the side, then return |
+| `success` | happy eyes with a long bounce |
+| `warning` | a wince: the eyes shift aside, heavy lids press down twice, the head dips and rises |
+| `error` | the eyes morph into `x x` crosses, then the head and eyes sink, hold, and recover |
+| `surprised` | a squint, then wide eyes with a tremble |
+| `sigh` | a small breath in, then the lids sink and the head slumps before it recovers |
+| `yawn` | the head stretches tall while the eyes close, then a blink awake |
+
+Under `prefers-reduced-motion`, or while the page is hidden, `play()` resolves immediately.
+
+### Rendering
+
+Each name blinks, glances and loops at its own tempo and phase, in CSS only. The `follow` gaze uses one shared pointer listener, updated once per frame. Offscreen avatars pause their loops. The glyphs (`>_`, `x x`, the cursor) are the eyes themselves, morphing their outline: smoothly in Chrome and Firefox, as an instant swap in Safari, which does not animate the SVG `d` property.
 
 ## AvatarGroup
 
@@ -50,10 +149,6 @@ Unset `shape`, `eyes` and colours come from the name. `mouth` and `accessory` st
 <AvatarGroup max={4} size={28} members={[{ name: "Ada", content: "initial" }, { name: "Research" }]} />
 ```
 
-## Stored value
-
-`formatAvatarValue({ shape: "hex", accessory: "hat" })` gives `shape=hex;accessory=hat`. `parseAvatarValue(text)` returns `{ ok: true, value }` to spread onto `<Avatar>`, or `{ ok: false, error }` naming the invalid field.
-
 ## Static SVG
 
 ```ts

package/dist/Avatar.d.ts

@@ -2,14 +2,23 @@ import { type ReactNode } from "react";
 import { type AvatarEvent } from "./animations.js";
 import { type RenderMouth } from "./parts.js";
 import { type Accessory, type Eyes, type Fill, type Mouth, type Shape } from "./spec.js";
-export declare const AVATAR_STATUSES: readonly ["idle", "thinking", "working", "waiting", "error", "sleeping"];
-export type AvatarStatus = (typeof AVATAR_STATUSES)[number];
+export declare const ACTIVITIES: readonly ["idle", "thinking", "working", "reading", "searching", "reviewing", "coding", "writing", "waiting", "asking", "listening", "speaking", "stuck", "sleeping"];
+export declare const EXPRESSIONS: readonly ["neutral", "happy", "sad", "angry", "confused", "curious", "tired", "love"];
+export declare const GAZES: readonly ["follow", "ponder", "scan", "read", "wander", "ahead", "down", "away"];
+export type Activity = (typeof ACTIVITIES)[number];
+export type Expression = (typeof EXPRESSIONS)[number];
+export type Gaze = (typeof GAZES)[number];
+export declare const EVENT_LAYERS: Record<AvatarEvent, {
+    expression: Expression;
+    gaze: Gaze;
+}>;
 export type AvatarContent = "face" | "initial";
 export interface AvatarHandle {
     play: (event: AvatarEvent) => Promise<void>;
 }
 export interface AvatarProps {
     accessory?: Accessory;
+    activity?: Activity;
     background?: string;
     badge?: ReactNode;
     blink?: boolean;
@@ -17,21 +26,22 @@ export interface AvatarProps {
     className?: string;
     colors?: readonly string[];
     content?: AvatarContent;
+    expression?: Expression;
     eyes?: Eyes;
     fill?: Fill;
     frame?: false | number;
+    gaze?: Gaze;
     interactive?: boolean;
     label?: string;
-    look?: boolean;
     motion?: boolean;
     mouth?: Mouth;
     name: string;
+    onChange?: (event: AvatarEvent | null) => void;
     renderMouth?: RenderMouth;
     shading?: number;
     shape?: Shape;
     size?: number;
     src?: string;
-    status?: AvatarStatus;
 }
 export declare function frameRadius(frame: false | number | undefined): string | undefined;
 export declare const Avatar: import("react").ForwardRefExoticComponent<AvatarProps & import("react").RefAttributes<AvatarHandle>>;

package/dist/Avatar.js

@@ -1,19 +1,70 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState, } from "react";
-import { EVENT_ANIMATIONS, MOOD_SWAP_REST, MOOD_SWAP_SHOW, } from "./animations.js";
+import { EVENT_ANIMATIONS, MOOD_SWAP_REST, MOOD_SWAP_SHOW, PREP_MS, SLEEP_ANIMATION, STUCK_ANIMATION, WAKE_ANIMATION, stage, } from "./animations.js";
 import { SHAPE_GEOMETRY } from "./geometry.js";
 import { AccessoryShape, EyePair, MoodMouths, MouthShape, mouthSlot, } from "./parts.js";
 import { createSpec, shadeHex, } from "./spec.js";
-import { watchPointer } from "./pointer.js";
+import { restartGazeCentred, watchPointer } from "./pointer.js";
 import { AVATAR_CSS } from "./styles.js";
-export const AVATAR_STATUSES = [
+import { watchVisibility } from "./visibility.js";
+export const ACTIVITIES = [
     "idle",
     "thinking",
     "working",
+    "reading",
+    "searching",
+    "reviewing",
+    "coding",
+    "writing",
     "waiting",
-    "error",
+    "asking",
+    "listening",
+    "speaking",
+    "stuck",
     "sleeping",
 ];
+export const EXPRESSIONS = [
+    "neutral",
+    "happy",
+    "sad",
+    "angry",
+    "confused",
+    "curious",
+    "tired",
+    "love",
+];
+export const GAZES = ["follow", "ponder", "scan", "read", "wander", "ahead", "down", "away"];
+const ACTIVITY_GAZE = {
+    idle: "follow",
+    thinking: "ponder",
+    working: "scan",
+    reading: "read",
+    searching: "ahead",
+    reviewing: "ahead",
+    coding: "ahead",
+    writing: "read",
+    waiting: "ahead",
+    asking: "ahead",
+    listening: "ahead",
+    speaking: "follow",
+    stuck: "ahead",
+    sleeping: "ahead",
+};
+export const EVENT_LAYERS = {
+    acknowledge: { expression: "neutral", gaze: "ahead" },
+    handoff: { expression: "neutral", gaze: "ahead" },
+    success: { expression: "happy", gaze: "ahead" },
+    warning: { expression: "neutral", gaze: "ahead" },
+    error: { expression: "neutral", gaze: "ahead" },
+    surprised: { expression: "neutral", gaze: "ahead" },
+    sigh: { expression: "tired", gaze: "ahead" },
+    yawn: { expression: "tired", gaze: "ahead" },
+};
+const ACTIVITY_POSE = {
+    coding: "prompt",
+    stuck: "cross",
+    listening: "cursor",
+};
 const DRAG_THRESHOLD = 3;
 const HOLD_MS = 600;
 const SQUISH_LIMIT = 40;
@@ -21,6 +72,44 @@ function prefersReducedMotion() {
     return (typeof window.matchMedia === "function" &&
         window.matchMedia("(prefers-reduced-motion: reduce)").matches);
 }
+function lidPairs(root, lids) {
+    if (!root || !lids)
+        return [];
+    return [...root.querySelectorAll(".aaa-lid")].map((lid) => {
+        const half = Number(lid.dataset.h);
+        const top = lid.classList.contains("aaa-lid-top");
+        const side = lid.classList.contains("aaa-lid-l") ? -1 : 1;
+        return [
+            lid,
+            lids.map(({ bottom, easing, offset, tilt = 0, top: drop }) => {
+                if (bottom === undefined && drop === undefined)
+                    return { offset, ...(easing && { easing }) };
+                const transform = top
+                    ? `translateY(${((drop ?? 0) * half).toFixed(2)}px) rotate(${side * tilt}deg)`
+                    : `translateY(${(-(bottom ?? 0) * half).toFixed(2)}px)`;
+                return { offset, transform, ...(easing && { easing }) };
+            }),
+        ];
+    });
+}
+function eyePairs(root, animation) {
+    const frames = animation.eye;
+    if (!root || !frames)
+        return [];
+    return [...root.querySelectorAll(".aaa-eye")].map((eye) => [
+        eye,
+        frames(eye.classList.contains("aaa-eye-l") ? -1 : 1, {
+            gap: Number(eye.dataset.gap),
+            h: Number(eye.dataset.h),
+            w: Number(eye.dataset.w),
+        }),
+    ]);
+}
+function heldValues(element, frames) {
+    const style = getComputedStyle(element);
+    const properties = new Set(frames.flatMap((frame) => Object.keys(frame).filter((key) => !["offset", "easing", "composite", "transform"].includes(key))));
+    return Object.fromEntries([...properties].map((property) => [property, style.getPropertyValue(property)]));
+}
 function clampFrame(frame) {
     return Math.min(Math.max(frame, 0), 0.5);
 }
@@ -29,7 +118,7 @@ export function frameRadius(frame) {
         return undefined;
     return `${clampFrame(frame ?? 0.5) * 100}%`;
 }
-export const Avatar = forwardRef(function Avatar({ accessory, background, badge, blink = true, body, className, colors, content = "face", eyes, fill = "solid", frame = 0.5, interactive = false, label, look = true, motion = true, mouth, name, renderMouth, shading = 0, shape, size = 64, src, status = "idle", }, ref) {
+export const Avatar = forwardRef(function Avatar({ accessory, activity = "idle", background, badge, blink = true, body, className, colors, content = "face", expression = "neutral", eyes, fill = "solid", frame = 0.5, gaze, interactive = false, label, motion = true, mouth, name, onChange, renderMouth, shading = 0, shape, size = 64, src, }, ref) {
     const uid = `aaa-${useId().replace(/[^a-zA-Z0-9-_]/g, "")}`;
     const svgRef = useRef(null);
     const bodyRef = useRef(null);
@@ -39,6 +128,10 @@ export const Avatar = forwardRef(function Avatar({ accessory, background, badge,
     const drag = useRef(null);
     const suppressClick = useRef(false);
     const [imageFailed, setImageFailed] = useState(false);
+    const [reacting, setReacting] = useState(null);
+    const latestOnChange = useRef(onChange);
+    latestOnChange.current = onChange;
+    const latestPlay = useRef(0);
     useEffect(() => setImageFailed(false), [src]);
     const spec = useMemo(() => createSpec(name, { accessory, background, body, colors, eyes, mouth, shape }), [name, accessory, background, body, colors, eyes, mouth, shape]);
     const geometry = SHAPE_GEOMETRY[spec.shape];
@@ -47,13 +140,18 @@ export const Avatar = forwardRef(function Avatar({ accessory, background, badge,
     const showImage = Boolean(src) && !imageFailed;
     const hasMouth = content === "face" && (Boolean(renderMouth) || spec.mouth !== "none");
     const accessoryBehind = spec.accessory === "antenna" || spec.accessory === "sprout";
-    const tracksPointer = look && !showImage;
+    const resolvedGaze = gaze ?? ACTIVITY_GAZE[activity];
+    const shownExpression = activity === "sleeping" ? "neutral" : expression;
+    const pose = reacting ?? (shownExpression === "neutral" ? (ACTIVITY_POSE[activity] ?? "eye") : "eye");
+    const tracksPointer = resolvedGaze === "follow" && !showImage;
     const slot = mouthSlot(geometry, spec.eyeColor);
     const bodyFill = fill === "gradient" ? `url(#${uid}-fill)` : spec.body;
+    const clay = shading > 0;
+    const sheenY = geometry.top + (geometry.bottom - geometry.top) * 0.26;
     const placement = framed
         ? `translate(${50 + spec.offsetX} ${50 + spec.offsetY}) rotate(${spec.rotate}) scale(0.78) translate(-50 -50)`
         : "translate(50 50) scale(0.92) translate(-50 -50)";
-    const play = useCallback((event) => {
+    const run = useCallback((name, animation, immediate = false) => {
         for (const animation of running.current)
             animation.cancel();
         const target = bodyRef.current;
@@ -64,8 +162,8 @@ export const Avatar = forwardRef(function Avatar({ accessory, background, badge,
             prefersReducedMotion()) {
             return Promise.resolve();
         }
-        const animation = EVENT_ANIMATIONS[event];
-        const timing = { duration: animation.duration, easing: "ease-in-out" };
+        const prep = immediate ? 0 : (animation.prep ?? PREP_MS);
+        const timing = { duration: prep + animation.duration, easing: "linear" };
         const root = svgRef.current;
         const rest = root?.querySelector(".aaa-mouth-rest");
         const accessory = root?.querySelector(".aaa-accessory");
@@ -80,11 +178,50 @@ export const Avatar = forwardRef(function Avatar({ accessory, background, badge,
             [rest, animation.mood ? (animation.mood.rest ?? MOOD_SWAP_REST) : animation.mouth],
             [mood, animation.mood ? (animation.mood.frames ?? MOOD_SWAP_SHOW) : undefined],
             [accessory, accessoryFrames],
+            ...lidPairs(root, animation.lids),
+            ...eyePairs(root, animation),
         ];
-        running.current = pairs.flatMap(([element, frames]) => element && frames ? [element.animate(frames, timing)] : []);
-        return Promise.all(running.current.map((animation) => animation.finished)).then(() => undefined, () => undefined);
+        const started = pairs.flatMap(([element, frames]) => element && frames?.length
+            ? [element.animate(stage(frames, animation.duration, prep, heldValues(element, frames)), timing)]
+            : []);
+        running.current = started;
+        root?.setAttribute("data-reacting", name);
+        setReacting(animation.pose ?? "eye");
+        return Promise.all(started.map((animation) => animation.finished)).then(() => undefined, () => undefined).then(() => {
+            if (running.current !== started || !root)
+                return;
+            restartGazeCentred(root);
+            root.removeAttribute("data-reacting");
+            setReacting(null);
+        });
+    }, []);
+    const play = useCallback(async (event, immediate = false) => {
+        const id = ++latestPlay.current;
+        latestOnChange.current?.(event);
+        await run(event, EVENT_ANIMATIONS[event], immediate);
+        if (id === latestPlay.current)
+            latestOnChange.current?.(null);
+    }, [run]);
+    useImperativeHandle(ref, () => ({ play: (event) => play(event) }), [play]);
+    const previousActivity = useRef(activity);
+    useEffect(() => {
+        const previous = previousActivity.current;
+        previousActivity.current = activity;
+        if (previous === activity)
+            return;
+        if (activity === "sleeping")
+            void run("sleep", SLEEP_ANIMATION);
+        else if (previous === "sleeping")
+            void run("wake", WAKE_ANIMATION);
+        else if (activity === "stuck")
+            void run("stuck", STUCK_ANIMATION);
+    }, [activity, play, run]);
+    useEffect(() => {
+        const svg = svgRef.current;
+        if (!svg)
+            return;
+        return watchVisibility(svg);
     }, []);
-    useImperativeHandle(ref, () => ({ play }), [play]);
     useEffect(() => {
         const svg = svgRef.current;
         if (!tracksPointer || !svg || prefersReducedMotion())
@@ -102,7 +239,7 @@ export const Avatar = forwardRef(function Avatar({ accessory, background, badge,
         };
         state.holdTimer = setTimeout(() => {
             state.held = true;
-            void play("success");
+            void play("success", true);
         }, HOLD_MS);
         drag.current = state;
     }
@@ -143,12 +280,16 @@ export const Avatar = forwardRef(function Avatar({ accessory, background, badge,
             suppressClick.current = false;
             return;
         }
-        void play(event.detail > 1 ? "surprise" : "acknowledge");
+        void play(event.detail > 1 ? "surprised" : "acknowledge", true);
     }
-    const svg = (_jsxs("svg", { ref: svgRef, "aria-label": label ? `${name}, ${label}` : name, className: className && !badge ? `aaa ${className}` : "aaa", "data-blink": blink ? undefined : "off", "data-interactive": interactive ? "" : undefined, "data-motion": motion ? undefined : "off", "data-status": status, height: size, overflow: framed ? undefined : "visible", role: "img", style: { "--aaa-phase": spec.phase, "--aaa-tempo": spec.tempo }, viewBox: "0 0 100 100", width: size, onClick: interactive ? handleClick : undefined, onPointerCancel: interactive ? endDrag : undefined, onPointerDown: interactive ? startDrag : undefined, onPointerMove: interactive ? moveDrag : undefined, onPointerUp: interactive ? endDrag : undefined, children: [label ? _jsx("title", { children: label }) : null, _jsx("style", { children: AVATAR_CSS }), _jsxs("defs", { children: [framed ? (_jsx("clipPath", { id: `${uid}-frame`, children: _jsx("rect", { width: 100, height: 100, rx: radius }) })) : null, fill === "gradient" ? (_jsxs("linearGradient", { id: `${uid}-fill`, x1: "0", y1: "0", x2: "1", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: shadeHex(spec.body, 0.18) }), _jsx("stop", { offset: "100%", stopColor: shadeHex(spec.body, -0.22) })] })) : null, shading > 0 ? (_jsxs("radialGradient", { id: `${uid}-shade`, cx: "0.35", cy: "0.3", r: "0.85", children: [_jsx("stop", { offset: "0%", stopColor: "#ffffff", stopOpacity: 0.55 * shading }), _jsx("stop", { offset: "45%", stopColor: "#ffffff", stopOpacity: 0 }), _jsx("stop", { offset: "100%", stopColor: "#000000", stopOpacity: 0.35 * shading })] })) : null] }), framed ? (_jsx("rect", { "data-frame": "", width: 100, height: 100, rx: radius, fill: spec.background })) : null, _jsx("g", { clipPath: framed ? `url(#${uid}-frame)` : undefined, children: showImage ? (_jsx("g", { ref: bodyRef, className: "aaa-react", children: _jsx("image", { "data-image": "", height: 100, href: src, preserveAspectRatio: "xMidYMid slice", width: 100, onError: () => setImageFailed(true) }) })) : (_jsx("g", { transform: placement, children: _jsx("g", { ref: squishRef, className: "aaa-squish", children: _jsx("g", { className: "aaa-body-motion", children: _jsxs("g", { ref: bodyRef, className: "aaa-react", children: [accessoryBehind ? (_jsx(AccessoryShape, { accent: spec.accent, accessory: spec.accessory, body: spec.body, geometry: geometry })) : null, _jsx("path", { d: geometry.path, fill: bodyFill, stroke: bodyFill, strokeLinejoin: "round", strokeWidth: 8 }), shading > 0 ? (_jsx("path", { d: geometry.path, fill: `url(#${uid}-shade)`, stroke: `url(#${uid}-shade)`, strokeLinejoin: "round", strokeWidth: 8 })) : null, _jsx("g", { ref: eyesRef, className: "aaa-eyes-react", fill: spec.eyeColor, children: _jsx("g", { className: "aaa-look", children: content === "initial" ? (_jsx("text", { dominantBaseline: "central", fontFamily: "system-ui, sans-serif", fontSize: 38, fontWeight: 700, textAnchor: "middle", x: 50, y: (geometry.top + geometry.bottom) / 2 + 2, children: name.trim().charAt(0).toUpperCase() })) : (_jsx("g", { className: "aaa-eyes-motion", children: _jsx("g", { className: "aaa-blink", style: {
-                                                        animationDelay: `${spec.blinkDelay}s`,
-                                                        animationDuration: `${spec.blinkDuration}s`,
-                                                    }, children: _jsx(EyePair, { eyes: spec.eyes, gap: geometry.eyeGap, y: geometry.eyeY }) }) })) }) }), hasMouth ? (_jsxs("g", { className: "aaa-look", children: [_jsx("g", { className: "aaa-mouth-rest", children: renderMouth ? (renderMouth(slot)) : (_jsx(MouthShape, { mouth: spec.mouth, slot: slot })) }), _jsx(MoodMouths, { slot: slot })] })) : null, !accessoryBehind && (spec.accessory !== "glasses" || content === "face") ? (_jsx(AccessoryShape, { accent: spec.accent, accessory: spec.accessory, body: spec.body, geometry: geometry })) : null] }) }) }) })) })] }));
+    const svg = (_jsxs("svg", { ref: svgRef, "aria-label": label ? `${name}, ${label}` : name, className: className && !badge ? `aaa ${className}` : "aaa", "data-activity": activity, "data-blink": blink ? undefined : "off", "data-expression": shownExpression, "data-gaze": resolvedGaze, "data-interactive": interactive ? "" : undefined, "data-motion": motion ? undefined : "off", height: size, overflow: framed ? undefined : "visible", role: "img", style: {
+            "--aaa-gap": geometry.eyeGap,
+            "--aaa-phase": spec.phase,
+            "--aaa-tempo": spec.tempo,
+        }, viewBox: "0 0 100 100", width: size, onClick: interactive ? handleClick : undefined, onPointerCancel: interactive ? endDrag : undefined, onPointerDown: interactive ? startDrag : undefined, onPointerMove: interactive ? moveDrag : undefined, onPointerUp: interactive ? endDrag : undefined, children: [label ? _jsx("title", { children: label }) : null, _jsx("style", { children: AVATAR_CSS }), _jsxs("defs", { children: [framed ? (_jsx("clipPath", { id: `${uid}-frame`, children: _jsx("rect", { width: 100, height: 100, rx: radius }) })) : null, fill === "gradient" ? (_jsxs("linearGradient", { id: `${uid}-fill`, x1: "0", y1: "0", x2: "1", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: shadeHex(spec.body, 0.18) }), _jsx("stop", { offset: "100%", stopColor: shadeHex(spec.body, -0.22) })] })) : null, clay ? (_jsxs(_Fragment, { children: [_jsx("clipPath", { id: `${uid}-body`, children: _jsx("path", { d: geometry.path }) }), _jsxs("mask", { id: `${uid}-outside`, maskUnits: "userSpaceOnUse", x: -20, y: -20, width: 140, height: 140, children: [_jsx("rect", { x: -20, y: -20, width: 140, height: 140, fill: "#fff" }), _jsx("path", { d: geometry.path, fill: "#000" })] }), _jsxs("radialGradient", { id: `${uid}-rim`, cx: "0.5", cy: "0.5", fx: "0.42", fy: "0.36", r: "0.5", children: [_jsx("stop", { offset: "45%", stopColor: "#000000", stopOpacity: 0 }), _jsx("stop", { offset: "80%", stopColor: "#000000", stopOpacity: 0.1 * shading }), _jsx("stop", { offset: "100%", stopColor: "#000000", stopOpacity: 0.3 * shading })] }), _jsxs("radialGradient", { id: `${uid}-sheen`, children: [_jsx("stop", { offset: "0%", stopColor: "#ffffff", stopOpacity: 0.6 * shading }), _jsx("stop", { offset: "100%", stopColor: "#ffffff", stopOpacity: 0 })] }), _jsxs("radialGradient", { id: `${uid}-shadow`, children: [_jsx("stop", { offset: "0%", stopColor: "#000000", stopOpacity: 0.3 * shading }), _jsx("stop", { offset: "100%", stopColor: "#000000", stopOpacity: 0 })] })] })) : null] }), framed ? (_jsx("rect", { "data-frame": "", width: 100, height: 100, rx: radius, fill: spec.background })) : null, _jsx("g", { clipPath: framed ? `url(#${uid}-frame)` : undefined, children: showImage ? (_jsx("g", { ref: bodyRef, className: "aaa-react", children: _jsx("image", { "data-image": "", height: 100, href: src, preserveAspectRatio: "xMidYMid slice", width: 100, onError: () => setImageFailed(true) }) })) : (_jsx("g", { transform: placement, children: _jsx("g", { ref: squishRef, className: "aaa-squish", children: _jsxs("g", { className: "aaa-head", children: [clay ? (_jsx("ellipse", { className: "aaa-shadow", cx: 50, cy: geometry.bottom + 5, fill: `url(#${uid}-shadow)`, rx: 30, ry: 5 })) : null, _jsx("g", { className: "aaa-body-motion", children: _jsxs("g", { ref: bodyRef, className: "aaa-react", children: [accessoryBehind ? (_jsx(AccessoryShape, { accent: spec.accent, accessory: spec.accessory, body: spec.body, geometry: geometry })) : null, _jsx("path", { d: geometry.path, fill: bodyFill, stroke: bodyFill, strokeLinejoin: "round", strokeWidth: 8 }), clay ? (_jsxs(_Fragment, { children: [_jsxs("g", { className: "aaa-rim", children: [_jsx("path", { d: geometry.path, fill: `url(#${uid}-rim)` }), _jsx("path", { d: geometry.path, fill: "none", mask: `url(#${uid}-outside)`, stroke: "#000000", strokeLinejoin: "round", strokeOpacity: 0.3 * shading, strokeWidth: 8 })] }), _jsx("g", { clipPath: `url(#${uid}-body)`, children: _jsx("g", { className: "aaa-look", children: _jsx("g", { className: "aaa-gaze", children: _jsx("ellipse", { className: "aaa-sheen", cx: 39, cy: sheenY, fill: `url(#${uid}-sheen)`, rx: 17, ry: 11, transform: `rotate(-24 39 ${sheenY})` }) }) }) })] })) : null, _jsx("g", { ref: eyesRef, className: "aaa-eyes-react", fill: spec.eyeColor, children: _jsx("g", { className: "aaa-look", children: content === "initial" ? (_jsx("text", { dominantBaseline: "central", fontFamily: "system-ui, sans-serif", fontSize: 38, fontWeight: 700, textAnchor: "middle", x: 50, y: (geometry.top + geometry.bottom) / 2 + 2, children: name.trim().charAt(0).toUpperCase() })) : (_jsx("g", { className: "aaa-gaze", children: _jsx("g", { className: "aaa-eyes-motion", children: _jsx("g", { className: "aaa-blink", style: {
+                                                                    animationDelay: `${spec.blinkDelay}s`,
+                                                                    animationDuration: `${spec.blinkDuration * 2}s`,
+                                                                }, children: _jsx(EyePair, { eyes: spec.eyes, gap: geometry.eyeGap, id: uid, pose: pose, y: geometry.eyeY }) }) }) })) }) }), hasMouth ? (_jsxs("g", { className: "aaa-look", children: [_jsx("g", { className: "aaa-mouth-rest", children: renderMouth ? (renderMouth(slot)) : (_jsx(MouthShape, { mouth: spec.mouth, slot: slot })) }), _jsx(MoodMouths, { slot: slot })] })) : null, !accessoryBehind && (spec.accessory !== "glasses" || content === "face") ? (_jsx(AccessoryShape, { accent: spec.accent, accessory: spec.accessory, body: spec.body, geometry: geometry })) : null] }) })] }) }) })) })] }));
     if (!badge)
         return svg;
     return (_jsxs("span", { className: className, style: {

package/dist/animations.d.ts

@@ -1,21 +1,46 @@
-export declare const AVATAR_EVENTS: readonly ["acknowledge", "handoff", "done", "success", "failure", "surprise", "wake"];
-import type { Mood } from "./parts.js";
+export declare const AVATAR_EVENTS: readonly ["acknowledge", "handoff", "success", "warning", "error", "surprised", "sigh", "yawn"];
+import type { EyePose, Mood } from "./parts.js";
 import type { Accessory } from "./spec.js";
 export type AvatarEvent = (typeof AVATAR_EVENTS)[number];
 type AccessoryFrames = Partial<Record<Exclude<Accessory, "none">, Keyframe[]>>;
-interface EventAnimation {
+export interface LidFrame {
+    bottom?: number;
+    easing?: string;
+    offset: number;
+    tilt?: number;
+    top?: number;
+}
+export interface EyeSize {
+    gap: number;
+    h: number;
+    w: number;
+}
+export interface EventAnimation {
     accessory?: AccessoryFrames;
     body: Keyframe[];
     duration: number;
+    eye?: (side: -1 | 1, size: EyeSize) => Keyframe[];
     eyes: Keyframe[];
+    lids?: LidFrame[];
     mood?: {
         frames?: Keyframe[];
         name: Mood;
         rest?: Keyframe[];
     };
     mouth?: Keyframe[];
+    pose?: EyePose;
+    prep?: number;
 }
+export declare const EASE_OUT = "cubic-bezier(.22,1,.36,1)";
+export declare const EASE_IN_OUT = "cubic-bezier(.65,0,.35,1)";
+export declare const EASE_HEAD = "cubic-bezier(.16,1,.3,1)";
+export declare const EASE_SINE = "cubic-bezier(.37,0,.63,1)";
+export declare const PREP_MS = 500;
+export declare function stage(frames: Keyframe[], duration: number, prep: number, current?: Keyframe): Keyframe[];
 export declare const MOOD_SWAP_REST: Keyframe[];
 export declare const MOOD_SWAP_SHOW: Keyframe[];
 export declare const EVENT_ANIMATIONS: Record<AvatarEvent, EventAnimation>;
+export declare const WAKE_ANIMATION: EventAnimation;
+export declare const SLEEP_ANIMATION: EventAnimation;
+export declare const STUCK_ANIMATION: EventAnimation;
 export {};