# @webavatar/webavatar-humanoid

Renderer-agnostic avatar-state derivation and animation-channel composition for 3D humanoid avatars rigged with ARKit blend shapes. An **optional** package — infrastructure only some webavatar client projects need (one building a 2D avatar has no reason to depend on this at all). See the monorepo root's `docs/HUMANOID.md` for the full design writeup.

**ESM-only.** No CommonJS build; `require()` is unsupported by design.

## Entry points

| Entry                                      | Contains                                                                                                                                                                                                                                   |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@webavatar/webavatar-humanoid`            | `AvatarState`/`AvatarSignal`/`nextAvatarState` (the pure state-transition reducer), `AnimationConfig`/`DEFAULT_ANIMATION_CONFIG`/`resolveAnimationConfig`, `ARKitBlendShape`/`AnimationFrame`/`AnimationLayer`/`compositeAnimationFrames`. |
| `@webavatar/webavatar-humanoid/client`     | `deriveAvatarState` — the browser wrapper that folds a live `RealtimeClient`'s `ServerEvent`s through the pure reducer and owns the `idleActive`→`idlePassive` timer.                                                                      |
| `@webavatar/webavatar-humanoid/eye`        | The first animation library built as a consumer of the root contract: the Macro/Micro/Nano gaze system (`stepEyeGaze`, `EyeConfig`/`DEFAULT_EYE_CONFIG`/`resolveEyeConfig`, `gazeOffsetToBlendShapes`).                                    |
| `@webavatar/webavatar-humanoid/eye/client` | `createEyeGazeController` — the browser wrapper that owns the gaze system's per-frame clock and `Math.random`.                                                                                                                             |

Future animation libraries (blink, lip-sync, body/gesture) are expected to nest the same way, as `./<name>` / `./<name>/client` sub-packages, rather than becoming further top-level packages.

## What this package is not

No renderer knowledge (Three.js, Babylon, a game engine — none of it), no rig/mesh binding, no Svelte dependency (its hand-rolled stores satisfy the Svelte store contract structurally). Consuming code owns which `ARKitBlendShape` maps to which morph target on its own mesh.

## Core dependency: type-only

This package's only relationship to `@webavatar/webavatar-core` is a **type-only** import (`import type { ServerEvent }`) — its built JavaScript contains no runtime reference to core at all, verified as part of this package's own build (`grep -rl "webavatar-core" dist --include="*.js"` finds nothing). Core is declared as a `peerDependency` purely so npm reports a version-compatibility error at install time if a project's core and humanoid versions drift apart — not because this package calls into core at runtime.

## Compatibility

Caret-ranged (`^0.1.0`) during the `0.x` window — every humanoid release during this window bumps its peer/dev range on core in the same commit as any core minor it needs to track. See the monorepo root's `docs/MONOREPO_MIGRATION_BRIEF.md` ("Versions, ranges, and the `0.x` window") for the full policy.