@vibeo/cli 0.3.4 → 0.4.0

package/skills/vibeo-rendering/SKILL.md

@@ -0,0 +1,367 @@
+# Vibeo Rendering (`@vibeo/renderer` + `@vibeo/cli`)
+
+## Overview
+
+`@vibeo/renderer` provides the headless rendering pipeline: bundling a Vibeo project, launching Playwright browser instances, capturing frames, and stitching them into video via FFmpeg. `@vibeo/cli` wraps this in a CLI.
+
+**When to use**: When you need to render a composition to a video file, preview it, or list available compositions.
+
+---
+
+## CLI Commands
+
+### `vibeo render`
+
+Render a composition to a video file.
+
+```bash
+bunx vibeo render --entry src/index.tsx --composition MyComp --output out.mp4
+```
+
+**Required flags**:
+| Flag | Description |
+|------|-------------|
+| `--entry <path>` | Path to the root file with compositions |
+| `--composition <id>` | Composition ID to render |
+
+**Optional flags**:
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--output <path>` | `out/<compositionId>.<ext>` | Output file path |
+| `--fps <number>` | Composition fps | Override frames per second |
+| `--frames <range>` | Full duration | Frame range, e.g. `"0-100"` |
+| `--codec <codec>` | `h264` | `h264 \| h265 \| vp9 \| prores` |
+| `--concurrency <n>` | `CPU cores / 2` | Parallel browser tabs |
+| `--image-format <fmt>` | `png` | `png \| jpeg` |
+| `--quality <n>` | `80` | JPEG quality / CRF value (0-100) |
+
+### `vibeo preview`
+
+Start a dev server with live preview in the browser.
+
+```bash
+bunx vibeo preview --entry src/index.tsx --port 3000
+```
+
+**Required flags**:
+| Flag | Description |
+|------|-------------|
+| `--entry <path>` | Path to the root file with compositions |
+
+**Optional flags**:
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port <number>` | `3000` | Port for the dev server |
+| `--help`, `-h` | — | Show help |
+
+### `vibeo list`
+
+List all registered compositions in the project. Bundles the entry, launches a headless browser, and prints a table of composition IDs with their dimensions, FPS, and duration.
+
+```bash
+bunx vibeo list --entry src/index.tsx
+```
+
+**Required flags**:
+| Flag | Description |
+|------|-------------|
+| `--entry <path>` | Path to the root file with compositions |
+
+**Optional flags**:
+| Flag | Description |
+|------|-------------|
+| `--help`, `-h` | Show help |
+
+---
+
+## Programmatic Rendering API
+
+### `renderComposition(config, compositionInfo): Promise<string>`
+
+Full render orchestration: bundle → capture frames → stitch video. Returns the path to the final output file.
+
+```ts
+import { renderComposition } from "@vibeo/renderer";
+
+const outputPath = await renderComposition(
+  {
+    entry: "src/index.tsx",
+    compositionId: "MyComp",
+    outputPath: "out/video.mp4",
+    codec: "h264",
+    imageFormat: "png",
+    quality: 80,
+    fps: null,           // use composition fps
+    frameRange: null,     // render all frames
+    concurrency: 4,
+    pixelFormat: "yuv420p",
+    onProgress: (p) => console.log(`${(p.percent * 100).toFixed(1)}%`),
+  },
+  { width: 1920, height: 1080, fps: 30, durationInFrames: 300 },
+);
+console.log(`Rendered to ${outputPath}`);
+```
+
+### `RenderConfig`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entry` | `string` | Path to the entry file |
+| `compositionId` | `string` | Composition ID |
+| `outputPath` | `string` | Output video path |
+| `codec` | `Codec` | Video codec |
+| `imageFormat` | `ImageFormat` | `"png" \| "jpeg"` |
+| `quality` | `number` | 0-100 quality/CRF |
+| `fps` | `number \| null` | FPS override |
+| `frameRange` | `FrameRange \| null` | `[start, end]` or null for all |
+| `concurrency` | `number` | Parallel browser tabs |
+| `pixelFormat` | `string` | FFmpeg pixel format |
+| `onProgress?` | `(progress: RenderProgress) => void` | Progress callback |
+
+### `RenderProgress`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `framesRendered` | `number` | Frames completed |
+| `totalFrames` | `number` | Total frames |
+| `percent` | `number` | 0-1 fraction |
+| `etaMs` | `number \| null` | Estimated time remaining (ms) |
+
+### Browser Lifecycle
+
+```ts
+import { launchBrowser, closeBrowser, createPage } from "@vibeo/renderer";
+
+const browser = await launchBrowser();
+const page = await createPage(browser, 1920, 1080); // browser, width, height
+// ... render frames ...
+await closeBrowser(); // closes the singleton browser, no argument needed
+```
+
+### Bundler
+
+```ts
+import { bundle } from "@vibeo/renderer";
+
+const result: BundleResult = await bundle(entryPath);
+// result.outDir — bundled output directory
+// result.url — URL to access bundled app
+// result.cleanup() — stop server and remove temp files
+```
+
+### Frame Operations
+
+```ts
+import { seekToFrame, loadBundle, captureFrame } from "@vibeo/renderer";
+
+await loadBundle(page, bundleUrl);
+await seekToFrame(page, 42, "MyComp");
+const filePath = await captureFrame(page, outputDir, frameNumber, {
+  imageFormat: "png",
+  quality: 80,  // optional, for jpeg
+});
+```
+
+### Frame Range Utilities
+
+```ts
+import { parseFrameRange, getRealFrameRange, validateFrameRange } from "@vibeo/renderer";
+
+const range = parseFrameRange("0-100", 300);         // parseFrameRange(input, durationInFrames) → [0, 100]
+const real = getRealFrameRange(300, range);           // getRealFrameRange(durationInFrames, frameRange) → [0, 100]
+const fullRange = getRealFrameRange(300, null);       // → [0, 299]
+validateFrameRange([0, 100], 300);                    // throws on invalid
+```
+
+### FFmpeg Stitching
+
+```ts
+import { stitchFrames, getContainerExt, stitchAudio } from "@vibeo/renderer";
+
+await stitchFrames({
+  framesDir: "/tmp/frames",
+  outputPath: "out.mp4",
+  fps: 30,
+  codec: "h264",
+  imageFormat: "png",
+  pixelFormat: "yuv420p",
+  quality: 80,
+  width: 1920,
+  height: 1080,
+});
+
+const ext = getContainerExt("vp9"); // "webm"
+
+await stitchAudio({
+  videoPath: "out.mp4",
+  audioPaths: ["/tmp/audio.wav"],
+  outputPath: "final.mp4",
+});
+```
+
+### Parallel Rendering
+
+```ts
+import { parallelRender } from "@vibeo/renderer";
+
+await parallelRender({
+  browser,               // Playwright Browser instance
+  bundleUrl,             // URL from bundle()
+  compositionId: "MyComp",
+  frameRange: [0, 299],  // [start, end] inclusive
+  outputDir: "/tmp/frames",
+  width: 1920,
+  height: 1080,
+  concurrency: 8,
+  imageFormat: "png",
+  quality: 80,            // optional
+  onProgress: (p) => {},  // optional RenderProgress callback
+});
+```
+
+---
+
+## Codec Options
+
+| Codec | Container | Use Case |
+|-------|-----------|----------|
+| `h264` | `.mp4` | General purpose, best compatibility |
+| `h265` | `.mp4` | Better compression, less compatible |
+| `vp9` | `.webm` | Web delivery, open format |
+| `prores` | `.mov` | Professional editing, lossless quality |
+
+### When to use each
+
+- **`h264`**: Default. Works everywhere. Good quality/size trade-off.
+- **`h265`**: 30-50% smaller files than h264 at same quality. Use when file size matters and playback devices support it.
+- **`vp9`**: Best for web embedding. Royalty-free.
+- **`prores`**: Editing workflows (Premiere, DaVinci). Large files but no quality loss.
+
+---
+
+## Output Format Options
+
+- **`png` frames**: Lossless intermediate frames. Larger but no quality loss during capture.
+- **`jpeg` frames**: Lossy but much smaller intermediate files. Use `--quality` to control (80 is good default).
+- **`pixelFormat: "yuv420p"`**: Standard for h264/h265. Use `"yuv444p"` for maximum color fidelity with prores.
+
+---
+
+## Parallel Rendering Config
+
+```bash
+# Use 8 parallel browser tabs
+bunx vibeo render --entry src/index.tsx --composition MyComp --concurrency 8
+```
+
+The frame range is split evenly across tabs. Default concurrency is `CPU cores / 2`.
+
+For a 300-frame video with `--concurrency 4`:
+- Tab 1: frames 0-74
+- Tab 2: frames 75-149
+- Tab 3: frames 150-224
+- Tab 4: frames 225-299
+
+---
+
+## Types
+
+```ts
+import type {
+  RenderConfig,
+  RenderProgress,
+  Codec,
+  ImageFormat,
+  FrameRange,
+  StitchOptions,
+  AudioMuxOptions,
+  BundleResult,
+} from "@vibeo/renderer";
+```
+
+---
+
+## Gotchas and Tips
+
+1. **FFmpeg must be installed** and available on `PATH` for stitching to work.
+
+2. **Playwright is required** — the renderer uses it for headless browser rendering. Install with `bunx playwright install chromium`.
+
+3. **Frame capture is the bottleneck** — increase `--concurrency` on machines with many cores to speed up rendering.
+
+4. **`--frames` range is inclusive** — `--frames=0-100` renders 101 frames.
+
+5. **Output directory is created automatically** — you don't need to `mkdir` before rendering.
+
+6. **`pixelFormat: "yuv420p"`** is required for most players to handle h264/h265 correctly.
+
+
+---
+
+## 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. **Create a project**: `bunx @vibeo/cli create my-video --template basic`
+2. **Install deps**: `cd my-video && bun install`
+3. **Install Playwright** (REQUIRED for render/list): `bunx playwright install chromium`
+4. **Edit `src/index.tsx`**: Write React components using `@vibeo/core` hooks and components
+5. **Preview**: `bunx @vibeo/cli preview --entry src/index.tsx`
+6. **Render**: `bunx @vibeo/cli render --entry src/index.tsx --composition MyComp`
+
+**Step 3 is mandatory** — `vibeo render` and `vibeo list` will fail with a cryptic Playwright error without it. `vibeo preview` works without it (uses Bun.serve, not Playwright).
+
+All commands accept `--format json` for structured output that LLMs can parse reliably.

