aaavatars 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rudolf Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# aaavatars
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deterministic 2D character avatars for AI agents. Same name, same character. A `status` prop drives looping states and `play()` triggers one-shot reactions.
+
+[Live demo](https://rsmdt.github.io/aaavatars/)
+
+![aaavatars demo](https://raw.githubusercontent.com/rsmdt/aaavatars/main/docs/demo.gif)
+
+```sh
+npm install aaavatars
+```
+
+```tsx
+import { Avatar, AvatarGroup, type AvatarHandle, parseAvatarValue } from "aaavatars";
+
+const avatar = useRef<AvatarHandle>(null);
+
+<Avatar ref={avatar} name="Chief of Staff" size={36} status="working" label="Searching the web" />;
+
+await avatar.current?.play("done");
+```
+
+## Avatar
+
+| Prop | Values |
+|---|---|
+| `name` | seed string |
+| `frame` | `false` (no background), `0` (square) to `0.5` (circle) |
+| `status` | `idle`, `thinking`, `working`, `waiting`, `error`, `sleeping` |
+| `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` |
+| `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 |
+| `interactive` | click, double-click, drag-to-squish and press-and-hold reactions |
+
+Unset `shape`, `eyes`, `mouth`, `accessory` and colours come from the name.
+
+`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.
+
+## AvatarGroup
+
+```tsx
+<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
+import { renderAvatarSvg } from "aaavatars/server";
+
+const svg = renderAvatarSvg({ name: "Research", size: 128 });
+```
+
+Requires `react-dom`.
+
+```sh
+npm run dev        # playground
+npm test
+npm run build
+```

package/dist/Avatar.d.ts

@@ -0,0 +1,37 @@
+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 type AvatarContent = "face" | "initial";
+export interface AvatarHandle {
+    play: (event: AvatarEvent) => Promise<void>;
+}
+export interface AvatarProps {
+    accessory?: Accessory;
+    background?: string;
+    badge?: ReactNode;
+    blink?: boolean;
+    body?: string;
+    className?: string;
+    colors?: readonly string[];
+    content?: AvatarContent;
+    eyes?: Eyes;
+    fill?: Fill;
+    frame?: false | number;
+    interactive?: boolean;
+    label?: string;
+    look?: boolean;
+    motion?: boolean;
+    mouth?: Mouth;
+    name: string;
+    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

@@ -0,0 +1,170 @@
+import { 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 { SHAPE_GEOMETRY } from "./geometry.js";
+import { AccessoryShape, EyePair, MoodMouths, MouthShape, mouthSlot, } from "./parts.js";
+import { createSpec, shadeHex, } from "./spec.js";
+import { AVATAR_CSS } from "./styles.js";
+export const AVATAR_STATUSES = [
+    "idle",
+    "thinking",
+    "working",
+    "waiting",
+    "error",
+    "sleeping",
+];
+const LOOK_RANGE = 4;
+const DRAG_THRESHOLD = 3;
+const HOLD_MS = 600;
+const SQUISH_LIMIT = 40;
+function prefersReducedMotion() {
+    return (typeof window.matchMedia === "function" &&
+        window.matchMedia("(prefers-reduced-motion: reduce)").matches);
+}
+function clampFrame(frame) {
+    return Math.min(Math.max(frame, 0), 0.5);
+}
+export function frameRadius(frame) {
+    if (frame === false)
+        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) {
+    const uid = `aaa-${useId().replace(/[^a-zA-Z0-9-_]/g, "")}`;
+    const svgRef = useRef(null);
+    const bodyRef = useRef(null);
+    const eyesRef = useRef(null);
+    const squishRef = useRef(null);
+    const running = useRef([]);
+    const drag = useRef(null);
+    const suppressClick = useRef(false);
+    const [imageFailed, setImageFailed] = useState(false);
+    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 radius = framed ? clampFrame(frame) * 100 : 0;
+    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 slot = mouthSlot(geometry, spec.eyeColor);
+    const bodyFill = fill === "gradient" ? `url(#${uid}-fill)` : spec.body;
+    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) => {
+        for (const animation of running.current)
+            animation.cancel();
+        const target = bodyRef.current;
+        const eyePair = eyesRef.current;
+        if (!target ||
+            typeof target.animate !== "function" ||
+            document.hidden ||
+            prefersReducedMotion()) {
+            return Promise.resolve();
+        }
+        const animation = EVENT_ANIMATIONS[event];
+        const timing = { duration: animation.duration, easing: "ease-in-out" };
+        const root = svgRef.current;
+        const rest = root?.querySelector(".aaa-mouth-rest");
+        const accessory = root?.querySelector(".aaa-accessory");
+        const accessoryName = accessory?.dataset.accessory;
+        const accessoryFrames = accessoryName ? animation.accessory?.[accessoryName] : undefined;
+        const mood = animation.mood
+            ? root?.querySelector(`.aaa-mood-${animation.mood.name}`)
+            : undefined;
+        const pairs = [
+            [target, animation.body],
+            [eyePair, animation.eyes],
+            [rest, animation.mood ? (animation.mood.rest ?? MOOD_SWAP_REST) : animation.mouth],
+            [mood, animation.mood ? (animation.mood.frames ?? MOOD_SWAP_SHOW) : undefined],
+            [accessory, accessoryFrames],
+        ];
+        running.current = pairs.flatMap(([element, frames]) => element && frames ? [element.animate(frames, timing)] : []);
+        return Promise.all(running.current.map((animation) => animation.finished)).then(() => undefined, () => undefined);
+    }, []);
+    useImperativeHandle(ref, () => ({ play }), [play]);
+    function lookAt(event) {
+        const bounds = event.currentTarget.getBoundingClientRect();
+        const x = ((event.clientX - bounds.left) / bounds.width - 0.5) * 2 * LOOK_RANGE;
+        const y = ((event.clientY - bounds.top) / bounds.height - 0.5) * 2 * LOOK_RANGE;
+        event.currentTarget.style.setProperty("--aaa-look-x", `${x}px`);
+        event.currentTarget.style.setProperty("--aaa-look-y", `${y}px`);
+    }
+    function resetLook(event) {
+        event.currentTarget.style.removeProperty("--aaa-look-x");
+        event.currentTarget.style.removeProperty("--aaa-look-y");
+    }
+    function startDrag(event) {
+        event.currentTarget.setPointerCapture?.(event.pointerId);
+        const state = {
+            held: false,
+            holdTimer: undefined,
+            moved: false,
+            x: event.clientX,
+            y: event.clientY,
+        };
+        state.holdTimer = setTimeout(() => {
+            state.held = true;
+            void play("success");
+        }, HOLD_MS);
+        drag.current = state;
+    }
+    function moveDrag(event) {
+        const state = drag.current;
+        const squish = squishRef.current;
+        if (!state || !squish)
+            return;
+        const unitsPerPixel = 100 / event.currentTarget.getBoundingClientRect().width;
+        const dx = (event.clientX - state.x) * unitsPerPixel;
+        const dy = (event.clientY - state.y) * unitsPerPixel;
+        if (!state.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD)
+            return;
+        state.moved = true;
+        clearTimeout(state.holdTimer);
+        const clampedX = Math.max(-SQUISH_LIMIT, Math.min(SQUISH_LIMIT, dx));
+        const clampedY = Math.max(-SQUISH_LIMIT, Math.min(SQUISH_LIMIT, dy));
+        const stretchX = 1 + Math.abs(clampedX) / 100 - Math.abs(clampedY) / 250;
+        const stretchY = 1 + Math.abs(clampedY) / 100 - Math.abs(clampedX) / 250;
+        squish.setAttribute("data-dragging", "");
+        squish.style.transform = `translate(${clampedX * 0.3}px, ${clampedY * 0.3}px) scale(${stretchX}, ${stretchY})`;
+    }
+    function endDrag() {
+        const state = drag.current;
+        drag.current = null;
+        if (!state)
+            return;
+        clearTimeout(state.holdTimer);
+        suppressClick.current = state.moved || state.held;
+        const squish = squishRef.current;
+        if (squish) {
+            squish.removeAttribute("data-dragging");
+            squish.style.transform = "";
+        }
+    }
+    function handleClick(event) {
+        if (suppressClick.current) {
+            suppressClick.current = false;
+            return;
+        }
+        void play(event.detail > 1 ? "surprise" : "acknowledge");
+    }
+    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, role: "img", viewBox: "0 0 100 100", width: size, onClick: interactive ? handleClick : undefined, onPointerCancel: interactive ? endDrag : undefined, onPointerDown: interactive ? startDrag : undefined, onPointerLeave: tracksPointer ? resetLook : undefined, onPointerMove: tracksPointer || interactive
+            ? (event) => {
+                if (tracksPointer)
+                    lookAt(event);
+                if (interactive)
+                    moveDrag(event);
+            }
+            : 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", 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] }) }) }) })) })] }));
+    if (!badge)
+        return svg;
+    return (_jsxs("span", { className: className, style: {
+            display: "inline-block",
+            height: size,
+            lineHeight: 0,
+            position: "relative",
+            width: size,
+        }, children: [svg, _jsx("span", { "data-badge": "", style: { bottom: 0, position: "absolute", right: 0, transform: "translate(20%, 20%)" }, children: badge })] }));
+});

package/dist/AvatarGroup.d.ts

@@ -0,0 +1,10 @@
+import { type AvatarProps } from "./Avatar.js";
+export interface AvatarGroupProps {
+    className?: string;
+    max?: number;
+    members: readonly Omit<AvatarProps, "size">[];
+    overlap?: number;
+    ringColor?: string;
+    size?: number;
+}
+export declare function AvatarGroup({ className, max, members, overlap, ringColor, size, }: AvatarGroupProps): import("react").JSX.Element;

package/dist/AvatarGroup.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Avatar, frameRadius } from "./Avatar.js";
+export function AvatarGroup({ className, max = 4, members, overlap = 0.3, ringColor = "#FFFFFF", size = 32, }) {
+    const visible = members.length > max ? members.slice(0, max - 1) : members;
+    const hidden = members.length - visible.length;
+    const label = [
+        visible.map((member) => member.name).join(", "),
+        hidden ? `and ${hidden} more` : "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    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}`,
+                    display: "inline-flex",
+                    marginLeft: index === 0 ? 0 : offset,
+                    zIndex: visible.length - index,
+                }, children: _jsx(Avatar, { ...member, size: size }) }, `${member.name}-${index}`))), hidden ? (_jsxs("span", { "data-overflow": "", style: {
+                    alignItems: "center",
+                    background: "#F1F2F3",
+                    borderRadius: "50%",
+                    boxShadow: `0 0 0 2px ${ringColor}`,
+                    color: "#333333",
+                    display: "inline-flex",
+                    fontFamily: "system-ui, sans-serif",
+                    fontSize: Math.round(size * 0.36),
+                    fontWeight: 600,
+                    height: size,
+                    justifyContent: "center",
+                    marginLeft: offset,
+                    width: size,
+                }, children: ["+", hidden] })) : null] }));
+}

