excalidraw/docs/threejs-libraries.md

# Three.js Libraries for Advanced Liquid Glass Effects

## React Three Fiber Ecosystem

### 1. React Three Fiber (@react-three/fiber)
**Purpose**: React bindings for Three.js
**Why Perfect for Excalidraw**: Integrates seamlessly with your existing React architecture

```jsx
import { Canvas } from '@react-three/fiber'

function GlassMenu() {
  return (
    <Canvas>
      <LiquidGlassMesh />
    </Canvas>
  )
}
```

### 2. Drei (@react-three/drei)
**Purpose**: Pre-built components and utilities for R3F
**Key Components for Glass Effects**:
- `MeshTransmissionMaterial` - Realistic glass/liquid refraction
- `Text` - 3D text with glass properties
- `Float` - Floating/hovering animations
- `Environment` - HDRI environments for realistic reflections

```jsx
import { MeshTransmissionMaterial, Float } from '@react-three/drei'

function GlassMenuItem() {
  return (
    <Float speed={2} rotationIntensity={0.1} floatIntensity={0.2}>
      <mesh>
        <boxGeometry args={[2, 0.5, 0.1]} />
        <MeshTransmissionMaterial
          transmission={0.9}
          roughness={0.1}
          thickness={0.5}
          ior={1.5}
          chromaticAberration={0.02}
        />
      </mesh>
    </Float>
  )
}
```

### 3. React Spring Three (@react-spring/three)
**Purpose**: Physics-based animations
**Perfect for**: Mercury-like surface tension behavior

```jsx
import { useSpring, animated } from '@react-spring/three'

function MercuryDroplet({ separated }) {
  const { position, scale } = useSpring({
    position: separated ? [2, 0, 0] : [0, 0, 0],
    scale: separated ? 0.8 : 1,
    config: { tension: 280, friction: 60 } // Mercury-like physics
  })
  
  return (
    <animated.mesh position={position} scale={scale}>
      {/* Glass geometry */}
    </animated.mesh>
  )
}
```

## Shader Libraries

### 4. Three.js Shader Material
**Purpose**: Custom glass displacement shaders
**Implementation**: Advanced refraction and chromatic aberration

```glsl
// Fragment shader for liquid glass
uniform float time;
uniform float displacement;
uniform vec3 aberrationStrength;

varying vec2 vUv;

void main() {
  // Displacement calculation
  vec2 distortedUv = vUv + sin(vUv * 10.0 + time) * displacement;
  
  // Chromatic aberration
  float r = texture2D(backgroundTexture, distortedUv + aberrationStrength.r).r;
  float g = texture2D(backgroundTexture, distortedUv + aberrationStrength.g).g;
  float b = texture2D(backgroundTexture, distortedUv + aberrationStrength.b).b;
  
  gl_FragColor = vec4(r, g, b, 0.8);
}
```

### 5. Lamina (Shader Material Builder)
**Purpose**: Visual shader editor for complex effects
**Benefits**: No GLSL knowledge required, visual node editor

```jsx
import { DiscardMaterial } from 'lamina'

<mesh>
  <DiscardMaterial
    baseMaterial={MeshPhysicalMaterial}
    onBeforeCompile={(shader) => {
      // Custom glass modifications
    }}
  />
</mesh>
```

## Physics and Interaction Libraries

### 6. use-gesture (@use-gesture/react)
**Purpose**: Advanced gesture handling
**Perfect for**: Drag-to-separate droplet interactions

```jsx
import { useDrag } from '@use-gesture/react'

function DraggableMenuItem() {
  const [{ x, y }, api] = useSpring(() => ({ x: 0, y: 0 }))
  
  const bind = useDrag(({ offset: [ox, oy], active }) => {
    api.start({ x: ox, y: oy, immediate: active })
    
    // Surface tension - snap back when released
    if (!active) {
      api.start({ x: 0, y: 0, config: { tension: 300, friction: 30 } })
    }
  })
  
  return (
    <animated.div {...bind()} style={{ x, y }}>
      {/* Menu item content */}
    </animated.div>
  )
}
```

### 7. Cannon.js Physics (use-cannon)
**Purpose**: Realistic physics simulation
**For Advanced Effects**: True fluid dynamics simulation

```jsx
import { useBox, useSphere, Physics } from '@react-three/cannon'

function PhysicsGlassMenu() {
  return (
    <Physics>
      <MainGlassContainer />
      <FloatingMenuItem />
    </Physics>
  )
}
```

## Recommended Implementation Approach

### Phase 1: CSS Prototype (Current)
- Use the CSS version I provided above
- Test user interactions and visual appeal
- Validate performance on your target devices

### Phase 2: Basic Three.js Integration
```bash
npm install @react-three/fiber @react-three/drei @react-spring/three
```

### Phase 3: Advanced Glass Materials
```jsx
// Advanced glass menu component
function AdvancedGlassMenu() {
  return (
    <Canvas>
      <Environment preset="studio" />
      <GlassMenuContainer>
        {menuItems.map((item, index) => (
          <GlassMenuItem key={index} {...item} />
        ))}
      </GlassMenuContainer>
    </Canvas>
  )
}
```

### Phase 4: Mercury Physics
- Implement surface tension using React Spring
- Add gesture-based separation with use-gesture
- Fine-tune physics parameters for mercury-like behavior

## Integration with Excalidraw Architecture

### Vite Configuration Updates
```js
// vite.config.mts additions
export default {
  // ... existing config
  optimizeDeps: {
    include: ['@react-three/fiber', '@react-three/drei']
  },
  resolve: {
    alias: {
      // Ensure Three.js uses single instance
      'three': 'three'
    }
  }
}
```

### Performance Considerations
- **WebGL Fallback**: Graceful degradation to CSS version
- **Bundle Size**: Tree-shake unused Three.js features
- **Mobile Support**: Simplified effects for touch devices
- **Accessibility**: Maintain keyboard navigation

## Next Steps for Your Implementation

1. **Start with CSS prototype** (provided above)
2. **Test in your Excalidraw environment**
3. **Choose Three.js approach** based on complexity needs:
   - Simple: Just MeshTransmissionMaterial
   - Advanced: Custom shaders + physics
4. **Implement progressive enhancement**
5. **A/B test with users** for optimal mercury physics settings