aaavatars 3.0.1 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # aaavatars
 
-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.
+Deterministic 2D character avatars for AI agents. Same name, same character. The eyes show what the agent is doing, how it feels, where it looks and what just happened.
 
 [Live demo](https://rsmdt.github.io/aaavatars/)
 
@@ -11,11 +11,11 @@ npm install aaavatars
 ```
 
 ```tsx
-import { Avatar, AvatarGroup, type AvatarHandle } from "aaavatars";
+import { Avatar, type AvatarHandle } from "aaavatars";
 
 const avatar = useRef<AvatarHandle>(null);
 
-<Avatar ref={avatar} name="Chief of Staff" size={36} activity="coding" label="Writing code" />;
+<Avatar ref={avatar} name="Chief of Staff" frame={0.5} blink loop activity="coding" />;
 
 await avatar.current?.play("success");
 ```
@@ -25,75 +25,57 @@ await avatar.current?.play("success");
 | Prop | Values |
 |---|---|
 | `name` | seed string |
-| `frame` | `false` (no background), `0` (square) to `0.5` (circle) |
-| `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 |
+| `activity` / `expression` / `gaze` | see [Layers](#layers) |
+| `frame` | background from `0` (square) to `0.5` (circle) |
+| `blink` / `loop` | blinking and the looping animations |
+| `interactive` | click, double-click, drag-to-squish and press-and-hold reactions |
 | `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`; soft-clay depth from `0` (flat, the default) to `1` |
+| `fill` | `solid` or `gradient` |
+| `shading` | soft-clay depth from `0` 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` / `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 |
+| `label` | tooltip and accessible description |
+| `onChange` | called with an event when it starts playing, and `null` when it ends |
 
-Unset `shape`, `eyes` and colours come from the name. `mouth` and `accessory` stay off until you set them.
-
-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.
+`frame`, `blink`, `loop`, `interactive`, `mouth`, `accessory` and `shading` are off until you set them. Unset `shape`, `eyes` and colours come from the name.
 
 ## 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.
+| Layer | Answers | Set with |
+|---|---|---|
+| Activity | what is it doing? | `activity` |
+| Expression | how does it feel? | `expression` |
+| Gaze | where is it looking? | `gaze`, defaults per activity |
+| Event | what just happened? | `play(event)`, lasts 1 to 3 seconds |
 
-`sleeping` is the one exception: it keeps the eyes closed whatever the expression.
+Each layer changes without touching the others. While an event plays it owns the face. Otherwise a non-`neutral` expression owns the eyes, the activity owns the body, and the gaze only moves where the eyes point.
 
 ### 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 |
+| Activity | Body | Eyes, while `neutral` | 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` |
+| `searching` | leans in | dart and hold | `ahead` |
+| `reviewing` | head dips | narrow, look down and up | `ahead` |
+| `coding` | bob | a `>_` 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` |
+| `waiting` | still | circle around each other | `ahead` |
+| `asking` | head tilted | one eye wider | `ahead` |
+| `listening` | nod | 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` |
+| `stuck` | tilted | sweep, then `x x` | `ahead` |
+| `sleeping` | breathe, sunk | droop and close, whatever the expression | `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 |
@@ -102,46 +84,36 @@ An expression is a mood that can last for minutes, shown through the lids and, w
 | `angry` | top lids down, tilted inward |
 | `confused` | one lid lowered |
 | `curious` | both eyes slightly wider |
-| `tired` | heavy top lids, drooping outward |
-| `love` | both eyes tilt together into one beating heart |
+| `tired` | heavy top lids |
+| `love` | one beating heart |
 
 ### 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 |
+| `follow` | follow the pointer anywhere on the page |
+| `wander` | glance around, ignoring the pointer |
+| `ponder` | look up-left, then up-right |
+| `scan` | sweep right, jump back |
+| `read` | read line by line |
 | `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 |
+| `down` | look down at the work |
+| `away` | look off to the side |
 
 ### 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.
+`play(event)` resolves when the reaction ends, or immediately under `prefers-reduced-motion`. It does not change the props. `EVENT_LAYERS[event]` names the expression and gaze it shows, for example `success` shows `happy` eyes looking `ahead`.
 
 | 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.
+| `acknowledge` | a double nod |
+| `handoff` | lean to the side and back |
+| `success` | happy eyes with a bounce |
+| `warning` | a wince |
+| `error` | `x x` eyes, then sink and recover |
+| `surprised` | a squint, then wide eyes |
+| `sigh` | breathe in, then slump |
+| `yawn` | stretch tall with closed eyes |
 
 ## AvatarGroup
 
@@ -159,8 +131,10 @@ const svg = renderAvatarSvg({ name: "Research", size: 128 });
 
 Requires `react-dom`.
 
+## Development
+
 ```sh
-npm run dev        # playground
+npm run dev
 npm test
 npm run build
 ```

package/dist/Avatar.d.ts

@@ -29,11 +29,11 @@ export interface AvatarProps {
     expression?: Expression;
     eyes?: Eyes;
     fill?: Fill;
-    frame?: false | number;
+    frame?: number;
     gaze?: Gaze;
     interactive?: boolean;
     label?: string;
-    motion?: boolean;
+    loop?: boolean;
     mouth?: Mouth;
     name: string;
     onChange?: (event: AvatarEvent | null) => void;
@@ -43,5 +43,5 @@ export interface AvatarProps {
     size?: number;
     src?: string;
 }
-export declare function frameRadius(frame: false | number | undefined): string | undefined;
+export declare function frameRadius(frame: number | undefined): string | undefined;
 export declare const Avatar: import("react").ForwardRefExoticComponent<AvatarProps & import("react").RefAttributes<AvatarHandle>>;

package/dist/Avatar.js

@@ -114,11 +114,11 @@ function clampFrame(frame) {
     return Math.min(Math.max(frame, 0), 0.5);
 }
 export function frameRadius(frame) {
-    if (frame === false)
+    if (frame === undefined)
         return undefined;
-    return `${clampFrame(frame ?? 0.5) * 100}%`;
+    return `${clampFrame(frame) * 100}%`;
 }
-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) {
+export const Avatar = forwardRef(function Avatar({ accessory, activity = "idle", background, badge, blink = false, body, className, colors, content = "face", expression = "neutral", eyes, fill = "solid", frame, gaze, interactive = false, label, loop = false, 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);
@@ -135,7 +135,7 @@ export const Avatar = forwardRef(function Avatar({ accessory, activity = "idle",
     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];
-    const framed = frame !== false;
+    const framed = frame !== undefined;
     const radius = framed ? clampFrame(frame) * 100 : 0;
     const showImage = Boolean(src) && !imageFailed;
     const hasMouth = content === "face" && (Boolean(renderMouth) || spec.mouth !== "none");
@@ -282,7 +282,7 @@ export const Avatar = forwardRef(function Avatar({ accessory, activity = "idle",
         }
         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-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: {
+    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-loop": loop ? undefined : "off", height: size, overflow: framed ? undefined : "visible", role: "img", style: {
             "--aaa-gap": geometry.eyeGap,
             "--aaa-phase": spec.phase,
             "--aaa-tempo": spec.tempo,

package/dist/AvatarGroup.js

@@ -12,7 +12,7 @@ export function AvatarGroup({ className, max = 4, members, overlap = 0.3, ringCo
     const offset = -Math.round(size * overlap);
     return (_jsxs("div", { "aria-label": label, className: className, role: "group", style: { display: "inline-flex" }, children: [visible.map((member, index) => (_jsx("span", { style: {
                     borderRadius: frameRadius(member.frame),
-                    boxShadow: member.frame === false ? undefined : `0 0 0 2px ${ringColor}`,
+                    boxShadow: member.frame === undefined ? undefined : `0 0 0 2px ${ringColor}`,
                     display: "inline-flex",
                     marginLeft: index === 0 ? 0 : offset,
                     zIndex: visible.length - index,

package/dist/styles.js

@@ -141,7 +141,7 @@ export const AVATAR_CSS = `
 .aaa[data-reacting] .aaa-look{--aaa-look-x:0px;--aaa-look-y:0px;--aaa-look-sx:1}
 .aaa[data-reacting] .aaa-head{--aaa-head-x:0px;--aaa-head-y:0px;--aaa-head-r:0deg}
 .aaa[data-blink=off] .aaa-blink{animation:none}
-.aaa[data-motion=off] *{animation:none!important}
+.aaa[data-loop=off] *:not(.aaa-blink){animation:none!important}
 .aaa[data-offscreen] *{animation-play-state:paused!important}
 ${blinks([3, 21, 47, 66, 88], 0.6)}
 ${glances("aaa-saccade", [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aaavatars",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Deterministic 2D character avatars with a play() animation API",
   "keywords": [
     "avatar",