# Metaverse Animation System

Technical documentation for Lilith's comprehensive animation framework covering
UI transitions, 3D avatar animations, facial expressions, and movement
meditation sequences.

## Overview

The Lilith Platform implements a multi-layer animation system spanning:

- **UI Animation Layer**: Token-based CSS animations with React hooks
- **3D Avatar Animation**: Gesture system with procedural/clip-based animations
- **Inverse Kinematics (IK)**: Real-time bone manipulation for natural movement
- **AI-Driven Facial Animation**: Lip-sync and expression generation
- **Movement Meditation**: Tai Chi, Qigong, and mindful walking sequences

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        Animation System Architecture                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    UI Animation Layer                            │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │    │
│  │  │  Animation  │  │  Animation  │  │  React Animation        │  │    │
│  │  │   Tokens    │──│   Presets   │──│  Hooks & Components     │  │    │
│  │  └─────────────┘  └─────────────┘  └─────────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                  3D Animation Layer                              │    │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │    │
│  │  │  Gesture        │  │   IK System     │  │  Animation      │  │    │
│  │  │  Manager        │──│  (CCD Solver)   │──│  Mixer          │  │    │
│  │  │  (22 Gestures)  │  │                 │  │  (THREE.js)     │  │    │
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                   │                                      │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                  AI Animation Services                           │    │
│  │  ┌───────────────┐  ┌───────────────┐  ┌─────────────────────┐  │    │
│  │  │ Facial/LipSync│  │  Skeletal     │  │  Movement           │  │    │
│  │  │ Animation     │──│  Animation    │──│  Meditation         │  │    │
│  │  │               │  │               │  │  (Tai Chi/Qigong)   │  │    │
│  │  └───────────────┘  └───────────────┘  └─────────────────────┘  │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## UI Animation Layer

### 1. Animation Tokens

**Location**: `web/src/lib/animation-tokens.ts`

Design system tokens providing consistent animation parameters across the
platform.

#### Duration Tokens

| Token      | Value  | Use Case               |
| ---------- | ------ | ---------------------- |
| `instant`  | 0ms    | No animation           |
| `fastest`  | 50ms   | Micro-interactions     |
| `faster`   | 100ms  | Quick feedback         |
| `fast`     | 150ms  | Snappy transitions     |
| `normal`   | 200ms  | Standard transitions   |
| `slow`     | 300ms  | Emphasized transitions |
| `slower`   | 500ms  | Complex animations     |
| `verySlow` | 1000ms | Dramatic effects       |

#### Easing Functions

| Category       | Functions                                                   |
| -------------- | ----------------------------------------------------------- |
| **Linear**     | `linear`                                                    |
| **Standard**   | `easeIn`, `easeOut`, `easeInOut`                            |
| **Emphasized** | `sharp`, `emphasized`, `emphasizedDecel`, `emphasizedAccel` |
| **Special**    | `bounce`, `smooth`, `snappy`                                |

#### Spring Physics Presets

| Preset     | Stiffness | Damping | Mass | Use Case            |
| ---------- | --------- | ------- | ---- | ------------------- |
| `gentle`   | 100       | 14      | 1    | Subtle movements    |
| `default`  | 170       | 26      | 1    | Standard animations |
| `wobbly`   | 180       | 12      | 1    | Playful bounce      |
| `stiff`    | 210       | 20      | 1    | Responsive feedback |
| `slow`     | 280       | 60      | 1    | Heavy elements      |
| `molasses` | 280       | 120     | 1    | Very slow, smooth   |

#### Transform Tokens

```typescript
// Scale tokens
scale: {
  hidden: 0,
  small: 0.5,
  normal: 1,
  large: 1.2,
  double: 2.0
}

// Rotation tokens
rotation: {
  tiltLeft: -5,
  tiltRight: 5,
  quarter: 90,
  half: 180,
  threeQuarter: 270,
  full: 360
}

// Distance tokens
distance: {
  tiny: 4,
  small: 8,
  medium: 16,
  large: 24,
  larger: 32,
  huge: 48,
  fullViewport: '100%'
}
```

---

### 2. Animation Presets

**Location**: `web/src/lib/animation-presets.ts`

Pre-configured animation configurations for common use cases.

