# remotion-bits — High-Level Components for Remotion

`remotion-bits` is a companion library that provides pre-built, animated components for common video patterns. **Use these instead of building from scratch.**

## Installation

Already included in VibeEditing session projects:
```json
"remotion-bits": "^0.1.12"
```

## Components

### AnimatedText
Text with built-in entrance animations.

```tsx
import { AnimatedText } from 'remotion-bits';

<AnimatedText
  text="Hello World"
  animation="fadeUp" // or "fadeIn", "slideLeft", etc.
  delay={0}
  duration={30}
  style={{ fontSize: 80, fontWeight: 700 }}
/>
```

### TypeWriter
Character-by-character text reveal with cursor.

```tsx
import { TypeWriter } from 'remotion-bits';

<TypeWriter
  text="Building the future..."
  speed={2} // characters per frame
  cursor={true}
  cursorChar="|"
  style={{ fontFamily: 'monospace' }}
/>
```

### AnimatedCounter
Smooth number counting animation.

```tsx
import { AnimatedCounter } from 'remotion-bits';

<AnimatedCounter
  from={0}
  to={1000}
  duration={60}
  format={(n) => `$${n.toLocaleString()}`}
  style={{ fontSize: 120 }}
/>
```

### StaggeredMotion
Animate children with staggered delays.

```tsx
import { StaggeredMotion } from 'remotion-bits';

<StaggeredMotion
  stagger={10} // frames between each child
  animation="fadeUp"
>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</StaggeredMotion>
```

### Particles + Spawner + Behavior
Configurable particle system for backgrounds.

```tsx
import { Particles, Spawner, Behavior, useViewportRect } from 'remotion-bits';

const rect = useViewportRect();

<Particles count={50}>
  <Spawner 
    rect={rect} 
    initialVelocity={{ x: 0, y: -0.5 }} 
  />
  <Behavior
    type="float"
    amplitude={10}
    frequency={0.02}
  />
</Particles>
```

### GradientTransition
Animated gradient backgrounds.

```tsx
import { GradientTransition } from 'remotion-bits';

<GradientTransition
  colors={['#7c3aed', '#c026d3', '#e11d48']}
  angle={135}
  duration={90}
/>
```

### MatrixRain
Matrix-style falling characters effect.

```tsx
import { MatrixRain } from 'remotion-bits';

<MatrixRain
  color="#00ff00"
  speed={2}
  density={0.8}
/>
```

### ScrollingColumns
Infinite scrolling image/content columns.

```tsx
import { ScrollingColumns } from 'remotion-bits';

<ScrollingColumns
  columns={[
    { items: [img1, img2, img3], speed: 1, direction: 'up' },
    { items: [img4, img5, img6], speed: 1.5, direction: 'down' },
  ]}
  gap={20}
/>
```

### CodeBlock
Syntax-highlighted code display.

```tsx
import { CodeBlock } from 'remotion-bits';

<CodeBlock
  code={`const hello = "world";`}
  language="typescript"
  theme="dark"
  showLineNumbers={true}
/>
```

### Scene3D + Step + Element3D + Transform3D
**AE-style flying camera system.** See [scene3d-camera.md](scene3d-camera.md) for full docs.

```tsx
import { Scene3D, Step, Element3D, Transform3D } from 'remotion-bits';

<Scene3D 
  perspective={1200} 
  transitionDuration={60}  // frames to fly between steps
  stepDuration={80}        // frames per step
  easing="easeInOutCubic"
>
  <Step id="intro" x={0} y={0} z={0}>
    <IntroContent />
  </Step>
  
  <Step id="feature" x={200} y={0} z={-100} rotateY={-15}>
    <FeatureContent />
  </Step>
</Scene3D>

// Chainable transforms
const t = Transform3D.identity()
  .translate(100, 0, -50)
  .rotateY(-15)
  .scaleBy(1.5);

<Step id="scene" {...t.toProps()} />
```

Camera automatically flies between Steps with quaternion SLERP (no gimbal lock).

## Utility Functions

### Color Utilities
```tsx
import { hexToRgb, rgbToHex, interpolateColor } from 'remotion-bits';

const midColor = interpolateColor('#ff0000', '#0000ff', 0.5);
```

### Gradient Utilities
```tsx
import { createGradient, animateGradient } from 'remotion-bits';

const gradient = createGradient(['#7c3aed', '#c026d3'], 135);
```

### Motion Utilities
```tsx
import { spring, easeInOut, cubicBezier } from 'remotion-bits';
```

### Geometry Utilities
```tsx
import { distance, angle, lerp, clamp } from 'remotion-bits';
```

### Random Utilities (deterministic)
```tsx
import { seededRandom, shuffle, pick } from 'remotion-bits';

// Use frame as seed for deterministic randomness
const value = seededRandom(frame);
```

## Hooks

### useViewportRect
Get the viewport dimensions for responsive layouts.

```tsx
import { useViewportRect } from 'remotion-bits';

const Component = () => {
  const rect = useViewportRect();
  // rect = { width: 1080, height: 1920, ... }
};
```

## When to Use remotion-bits

| Task | Use remotion-bits | Build from scratch |
|------|-------------------|-------------------|
| Text with entrance animation | ✅ `AnimatedText` | ❌ |
| Typewriter effect | ✅ `TypeWriter` | ❌ |
| Number counting | ✅ `AnimatedCounter` | ❌ |
| List with staggered reveal | ✅ `StaggeredMotion` | ❌ |
| Floating particles | ✅ `Particles` | ❌ |
| Gradient backgrounds | ✅ `GradientTransition` | ❌ |
| 3D transforms | ✅ `Scene3D` | Maybe (if simple) |
| Custom complex animation | Maybe | ✅ |

**Rule:** If remotion-bits has a component for it, **use it**. Don't reinvent.