package/dist/animations.d.ts

@@ -0,0 +1,21 @@
+export declare const AVATAR_EVENTS: readonly ["acknowledge", "handoff", "done", "success", "failure", "surprise", "wake"];
+import type { 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 {
+    accessory?: AccessoryFrames;
+    body: Keyframe[];
+    duration: number;
+    eyes: Keyframe[];
+    mood?: {
+        frames?: Keyframe[];
+        name: Mood;
+        rest?: Keyframe[];
+    };
+    mouth?: Keyframe[];
+}
+export declare const MOOD_SWAP_REST: Keyframe[];
+export declare const MOOD_SWAP_SHOW: Keyframe[];
+export declare const EVENT_ANIMATIONS: Record<AvatarEvent, EventAnimation>;
+export {};

package/dist/animations.js

@@ -0,0 +1,222 @@
+export const AVATAR_EVENTS = [
+    "acknowledge",
+    "handoff",
+    "done",
+    "success",
+    "failure",
+    "surprise",
+    "wake",
+];
+function hold(transform, from, to) {
+    return [
+        { transform, offset: from },
+        { transform, offset: to },
+    ];
+}
+function stalk(frames) {
+    return { antenna: frames, sprout: frames };
+}
+export const MOOD_SWAP_REST = [
+    { opacity: 0, offset: 0.12 },
+    { opacity: 0, offset: 0.88 },
+];
+export const MOOD_SWAP_SHOW = [
+    { opacity: 1, offset: 0.12 },
+    { opacity: 1, offset: 0.88 },
+];
+export const EVENT_ANIMATIONS = {
+    acknowledge: {
+        mouth: [{ transform: "scaleY(0.5)", offset: 0.35 }],
+        accessory: {
+            ...stalk([
+                { transform: "rotate(-12deg)", offset: 0.3 },
+                { transform: "rotate(8deg)", offset: 0.65 },
+            ]),
+            hat: [{ transform: "translateY(-4px)", offset: 0.35 }],
+            glasses: [{ transform: "translateY(-2px)", offset: 0.35 }],
+            bowtie: [{ transform: "scale(1.25)", offset: 0.35 }],
+        },
+        duration: 420,
+        body: [
+            { transform: "scale(1, 1)" },
+            { transform: "scale(1.12, 0.88)" },
+            { transform: "scale(0.94, 1.06)" },
+            { transform: "scale(1, 1)" },
+        ],
+        eyes: [{ transform: "scaleY(1)" }, { transform: "scaleY(0.2)" }, { transform: "scaleY(1)" }],
+    },
+    handoff: {
+        mouth: hold("translateX(5px)", 0.35, 0.65),
+        accessory: {
+            ...stalk(hold("rotate(-15deg)", 0.35, 0.65)),
+            hat: hold("translateX(3px) rotate(6deg)", 0.35, 0.65),
+            glasses: hold("translateX(4px)", 0.3, 0.7),
+            bowtie: hold("rotate(-12deg)", 0.35, 0.65),
+        },
+        duration: 900,
+        body: [
+            { transform: "translateX(0)" },
+            { transform: "translateX(10px)", offset: 0.35 },
+            { transform: "translateX(10px)", offset: 0.65 },
+            { transform: "translateX(0)" },
+        ],
+        eyes: [
+            { transform: "translateX(0)" },
+            { transform: "translateX(6px)", offset: 0.3 },
+            { transform: "translateX(6px)", offset: 0.7 },
+            { transform: "translateX(0)" },
+        ],
+    },
+    done: {
+        mood: { name: "happy" },
+        accessory: {
+            antenna: [{ transform: "scaleY(1.25)", offset: 0.3 }],
+            sprout: [{ transform: "scale(1.25)", offset: 0.3 }],
+            hat: hold("translateY(-3px) rotate(-10deg)", 0.3, 0.7),
+            glasses: [{ transform: "translateY(-3px)", offset: 0.3 }],
+            bowtie: [{ transform: "scale(1.3)", offset: 0.3 }],
+        },
+        duration: 700,
+        body: [
+            { transform: "translateY(0)" },
+            { transform: "translateY(-9px)", offset: 0.3 },
+            { transform: "translateY(0)", offset: 0.6 },
+            { transform: "translateY(-4px)", offset: 0.8 },
+            { transform: "translateY(0)" },
+        ],
+        eyes: [
+            { transform: "scaleY(1)" },
+            { transform: "scaleY(0.45)", offset: 0.25 },
+            { transform: "scaleY(0.45)", offset: 0.75 },
+            { transform: "scaleY(1)" },
+        ],
+    },
+    success: {
+        mood: {
+            name: "happy",
+            frames: [
+                { opacity: 1, transform: "scale(1.15)", offset: 0.12 },
+                { opacity: 1, transform: "scale(1.15)", offset: 0.88 },
+            ],
+        },
+        accessory: {
+            antenna: [
+                { transform: "rotate(-20deg)", offset: 0.2 },
+                { transform: "rotate(20deg)", offset: 0.45 },
+                { transform: "rotate(-10deg)", offset: 0.7 },
+            ],
+            sprout: hold("scale(1.35)", 0.3, 0.7),
+            hat: hold("translateY(-4px) rotate(-15deg)", 0.3, 0.7),
+            glasses: hold("translateY(-4px)", 0.3, 0.7),
+            bowtie: hold("scale(1.35)", 0.3, 0.7),
+        },
+        duration: 900,
+        body: [
+            { transform: "translateY(0) rotate(0deg) scale(1)" },
+            { transform: "translateY(-9px) rotate(-8deg) scale(1.06)", offset: 0.3 },
+            { transform: "translateY(-9px) rotate(8deg) scale(1.06)", offset: 0.55 },
+            { transform: "translateY(0) rotate(0deg) scale(1)" },
+        ],
+        eyes: [
+            { transform: "scaleY(1)" },
+            { transform: "scaleY(0.35)", offset: 0.2 },
+            { transform: "scaleY(0.35)", offset: 0.8 },
+            { transform: "scaleY(1)" },
+        ],
+    },
+    failure: {
+        mood: { name: "sad" },
+        accessory: {
+            ...stalk(hold("rotate(30deg)", 0.2, 0.85)),
+            hat: hold("translateY(4px) rotate(10deg)", 0.2, 0.85),
+            glasses: hold("translateY(3px) rotate(10deg)", 0.2, 0.85),
+            bowtie: hold("rotate(20deg)", 0.2, 0.85),
+        },
+        duration: 700,
+        body: [
+            { transform: "translateX(0)" },
+            { transform: "translateX(-6px)", offset: 0.15 },
+            { transform: "translateX(6px)", offset: 0.3 },
+            { transform: "translateX(-5px)", offset: 0.45 },
+            { transform: "translateX(4px)", offset: 0.6 },
+            { transform: "translateX(0)" },
+        ],
+        eyes: [
+            { transform: "translateY(0) scaleY(1)" },
+            { transform: "translateY(3px) scaleY(0.6)", offset: 0.2 },
+            { transform: "translateY(3px) scaleY(0.6)", offset: 0.8 },
+            { transform: "translateY(0) scaleY(1)" },
+        ],
+    },
+    surprise: {
+        mood: {
+            name: "o",
+            frames: [
+                { opacity: 1, transform: "scale(1.3)", offset: 0.12 },
+                { opacity: 1, transform: "scale(1.3)", offset: 0.75 },
+                { opacity: 0, offset: 0.9 },
+            ],
+            rest: [
+                { opacity: 0, offset: 0.12 },
+                { opacity: 0, offset: 0.8 },
+            ],
+        },
+        accessory: {
+            antenna: hold("scaleY(1.4)", 0.2, 0.7),
+            sprout: hold("scale(1.3)", 0.2, 0.7),
+            hat: hold("translateY(-5px)", 0.2, 0.6),
+            glasses: hold("translateY(-5px)", 0.2, 0.7),
+            bowtie: hold("scale(1.3)", 0.2, 0.7),
+        },
+        duration: 650,
+        body: [
+            { transform: "translateY(0) scale(1)" },
+            { transform: "translateY(-8px) scale(1.04, 1.1)", offset: 0.25 },
+            { transform: "translateY(0) scale(0.97, 1.02)", offset: 0.6 },
+            { transform: "translateY(0) scale(1)" },
+        ],
+        eyes: [
+            { transform: "scale(1)" },
+            { transform: "scale(1.45)", offset: 0.2 },
+            { transform: "scale(1.45)", offset: 0.7 },
+            { transform: "scale(1)" },
+        ],
+    },
+    wake: {
+        mood: {
+            name: "o",
+            frames: [
+                { opacity: 1, offset: 0.1 },
+                { opacity: 1, transform: "scale(1.2)", offset: 0.45 },
+                { opacity: 0, offset: 0.65 },
+            ],
+            rest: [
+                { opacity: 0, offset: 0.1 },
+                { opacity: 0, offset: 0.6 },
+            ],
+        },
+        accessory: {
+            ...stalk([
+                { transform: "rotate(-35deg)", offset: 0.05 },
+                { transform: "rotate(-35deg)", offset: 0.35 },
+                { transform: "rotate(10deg)", offset: 0.7 },
+            ]),
+            hat: hold("translateY(5px)", 0.05, 0.35),
+            glasses: hold("translateY(4px)", 0.05, 0.35),
+            bowtie: hold("rotate(15deg)", 0.05, 0.35),
+        },
+        duration: 800,
+        body: [
+            { transform: "scale(1, 1)" },
+            { transform: "scale(0.96, 1.1)", offset: 0.4 },
+            { transform: "scale(1.02, 0.98)", offset: 0.7 },
+            { transform: "scale(1, 1)" },
+        ],
+        eyes: [
+            { transform: "scaleY(0.12)" },
+            { transform: "scaleY(0.12)", offset: 0.3 },
+            { transform: "scaleY(1.2)", offset: 0.6 },
+            { transform: "scaleY(1)" },
+        ],
+    },
+};

package/dist/geometry.d.ts

@@ -0,0 +1,9 @@
+import type { Shape } from "./spec.js";
+export interface ShapeGeometry {
+    bottom: number;
+    eyeGap: number;
+    eyeY: number;
+    path: string;
+    top: number;
+}
+export declare const SHAPE_GEOMETRY: Record<Shape, ShapeGeometry>;

package/dist/geometry.js

@@ -0,0 +1,58 @@
+export const SHAPE_GEOMETRY = {
+    circle: {
+        path: "M50 10a40 40 0 1 0 0.01 0Z",
+        eyeY: 46,
+        eyeGap: 16,
+        top: 10,
+        bottom: 90,
+    },
+    squircle: {
+        path: "M50 10C82 10 90 18 90 50C90 82 82 90 50 90C18 90 10 82 10 50C10 18 18 10 50 10Z",
+        eyeY: 46,
+        eyeGap: 17,
+        top: 10,
+        bottom: 90,
+    },
+    pill: {
+        path: "M30 24H70A26 26 0 0 1 70 76H30A26 26 0 0 1 30 24Z",
+        eyeY: 48,
+        eyeGap: 17,
+        top: 24,
+        bottom: 76,
+    },
+    hex: {
+        path: "M50 10L85 30V70L50 90L15 70V30Z",
+        eyeY: 48,
+        eyeGap: 16,
+        top: 10,
+        bottom: 90,
+    },
+    triangle: {
+        path: "M50 14L89 84H11Z",
+        eyeY: 62,
+        eyeGap: 12,
+        top: 14,
+        bottom: 84,
+    },
+    drop: {
+        path: "M50 8C50 8 84 44 84 63C84 82 69 92 50 92C31 92 16 82 16 63C16 44 50 8 50 8Z",
+        eyeY: 62,
+        eyeGap: 14,
+        top: 8,
+        bottom: 92,
+    },
+    cloud: {
+        path: "M28 82C14 82 8 70 12 60C4 48 14 34 28 38C30 22 48 16 58 26C70 16 88 26 84 42C96 46 96 66 86 72C86 80 78 84 70 82Z",
+        eyeY: 56,
+        eyeGap: 16,
+        top: 20,
+        bottom: 82,
+    },
+    blob: {
+        path: "M54 10C76 12 92 30 88 54C85 76 66 92 44 88C22 85 8 66 12 44C16 22 32 8 54 10Z",
+        eyeY: 47,
+        eyeGap: 16,
+        top: 10,
+        bottom: 89,
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { AVATAR_EVENTS, type AvatarEvent } from "./animations.js";
+export { AVATAR_STATUSES, Avatar, type AvatarContent, type AvatarHandle, type AvatarProps, type AvatarStatus, } from "./Avatar.js";
+export { AvatarGroup, type AvatarGroupProps } from "./AvatarGroup.js";
+export type { MouthSlot, RenderMouth } from "./parts.js";
+export { ACCESSORIES, type Accessory, type AvatarSpec, DEFAULT_COLORS, EYES, type Eyes, FILLS, type Fill, MOUTHS, type Mouth, SHAPES, type Shape, type SpecOptions, createSpec, } from "./spec.js";
+export { AVATAR_VALUE_MAX_LENGTH, type AvatarValue, type ParsedAvatarValue, formatAvatarValue, parseAvatarValue, } from "./value.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AVATAR_EVENTS } from "./animations.js";
+export { AVATAR_STATUSES, Avatar, } from "./Avatar.js";
+export { AvatarGroup } from "./AvatarGroup.js";
+export { ACCESSORIES, DEFAULT_COLORS, EYES, FILLS, MOUTHS, SHAPES, createSpec, } from "./spec.js";
+export { AVATAR_VALUE_MAX_LENGTH, formatAvatarValue, parseAvatarValue, } from "./value.js";

package/dist/parts.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from "react";
+import type { ShapeGeometry } from "./geometry.js";
+import type { Accessory, Eyes, Mouth } from "./spec.js";
+export interface MouthSlot {
+    color: string;
+    width: number;
+    x: number;
+    y: number;
+}
+export type RenderMouth = (mouth: MouthSlot) => ReactNode;
+export declare function mouthSlot(geometry: ShapeGeometry, color: string): MouthSlot;
+export declare function EyePair({ eyes, gap, y }: {
+    eyes: Eyes;
+    gap: number;
+    y: number;
+}): import("react").JSX.Element;
+export declare function MouthShape({ mouth, slot }: {
+    mouth: Mouth;
+    slot: MouthSlot;
+}): import("react").JSX.Element | null;
+export declare const MOODS: readonly ["happy", "sad", "o", "small"];
+export type Mood = (typeof MOODS)[number];
+export declare function MoodMouths({ slot }: {
+    slot: MouthSlot;
+}): import("react").JSX.Element;
+interface AccessoryProps {
+    accent: string;
+    accessory: Accessory;
+    body: string;
+    geometry: ShapeGeometry;
+}
+export declare function AccessoryShape(props: AccessoryProps): import("react").JSX.Element | null;
+export {};

package/dist/parts.js

@@ -0,0 +1,65 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const STROKE = { fill: "none", strokeLinecap: "round", strokeWidth: 4 };
+export function mouthSlot(geometry, color) {
+    return { color, width: geometry.eyeGap * 1.2, x: 50, y: geometry.eyeY + 17 };
+}
+export function EyePair({ eyes, gap, y }) {
+    return (_jsx(_Fragment, { children: [50 - gap, 50 + gap].map((x) => {
+            if (eyes === "dot")
+                return _jsx("circle", { cx: x, cy: y, r: 7 }, x);
+            if (eyes === "tall") {
+                return _jsx("rect", { x: x - 5, y: y - 11, width: 10, height: 22, rx: 5 }, x);
+            }
+            if (eyes === "wide")
+                return _jsx("ellipse", { cx: x, cy: y, rx: 11, ry: 7 }, x);
+            return _jsx("ellipse", { cx: x, cy: y, rx: 8, ry: 10 }, x);
+        }) }));
+}
+export function MouthShape({ mouth, slot }) {
+    const half = slot.width / 2;
+    if (mouth === "smile") {
+        return (_jsx("path", { d: `M${slot.x - half} ${slot.y - 2}Q${slot.x} ${slot.y + 7} ${slot.x + half} ${slot.y - 2}`, stroke: slot.color, ...STROKE }));
+    }
+    if (mouth === "flat") {
+        return (_jsx("path", { d: `M${slot.x - half * 0.7} ${slot.y}H${slot.x + half * 0.7}`, stroke: slot.color, ...STROKE }));
+    }
+    if (mouth === "open") {
+        return _jsx("ellipse", { cx: slot.x, cy: slot.y, rx: half * 0.5, ry: 5, fill: slot.color });
+    }
+    return null;
+}
+export const MOODS = ["happy", "sad", "o", "small"];
+export function MoodMouths({ slot }) {
+    const half = slot.width / 2;
+    const { color, x, y } = slot;
+    return (_jsxs(_Fragment, { children: [_jsx("g", { className: "aaa-mood aaa-mood-happy", children: _jsx("path", { d: `M${x - half} ${y - 3}Q${x} ${y + 12} ${x + half} ${y - 3}Z`, fill: color }) }), _jsx("g", { className: "aaa-mood aaa-mood-sad", children: _jsx("path", { d: `M${x - half * 0.8} ${y + 4}Q${x} ${y - 5} ${x + half * 0.8} ${y + 4}`, stroke: color, ...STROKE }) }), _jsx("g", { className: "aaa-mood aaa-mood-o", children: _jsx("ellipse", { cx: x, cy: y + 1, rx: 5, ry: 6.5, fill: color }) }), _jsx("g", { className: "aaa-mood aaa-mood-small", children: _jsx("path", { d: `M${x + 1} ${y}H${x + 9}`, stroke: color, ...STROKE }) })] }));
+}
+export function AccessoryShape(props) {
+    if (props.accessory === "none")
+        return null;
+    return (_jsx("g", { className: "aaa-accessory", "data-accessory": props.accessory, children: _jsx(AccessoryArt, { ...props }) }));
+}
+function AccessoryArt({ accessory, accent, body, geometry }) {
+    const top = geometry.top - 4;
+    const bottom = geometry.bottom;
+    if (accessory === "antenna") {
+        return (_jsxs("g", { children: [_jsx("path", { d: `M50 ${top}V${top - 9}`, stroke: body, ...STROKE, strokeWidth: 5 }), _jsx("circle", { className: "aaa-antenna-tip", cx: 50, cy: top - 13, r: 6, fill: accent })] }));
+    }
+    if (accessory === "sprout") {
+        return (_jsxs("g", { fill: accent, children: [_jsx("path", { d: `M50 ${top + 2}V${top - 10}`, stroke: accent, ...STROKE }), _jsx("ellipse", { cx: 42, cy: top - 12, rx: 9, ry: 5, transform: `rotate(-30 42 ${top - 12})` }), _jsx("ellipse", { cx: 58, cy: top - 14, rx: 9, ry: 5, transform: `rotate(25 58 ${top - 14})` })] }));
+    }
+    if (accessory === "hat") {
+        return (_jsxs("g", { fill: accent, children: [_jsx("rect", { x: 32, y: top - 14, width: 36, height: 16, rx: 5 }), _jsx("rect", { x: 24, y: top - 2, width: 52, height: 7, rx: 3.5 })] }));
+    }
+    if (accessory === "glasses") {
+        const radius = 13;
+        const left = 50 - geometry.eyeGap;
+        const right = 50 + geometry.eyeGap;
+        return (_jsxs("g", { stroke: accent, fill: "none", strokeWidth: 3.5, children: [_jsx("circle", { cx: left, cy: geometry.eyeY, r: radius }), _jsx("circle", { cx: right, cy: geometry.eyeY, r: radius }), _jsx("path", { d: `M${left + radius} ${geometry.eyeY}H${right - radius}` })] }));
+    }
+    if (accessory === "bowtie") {
+        const y = bottom - 6;
+        return (_jsxs("g", { fill: accent, children: [_jsx("path", { d: `M50 ${y}L37 ${y - 8}V${y + 8}Z` }), _jsx("path", { d: `M50 ${y}L63 ${y - 8}V${y + 8}Z` }), _jsx("circle", { cx: 50, cy: y, r: 4 })] }));
+    }
+    return null;
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { type AvatarProps } from "./Avatar.js";
+export type StaticAvatarProps = Omit<AvatarProps, "badge" | "interactive" | "renderMouth">;
+export declare function renderAvatarSvg(props: StaticAvatarProps): string;

package/dist/server.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { renderToStaticMarkup } from "react-dom/server";
+import { Avatar } from "./Avatar.js";
+export function renderAvatarSvg(props) {
+    return renderToStaticMarkup(_jsx(Avatar, { ...props }));
+}

package/dist/spec.d.ts

@@ -0,0 +1,35 @@
+export declare const SHAPES: readonly ["circle", "squircle", "pill", "hex", "triangle", "drop", "cloud", "blob"];
+export declare const EYES: readonly ["round", "dot", "tall", "wide"];
+export declare const MOUTHS: readonly ["none", "smile", "flat", "open"];
+export declare const ACCESSORIES: readonly ["none", "antenna", "sprout", "hat", "glasses", "bowtie"];
+export declare const FILLS: readonly ["solid", "gradient"];
+export declare const DEFAULT_COLORS: string[];
+export type Shape = (typeof SHAPES)[number];
+export type Eyes = (typeof EYES)[number];
+export type Mouth = (typeof MOUTHS)[number];
+export type Accessory = (typeof ACCESSORIES)[number];
+export type Fill = (typeof FILLS)[number];
+export interface AvatarSpec {
+    accent: string;
+    accessory: Accessory;
+    background: string;
+    body: string;
+    eyeColor: string;
+    eyes: Eyes;
+    mouth: Mouth;
+    offsetX: number;
+    offsetY: number;
+    rotate: number;
+    shape: Shape;
+}
+export interface SpecOptions {
+    accessory?: Accessory;
+    background?: string;
+    body?: string;
+    colors?: readonly string[];
+    eyes?: Eyes;
+    mouth?: Mouth;
+    shape?: Shape;
+}
+export declare function createSpec(name: string, options?: SpecOptions): AvatarSpec;
+export declare function shadeHex(hex: string, amount: number): string;

package/dist/spec.js

@@ -0,0 +1,102 @@
+export const SHAPES = [
+    "circle",
+    "squircle",
+    "pill",
+    "hex",
+    "triangle",
+    "drop",
+    "cloud",
+    "blob",
+];
+export const EYES = ["round", "dot", "tall", "wide"];
+export const MOUTHS = ["none", "smile", "flat", "open"];
+export const ACCESSORIES = ["none", "antenna", "sprout", "hat", "glasses", "bowtie"];
+export const FILLS = ["solid", "gradient"];
+const HASHED_MOUTHS = ["none", "none", "none", "smile", "flat", "open"];
+const HASHED_ACCESSORIES = [
+    "none",
+    "none",
+    "none",
+    "none",
+    "antenna",
+    "sprout",
+    "hat",
+    "glasses",
+    "bowtie",
+];
+export const DEFAULT_COLORS = ["#264653", "#2A9D8F", "#E9C46A", "#F4A261", "#E76F51"];
+function hash(value) {
+    let result = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        result = Math.imul(result ^ value.charCodeAt(index), 16777619);
+    }
+    return result >>> 0;
+}
+function seededRandom(seed) {
+    let state = seed;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let next = Math.imul(state ^ (state >>> 15), 1 | state);
+        next = (next + Math.imul(next ^ (next >>> 7), 61 | next)) ^ next;
+        return ((next ^ (next >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function pick(items, random) {
+    return items[Math.floor(random() * items.length)];
+}
+function signedRange(random, limit) {
+    return Math.round((random() * 2 - 1) * limit);
+}
+function relativeLuminance(hex) {
+    const digits = hex.replace("#", "");
+    const full = digits.length === 3 ? [...digits].map((digit) => digit + digit).join("") : digits;
+    const [red, green, blue] = [0, 2, 4].map((start) => {
+        const channel = Number.parseInt(full.slice(start, start + 2), 16) / 255;
+        return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * red + 0.7152 * green + 0.0722 * blue;
+}
+export function createSpec(name, options = {}) {
+    const colors = options.colors?.length ? options.colors : DEFAULT_COLORS;
+    const random = seededRandom(hash(name));
+    const backgroundIndex = Math.floor(random() * colors.length);
+    const bodyShift = 1 + Math.floor(random() * Math.max(colors.length - 1, 1));
+    const bodyIndex = (backgroundIndex + bodyShift) % colors.length;
+    const shape = pick(SHAPES, random);
+    const eyes = pick(EYES, random);
+    const offsetX = signedRange(random, 6);
+    const offsetY = signedRange(random, 5);
+    const rotate = signedRange(random, 12);
+    const mouth = pick(HASHED_MOUTHS, random);
+    const accessory = pick(HASHED_ACCESSORIES, random);
+    const accentCandidates = colors.filter((_, index) => index !== bodyIndex && index !== backgroundIndex);
+    const accent = accentCandidates.length ? pick(accentCandidates, random) : colors[0];
+    const background = options.background ?? colors[backgroundIndex];
+    const body = options.body ?? colors[bodyIndex];
+    return {
+        accent,
+        accessory: options.accessory ?? accessory,
+        background,
+        body,
+        eyeColor: relativeLuminance(body) > 0.4 ? "#141414" : "#FFFFFF",
+        eyes: options.eyes ?? eyes,
+        mouth: options.mouth ?? mouth,
+        offsetX,
+        offsetY,
+        rotate,
+        shape: options.shape ?? shape,
+    };
+}
+export function shadeHex(hex, amount) {
+    const digits = hex.replace("#", "");
+    const full = digits.length === 3 ? [...digits].map((digit) => digit + digit).join("") : digits;
+    const target = amount < 0 ? 0 : 255;
+    const weight = Math.abs(amount);
+    const channels = [0, 2, 4].map((start) => {
+        const channel = Number.parseInt(full.slice(start, start + 2), 16);
+        return Math.round(channel + (target - channel) * weight)
+            .toString(16)
+            .padStart(2, "0");
+    });
+    return `#${channels.join("")}`;
+}

package/dist/styles.d.ts

@@ -0,0 +1 @@
+export declare const AVATAR_CSS = "\n.aaa-body-motion,.aaa-react,.aaa-eyes-react,.aaa-eyes-motion,.aaa-blink,.aaa-squish{transform-box:fill-box;transform-origin:center}\n.aaa-mouth-rest,.aaa-mood{transform-box:fill-box;transform-origin:center;transition:opacity .2s,transform .2s}\n.aaa-mood{opacity:0}\n.aaa-accessory{transform-box:fill-box;transform-origin:50% 100%;transition:transform .3s ease-out}\n.aaa-accessory[data-accessory=glasses],.aaa-accessory[data-accessory=bowtie]{transform-origin:center}\n.aaa-squish{transition:transform .45s cubic-bezier(.34,1.56,.64,1)}\n.aaa-squish[data-dragging]{transition:none}\n.aaa[data-interactive]{cursor:grab;touch-action:none}\n.aaa[data-interactive]:active{cursor:grabbing}\n.aaa-look{transform:translate(var(--aaa-look-x,0px),var(--aaa-look-y,0px));transition:transform .25s ease-out}\n.aaa-blink{animation:aaa-blink 4.6s infinite}\n.aaa[data-status=idle] .aaa-body-motion{animation:aaa-bob 3.6s ease-in-out infinite}\n.aaa[data-status=thinking] .aaa-body-motion{animation:aaa-sway 3s ease-in-out infinite}\n.aaa[data-status=thinking] .aaa-eyes-motion{transform:translate(-5px,-6px);animation:aaa-ponder 2.4s ease-in-out infinite}\n.aaa[data-status=working] .aaa-body-motion{animation:aaa-bob .9s ease-in-out infinite}\n.aaa[data-status=working] .aaa-eyes-motion{animation:aaa-scan 1.1s ease-in-out infinite}\n.aaa[data-status=waiting] .aaa-body-motion{animation:aaa-hop 1.6s ease-out infinite}\n.aaa[data-status=waiting] .aaa-eyes-motion{transform:scale(1.18)}\n.aaa[data-status=error] .aaa-body-motion{transform:rotate(-10deg)}\n.aaa[data-status=error] .aaa-eyes-motion{transform:scaleY(.25)}\n.aaa[data-status=error] .aaa-blink{animation:none}\n.aaa[data-status=sleeping] .aaa-body-motion{animation:aaa-breathe 4.2s ease-in-out infinite}\n.aaa[data-status=sleeping] .aaa-eyes-motion{transform:translateY(2px) scaleY(.12)}\n.aaa[data-status=sleeping] .aaa-blink{animation:none}\n.aaa[data-status=working] .aaa-antenna-tip{animation:aaa-signal .9s ease-in-out infinite}\n.aaa[data-status=thinking] .aaa-mouth-rest{opacity:0}\n.aaa[data-status=thinking] .aaa-mood-small{opacity:1}\n.aaa[data-status=thinking] .aaa-accessory:is([data-accessory=antenna],[data-accessory=sprout]){animation:aaa-acc-sway 2.4s ease-in-out infinite}\n.aaa[data-status=thinking] .aaa-accessory[data-accessory=glasses]{animation:aaa-glasses-think 2.4s ease-in-out infinite}\n.aaa[data-status=working] .aaa-mouth-rest{transform:scaleX(.7)}\n.aaa[data-status=working] .aaa-accessory[data-accessory=bowtie]{animation:aaa-wobble .9s ease-in-out infinite}\n.aaa[data-status=waiting] .aaa-mouth-rest{opacity:0}\n.aaa[data-status=waiting] .aaa-mood-happy{opacity:1}\n.aaa[data-status=waiting] .aaa-accessory:not([data-accessory=glasses]){animation:aaa-wobble 1.6s ease-in-out infinite}\n.aaa[data-status=error] .aaa-mouth-rest{opacity:0}\n.aaa[data-status=error] .aaa-mood-sad{opacity:1}\n.aaa[data-status=error] .aaa-accessory:is([data-accessory=antenna],[data-accessory=sprout]){transform:rotate(28deg)}\n.aaa[data-status=error] .aaa-accessory:is([data-accessory=hat],[data-accessory=glasses]){transform:translateY(3px) rotate(8deg)}\n.aaa[data-status=error] .aaa-accessory[data-accessory=bowtie]{transform:rotate(18deg)}\n.aaa[data-status=sleeping] .aaa-mouth-rest{opacity:0}\n.aaa[data-status=sleeping] .aaa-mood-o{opacity:1;animation:aaa-snore 4.2s ease-in-out infinite}\n.aaa[data-status=sleeping] .aaa-accessory:is([data-accessory=antenna],[data-accessory=sprout]){transform:rotate(-35deg)}\n.aaa[data-status=sleeping] .aaa-accessory:is([data-accessory=hat],[data-accessory=glasses]){transform:translateY(5px)}\n.aaa[data-blink=off] .aaa-blink{animation:none}\n.aaa[data-motion=off] *{animation:none!important}\n@keyframes aaa-blink{0%,93%,100%{transform:scaleY(1)}96%{transform:scaleY(.1)}}\n@keyframes aaa-bob{0%,100%{transform:translateY(0)}50%{transform:translateY(-3px)}}\n@keyframes aaa-sway{0%,100%{transform:rotate(-4deg)}50%{transform:rotate(4deg)}}\n@keyframes aaa-ponder{0%,100%{transform:translate(-5px,-6px)}50%{transform:translate(5px,-6px)}}\n@keyframes aaa-scan{0%,100%{transform:translateX(-5px)}50%{transform:translateX(5px)}}\n@keyframes aaa-breathe{0%,100%{transform:scale(1)}50%{transform:scale(1.035,.97)}}\n@keyframes aaa-signal{0%,100%{opacity:1}50%{opacity:.25}}\n@keyframes aaa-acc-sway{0%,100%{transform:rotate(-8deg)}50%{transform:rotate(8deg)}}\n@keyframes aaa-wobble{0%,100%{transform:rotate(-12deg)}50%{transform:rotate(12deg)}}\n@keyframes aaa-glasses-think{0%,100%{transform:translateY(0)}50%{transform:translateY(-3px)}}\n@keyframes aaa-snore{0%,100%{transform:scale(.7)}50%{transform:scale(1.1)}}\n@keyframes aaa-hop{0%,55%,100%{transform:translateY(0)}68%{transform:translateY(-7px)}80%{transform:translateY(0)}90%{transform:translateY(-3px)}}\n@media (prefers-reduced-motion:reduce){.aaa *{animation:none!important;transition:none!important}}\n";

package/dist/styles.js

@@ -0,0 +1,60 @@
+export const AVATAR_CSS = `
+.aaa-body-motion,.aaa-react,.aaa-eyes-react,.aaa-eyes-motion,.aaa-blink,.aaa-squish{transform-box:fill-box;transform-origin:center}
+.aaa-mouth-rest,.aaa-mood{transform-box:fill-box;transform-origin:center;transition:opacity .2s,transform .2s}
+.aaa-mood{opacity:0}
+.aaa-accessory{transform-box:fill-box;transform-origin:50% 100%;transition:transform .3s ease-out}
+.aaa-accessory[data-accessory=glasses],.aaa-accessory[data-accessory=bowtie]{transform-origin:center}
+.aaa-squish{transition:transform .45s cubic-bezier(.34,1.56,.64,1)}
+.aaa-squish[data-dragging]{transition:none}
+.aaa[data-interactive]{cursor:grab;touch-action:none}
+.aaa[data-interactive]:active{cursor:grabbing}
+.aaa-look{transform:translate(var(--aaa-look-x,0px),var(--aaa-look-y,0px));transition:transform .25s ease-out}
+.aaa-blink{animation:aaa-blink 4.6s infinite}
+.aaa[data-status=idle] .aaa-body-motion{animation:aaa-bob 3.6s ease-in-out infinite}
+.aaa[data-status=thinking] .aaa-body-motion{animation:aaa-sway 3s ease-in-out infinite}
+.aaa[data-status=thinking] .aaa-eyes-motion{transform:translate(-5px,-6px);animation:aaa-ponder 2.4s ease-in-out infinite}
+.aaa[data-status=working] .aaa-body-motion{animation:aaa-bob .9s ease-in-out infinite}
+.aaa[data-status=working] .aaa-eyes-motion{animation:aaa-scan 1.1s ease-in-out infinite}
+.aaa[data-status=waiting] .aaa-body-motion{animation:aaa-hop 1.6s ease-out infinite}
+.aaa[data-status=waiting] .aaa-eyes-motion{transform:scale(1.18)}
+.aaa[data-status=error] .aaa-body-motion{transform:rotate(-10deg)}
+.aaa[data-status=error] .aaa-eyes-motion{transform:scaleY(.25)}
+.aaa[data-status=error] .aaa-blink{animation:none}
+.aaa[data-status=sleeping] .aaa-body-motion{animation:aaa-breathe 4.2s ease-in-out infinite}
+.aaa[data-status=sleeping] .aaa-eyes-motion{transform:translateY(2px) scaleY(.12)}
+.aaa[data-status=sleeping] .aaa-blink{animation:none}
+.aaa[data-status=working] .aaa-antenna-tip{animation:aaa-signal .9s ease-in-out infinite}
+.aaa[data-status=thinking] .aaa-mouth-rest{opacity:0}
+.aaa[data-status=thinking] .aaa-mood-small{opacity:1}
+.aaa[data-status=thinking] .aaa-accessory:is([data-accessory=antenna],[data-accessory=sprout]){animation:aaa-acc-sway 2.4s ease-in-out infinite}
+.aaa[data-status=thinking] .aaa-accessory[data-accessory=glasses]{animation:aaa-glasses-think 2.4s ease-in-out infinite}
+.aaa[data-status=working] .aaa-mouth-rest{transform:scaleX(.7)}
+.aaa[data-status=working] .aaa-accessory[data-accessory=bowtie]{animation:aaa-wobble .9s ease-in-out infinite}
+.aaa[data-status=waiting] .aaa-mouth-rest{opacity:0}
+.aaa[data-status=waiting] .aaa-mood-happy{opacity:1}
+.aaa[data-status=waiting] .aaa-accessory:not([data-accessory=glasses]){animation:aaa-wobble 1.6s ease-in-out infinite}
+.aaa[data-status=error] .aaa-mouth-rest{opacity:0}
+.aaa[data-status=error] .aaa-mood-sad{opacity:1}
+.aaa[data-status=error] .aaa-accessory:is([data-accessory=antenna],[data-accessory=sprout]){transform:rotate(28deg)}
+.aaa[data-status=error] .aaa-accessory:is([data-accessory=hat],[data-accessory=glasses]){transform:translateY(3px) rotate(8deg)}
+.aaa[data-status=error] .aaa-accessory[data-accessory=bowtie]{transform:rotate(18deg)}
+.aaa[data-status=sleeping] .aaa-mouth-rest{opacity:0}
+.aaa[data-status=sleeping] .aaa-mood-o{opacity:1;animation:aaa-snore 4.2s ease-in-out infinite}
+.aaa[data-status=sleeping] .aaa-accessory:is([data-accessory=antenna],[data-accessory=sprout]){transform:rotate(-35deg)}
+.aaa[data-status=sleeping] .aaa-accessory:is([data-accessory=hat],[data-accessory=glasses]){transform:translateY(5px)}
+.aaa[data-blink=off] .aaa-blink{animation:none}
+.aaa[data-motion=off] *{animation:none!important}
+@keyframes aaa-blink{0%,93%,100%{transform:scaleY(1)}96%{transform:scaleY(.1)}}
+@keyframes aaa-bob{0%,100%{transform:translateY(0)}50%{transform:translateY(-3px)}}
+@keyframes aaa-sway{0%,100%{transform:rotate(-4deg)}50%{transform:rotate(4deg)}}
+@keyframes aaa-ponder{0%,100%{transform:translate(-5px,-6px)}50%{transform:translate(5px,-6px)}}
+@keyframes aaa-scan{0%,100%{transform:translateX(-5px)}50%{transform:translateX(5px)}}
+@keyframes aaa-breathe{0%,100%{transform:scale(1)}50%{transform:scale(1.035,.97)}}
+@keyframes aaa-signal{0%,100%{opacity:1}50%{opacity:.25}}
+@keyframes aaa-acc-sway{0%,100%{transform:rotate(-8deg)}50%{transform:rotate(8deg)}}
+@keyframes aaa-wobble{0%,100%{transform:rotate(-12deg)}50%{transform:rotate(12deg)}}
+@keyframes aaa-glasses-think{0%,100%{transform:translateY(0)}50%{transform:translateY(-3px)}}
+@keyframes aaa-snore{0%,100%{transform:scale(.7)}50%{transform:scale(1.1)}}
+@keyframes aaa-hop{0%,55%,100%{transform:translateY(0)}68%{transform:translateY(-7px)}80%{transform:translateY(0)}90%{transform:translateY(-3px)}}
+@media (prefers-reduced-motion:reduce){.aaa *{animation:none!important;transition:none!important}}
+`;

package/dist/value.d.ts

@@ -0,0 +1,20 @@
+import { type Accessory, type Eyes, type Fill, type Mouth, type Shape } from "./spec.js";
+export interface AvatarValue {
+    accessory?: Accessory;
+    background?: string;
+    body?: string;
+    eyes?: Eyes;
+    fill?: Fill;
+    mouth?: Mouth;
+    shape?: Shape;
+}
+export type ParsedAvatarValue = {
+    ok: true;
+    value: AvatarValue;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const AVATAR_VALUE_MAX_LENGTH = 200;
+export declare function parseAvatarValue(raw: string): ParsedAvatarValue;
+export declare function formatAvatarValue(value: AvatarValue): string;

package/dist/value.js

@@ -0,0 +1,66 @@
+import { ACCESSORIES, EYES, FILLS, MOUTHS, SHAPES, } from "./spec.js";
+export const AVATAR_VALUE_MAX_LENGTH = 200;
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+const ENUM_FIELDS = {
+    shape: SHAPES,
+    eyes: EYES,
+    mouth: MOUTHS,
+    accessory: ACCESSORIES,
+    fill: FILLS,
+};
+const COLOR_FIELDS = ["body", "background"];
+const FIELD_ORDER = [
+    "shape",
+    "eyes",
+    "mouth",
+    "accessory",
+    "body",
+    "background",
+    "fill",
+];
+function isEnumField(key) {
+    return key in ENUM_FIELDS;
+}
+function isColorField(key) {
+    return COLOR_FIELDS.includes(key);
+}
+export function parseAvatarValue(raw) {
+    if (raw.length > AVATAR_VALUE_MAX_LENGTH) {
+        return {
+            ok: false,
+            error: `Avatar value is longer than ${AVATAR_VALUE_MAX_LENGTH} characters.`,
+        };
+    }
+    const value = {};
+    for (const entry of raw
+        .split(";")
+        .map((part) => part.trim())
+        .filter(Boolean)) {
+        const separator = entry.indexOf("=");
+        const key = separator === -1 ? entry : entry.slice(0, separator).trim();
+        const field = separator === -1 ? "" : entry.slice(separator + 1).trim();
+        if (key in value)
+            return { ok: false, error: `"${key}" is set more than once.` };
+        if (isEnumField(key)) {
+            const allowed = ENUM_FIELDS[key];
+            if (!allowed.includes(field)) {
+                return { ok: false, error: `"${key}" must be one of ${allowed.join(", ")}.` };
+            }
+        }
+        else if (isColorField(key)) {
+            if (!HEX_COLOR.test(field)) {
+                return { ok: false, error: `"${key}" must be a hex color like #E76F51.` };
+            }
+        }
+        else {
+            return { ok: false, error: `Unknown avatar field "${key}". Use ${FIELD_ORDER.join(", ")}.` };
+        }
+        value[key] = field;
+    }
+    return { ok: true, value: value };
+}
+export function formatAvatarValue(value) {
+    return FIELD_ORDER.filter((key) => value[key] !== undefined)
+        .map((key) => `${key}=${value[key]}`)
+        .join(";");
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "aaavatars",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Deterministic 2D character avatars with a play() animation API",
+  "keywords": [
+    "avatar",
+    "react",
+    "svg",
+    "ai-agent",
+    "agent-avatar",
+    "animation",
+    "identicon",
+    "generative",
+    "deterministic"
+  ],
+  "author": "Rudolf Schmidt",
+  "license": "MIT",
+  "homepage": "https://rsmdt.github.io/aaavatars/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rsmdt/aaavatars.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rsmdt/aaavatars/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -p tsconfig.build.json",
+    "build:demo": "vite build --base=/aaavatars/ --outDir demo-dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^29.1.1",
+    "lucide-react": "^1.57.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.4"
+  }
+}