@vibeo/cli 0.3.3 → 0.3.5

package/skills/vibeo-effects/SKILL.md

@@ -0,0 +1,432 @@
+# Vibeo Effects (`@vibeo/effects`)
+
+## Overview
+
+`@vibeo/effects` provides advanced animation primitives that go beyond basic interpolation: declarative keyframes, spring physics, scene transitions, and audio-reactive animation hooks.
+
+**When to use**: When you need keyframe animation, physics-based springs, transitions between scenes, or audio-driven visuals.
+
+---
+
+## API Reference
+
+### `useKeyframes(frame, keyframes, options?): number`
+
+Declarative keyframe animation. Automatically interpolates between keyframe stops.
+
+```ts
+import { useKeyframes } from "@vibeo/effects";
+import { useCurrentFrame, easeInOut } from "@vibeo/core";
+
+const frame = useCurrentFrame();
+const y = useKeyframes(frame, { 0: 0, 30: 100, 60: 0 }, { easing: easeInOut });
+```
+
+**Parameters**:
+| Param | Type | Description |
+|-------|------|-------------|
+| `frame` | `number` | Current frame (pass `useCurrentFrame()`) |
+| `keyframes` | `KeyframeMap` | `Record<number, KeyframeStop>` — frame-to-value mapping |
+| `options?` | `KeyframeOptions` | Default easing function |
+
+**`KeyframeStop`**: `number | { value: number; easing?: (t: number) => number }`
+
+Per-segment easing uses the **starting** stop's easing function for that segment.
+
+```ts
+const scale = useKeyframes(frame, {
+  0: { value: 0, easing: easeIn },
+  20: { value: 1.2, easing: easeOut },
+  30: 1,
+});
+```
+
+### `useSpring(options): number`
+
+Physics-based spring animation. Simulates mass-spring-damper system per frame.
+
+```ts
+import { useSpring } from "@vibeo/effects";
+
+const x = useSpring({ from: 0, to: 100 });
+const bouncy = useSpring({ from: 0, to: 1, config: { mass: 1, stiffness: 300, damping: 10 } });
+```
+
+**`SpringOptions`**:
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `from` | `number` | — | Start value |
+| `to` | `number` | — | Target value |
+| `frame?` | `number` | `useCurrentFrame()` | Frame override |
+| `fps?` | `number` | `useVideoConfig().fps` | FPS override |
+| `config?` | `SpringConfig` | see below | Physics parameters |
+
+**`SpringConfig`** (defaults):
+| Field | Default | Description |
+|-------|---------|-------------|
+| `mass` | `1` | Mass of the object |
+| `stiffness` | `170` | Spring stiffness |
+| `damping` | `26` | Damping coefficient |
+
+### `springDuration(options): number`
+
+Compute how many frames a spring takes to settle.
+
+```ts
+const dur = springDuration({ fps: 30, config: { stiffness: 300, damping: 10 } });
+```
+
+### `Transition`
+
+Component for transitioning between exactly two children.
+
+```tsx
+import { Transition } from "@vibeo/effects";
+import { Sequence } from "@vibeo/core";
+
+<Sequence from={55} durationInFrames={20}>
+  <Transition type="fade" durationInFrames={20}>
+    <SceneA />
+    <SceneB />
+  </Transition>
+</Sequence>
+```
+
+**`TransitionProps`**:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `TransitionType` | — | `"fade" \| "wipe" \| "slide" \| "dissolve"` |
+| `durationInFrames` | `number` | — | Frames the transition lasts |
+| `timing?` | `TransitionTiming` | `"in-and-out"` | `"in-and-out" \| "in" \| "out"` |
+| `direction?` | `TransitionDirection` | `"left"` | `"left" \| "right" \| "up" \| "down"` (for wipe/slide) |
+| `children` | `[ReactNode, ReactNode]` | — | Exactly 2 children |
+
+### Transition Strategies
+
+```ts
+import { fade, wipe, slide, dissolve } from "@vibeo/effects";
+```
+
+Each returns `{ childA: CSSProperties; childB: CSSProperties }` for a given `TransitionState`.
+
+| Strategy | Effect |
+|----------|--------|
+| `fade` | Opacity crossfade |
+| `wipe` | Clip-path reveal |
+| `slide` | Transform slide in/out |
+| `dissolve` | Mix-blend + opacity |
+
+### `useAudioData(audioSrc, options?): AudioAnalysis | null`
+
+Pre-analyzes an audio file and returns per-frame frequency/amplitude data. Returns `null` while loading.
+
+```ts
+import { useAudioData } from "@vibeo/effects";
+
+const data = useAudioData("/music.mp3", { fftSize: 2048 });
+if (data) {
+  // data.amplitude — overall RMS amplitude (0-1)
+  // data.bass      — average energy in 20-250 Hz
+  // data.mid       — average energy in 250-4000 Hz
+  // data.treble    — average energy in 4000-20000 Hz
+  // data.frequencies — Float32Array of FFT magnitude data (dB)
+}
+```
+
+**`AudioDataOptions`**:
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `fftSize?` | `number` | `2048` | FFT window size (power of 2) |
+
+**`AudioAnalysis`**:
+| Field | Type | Description |
+|-------|------|-------------|
+| `amplitude` | `number` | Overall RMS amplitude (0-1 range) |
+| `frequencies` | `Float32Array` | Full FFT magnitude data in dB |
+| `bass` | `number` | Average energy 20-250 Hz |
+| `mid` | `number` | Average energy 250-4000 Hz |
+| `treble` | `number` | Average energy 4000-20000 Hz |
+
+### `useTransitionProgress(durationInFrames): number | null`
+
+Returns the transition progress (0 to 1) within a transition window, or `null` outside.
+
+```ts
+const progress = useTransitionProgress(20);
+if (progress !== null) {
+  // 0 at start of transition, 1 at end
+}
+```
+
+### Types
+
+```ts
+import type {
+  KeyframeStop,
+  KeyframeMap,
+  KeyframeOptions,
+  SpringConfig,
+  SpringOptions,
+  TransitionTiming,
+  TransitionDirection,
+  TransitionType,
+  TransitionProps,
+  TransitionState,
+  AudioAnalysis,
+  AudioDataOptions,
+} from "@vibeo/effects";
+```
+
+---
+
+## Keyframe Animation Recipes
+
+### Fade in
+
+```ts
+const opacity = useKeyframes(frame, { 0: 0, 30: 1 });
+```
+
+### Bounce
+
+```ts
+const y = useKeyframes(frame, {
+  0: 0,
+  15: { value: -100, easing: easeOut },
+  30: { value: 0, easing: easeIn },
+  45: { value: -40, easing: easeOut },
+  60: 0,
+});
+```
+
+### Slide in from left
+
+```ts
+const x = useKeyframes(frame, {
+  0: -1920,
+  30: { value: 0, easing: easeOut },
+});
+```
+
+### Scale pulse
+
+```ts
+const scale = useKeyframes(frame, { 0: 1, 15: 1.2, 30: 1 }, { easing: easeInOut });
+```
+
+---
+
+## Spring Animation Guide
+
+### Snappy UI motion
+```ts
+useSpring({ from: 0, to: 1, config: { stiffness: 300, damping: 30 } })
+```
+
+### Bouncy entrance
+```ts
+useSpring({ from: 0, to: 1, config: { stiffness: 400, damping: 10, mass: 1 } })
+```
+
+### Slow, heavy drag
+```ts
+useSpring({ from: 0, to: 1, config: { stiffness: 50, damping: 20, mass: 3 } })
+```
+
+### Gentle ease
+```ts
+useSpring({ from: 0, to: 1, config: { stiffness: 100, damping: 26 } })
+```
+
+**Tuning guide**:
+- Higher `stiffness` = faster motion, more overshoot
+- Higher `damping` = less bounce, settles faster
+- Higher `mass` = slower, more momentum
+
+---
+
+## Transition Usage Between Scenes
+
+```tsx
+function MyVideo() {
+  return (
+    <>
+      {/* Scene A plays frames 0-59 */}
+      <Sequence from={0} durationInFrames={75}>
+        <SceneA />
+      </Sequence>
+
+      {/* 15-frame fade transition overlapping scenes */}
+      <Sequence from={55} durationInFrames={20}>
+        <Transition type="fade" durationInFrames={20}>
+          <SceneA />
+          <SceneB />
+        </Transition>
+      </Sequence>
+
+      {/* Scene B continues */}
+      <Sequence from={75} durationInFrames={90}>
+        <SceneB />
+      </Sequence>
+    </>
+  );
+}
+```
+
+For directional transitions:
+```tsx
+<Transition type="slide" durationInFrames={20} direction="right">
+  <OldScene />
+  <NewScene />
+</Transition>
+```
+
+---
+
+## Audio-Reactive Animation Patterns
+
+### Beat-reactive scale
+
+```tsx
+function BeatCircle() {
+  const frame = useCurrentFrame();
+  const audio = useAudioData("/track.mp3");
+  const baseScale = audio ? 1 + audio.bass * 2 : 1;
+
+  return (
+    <div style={{
+      width: 100,
+      height: 100,
+      borderRadius: "50%",
+      background: "white",
+      transform: `scale(${baseScale})`,
+    }} />
+  );
+}
+```
+
+### Audio visualizer bars
+
+```tsx
+function Visualizer() {
+  const audio = useAudioData("/music.mp3", { fftSize: 512 });
+  if (!audio) return null;
+
+  const barCount = 32;
+  const step = Math.floor(audio.frequencies.length / barCount);
+
+  return (
+    <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
+      {Array.from({ length: barCount }, (_, i) => {
+        const db = audio.frequencies[i * step];
+        const height = Math.max(2, ((db + 100) / 100) * 200);
+        return <div key={i} style={{ width: 8, height, margin: 1, background: "cyan" }} />;
+      })}
+    </div>
+  );
+}
+```
+
+### Background color shift with amplitude
+
+```tsx
+function ReactiveBackground({ children }: { children: React.ReactNode }) {
+  const audio = useAudioData("/music.mp3");
+  const hue = audio ? Math.round(audio.amplitude * 360) : 200;
+  const lightness = audio ? 20 + audio.amplitude * 30 : 20;
+
+  return (
+    <div style={{
+      width: "100%",
+      height: "100%",
+      background: `hsl(${hue}, 70%, ${lightness}%)`,
+    }}>
+      {children}
+    </div>
+  );
+}
+```
+
+---
+
+## Gotchas and Tips
+
+1. **`useAudioData` returns `null` initially** — always handle the loading state.
+
+2. **`useKeyframes` clamps at boundaries** — it won't extrapolate beyond the first/last keyframe.
+
+3. **`<Transition>` must have exactly 2 children** — it throws if you pass more or fewer.
+
+4. **Spring simulations are cached** at the module level for identical parameters, so repeated renders are cheap.
+
+5. **`useKeyframes` requires you to pass `frame` explicitly** — it doesn't call `useCurrentFrame()` internally. This gives you flexibility to use any frame value.
+
+6. **`springDuration()` is useful for sizing `<Sequence>` wrappers** to match how long a spring animation takes to settle.
+
+
+---
+
+## LLM & Agent Integration
+
+Vibeo's CLI is built with [incur](https://github.com/wevm/incur), making it natively discoverable by AI agents and LLMs.
+
+### Discovering the API
+
+```bash
+# Get a compact summary of all CLI commands (ideal for LLM system prompts)
+bunx @vibeo/cli --llms
+
+# Get the full manifest with schemas, examples, and argument details
+bunx @vibeo/cli --llms-full
+
+# Get JSON Schema for a specific command (useful for structured tool calls)
+bunx @vibeo/cli render --schema
+bunx @vibeo/cli create --schema
+```
+
+### Using as an MCP Server
+
+```bash
+# Start Vibeo as an MCP (Model Context Protocol) server
+bunx @vibeo/cli --mcp
+
+# Register as a persistent MCP server for your agent
+bunx @vibeo/cli mcp add
+```
+
+This lets LLMs call `create`, `render`, `preview`, and `list` as structured tool calls through the MCP protocol.
+
+### Generating Skill Files
+
+```bash
+# Sync skill files to your agent's skill directory
+bunx @vibeo/cli skills add
+```
+
+This generates markdown skill files that agents like Claude Code can discover and use to write Vibeo code without reading source.
+
+### Agent-Friendly Output
+
+```bash
+# Output as JSON for programmatic consumption
+bunx @vibeo/cli list --entry src/index.tsx --format json
+
+# Output as YAML
+bunx @vibeo/cli list --entry src/index.tsx --format yaml
+
+# Filter output to specific keys
+bunx @vibeo/cli list --entry src/index.tsx --filter-output compositions[0].id
+
+# Count tokens in output (useful for context window planning)
+bunx @vibeo/cli render --schema --token-count
+```
+
+### How LLMs Should Use Vibeo
+
+1. **Discover commands**: Run `bunx @vibeo/cli --llms` to get the command manifest
+2. **Create a project**: `bunx @vibeo/cli create my-video --template basic`
+3. **Edit `src/index.tsx`**: Write React components using `@vibeo/core` hooks and components
+4. **Preview**: `bunx @vibeo/cli preview --entry src/index.tsx`
+5. **Render**: `bunx @vibeo/cli render --entry src/index.tsx --composition MyComp`
+
+All commands accept `--format json` for structured output that LLMs can parse reliably.