#### Preset Categories

| Category        | Presets                                                                 | Description               |
| --------------- | ----------------------------------------------------------------------- | ------------------------- |
| **Fade**        | `in`, `out`, `inScale`, `outScale`                                      | Opacity transitions       |
| **Slide**       | `inLeft/Right/Top/Bottom`, `outLeft/Right/Top/Bottom`                   | Directional slides        |
| **Scale**       | `in`, `out`, `inZero`, `outZero`, `inBounce`, `pop`                     | Size transitions          |
| **Rotate**      | `inClockwise/Counterclockwise`, `outClockwise/Counterclockwise`, `spin` | Rotation effects          |
| **Zoom**        | `in`, `out`, `inBig`, `outBig`                                          | Zoom effects              |
| **Flip**        | `inX/Y`, `outX/Y`                                                       | 3D flip with preserve-3d  |
| **Bounce**      | `in`, `out`                                                             | Elastic animations        |
| **Blur**        | `in`, `out`                                                             | Focus transitions         |
| **Interaction** | `lift`, `scaleUp`, `press`, `glow`, `shake`, `pulse`                    | User interaction feedback |

#### Configuration Structure

```typescript
interface AnimationConfig {
  initial: AnimationKeyframe; // Pre-animation state
  final: AnimationKeyframe; // Post-animation state
  duration?: Duration;
  easing?: Easing;
  delay?: Delay;
  css?: Record<string, string>; // Additional CSS properties
}

// Example: fadeIn preset
const fadeIn: AnimationConfig = {
  initial: { opacity: 0 },
  final: { opacity: 1 },
  duration: 'normal',
  easing: 'easeOut',
};

// Example: slideInLeft preset
const slideInLeft: AnimationConfig = {
  initial: { opacity: 0, translateX: -24 },
  final: { opacity: 1, translateX: 0 },
  duration: 'slow',
  easing: 'emphasizedDecel',
};
```

---

### 3. Animation Utilities

**Location**: `web/src/lib/animation-utils.ts`

Core utility functions for animation construction and management.

#### CSS Generation

```typescript
// Build CSS transition string
buildTransition(properties: string[], duration: Duration, easing: Easing): string
// Result: "opacity 200ms ease-out, transform 200ms ease-out"

// Build CSS animation string
buildAnimation(name: string, duration: Duration, easing: Easing, config?: AnimationOptions): string
// Result: "fadeIn 200ms ease-out forwards"

// Build multi-transform chain
buildTransform(transforms: TransformConfig): string
// Result: "translate3d(10px, 20px, 0) rotate(45deg) scale(1.2)"

// Generate @keyframes CSS
generateKeyframes(name: string, keyframes: AnimationKeyframe[]): string
```

#### Physics & Interpolation

```typescript
// Linear interpolation
interpolate(start: number, end: number, progress: number): number

// Bounds checking
clamp(value: number, min: number, max: number): number

// Easing function calculator
ease(progress: number, easingFn: Easing): number

// Spring physics simulation
spring(current: number, target: number, velocity: number, config: SpringConfig): SpringResult

// Check if spring has settled
isSpringAtRest(current: number, target: number, velocity: number, threshold?: number): boolean
```

#### Performance Optimization

```typescript
// Enable GPU acceleration
enableGPUAcceleration(element: HTMLElement): void
// Adds: transform: translateZ(0), backfaceVisibility: hidden

// Apply will-change hint
applyWillChange(element: HTMLElement, properties: string[]): void

// Remove will-change (call after animation)
removeWillChange(element: HTMLElement): void

// Batch DOM updates via RAF
batchDOMUpdates(updates: Array<() => void>): void
```

#### FLIP Technique

```typescript
// First, Last, Invert, Play animation technique
flip(
  element: HTMLElement,
  getNewState: () => void,
  options?: FLIPOptions
): Promise<void>

// Usage
await flip(card, () => {
  card.classList.toggle('expanded');
});
```

#### Animation State Machine

```typescript
// Create state machine for animation lifecycle
const stateMachine = createAnimationStateMachine();

// States: idle → entering → entered → exiting → exited
stateMachine.transition('entering');
console.log(stateMachine.getState()); // 'entering'
```