package/skills/vibeo-tiktok/SKILL.md

@@ -0,0 +1,319 @@
+# Vibeo TikTok / Short-Form Video Generator
+
+Generate TikTok, YouTube Shorts, Instagram Reels, and other vertical (9:16) videos using Vibeo.
+
+**Trigger**: user says "TikTok", "Short", "Reel", "vertical video", "short-form", or asks for content for social media platforms.
+
+---
+
+## Format: ALWAYS 1080x1920 (9:16)
+
+```tsx
+<Composition
+  id="MyTikTok"
+  component={TikTokVideo}
+  width={1080}
+  height={1920}
+  fps={30}
+  durationInFrames={450} // 15 seconds
+/>
+```
+
+### Duration Guidelines
+
+| Platform | Sweet Spot | Max | Frames @ 30fps |
+|----------|-----------|-----|-----------------|
+| **TikTok** | 15-60s | 10 min | 450-1800 |
+| **YouTube Short** | 30-60s | 3 min | 900-1800 |
+| **Instagram Reel** | 15-30s | 20 min | 450-900 |
+| **Twitter/X** | 15-45s | 2m20s | 450-1350 |
+
+---
+
+## Vertical Layout Rules
+
+### DO
+
+```tsx
+// Stack vertically — top to bottom flow
+<div style={{
+  width: 1080, height: 1920,
+  display: "flex", flexDirection: "column",
+  justifyContent: "center", alignItems: "center",
+  padding: "100px 60px 150px", // safe zones: top status bar + bottom nav
+}}>
+  <h1 style={{ fontSize: 72, textAlign: "center" }}>Title</h1>
+  <div style={{ marginTop: 40 }}>
+    {/* Content */}
+  </div>
+</div>
+```
+
+### DON'T
+
+- No side-by-side layouts (too narrow at 1080px)
+- No font size < 36px (unreadable on phones)
+- No content in top 100px (status bar) or bottom 150px (nav gestures)
+- No multi-column grids
+- No landscape aspect ratios embedded inside
+
+---
+
+## Complete TikTok Template
+
+Hook → Content → CTA pattern (the standard viral format):
+
+```tsx
+import React from "react";
+import {
+  Composition, Sequence, VibeoRoot,
+  useCurrentFrame, useVideoConfig, interpolate, easeOut, easeInOut,
+} from "@vibeo/core";
+
+// ---- Scene Timing (centralized) ----
+const SCENES = {
+  hook:    { from: 0,    duration: 90  },  // 3s — attention grabber
+  content: { from: 90,   duration: 270 },  // 9s — main content
+  cta:     { from: 360,  duration: 90  },  // 3s — call to action
+} as const;
+const TOTAL = 450; // 15s
+
+// ---- Hook Scene (first 3 seconds = make or break) ----
+function HookScene({ text }: { text: string }) {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+
+  const scale = interpolate(frame, [0, 15], [0.5, 1], {
+    easing: easeOut, extrapolateRight: "clamp",
+  });
+  const opacity = interpolate(frame, [0, 10], [0, 1], { extrapolateRight: "clamp" });
+
+  // Pulsing glow effect
+  const glow = interpolate(frame % 30, [0, 15, 30], [0, 15, 0]);
+
+  return (
+    <div style={{
+      width, height, display: "flex", justifyContent: "center", alignItems: "center",
+      background: "linear-gradient(180deg, #0a0a0a, #1a0a2e)",
+      padding: "100px 60px 150px",
+    }}>
+      <h1 style={{
+        fontSize: 80, fontWeight: 900, color: "white",
+        textAlign: "center", lineHeight: 1.2,
+        opacity, transform: `scale(${scale})`,
+        textShadow: `0 0 ${glow}px rgba(138, 92, 246, 0.8)`,
+      }}>
+        {text}
+      </h1>
+    </div>
+  );
+}
+
+// ---- Content Scene (staggered points) ----
+function ContentScene({ points }: { points: string[] }) {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+
+  return (
+    <div style={{
+      width, height, display: "flex", flexDirection: "column",
+      justifyContent: "center", padding: "100px 60px 150px",
+      background: "#0a0a0a", gap: 24,
+    }}>
+      {points.map((point, i) => {
+        const delay = 15 + i * 20;
+        const opacity = interpolate(frame, [delay, delay + 15], [0, 1], {
+          extrapolateLeft: "clamp", extrapolateRight: "clamp",
+        });
+        const x = interpolate(frame, [delay, delay + 15], [-40, 0], {
+          easing: easeOut, extrapolateLeft: "clamp", extrapolateRight: "clamp",
+        });
+
+        return (
+          <div key={i} style={{
+            opacity, transform: `translateX(${x}px)`,
+            display: "flex", alignItems: "center", gap: 16,
+          }}>
+            <div style={{
+              width: 48, height: 48, borderRadius: 12,
+              background: "linear-gradient(135deg, #8b5cf6, #06b6d4)",
+              display: "flex", alignItems: "center", justifyContent: "center",
+              fontSize: 24, fontWeight: 700, color: "white",
+            }}>
+              {i + 1}
+            </div>
+            <span style={{ fontSize: 40, color: "white", fontWeight: 600 }}>
+              {point}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ---- CTA Scene ----
+function CTAScene({ text, subtext }: { text: string; subtext: string }) {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+
+  const scale = interpolate(frame, [0, 20], [0.8, 1], {
+    easing: easeOut, extrapolateRight: "clamp",
+  });
+  // Pulsing button effect
+  const btnScale = interpolate(frame % 30, [0, 15, 30], [1, 1.05, 1]);
+
+  return (
+    <div style={{
+      width, height, display: "flex", flexDirection: "column",
+      justifyContent: "center", alignItems: "center",
+      background: "linear-gradient(180deg, #0a0a0a, #1a0a2e)",
+      padding: "100px 60px 150px", transform: `scale(${scale})`,
+    }}>
+      <h1 style={{ fontSize: 72, fontWeight: 900, color: "white", textAlign: "center" }}>
+        {text}
+      </h1>
+      <div style={{
+        marginTop: 40, padding: "20px 60px", borderRadius: 50,
+        background: "linear-gradient(135deg, #8b5cf6, #06b6d4)",
+        fontSize: 36, fontWeight: 700, color: "white",
+        transform: `scale(${btnScale})`,
+      }}>
+        {subtext}
+      </div>
+    </div>
+  );
+}
+
+// ---- Main Video ----
+function TikTokVideo() {
+  return (
+    <>
+      <Sequence from={SCENES.hook.from} durationInFrames={SCENES.hook.duration}>
+        <HookScene text="3 things you didn't know about React" />
+      </Sequence>
+      <Sequence from={SCENES.content.from} durationInFrames={SCENES.content.duration}>
+        <ContentScene points={[
+          "Server Components are default",
+          "use() replaces useEffect",
+          "Actions replace forms",
+        ]} />
+      </Sequence>
+      <Sequence from={SCENES.cta.from} durationInFrames={SCENES.cta.duration}>
+        <CTAScene text="Follow for more" subtext="Like & Share →" />
+      </Sequence>
+    </>
+  );
+}
+
+// ---- Root ----
+export function Root() {
+  return (
+    <VibeoRoot>
+      <Composition
+        id="TikTokVideo"
+        component={TikTokVideo}
+        width={1080}
+        height={1920}
+        fps={30}
+        durationInFrames={TOTAL}
+      />
+    </VibeoRoot>
+  );
+}
+```
+
+---
+
+## TikTok Content Patterns
+
+### 1. "Did You Know" / Listicle (most common)
+
+```
+Hook (3s): Bold question or surprising claim
+Content (9-20s): 3-5 staggered points with numbers
+CTA (3s): Follow / Like / Share
+```
+
+### 2. Before/After
+
+```
+Hook (2s): "Before vs After"
+Before (5s): Show the "bad" version (top half)
+After (5s): Reveal the "good" version (bottom half) — use slide transition
+CTA (3s): "Try it yourself"
+```
+
+For vertical before/after, stack top/bottom:
+```tsx
+<div style={{ display: "flex", flexDirection: "column", width: 1080, height: 1920 }}>
+  <div style={{ flex: 1 }}>{before}</div>
+  <div style={{ height: 4, background: "#333" }} />
+  <div style={{ flex: 1 }}>{after}</div>
+</div>
+```
+
+### 3. Code Tutorial
+
+```
+Hook (3s): "This one trick..."
+Code (10-15s): Animated code block, line by line reveal
+Result (5s): Show the output/demo
+CTA (3s): "Link in bio"
+```
+
+Use the CodeBlock recipe from vibeo-effects skill, but with larger font (28px) for vertical.
+
+### 4. Product/Feature Showcase
+
+```
+Hook (3s): Pain point question
+Demo (10s): Screen recording or animated mockup
+Features (5s): 3 key bullets, staggered
+CTA (3s): "Download now"
+```
+
+---
+
+## Animation Rules for Short-Form
+
+1. **First 3 seconds are everything** — the hook must grab attention immediately. Use scale-in, glow, or spring entrance.
+
+2. **Constant motion** — never have a static frame for more than 1 second. Add subtle pulse, breathing, or background movement.
+
+3. **Text on screen** — most viewers watch without sound. Every key point should have on-screen text.
+
+4. **Fast transitions** — 10-15 frame transitions (0.3-0.5s). No slow fades.
+
+5. **Pulsing/breathing effects** — use `frame % N` for constant subtle animation:
+   ```tsx
+   const pulse = interpolate(frame % 60, [0, 30, 60], [1, 1.03, 1]);
+   ```
+
+6. **Number badges** — always number your points (1, 2, 3). It signals structure and keeps viewers watching.
+
+7. **Bold gradients** — dark backgrounds with vibrant gradient accents. Avoid flat solid colors.
+
+---
+
+## Rendering for Platforms
+
+```bash
+# TikTok / Reels (H.264, most compatible)
+bunx @vibeo/cli render --entry src/index.tsx --composition TikTokVideo --codec h264
+
+# High quality (H.265, smaller file)
+bunx @vibeo/cli render --entry src/index.tsx --composition TikTokVideo --codec h265
+
+# Twitter/X (needs smaller file, use lower quality)
+bunx @vibeo/cli render --entry src/index.tsx --composition TikTokVideo --codec h264 --quality 60
+```
+
+### Platform upload limits
+
+| Platform | Max File Size | Recommended Codec |
+|----------|--------------|-------------------|
+| TikTok | 287 MB | H.264 |
+| YouTube Shorts | 256 MB | H.264 |
+| Instagram Reels | 650 MB | H.264 |
+| Twitter/X | 512 MB | H.264 |

package/src/commands/create.ts

@@ -246,6 +246,7 @@ export async function createProject(
       dev: "bun vibeo preview --entry src/index.tsx",
       build: "bun vibeo render --entry src/index.tsx",
       list: "bun vibeo list --entry src/index.tsx",
+      editor: "bun vibeo editor --entry src/index.tsx",
       typecheck: "bunx tsc --noEmit",
     },
     dependencies: {