webavatar-core/packages/humanoid

@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 ServerEvents 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.