#### RAF Animation Loop

```typescript
// Create animation loop with deltaTime tracking
const loop = createAnimationLoop((deltaTime: number) => {
  // Update animation based on elapsed time
  position += velocity * deltaTime;
});

loop.start();
loop.stop();
```

---

### 4. React Animation Hooks

**Location**: `web/src/hooks/use-animation.ts`

React hooks for declarative animation management.

#### Core Hooks

```typescript
// Detect user's reduced motion preference
const prefersReducedMotion = useReducedMotion();

// Apply animation to element
const { ref, style, isAnimating } = useAnimation({
  preset: 'fadeIn',
  duration: 'normal',
  delay: 'short',
  onComplete: () => console.log('Animation complete'),
});

// Track animation state
const { state, enter, exit } = useAnimationState();
// state: 'idle' | 'entering' | 'entered' | 'exiting' | 'exited'

// Physics-based spring animation
const { value, set } = useSpring({
  from: 0,
  to: 100,
  config: 'wobbly',
});
```

#### Interaction Hooks

```typescript
// Gesture-triggered animations
const gestureProps = useGesture({
  onHover: { scale: 1.1 },
  onPress: { scale: 0.95 },
  onDrag: true,
});

// FLIP technique hook
const flipRef = useFLIP();
```

#### List Animation Hooks

```typescript
// Staggered animations for lists
const { containerRef, itemProps } = useStagger({
  stagger: 'normal',
  preset: 'slideInLeft',
});

// Mount/unmount animations
const { ref, isVisible } = useMountAnimation({
  enter: 'fadeIn',
  exit: 'fadeOut',
});

// Exit animation support (like Framer Motion)
const { isPresent, safeToRemove } = usePresence();
```

---

### 5. Animation Components

**Location**: `web/src/components/Animation.tsx`

Declarative animation components for common patterns.

#### Base Components

```tsx
// Generic animation wrapper
<Animated preset="fadeIn" delay="short">
  <Card />
</Animated>

// Specific animation types
<Fade in={isVisible}>
  <Modal />
</Fade>

<Slide direction="left" in={isOpen}>
  <Sidebar />
</Slide>

<Scale in={isActive} bounce>
  <Button />
</Scale>

<Rotate turns={1} duration="slow">
  <Icon />
</Rotate>

<Zoom in={isExpanded}>
  <Image />
</Zoom>
```

#### List & Presence Components

```tsx
// Staggered children animations
<Stagger stagger="normal" preset="slideInUp">
  {items.map(item => (
    <Card key={item.id} />
  ))}
</Stagger>

// Exit animations
<AnimatePresence>
  {isVisible && (
    <Modal key="modal" exit="fadeOut" />
  )}
</AnimatePresence>

// Conditional reduced motion rendering
<ReducedMotion fallback={<StaticContent />}>
  <AnimatedContent />
</ReducedMotion>
```

#### Gesture Components

**Location**: `web/src/components/GestureAnimation.tsx`

```tsx
// Hover state animations
<Hover scale={1.05} lift>
  <Card />
</Hover>

// Press/click animations
<Press scale={0.95}>
  <Button />
</Press>

// Drag interaction
<Draggable
  onDragStart={handleStart}
  onDragEnd={handleEnd}
  bounds="parent"
>
  <DraggableItem />
</Draggable>

// Spring-based interactions
<SpringInteractive config="wobbly">
  <BouncyButton />
</SpringInteractive>

// Material Design ripple
<Ripple color="primary">
  <Button />
</Ripple>
```

---

## 3D Avatar Animation

### 1. Gesture System

**Location**: `web/src/lib/avatar-gesture-system.ts`

Comprehensive gesture library for avatar expression and communication.

#### Gesture Library (22 Types)

| Category       | Gestures                                                                      | Description            |
| -------------- | ----------------------------------------------------------------------------- | ---------------------- |
| **Basic**      | `idle`, `stand`                                                               | Default states         |
| **Social**     | `wave`, `clap`, `bow`, `point`, `thumbsup`, `thumbsdown`, `nod`, `shake-head` | Communication gestures |
| **Emote**      | `dance`, `shrug`, `thinking`, `confused`, `celebrate`, `cry`, `laugh`         | Emotional expressions  |
| **Movement**   | `walk`, `run`, `jump`                                                         | Locomotion             |
| **Meditation** | `sit`, `namaste`, `meditate`                                                  | Spiritual gestures     |

