vargai 0.4.0-alpha2 → 0.4.0-alpha21

package/launch-videos/07-ugc-weight-loss.tsx

@@ -0,0 +1,132 @@
+/**
+ * Launch Video #7: UGC Weight Loss Transformation
+ *
+ * Ultra realistic AI UGC ad - split screen before/after with voiceover and captions.
+ * Left: overweight person (Higgsfield), Right: slim fit person (nano-banana-pro/edit)
+ *
+ * Run: bunx vargai render launch-videos/07-ugc-weight-loss.tsx
+ *
+ * Note: Requires GROQ_API_KEY for auto-captions transcription
+ */
+import { elevenlabs, fal, higgsfield } from "vargai/ai";
+import {
+  Captions,
+  Clip,
+  Image,
+  Music,
+  Render,
+  Speech,
+  SplitLayout,
+  Title,
+  Video,
+} from "vargai/react";
+
+// === VOICEOVER SCRIPT ===
+const VOICEOVER_SCRIPT =
+  "With this technique I lost 40 pounds in just 3 months!";
+
+// === VOICE SETTINGS ===
+// Using turbo model for faster generation, and a more energetic voice
+const VOICE_ID = "aMSt68OGf4xUZAnLpTU8"; // energetic female voice
+const VOICE_MODEL = elevenlabs.speechModel("eleven_multilingual_v2");
+
+// === CHARACTER DEFINITION ===
+const CHARACTER_DESCRIPTION = "woman in her 30s, brown hair, green eyes";
+const BEFORE_BODY = "overweight, puffy face, double chin, tired expression";
+const AFTER_BODY =
+  "fit slim, defined jawline, glowing skin, confident radiant smile";
+
+// === SCENE SETTINGS ===
+const SCENE_SETTING = "bathroom mirror selfie, iPhone photo quality";
+const BEFORE_LIGHTING =
+  "soft unflattering lighting, no makeup, messy hair in bun";
+const AFTER_LIGHTING =
+  "good lighting, light natural makeup, hair down and styled";
+
+// === PROMPTS ===
+const BEFORE_PROMPT = `ultra realistic photo of ${CHARACTER_DESCRIPTION}, ${BEFORE_BODY}, wearing loose grey t-shirt, ${SCENE_SETTING}, ${BEFORE_LIGHTING}, slightly sad eyes, authentic candid look, photorealistic, 8k`;
+
+const AFTER_PROMPT = `ultra realistic photo of ${CHARACTER_DESCRIPTION}, ${AFTER_BODY}, wearing fitted black tank top, ${SCENE_SETTING}, ${AFTER_LIGHTING}, bright happy eyes, authentic proud look, same woman as before but 40 pounds lighter, photorealistic, 8k`;
+
+// === MOTION DESCRIPTIONS ===
+const BEFORE_MOTION =
+  "woman looks down sadly, sighs, then looks at camera with tired expression, subtle breathing, authentic movement";
+const AFTER_MOTION =
+  "woman smiles confidently, touches hair, looks at camera proudly, slight head tilt, happy subtle movement";
+
+// === IMAGES ===
+// Before image - generated with Higgsfield Soul (realistic style)
+const beforeImage = Image({
+  prompt: BEFORE_PROMPT,
+  model: higgsfield.imageModel("soul", {
+    styleId: higgsfield.styles.REALISTIC,
+  }),
+  aspectRatio: "9:16",
+});
+
+// After image - generated with nano-banana-pro/edit using before as reference
+const afterImage = Image({
+  prompt: { text: AFTER_PROMPT, images: [beforeImage] },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// === VIDEOS ===
+// Before video - sad/tired movement
+const beforeVideo = Video({
+  prompt: { text: BEFORE_MOTION, images: [beforeImage] },
+  model: fal.videoModel("kling-v2.5"),
+  duration: 5,
+});
+
+// After video - confident/happy movement
+const afterVideo = Video({
+  prompt: { text: AFTER_MOTION, images: [afterImage] },
+  model: fal.videoModel("kling-v2.5"),
+  duration: 5,
+});
+
+// === VOICEOVER ===
+const voiceover = Speech({
+  model: VOICE_MODEL,
+  voice: VOICE_ID,
+  children: VOICEOVER_SCRIPT,
+});
+
+// === MUSIC ===
+const MUSIC_PROMPT =
+  "upbeat motivational pop, inspiring transformation music, energetic but not overwhelming, modern fitness vibe";
+const MUSIC_DURATION = 15;
+const MUSIC_VOLUME = 0.15; // Low volume so voiceover is clear
+
+// === CAPTIONS SETTINGS ===
+const CAPTIONS_STYLE = "tiktok";
+const CAPTIONS_COLOR = "#ffffff";
+
+// === TITLE TEXT ===
+const TITLE_TEXT = "My 3-Month Transformation";
+
+export default (
+  <Render width={1080 * 2} height={1920}>
+    {/* Background music (low volume) */}
+    <Music prompt={MUSIC_PROMPT} model={elevenlabs.musicModel()} />
+
+    {/* Main clip with split screen */}
+    <Clip duration={5}>
+      {/* Split layout - before on left, after on right */}
+      <SplitLayout
+        direction="horizontal"
+        left={beforeVideo}
+        right={afterVideo}
+      />
+
+      {/* Title at top */}
+      <Title position="top" color="#ffffff">
+        {TITLE_TEXT}
+      </Title>
+    </Clip>
+
+    {/* TikTok-style captions with voiceover */}
+    <Captions src={voiceover} style={CAPTIONS_STYLE} color={CAPTIONS_COLOR} />
+  </Render>
+);

package/launch-videos/08-talking-head-varg.tsx

@@ -0,0 +1,107 @@
+/**
+ * Launch Video #8: Talking Head - varg Promo with Lipsync
+ *
+ * A beautiful character says "with varg you can create anything at scale"
+ * Uses Higgsfield Soul for character, nano-banana-pro/edit for branded clothing,
+ * Animate for image-to-video, and Video with sync-v2 for lip synchronization
+ *
+ * Run: bunx vargai render launch-videos/08-talking-head-varg.tsx
+ */
+import { elevenlabs, fal, higgsfield } from "vargai/ai";
+import {
+  Captions,
+  Clip,
+  Image,
+  Music,
+  Render,
+  Speech,
+  Video,
+} from "vargai/react";
+
+// === VOICEOVER SCRIPT ===
+const VOICEOVER_SCRIPT =
+  "With varg, you can create any videos anything at scale!";
+
+// === VOICE SETTINGS ===
+const VOICE_ID = "5l5f8iK3YPeGga21rQIX"; // friendly female voice
+
+// === CHARACTER PROMPT ===
+const CHARACTER_BASE_PROMPT = `A close, spontaneous iPhone selfie of a beautiful East Asian woman in her early 20s with sleek jet-black chin-length bob hair and porcelain skin. She wears a fitted black t-shirt, with dewy, natural skin textures and almond-shaped dark brown eyes filling the frame. The soft morning light filters through a minimalist Scandinavian bedroom with blurred details, including simple, natural wood furniture and neutral textiles. Her calm, inviting expression appears relaxed and looking at camera, with a casual, slightly off-center framing emphasizing genuine intimacy. The image embodies authentic iPhone lighting and texture, capturing an intimate, natural moment with understated elegance.`;
+
+// === CLOTHING MODIFICATION PROMPT ===
+const CLOTHING_EDIT_PROMPT = `Same woman, same pose, same lighting. Her black tank t-shirt now has a stylish geometric pattern printed on it. Keep everything else identical - face, hair, expression, background.`;
+
+// === VARG PATTERN REFERENCE ===
+const VARG_PATTERN_URL =
+  "https://s3.varg.ai/uploads/images/varg-pattern_631fa5f2.png";
+
+// === MOTION PROMPT ===
+const MOTION_PROMPT =
+  "woman speaking naturally, subtle head movements, friendly expression, looking at camera";
+
+// === IMAGES ===
+// Base character - generated with Higgsfield Soul (realistic style)
+const baseCharacter = Image({
+  prompt: CHARACTER_BASE_PROMPT,
+  model: higgsfield.imageModel("soul", {
+    styleId: higgsfield.styles.REALISTIC,
+  }),
+  aspectRatio: "9:16",
+});
+
+// Character with varg pattern on clothing
+const brandedCharacter = Image({
+  prompt: {
+    text: CLOTHING_EDIT_PROMPT,
+    images: [baseCharacter, VARG_PATTERN_URL],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// === ANIMATED CHARACTER (image-to-video) ===
+const animatedCharacter = Video({
+  prompt: {
+    text: MOTION_PROMPT,
+    images: [brandedCharacter],
+  },
+  model: fal.videoModel("kling-v2.5"),
+});
+
+// === VOICEOVER ===
+const voiceover = Speech({
+  model: elevenlabs.speechModel("eleven_v3"),
+  voice: VOICE_ID,
+  children: VOICEOVER_SCRIPT,
+});
+
+// === MUSIC ===
+const MUSIC_PROMPT =
+  "modern tech ambient, subtle electronic, confident corporate vibe, minimal and clean";
+const MUSIC_VOLUME = 0.1;
+
+export default (
+  <Render width={1080} height={1920}>
+    {/* Subtle background music */}
+    <Music
+      prompt={MUSIC_PROMPT}
+      model={elevenlabs.musicModel()}
+      volume={MUSIC_VOLUME}
+    />
+
+    {/* Main talking head clip with lipsync */}
+    <Clip duration={5}>
+      {/* Lipsync: animated video + speech audio -> sync-v2 */}
+      <Video
+        prompt={{
+          video: animatedCharacter,
+          audio: voiceover,
+        }}
+        model={fal.videoModel("sync-v2-pro")}
+      />
+    </Clip>
+
+    {/* TikTok-style captions */}
+    <Captions src={voiceover} style="tiktok" color="#ffffff" />
+  </Render>
+);

package/launch-videos/09-girl.tsx

@@ -0,0 +1,160 @@
+import { fal } from "vargai/ai";
+import { Clip, Image, Render, Video } from "vargai/react";
+
+// ============ REFERENCES ============
+
+const WOMAN_REF =
+  "https://s3.varg.ai/uploads/images/tlhzlrio6janrkhrwd29h-qp3ofcnoqv0-m4z6gr_280fee62.png";
+const VARG_PATTERN = "https://s3.varg.ai/uploads/images/varg-pattern.png";
+
+// ============ CONFIG ============
+
+const OUTFIT =
+  "elegant black dress with bold graphic pattern from reference — fitted silhouette, off-shoulder neckline, knee-length, subtle sheen. Pattern integrated seamlessly into fabric";
+
+const characterBase = `Same girl from reference, consistent face and body proportions, same hairstyle, same posture.`;
+
+const location = `Elegant apartment with full-length mirror, warm ambient lighting, minimalist modern decor, soft evening glow through sheer curtains, neutral tones`;
+
+// ============ STEP 1: BASE CHARACTER IN WHITE ============
+
+const baseCharacter = Image({
+  prompt: {
+    text: `${characterBase}. She's taking a mirror selfie wearing a simple white cocktail dress. Standing in ${location}. Phone held up. Confident poised pose, weight on one hip. Full body visible in mirror reflection.`,
+    images: [WOMAN_REF],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// ============ STEP 2: EXTRACT BACKGROUND ============
+
+const background = Image({
+  prompt: {
+    text: `Remove the character completely from the image. Empty elegant apartment with full-length mirror, same lighting, same composition. No person.`,
+    images: [baseCharacter],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// ============ STEP 3: APPLY PATTERN TO DRESS ============
+
+const patternDressChar = Image({
+  prompt: {
+    text: `Change the dress to black with the exact pattern from the pattern reference image. Apply the pattern naturally across the dress fabric. Keep everything else exactly the same — same woman, same face, same pose, same lighting, same background.`,
+    images: [baseCharacter, VARG_PATTERN, background],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// ============ STEP 4: POSE VARIATIONS ============
+
+// Pose 2: Adjusting earring — close to mirror
+const pose2_earring = Image({
+  prompt: {
+    text: `${characterBase}. Wearing ${OUTFIT}. Mirror selfie in ${location}. Standing close to mirror, one hand adjusting earring, other holding phone. Soft smile, chin slightly lifted. Full body in reflection. Elegant posture. Dress has pattern from reference.`,
+    images: [patternDressChar, WOMAN_REF, VARG_PATTERN, background],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// Pose 3: Side angle — showing silhouette
+const pose3_side = Image({
+  prompt: {
+    text: `${characterBase}. Wearing ${OUTFIT}. Mirror selfie in ${location}. Standing at three-quarter angle to mirror, looking over shoulder at phone. Shows elegant silhouette and dress drape with pattern visible. Confident smile. Hand on hip.`,
+    images: [patternDressChar, WOMAN_REF, VARG_PATTERN, background],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// Pose 4: Back angle — DETAILED CONSISTENCY PROMPT
+const pose4_back = Image({
+  prompt: {
+    text: `Full back-view studio shot of the same girl from the reference, with perfect consistency of her body proportions, hairstyle, and posture. She is wearing the exact same outfit from the reference, including the identical fabric texture, the same material, the same pattern placement, the same silhouette, and the same fit across the shoulders, collar, sleeves, and back panel. Mirror selfie in ${location}. Looking over shoulder at phone with classy expression. One foot slightly forward.`,
+    images: [patternDressChar, WOMAN_REF, VARG_PATTERN, background],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+// ============ MOTION PROMPTS ============
+
+const motion1 = `Takes mirror selfie, shifts weight gracefully. Smooths dress with free hand. Tilts head finding best angle. Soft smile, taps phone. Confident elegant energy.`;
+
+const motion2 = `Standing close to mirror, adjusts earring. Touches hair, fixes strand behind ear. Lifts chin, takes pic. Checks phone, satisfied nod.`;
+
+const motion3 = `Turns to show side profile. Hand on hip, elongates posture. Looks over shoulder at mirror. Playful confident smile. Snaps pic.`;
+
+const motion4 = `Shows back to mirror, looks over shoulder elegantly. Slight sway, shows off dress back detail. Classy expression, subtle smile. Takes pic. Happy with result.`;
+
+// ============ VIDEOS ============
+
+const vid1 = Video({
+  prompt: {
+    images: [patternDressChar],
+    text: motion1,
+  },
+  model: fal.videoModel("kling-v2.5"),
+  duration: 5,
+  aspectRatio: "9:16",
+});
+
+const vid2 = Video({
+  prompt: {
+    images: [pose2_earring],
+    text: motion2,
+  },
+  model: fal.videoModel("kling-v2.5"),
+  duration: 5,
+  aspectRatio: "9:16",
+});
+
+const vid3 = Video({
+  prompt: {
+    images: [pose3_side],
+    text: motion3,
+  },
+  model: fal.videoModel("kling-v2.5"),
+  duration: 5,
+  aspectRatio: "9:16",
+});
+
+const vid4 = Video({
+  prompt: {
+    images: [pose4_back],
+    text: motion4,
+  },
+  model: fal.videoModel("kling-v2.5"),
+  duration: 5,
+  aspectRatio: "9:16",
+});
+
+// ============ FINAL RENDER ============
+
+export default (
+  <Render width={1080} height={1920}>
+    {/* Front pose — finding angle */}
+    <Clip cutFrom={0.5} cutTo={3}>
+      {vid1}
+    </Clip>
+
+    {/* Earring adjust — close-up vibes */}
+    <Clip cutFrom={0.5} cutTo={2.5}>
+      {vid2}
+    </Clip>
+
+    {/* Side — shows silhouette */}
+    <Clip cutFrom={0.5} cutTo={2.5}>
+      {vid3}
+    </Clip>
+
+    {/* Back — elegant reveal ✦ */}
+    <Clip cutFrom={0.5} cutTo={3}>
+      {vid4}
+    </Clip>
+  </Render>
+);

package/launch-videos/README.md

@@ -0,0 +1,42 @@
+# Launch Videos
+
+Pre-made video templates for vargai launch and demo purposes.
+
+## Videos
+
+| # | File | Description | Duration |
+|---|------|-------------|----------|
+| 1 | `01-hero.tsx` | Hero showcase - all capabilities in 15s | ~15s |
+| 2 | `02-talking-head.tsx` | AI presenter explaining vargai | ~25s |
+| 3 | `03-slideshow.tsx` | Dreamy AI-generated slideshow with music | ~25s |
+| 4 | `04-tiktok-style.tsx` | TikTok-style character video | ~10s |
+| 5 | `05-simple-demo.tsx` | Simplest possible video (one clip) | ~5s |
+
+## How to Render
+
+```bash
+# Preview mode (fast, uses placeholders)
+bunx vargai render launch-videos/01-hero.tsx --preview
+
+# Full render (uses AI generation)
+bunx vargai render launch-videos/01-hero.tsx
+
+# Output to specific path
+bunx vargai render launch-videos/01-hero.tsx -o my-video.mp4
+```
+
+## Requirements
+
+- `FAL_API_KEY` - Required for image/video generation
+- `ELEVENLABS_API_KEY` - Required for music/voice (videos 1, 2, 3, 4)
+
+## Output
+
+Videos are rendered to `output/` by default:
+- `output/01-hero.mp4`
+- `output/02-talking-head.mp4`
+- etc.
+
+## Customization
+
+Each file is a self-contained TSX component. Edit prompts, durations, or add/remove clips as needed.

package/package.json

@@ -3,7 +3,7 @@
   "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "varg": "./src/cli/index.ts"
+    "vargai": "./src/cli/index.ts"
   },
   "scripts": {
     "check": "biome check . && tsc --noEmit",
@@ -34,7 +34,8 @@
   },
   "peerDependencies": {
     "typescript": "^5",
-    "ai": "^6.0.0"
+    "ai": "^6.0.0",
+    "zod": "^3.25.76 || ^4.1.8"
   },
   "dependencies": {
     "@ai-sdk/fal": "^1.0.23",
@@ -61,9 +62,10 @@
     "react-dom": "^19.2.0",
     "remotion": "^4.0.377",
     "replicate": "^1.4.0",
+    "vargai": "^0.4.0-alpha11",
     "zod": "^4.2.1"
   },
-  "version": "0.4.0-alpha2",
+  "version": "0.4.0-alpha21",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",
@@ -71,6 +73,8 @@
     "./providers": "./src/providers/index.ts",
     "./definitions": "./src/definitions/index.ts",
     "./react": "./src/react/index.ts",
-    "./studio": "./src/studio/index.ts"
+    "./studio": "./src/studio/index.ts",
+    "./jsx-runtime": "./src/react/runtime/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/react/runtime/jsx-dev-runtime.ts"
   }
 }

package/skills/varg-video-generation/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: varg-video-generation
+description: Generate AI videos using varg SDK React engine. Use when creating videos, animations, talking characters, slideshows, or social media content. Always run onboarding first to check API keys.
+license: MIT
+metadata:
+  author: vargHQ
+  version: "1.0.0"
+compatibility: Requires bun runtime. FAL_API_KEY required. Optional ELEVENLABS_API_KEY, REPLICATE_API_TOKEN, GROQ_API_KEY
+allowed-tools: Bash(bun:*) Bash(cat:*) Read Write Edit
+---
+
+# Video Generation with varg React Engine
+
+Generate AI videos using declarative JSX syntax with automatic caching and parallel generation.
+
+## Quick Setup
+
+Run the setup script to initialize a project:
+
+```bash
+bun scripts/setup.ts
+```
+
+Or manually check API keys:
+
+```bash
+cat .env 2>/dev/null | grep -E "^(FAL_API_KEY|ELEVENLABS_API_KEY)=" || echo "No API keys found"
+```
+
+## Required API Keys
+
+### FAL_API_KEY (Required)
+
+| Detail | Value |
+|--------|-------|
+| Provider | Fal.ai |
+| Get it | https://fal.ai/dashboard/keys |
+| Free tier | Yes (limited credits) |
+| Used for | Image generation (Flux), Video generation (Wan 2.5, Kling) |
+
+If user doesn't have `FAL_API_KEY`:
+1. Direct them to https://fal.ai/dashboard/keys
+2. Create account and generate API key
+3. Add to `.env` file: `FAL_API_KEY=fal_xxxxx`
+
+### Optional Keys
+
+| Feature | Key | Provider | URL |
+|---------|-----|----------|-----|
+| Music/Voice | `ELEVENLABS_API_KEY` | ElevenLabs | https://elevenlabs.io/app/settings/api-keys |
+| Lipsync | `REPLICATE_API_TOKEN` | Replicate | https://replicate.com/account/api-tokens |
+| Transcription | `GROQ_API_KEY` | Groq | https://console.groq.com/keys |
+
+**Warn user about missing optional keys but continue with available features.**
+
+## Available Features by API Key
+
+**FAL_API_KEY only:**
+- Image generation (Flux models)
+- Image-to-video animation (Wan 2.5, Kling)
+- Text-to-video generation
+- Slideshows with transitions
+- Ken Burns zoom effects
+
+**FAL + ELEVENLABS:**
+- All above, plus:
+- AI-generated background music
+- Text-to-speech voiceovers
+- Talking character videos
+
+**All keys:**
+- Full production pipeline with lipsync and auto-captions
+
+## Quick Templates
+
+### Simple Slideshow (FAL only)
+
+```tsx
+import { render, Render, Clip, Image } from "vargai/react";
+
+const SCENES = ["sunset over ocean", "mountain peaks", "city at night"];
+
+await render(
+  <Render width={1080} height={1920}>
+    {SCENES.map((prompt, i) => (
+      <Clip key={i} duration={3} transition={{ name: "fade", duration: 0.5 }}>
+        <Image prompt={prompt} zoom="in" />
+      </Clip>
+    ))}
+  </Render>,
+  { output: "output/slideshow.mp4" }
+);
+```
+
+### Animated Video (FAL + ElevenLabs)
+
+```tsx
+import { render, Render, Clip, Image, Animate, Music } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+await render(
+  <Render width={1080} height={1920}>
+    <Music prompt="upbeat electronic" model={elevenlabs.musicModel()} duration={10} />
+    <Clip duration={5}>
+      <Animate
+        image={Image({ prompt: "cute cat on windowsill" })}
+        motion="cat turns head, blinks slowly"
+        model={fal.videoModel("wan-2.5")}
+        duration={5}
+      />
+    </Clip>
+  </Render>,
+  { output: "output/video.mp4" }
+);
+```
+
+### Talking Character
+
+```tsx
+import { render, Render, Clip, Image, Animate, Speech } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+await render(
+  <Render width={1080} height={1920}>
+    <Clip duration="auto">
+      <Animate
+        image={Image({ prompt: "friendly robot, blue metallic", aspectRatio: "9:16" })}
+        motion="robot talking, subtle head movements"
+        model={fal.videoModel("wan-2.5")}
+      />
+      <Speech voice="adam" model={elevenlabs.speechModel("turbo")}>
+        Hello! I'm your AI assistant. Let's create something amazing!
+      </Speech>
+    </Clip>
+  </Render>,
+  { output: "output/talking-robot.mp4" }
+);
+```
+
+See [references/templates.md](references/templates.md) for more templates.
+
+## Running Videos
+
+```bash
+bun run your-video.tsx
+```
+
+## Key Components
+
+| Component | Purpose | Required Key |
+|-----------|---------|--------------|
+| `<Render>` | Root container | - |
+| `<Clip>` | Sequential segment | - |
+| `<Image>` | AI image | FAL |
+| `<Animate>` | Image-to-video | FAL |
+| `<Music>` | Background music | ElevenLabs |
+| `<Speech>` | Text-to-speech | ElevenLabs |
+
+## Common Patterns
+
+### Character Consistency
+
+```tsx
+const character = Image({ prompt: "blue robot" });
+// Reuse same reference = same generated image
+<Animate image={character} motion="waving" />
+<Animate image={character} motion="dancing" />
+```
+
+### Transitions
+
+```tsx
+<Clip transition={{ name: "fade", duration: 0.5 }}>
+// Options: fade, crossfade, wipeleft, cube, slideup, etc.
+```
+
+### Aspect Ratios
+
+- `9:16` - TikTok, Reels, Shorts (vertical)
+- `16:9` - YouTube (horizontal)
+- `1:1` - Instagram (square)
+
+### Zoom Effects
+
+```tsx
+<Image prompt="landscape" zoom="in" />   // Zoom in
+<Image prompt="landscape" zoom="out" />  // Zoom out
+<Image prompt="landscape" zoom="left" /> // Pan left
+```
+
+## Troubleshooting
+
+### "FAL_API_KEY not found"
+- Check `.env` file exists in project root
+- Ensure no spaces around `=` sign
+- Restart terminal after adding keys
+
+### "Rate limit exceeded"
+- Free tier has limited credits
+- Wait or upgrade plan
+- Use caching to avoid regenerating
+
+### "Video generation failed"
+- Check prompt doesn't violate content policy
+- Try simpler motion descriptions
+- Reduce video duration
+
+## Next Steps
+
+1. Run `bun scripts/setup.ts` to initialize project
+2. Add your FAL_API_KEY to `.env`
+3. Run `bun run examples/my-first-video.tsx`
+4. Or ask the agent: "create a 10 second tiktok video about cats"