@vibeo/cli 0.3.3 → 0.3.5

package/skills/vibeo-rendering/SKILL.md

@@ -0,0 +1,364 @@
+# 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. **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.

package/src/commands/install-skills.ts

@@ -1,25 +1,33 @@
 import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { mkdir, writeFile, readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 
 // ---------------------------------------------------------------------------
-// Embedded skill content (so it works from npm without the skills/ dir)
+// Skill loader — resolves from the CLI package's own skills/ directory
 // ---------------------------------------------------------------------------
 
+const SKILL_NAMES = ["vibeo-core", "vibeo-audio", "vibeo-effects", "vibeo-extras", "vibeo-rendering"];
+
 async function loadSkills(): Promise<Record<string, string>> {
-  // Try to load from the repo's skills/ directory first
+  // Resolve from this file's location — skills/ is shipped alongside dist/ in the npm package
+  const thisFile = fileURLToPath(import.meta.url);
+  const thisDir = dirname(thisFile);
+
+  // From dist/commands/install-skills.js → ../../skills
+  // From src/commands/install-skills.ts → ../../skills
   const candidates = [
-    join(dirname(import.meta.url.replace("file://", "")), "../../../../skills"),
-    join(process.cwd(), "skills"),
+    join(thisDir, "..", "..", "skills"),       // from dist/commands/ or src/commands/
+    join(thisDir, "..", "..", "..", "skills"),  // from deeper nesting
+    join(process.cwd(), "skills"),             // from project root
   ];
 
   for (const dir of candidates) {
-    const names = ["vibeo-core", "vibeo-audio", "vibeo-effects", "vibeo-extras", "vibeo-rendering"];
     const skills: Record<string, string> = {};
     let found = true;
 
-    for (const name of names) {
+    for (const name of SKILL_NAMES) {
       const path = join(dir, name, "SKILL.md");
       if (existsSync(path)) {
         skills[name] = await readFile(path, "utf-8");
@@ -32,78 +40,11 @@ async function loadSkills(): Promise<Record<string, string>> {
     if (found) return skills;
   }
 
-  // Fallback: generate a minimal combined skill from --llms-full output
-  return {
-    vibeo: getEmbeddedSkill(),
-  };
-}
-
-function getEmbeddedSkill(): string {
-  return `# Vibeo — React Video Framework
-
-Vibeo is a React-based programmatic video framework. Write video compositions as React components, preview in the browser, and render to video with FFmpeg.
-
-## Quick Reference
-
-\`\`\`bash
-# Get full CLI docs
-bunx @vibeo/cli --llms-full
-
-# Create a project
-bunx @vibeo/cli create my-video --template basic
-
-# Preview
-bunx @vibeo/cli preview --entry src/index.tsx
-
-# Render
-bunx @vibeo/cli render --entry src/index.tsx --composition MyComp
-
-# List compositions
-bunx @vibeo/cli list --entry src/index.tsx
-\`\`\`
-
-## Packages
-
-- \`@vibeo/core\` — Composition, Sequence, Loop, useCurrentFrame, useVideoConfig, interpolate, easing
-- \`@vibeo/audio\` — Audio/Video components, 48kHz sync, volume curves, audio mixing
-- \`@vibeo/effects\` — useKeyframes, useSpring, Transition (fade/wipe/slide/dissolve), useAudioData
-- \`@vibeo/extras\` — Subtitle (SRT/VTT), AudioWaveform, AudioSpectrogram, SceneGraph, AudioMix
-- \`@vibeo/player\` — Interactive Player component with controls
-- \`@vibeo/renderer\` — Headless rendering via Playwright + FFmpeg
-- \`@vibeo/cli\` — CLI with incur (supports --llms, --mcp, --schema)
-
-## Core Pattern
-
-\`\`\`tsx
-import { Composition, Sequence, VibeoRoot, useCurrentFrame, useVideoConfig, interpolate } from "@vibeo/core";
-
-function MyScene() {
-  const frame = useCurrentFrame();
-  const { width, height, fps } = useVideoConfig();
-  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
-  return <div style={{ width, height, opacity }}>Hello</div>;
-}
-
-export function Root() {
-  return (
-    <VibeoRoot>
-      <Composition id="MyComp" component={MyScene} width={1920} height={1080} fps={30} durationInFrames={150} />
-    </VibeoRoot>
+  throw new Error(
+    "Could not find skill files. Make sure the @vibeo/cli package is installed correctly.",
   );
 }
-\`\`\`
-
-## Key Math
 
-- Frame to time: \`time = frame / fps\`
-- Samples per frame (audio): \`(48000 * 2) / fps\`
-- Media time with playback rate: uses interpolation with rate scaling
-- Sequence relative frame: \`absoluteFrame - (cumulatedFrom + relativeFrom)\`
-- Loop iteration: \`floor(currentFrame / durationInFrames)\`
-
-For full API details, run \`bunx @vibeo/cli --llms-full\` or \`bunx @vibeo/cli <command> --schema\`.
-`;
-}
 
 // ---------------------------------------------------------------------------
 // LLM tool targets
@@ -120,24 +61,26 @@ const home = homedir();
 const TARGETS: Target[] = [
   {
     name: "claude",
-    description: "Claude Code (~/.claude/skills/ + project CLAUDE.md)",
+    description: "Claude Code (~/.claude/skills/<name>/SKILL.md + project .claude/skills/<name>/SKILL.md)",
     async install(skills, cwd) {
       const files: string[] = [];
 
-      // Global skills directory
+      // Global skills directory — each skill in its own dir with SKILL.md
       const globalDir = join(home, ".claude", "skills");
-      await mkdir(globalDir, { recursive: true });
       for (const [name, content] of Object.entries(skills)) {
-        const path = join(globalDir, `${name}.md`);
+        const skillDir = join(globalDir, name);
+        await mkdir(skillDir, { recursive: true });
+        const path = join(skillDir, "SKILL.md");
         await writeFile(path, content);
         files.push(path);
       }
 
-      // Project-level .claude/skills/
+      // Project-level .claude/skills/<name>/SKILL.md
       const projectDir = join(cwd, ".claude", "skills");
-      await mkdir(projectDir, { recursive: true });
       for (const [name, content] of Object.entries(skills)) {
-        const path = join(projectDir, `${name}.md`);
+        const skillDir = join(projectDir, name);
+        await mkdir(skillDir, { recursive: true });
+        const path = join(skillDir, "SKILL.md");
         await writeFile(path, content);
         files.push(path);
       }