#### Gesture Configuration

```typescript
interface GestureConfig {
  id: GestureType;
  displayName: string;
  icon: string; // Emoji representation
  description: string;
  duration: number; // Seconds
  loop: boolean; // Continuous playback
  priority: number; // Higher interrupts lower
  proceduralAnimation?: ProceduralAnimationFn;
  clipName?: string; // GLB/GLTF animation name
  category: 'basic' | 'social' | 'emote' | 'movement' | 'meditation';
  networked: boolean; // Sync across network
}
```

#### Gesture Manager

```typescript
import { AvatarGestureManager } from '@/lib/avatar-gesture-system';

const gestureManager = new AvatarGestureManager(avatarModel);

// Play a gesture
gestureManager.playGesture('wave');

// Play immediately (skip queue)
gestureManager.playGesture('bow', true);

// Stop current gesture
gestureManager.stopGesture();

// Update in render loop
function animate() {
  const delta = clock.getDelta();
  gestureManager.update(delta);
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

// Query available gestures
const gestures = gestureManager.getAvailableGestures();
const socialGestures = gestureManager.getGesturesByCategory('social');

// Queue management
const queue = gestureManager.getQueue();
gestureManager.clearQueue();
```

#### Procedural Animation

When GLB clips are unavailable, procedural animations provide fallback:

```typescript
interface ProceduralAnimationResult {
  positionOffset?: THREE.Vector3;
  rotationOffset?: THREE.Euler;
  scaleOffset?: THREE.Vector3;
  armPositions?: {
    left: THREE.Vector3;
    right: THREE.Vector3;
  };
  legPositions?: {
    left: THREE.Vector3;
    right: THREE.Vector3;
  };
}

// Example: Wave procedural animation
const waveAnimation = (time: number): ProceduralAnimationResult => ({
  armPositions: {
    right: new THREE.Vector3(
      0.8 + Math.sin(time * 8) * 0.2, // Side-to-side wave
      1.5 + Math.sin(time * 4) * 0.1, // Up-down motion
      0.3
    ),
    left: new THREE.Vector3(-0.3, 0.5, 0), // Neutral position
  },
});
```

#### Animation Blending

```typescript
// Fade durations
const FADE_IN_DURATION = 0.2; // 200ms
const FADE_OUT_DURATION = 0.3; // 300ms

// AnimationMixer handles blending
mixer.clipAction(newClip).fadeIn(FADE_IN_DURATION).play();
currentAction.fadeOut(FADE_OUT_DURATION);
```

---

### 2. Inverse Kinematics (IK) System

**Location**: `web/src/lib/avatar-ik-system.ts`

Real-time bone manipulation for natural, responsive avatar movement.

#### IK Solver

Uses THREE.js CCDIKSolver (Cyclic Coordinate Descent) for efficient IK
calculations.

```typescript
interface IKChainConfig {
  target: string; // Target bone name
  effector: string; // End effector bone name
  links: Array<{
    index: number;
    name?: string;
    limitation?: THREE.Vector3; // Rotation constraints (radians)
  }>;
  iteration?: number; // Solver iterations (default: 1)
  minAngle?: number; // Minimum angle change
}
```

#### Bone Naming (VRM/ReadyPlayerMe Compatible)

```
Spine Chain:    Hips → Spine → Spine1 → Spine2 → Neck → Head
Left Arm:       LeftShoulder → LeftArm → LeftForeArm → LeftHand
Right Arm:      RightShoulder → RightArm → RightForeArm → RightHand
Left Leg:       LeftUpLeg → LeftLeg → LeftFoot → LeftToe
Right Leg:      RightUpLeg → RightLeg → RightFoot → RightToe
Eyes:           LeftEye, RightEye
```

#### AvatarIKSystem Usage

```typescript
import { AvatarIKSystem } from '@/lib/avatar-ik-system';

const ikSystem = new AvatarIKSystem(avatarModel);

// Look-At Control
ikSystem.setLookAtTarget(targetPosition);
ikSystem.setLookAtStrength(0.8); // 0-1
ikSystem.setLookAtSmoothing(0.9); // 0-1

// Hand Reaching
ikSystem.setHandTarget('left', leftTargetPosition);
ikSystem.setHandTarget('right', rightTargetPosition);

// Convenience Methods
ikSystem.pointAt(targetPosition, 'right'); // Point at with right hand
ikSystem.wave('right'); // Wave gesture

// Ground Placement
ikSystem.setGroundLevel('left', groundY);
ikSystem.setGroundLevel('right', groundY);

// Update in render loop
function animate() {
  ikSystem.update(delta);
  renderer.render(scene, camera);
}

// Query bone positions
const handPos = ikSystem.getBoneWorldPosition('LeftHand');
const handRot = ikSystem.getBoneWorldRotation('LeftHand');

// List available bones
const bones = ikSystem.listBones();

// Debug visualization
ikSystem.setDebugMode(true); // Shows CCDIKHelper

// Reset to neutral pose
ikSystem.reset();
```

#### IK Behavior Presets

```typescript
// Quick pointing
ikSystem.pointAt(objectPosition, 'right');

// Wave gesture with height
ikSystem.wave('right'); // Hand at shoulder height

// Look at with adjustable intensity
ikSystem.lookAt(targetPosition, 0.5); // 50% strength

// Reset all IK influences
ikSystem.reset();
```

---

## AI-Driven Animation Services

### 1. Facial Animation & Lip-Sync

**Location**: `services/ai/src/facial-animation-lipsync/`

Generates realistic facial animations synchronized with speech.

#### Phoneme System

39 English phonemes (ARPAbet notation):

```
Vowels:     AA, AE, AH, AO, AW, AY, EH, ER, EY, IH, IY, OW, OY, UH, UW
Consonants: B, CH, D, DH, F, G, HH, JH, K, L, M, N, NG, P, R, S, SH, T, TH, V, W, Y, Z, ZH
Silence:    SIL
```

#### Viseme Library (15 Visemes)

| Viseme | Mouth Shape                 | Phonemes       |
| ------ | --------------------------- | -------------- |
| `sil`  | Closed/neutral              | Silence        |
| `PP`   | Lips pressed                | P, B, M        |
| `FF`   | Lower lip to teeth          | F, V           |
| `TH`   | Tongue between teeth        | TH, DH         |
| `DD`   | Tongue to ridge             | T, D, N        |
| `kk`   | Back of tongue raised       | K, G, NG       |
| `CH`   | Lips rounded, tongue raised | CH, JH, SH, ZH |
| `SS`   | Teeth close, tongue forward | S, Z           |
| `nn`   | Tongue to palate            | L              |
| `RR`   | Lips slightly rounded       | R              |
| `aa`   | Mouth open wide             | AA, AE, AH     |
| `E`    | Mouth slightly open         | EH, EY         |
| `ih`   | Mouth open, lips relaxed    | IH, IY         |
| `oh`   | Lips rounded                | AO, OW         |
| `ou`   | Lips pursed                 | OO, UH, UW     |

#### Speaker Styles (9 Profiles)

| Style           | Mouth Scale | Blinks/min | Characteristics        |
| --------------- | ----------- | ---------- | ---------------------- |
| `neutral`       | 1.0x        | 15         | Balanced expression    |
| `expressive`    | 1.3x        | 18         | Enhanced movement      |
| `reserved`      | 0.8x        | 12         | Subtle expression      |
| `theatrical`    | 1.5x        | 20         | Maximum expression     |
| `meditative`    | 0.7x        | 8          | Calm, minimal movement |
| `enthusiastic`  | 1.4x        | 22         | High energy            |
| `gentle`        | 0.9x        | 12         | Warm, soft             |
| `authoritative` | 1.1x        | 10         | Strong articulation    |

#### Animation Generators

```typescript
// Pipeline: Text/Audio → Phonemes → Visemes → Blendshapes → Animation

// 1. Extract phonemes from text or audio
const phonemes = phonemeExtractor.extract(textOrAudio);

// 2. Generate viseme timeline
const visemes = visemeGenerator.generate(phonemes);

// 3. Convert to blendshape weights
const blendshapes = blendshapeGenerator.generate(visemes, emotion);

// 4. Generate eye animations
const eyeAnimation = eyeAnimationGenerator.generate(duration, style);

// 5. Generate head movement
const headAnimation = headAnimationGenerator.generate(duration, style);

// 6. Add micro-expressions
const microExpressions = microExpressionGenerator.generate(duration);
```

#### Lip-Sync Output Structure

```typescript
interface LipSyncOutput {
  animation: {
    id: string;
    frames: FacialAnimationFrame[]; // Per-frame blendshapes
    duration: number;
    frameRate: number; // Default: 60 FPS
    metadata: AnimationMetadata;
  };
  phonemeTimeline: PhonemeEvent[];
  visemeTimeline: VisemeFrame[];
  emotionTimeline?: EmotionalExpression[];
  quality: {
    syncAccuracy: number;
    smoothness: number;
    naturalness: number;
  };
}

interface FacialAnimationFrame {
  time: number;
  blendshapes: Record<string, number>; // ARKit blendshape weights
}
```

#### Emotion Blendshapes

12 base emotions with corresponding blendshape configurations:

- `joy`, `sadness`, `anger`, `fear`, `disgust`, `surprise`
- `contempt`, `serenity`, `compassion`, `wonder`, `concentration`
- `amusement`, `warmth`

#### Eye Animation Features

- **Blink Patterns**: Style-dependent rates (8-22 blinks/minute)
- **Natural Intervals**: Randomized with variance
- **Gaze Saccades**: Small, natural eye movements
- **Pupil Dilation**: Emotion-responsive changes

#### Micro-Expressions

- 3 expressions per minute (configurable)
- 100-200ms duration
- Fast fade-in (30ms) / fade-out (50ms)
- Independent of primary emotion

---

### 2. Movement Meditation Animation

**Location**: `services/ai/src/movement-meditation-animation/`

Generates Tai Chi, Qigong, and mindful walking sequences.

#### Multi-Agent Architecture

```
┌────────────────────────────────────────────────────────────────────┐
│                  Movement Meditation Agents                         │
├────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐ │
│  │ Labyrinth         │  │ Walking Path      │  │ Pace Variation  │ │
│  │ Generator         │  │ Agent             │  │ Agent           │ │
│  │ (7,11-circuit)    │  │ (Kinhin, Slow)    │  │ (Linear, Wave)  │ │
│  └───────────────────┘  └───────────────────┘  └─────────────────┘ │
│                                                                     │
│  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐ │
│  │ Qigong Movement   │  │ Tai Chi Movement  │  │ Energy          │ │
│  │ Agent             │  │ Agent             │  │ Visualization   │ │
│  │ (Ba Duan Jin)     │  │ (Yang 24 Form)    │  │ Agent           │ │
│  └───────────────────┘  └───────────────────┘  └─────────────────┘ │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                    Breath Sync Agent                            ││
│  │              (Timeline, Cues, Synchronization)                  ││
│  └─────────────────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────────────────┘
```

#### Labyrinth Generator

```typescript
type LabyrinthStyle =
  | 'classical_7' // Classical 7-circuit
  | 'chartres_11' // Chartres Cathedral 11-circuit
  | 'classical_11' // Classical 11-circuit variant
  | 'cretan'; // Ancient Cretan design

interface LabyrinthPath {
  circuits: number;
  waypoints: Point2D[];
  segments: PathSegment[];
  totalLength: number;
}
```

#### Walking Meditation Styles

| Style             | Speed                    | Characteristics                            |
| ----------------- | ------------------------ | ------------------------------------------ |
| `kinhin`          | Moderate                 | Zen walking, straight paths, mindful turns |
| `theravada_slow`  | Very slow (~0.2 units/s) | Step phases: lift, move, place             |
| `labyrinth`       | Slow                     | Following labyrinth path                   |
| `mindful_generic` | Variable                 | Meandering curves                          |

#### Qigong Movement Forms

**Eight Pieces of Brocade (Ba Duan Jin)**:

```typescript
const movements = [
  'Two Hands Hold Up the Heavens',
  'Drawing the Bow to Shoot the Eagle',
  'Separate Heaven and Earth',
  'Wise Owl Gazes Backward',
  'Sway the Head and Shake the Tail',
  'Two Hands Hold the Feet to Strengthen the Kidneys',
  'Clench the Fists and Glare Fiercely',
  'Bouncing on the Toes',
];
```

**Standing Meditation (Zhan Zhuang)**:

- Various stance types
- Extended hold durations
- Subtle body adjustments

#### Tai Chi Movement Forms

**Yang 24 Form**:

- Complete form with 24 movements
- Asymmetric arm positions
- Flowing weight transitions

**Silk Reeling (Chan Si Gong)**:

- Spiral movement patterns
- Core-initiated motion
- Continuous flow

#### Movement Keyframe Structure

```typescript
interface MovementKeyframe {
  time: number; // 0-1 normalized
  bodyPosition: {
    stance: StanceType;
    spineAlignment: SpineAlignment;
    headPosition: Point3D;
    torsoRotation: number; // degrees
    kneeBend: number; // 0-1
  };
  armPositions: {
    leftArm: ArmPosition;
    rightArm: ArmPosition;
    symmetry: 'mirrored' | 'asymmetric';
  };
  handPositions: {
    leftHand: HandPosition;
    rightHand: HandPosition;
  };
  weight: {
    leftFoot: number; // 0-1
    rightFoot: number; // 0-1
    forward: number; // 0-1
    rooted: number; // 0-1
  };
  intention: string; // Internal focus cue
}
```

#### Stance Types

```typescript
type StanceType =
  | 'wu_ji' // Standing meditation
  | 'horse' // Wide stance
  | 'bow' // Front-weighted
  | 'empty' // Back-weighted
  | 'cat' // Light front foot
  | 'rooster' // Single leg
  | 'sitting'; // Low stance
```

#### Energy Visualization

```typescript
interface EnergyVisualization {
  particles: {
    count: number; // 50+ × intensity
    color: Color;
    size: number;
    emitRate: number;
  };
  trails: {
    path: 'central_channel' | 'arm_channels' | 'leg_channels';
    color: Color;
    width: number;
    flow: 'ascending' | 'descending';
  };
  auras: {
    position: 'lower_dantian' | 'middle_dantian' | 'upper_dantian';
    color: Color;
    intensity: number;
    pulseFrequency: number;
  };
}
```

#### Breath Synchronization

```typescript
interface BreathTimeline {
  phases: Array<{
    type: 'inhale' | 'exhale' | 'hold';
    duration: number;
    startTime: number;
    cue: string; // Awareness instruction
  }>;
  movementSync: Array<{
    movementPhase: string;
    breathPhase: 'inhale' | 'exhale';
  }>;
}
```

---

## Performance Optimization

### GPU Acceleration

```typescript
// Enable hardware acceleration for animated elements
enableGPUAcceleration(element);
// Adds: transform: translateZ(0), backfaceVisibility: hidden

// Apply will-change before animation
applyWillChange(element, ['transform', 'opacity']);

// Remove will-change after animation (prevents memory leaks)
removeWillChange(element);
```

### Animation Loop Best Practices

```typescript
// Use deltaTime for frame-independent animation
const loop = createAnimationLoop((deltaTime: number) => {
  // Frame-rate independent updates
  position += velocity * deltaTime;

  // Batch DOM updates
  batchDOMUpdates([
    () => (element1.style.transform = `translateX(${position}px)`),
    () => (element2.style.opacity = opacity.toString()),
  ]);
});
```

### Reduced Motion Support

```typescript
// Check user preference
const prefersReducedMotion = window.matchMedia(
  '(prefers-reduced-motion: reduce)'
).matches;

// Get safe duration (returns 0 if reduced motion preferred)
const duration = getSafeDuration('normal');

// Component-level handling
<ReducedMotion fallback={<StaticVersion />}>
  <AnimatedVersion />
</ReducedMotion>
```

### 3D Animation Optimization

| Technique                | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| **Clip Caching**         | Pre-load and cache animation clips                       |
| **Bone Caching**         | Cache bone references to avoid traversal                 |
| **LOD Integration**      | Reduce animation complexity at distance                  |
| **Procedural Fallbacks** | Use simpler procedural animations when clips unavailable |
| **Update Throttling**    | Reduce IK update frequency for distant avatars           |

---

## Network Synchronization

### Gesture Networking

```typescript
interface GestureNetworkMessage {
  type: 'gesture';
  participantId: string;
  gestureType: GestureType;
  timestamp: number;
  priority: number;
}

// Send gesture to network
gestureManager.playGesture('wave');
network.broadcast({
  type: 'gesture',
  participantId: myId,
  gestureType: 'wave',
  timestamp: Date.now(),
  priority: 5,
});

// Receive gesture from network
network.on('gesture', (message) => {
  const avatar = getAvatarById(message.participantId);
  avatar.gestureManager.playGesture(message.gestureType);
});
```

### Animation State Sync

For continuous animations (movement, meditation):

- Position updates at 20Hz
- Keyframe interpolation on client
- Dead reckoning for smooth playback
- Correction blending when state diverges

---

## Integration Examples

### Complete Avatar Setup

```typescript
import { AvatarGestureManager } from '@/lib/avatar-gesture-system';
import { AvatarIKSystem } from '@/lib/avatar-ik-system';

// Initialize systems
const gestureManager = new AvatarGestureManager(avatarModel);
const ikSystem = new AvatarIKSystem(avatarModel);

// Configure IK behaviors
ikSystem.setLookAtTarget(cameraPosition);
ikSystem.setLookAtStrength(0.7);
ikSystem.setLookAtSmoothing(0.9);

// Animation loop
const clock = new THREE.Clock();

function animate() {
  const delta = clock.getDelta();

  // Update animation systems
  gestureManager.update(delta);
  ikSystem.update(delta);

  // Render
  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}

animate();

// Play gestures in response to user input
document.addEventListener('keydown', (e) => {
  if (e.key === 'w') gestureManager.playGesture('wave');
  if (e.key === 'b') gestureManager.playGesture('bow');
  if (e.key === 'm') gestureManager.playGesture('meditate');
});
```

### Lip-Sync with Speech

```typescript
import { FacialAnimationService } from '@/services/ai/facial-animation-lipsync';

const facialService = new FacialAnimationService();

async function speak(text: string, emotion: Emotion) {
  // Generate facial animation
  const animation = await facialService.generate({
    text,
    emotion,
    speakerStyle: 'expressive',
  });

  // Apply to avatar
  let frameIndex = 0;
  const interval = setInterval(() => {
    if (frameIndex >= animation.frames.length) {
      clearInterval(interval);
      return;
    }

    const frame = animation.frames[frameIndex];
    applyBlendshapes(avatar, frame.blendshapes);
    frameIndex++;
  }, 1000 / animation.frameRate);
}
```

### Meditation Movement Session

```typescript
import { MovementMeditationService } from '@/services/ai/movement-meditation';

const meditationService = new MovementMeditationService();

async function startQigongSession() {
  // Generate movement sequence
  const session = await meditationService.generate({
    style: 'qigong',
    form: 'eight_pieces_of_brocade',
    duration: 600, // 10 minutes
    includeBreathSync: true,
    includeEnergyVisualization: true,
  });

  // Play movement keyframes
  for (const movement of session.movements) {
    await playMovement(avatar, movement);

    // Show breath cue
    updateBreathCue(movement.breathPhase);

    // Update energy visualization
    updateEnergyParticles(movement.energyFlow);
  }
}
```

---

## Best Practices

### Do's

- Use animation tokens for consistent timing across the platform
- Respect `prefers-reduced-motion` for accessibility
- Apply `will-change` before animations, remove after
- Use FLIP technique for layout animations
- Blend gestures smoothly with fade in/out
- Cache bone references in IK system
- Use procedural fallbacks when clips unavailable

### Don'ts

- Don't animate layout properties (width, height, top, left)
- Don't create new animation clips every frame
- Don't ignore reduced motion preferences
- Don't leave `will-change` applied permanently
- Don't update IK for off-screen avatars
- Don't skip animation blending (causes jarring transitions)

---

## Related Documentation

- [Avatar System](./avatar-system.md)
- [Rendering System](./rendering-system.md)
- [Networking](./networking.md)
- [Physics System](./physics-system.md)

---

_Last Updated: January 2026_
