motionrender 0.2.1 → 0.2.2

package/skills/ove/SKILL.md

@@ -5,10 +5,24 @@ description: Create and edit videos with Open Video Engine (OVE) by writing a JS
 
 # Making videos with Open Video Engine
 
-Short task guides sit beside this one: `ove-code-video` (video written as code, code layers), `ove-make-reel` (social video from blocks), `ove-voiceover-captions`, `ove-batch-videos` and `ove-ai-compose` (AI drafts, refine, history). Use the one that matches the request, and come back here for field details.
+This is the entry-point skill for OVE: start here, choose the route below, and load the short task guide that matches the request — `ove-react-video` (high-end React videos with spring physics, glassmorphism and kinetic typography), `ove-code-video` (video written as code, code layers), `ove-make-reel` (social video from blocks), `ove-voiceover-captions`, `ove-batch-videos` and `ove-ai-compose` (AI drafts, refine, history). Come back here for field details.
 
 An OVE video is one JSON file, `composition.json`. You never write rendering code: you edit data, check it, look at frames, and render. `composition.schema.json` next to it is the authoritative JSON Schema; read it when unsure about a field.
 
+## Choose the route first
+
+Before composing anything, decide *how* this video gets made, in one step: run `ove ai capabilities` (machine-readable with `--json`) and pick the route that fits the brief. The template route is the primary path; the composed and agentic routes below it are secondary, for briefs no template fits.
+
+- **Template route (primary)** — the brief matches one of the registered templates (promo, slideshow, product card, flash sale…) in kind and aspect. Fastest, cheapest and most consistent: `ove ai compose` fills its text variables from the brief, or `ove init --template <name>` starts an editable project. A `--duration` different from the template's own stretches or trims the resolved composition to fit (scene timing scales proportionally; the result is saved as a plain composition, since the timing is then bespoke), so a length difference is not a reason to leave this route.
+- **JSON route (secondary)** — when no template fits the brief's kind and aspect: `ove ai compose --brief "…"` writes a full composition, or you write `composition.json` by hand from the fields below. Length, layout and motion are all yours; the registry lists every block, effect and sound you can name.
+- **React route (secondary)** — when the brief needs spring physics, interlocking layouts or generated visuals: load `ove-react-video` (or `ove-code-video` for scene logic as code) and use a `type: "react"` layer inside an otherwise ordinary composition.
+- **Batch or narration** — many rows of fields → `ove-batch-videos`; voiceover or captions → `ove-voiceover-captions`.
+- **Raw footage** — a recorded clip to clean up (talking head, demo, vlog) → `ove ai edit` (below): transcribe, cut silences and fillers, caption, and write an edited project. A long recording to split up (podcast, stream, webinar) → `ove ai shorts` (below): one transcription, the strongest runs scored and written as separate vertical reel projects. No brief needed; the clip is the input.
+
+If the brief also carries template fields (`--fields metric,value`), it goes to the JSON route: templates take neither batch fields nor data-driven lists. The chosen route is a real routing contract, not a suggestion — the AI planner makes the same decision (`template` vs `json`) before generating, prefers a template whenever its kind and aspect fit the brief (length differences included), and falls back to templates when planning fails. `--no-plan` opts out.
+
+The registry the planner reads is the same list you just saw: `ove ai capabilities --json` is the machine-readable menu of every template, theme, block, component, effect and sound, one entry per capability with its kind and name. Third-party agents and skills should compose *on* OVE — read that registry, write a `composition.json`, and use the validate → still → review loop here — rather than re-implementing rendering. Whatever generates the JSON (planner, model, or you), it stays outside the render path: the renderer only ever reads a validated schema-compliant composition.
+
 ## Loop
 
 1. For a new video of more than a few seconds, agree beats, look and storyboard first (see Planning a video). Then edit `composition.json`.
@@ -17,10 +31,12 @@ An OVE video is one JSON file, `composition.json`. You never write rendering cod
 4. `ove review composition.json --output review.png`: fix every error and warning it lists, then look at the contact sheet it writes (20 frames across the video, labelled with frame numbers) as a whole. Does each scene have one clear focus? Does the video keep moving? Do scenes look like one system?
 5. `ove render composition.json --output out.mp4` once the review is clean and the sheet looks right.
 
-`ove review` samples a frame every half second and reports, with frame numbers and layer ids: text cut short with "…", running off the frame, under 2% of the frame's short side, overlapping other text or sitting under the captions (when that lasts a second or more); more than 40 words on screen; text on screen too briefly to read its words (about a quarter of a second a word, plus half a second); more than two headline-size texts competing (a headline set one word per line counts once); caption lines on screen under 0.7 s or faster than about 20 characters a second; sounds cut off mid-phrase by the end of their scene or `endFrame`; nearly equal font sizes or more than 8 steps of size; more than 5 text colours; 4 seconds or more where nothing moves; scenes all the same length; three or more transition styles; and sound quieter than -20 LUFS, louder than -11 LUFS or peaking above -1 dBTP. It exits with an error when it finds errors, `--json` prints the findings as JSON, `--every n` samples every n frames, `--sheet-frames n` sets how many frames the sheet shows. It is a check, not a verdict on taste: a clean review still needs your eye on the sheet.
+`ove review` samples a frame every half second and reports, with frame numbers and layer ids: text cut short with "…", running off the frame, under 2% of the frame's short side, overlapping other text or sitting under the captions (when that lasts a second or more); text sitting where a platform's own UI covers the picture (on a 9:16 canvas the bottom 18% and right 11% — Instagram Reels, TikTok and YouTube Shorts all draw their caption, audio and action controls there; a wider tall canvas such as 4:5 or square is letterboxed in the player, so the bands shrink to where the chrome actually lands — flagging any text whose area is more than a quarter inside a band); more than 40 words on screen; text on screen too briefly to read its words (about a quarter of a second a word, plus half a second); more than two headline-size texts competing (a headline set one word per line counts once); caption lines on screen under 0.7 s or faster than about 20 characters a second; sounds cut off mid-phrase by the end of their scene or `endFrame`; nearly equal font sizes or more than 8 steps of size; more than 5 text colours; 4 seconds or more where nothing moves; scenes all the same length; three or more transition styles; and sound quieter than -20 LUFS, louder than -11 LUFS or peaking above -1 dBTP. It exits with an error when it finds errors, `--json` prints the findings as JSON, `--every n` samples every n frames, `--sheet-frames n` sets how many frames the sheet shows. It is a check, not a verdict on taste: a clean review still needs your eye on the sheet.
 
 `ove inspect composition.json` prints duration, scene count, variables and assets. A person working alongside you can run `ove dev composition.json` for a live preview that reloads on every save. Its Studio can also edit `composition.json` (layer timing and properties), so re-read the file before changing it rather than relying on an earlier copy. `ove doctor` checks FFmpeg, its encoders and the browser when a render fails for setup reasons. `ove schema` prints the JSON Schema. Every command checks its options: a misspelt or misplaced option stops it with a suggestion, and `--name=value` works as well as `--name value`. Inside the OVE repository itself, run the CLI as `npm run ove -- <command>`; paths are then relative to the repository root.
 
+What you leave behind in the project folder, every time: the final `composition.json`, `out.mp4`, the contact sheet (`review.png`), and one still per scene or beat (`still-<frame>.png`). Another agent, a person, or a CI run must be able to audit the video from those files alone — validation output is ephemeral, the artifacts are not. `ove review`'s contact sheet doubles as the storyboard for a first rough build (see Planning a video).
+
 ## Time
 
 - Everything is in integer frames. Seconds × `fps` = frames (2 s at 30 fps = 60).
@@ -214,10 +230,31 @@ Every audio and video asset is measured when a composition mentions `media`, so
 - `src` is a `captions` asset (or a path): an `.srt` or `.vtt` file, or JSON with timed lines (`{ "cues": [{ "text", "start", "end" }] }`) or timed words (`{ "words": [{ "text", "start", "end" }] }`, seconds). Give the layer the same `startFrame` as its voice layer.
 - With word timings the word being said is highlighted (`highlightColor`), words already said use `color`, and words still to come use `upcomingColor`; `mode: "lines"` shows plain lines. Words are grouped into lines at sentence ends, commas and pauses, up to `maxWords`.
 - The line is centred on `x` (with `textAlign: "center"`) with its top at `y`, wrapped to `maxWidth`, on a `background` box with `padding` and `radius`. Style with `fontSize`, `fontFamily`, `fontWeight` and the outline options. `offset` shifts the timing in seconds.
+- On a 9:16 canvas, keep the caption block above the bottom UI band (the bottom 18% is where Instagram/TikTok draw their controls) and inside the side bands: a top around y 77% of the height and a `maxWidth` of about 76% of the width clears both. A 4:5 or square canvas is letterboxed in the player, so the band lands lower and the check accounts for it. `ove review`'s `safe-zone` check flags text that sits in a band.
 - Filler words (um, uh, erm, ah, hmm…) and words said twice in a row are left out of captions by default (`dropFillers: false` keeps them), in the video and in exported subtitles.
 - `emphasis: ["agent", "goal"]` draws those words (any case, punctuation ignored) in `emphasisColor` (default `highlightColor`) once they are said: two or three key words per video, not one per line.
 - `ove captions composition.json --output captions.srt` (or `.vtt`) writes every captions layer as a subtitle file for uploads.
 
+## Editing raw footage
+
+```bash
+ove ai edit ./raw/take.mp4 --out reel --max-silence 0.5
+```
+
+- Turns a raw clip into an edited project: the clip's audio is transcribed with word timings, pauses longer than `--max-silence` seconds (default 0.5) and filler words (um, uh, erm…) plus immediate repeats become a cut list, and the project is written as `composition.json` + `composition.schema.json` + `assets/`. The result is one `video` layer per kept stretch (`trimStart` skips the removed source, the clip's own sound carried through, hard jump cuts between stretches) and a word-timed captions layer above the platform UI band.
+- `--width`/`--height` set the canvas (default 1080×1920, the clip centre-cropped with `objectFit: cover` — the standard landscape-talking-head-to-reel move); `--keep-fillers` leaves the ums in; `--no-captions` skips the captions layer; `--force` writes into a directory that already has files.
+- The output is an ordinary project: review it (`ove review reel/composition.json --output review.png`), tune it (the cut list is visible as the scene boundaries — delete a `clip-N` scene to restore a moment, or re-run with a different `--max-silence`), then render (`ove render reel/composition.json --output out.mp4`). Transcription needs a provider with `transcribe` (`--provider groq`, or any adapter that implements it); everything else is local.
+
+## Splitting a long recording into shorts
+
+```bash
+ove ai shorts ./raw/podcast.mp4 --out shorts --count 5 --min 15 --max 60
+```
+
+- Transcribes the recording **once**, splits it into sentence runs (punctuation or a pause over `--max-silence` seconds ends one), and scores every window of whole sentences with a transparent rubric: a clean ending (2), a hook in the first sentence — question, direct address, number, or words like *best/never/secret/mistake* (2), speech density near 2.5 words a second (0–1), and a length near the 25–45 s sweet spot (0–1). The best `--count` non-overlapping windows are written as `shorts/short-01/`, `short-02/`, … each a full project.
+- Each short gets the same edited-reel shape as `ove ai edit` (silences and fillers tightened inside it, word-timed captions above the platform UI band, 1080×1920 centre-cropped). `--no-cut` keeps each short one continuous stretch; `--no-captions`, `--width/--height/--fps` work as there.
+- The rubric is a lead, not a verdict: the summary prints each short's time range, score and opening line — swap a weak pick by editing its `composition.json`, or re-run with different `--min/--max`. Very long recordings may exceed the transcription provider's upload limit; trim or split the source first.
+
 ## Media
 
 - Declare files in `assets` with an `id`, then reference that id from an image or video layer's `src`. A `src` may also be a path relative to `composition.json` or an `https://` URL.
@@ -340,6 +377,7 @@ Aim for what a motion designer would hand over, not a slide. Before rendering, l
 - **A grid and margins.** Keep content inside 120 px margins at 1920 wide (100 at 1080 wide), align left edges to the same x, and use consistent gaps (multiples of 8). Left-aligned layouts read better for content scenes; save centred layouts for titles and endings. Keep the same layout pattern from scene to scene (for example a numbered label, heading and subheading in the same place).
 - **Fill the frame.** Content should span the width. Small cards floating in the top third look unfinished; make cards larger, use fewer of them, or add a supporting visual on the empty side.
 - **Leave a band for captions.** Keep content above about y 880 when captions sit at the bottom, and put captions in the same place in every scene.
+- **On a vertical canvas, respect the platform's UI bands.** The bottom 18% and the right 11% of a 9:16 frame are where Instagram Reels, TikTok and YouTube Shorts draw their own caption, audio tag and action buttons — text there is hidden in the feed (a 4:5 or square canvas is letterboxed in the player, so the bands shrink; the `safe-zone` review check knows). Keep text out of them, and keep captions above the bottom band.
 - **Depth without clutter.** Backgrounds: a dark gradient `background`, one or two large soft radial glows (a `circle` with a radial fill that fades to transparent), optionally a faint grid (`rgba(255,255,255,0.035)`) and a vignette (a full-frame `rect` with a radial fill from transparent to dark edges). Cards: `rgba(255,255,255,0.04)` fill, a 1–2 px `rgba(255,255,255,0.1)` stroke, radius 24–32, a large soft shadow. Highlight one thing with the accent, not everything.
 - **Icons, not letters.** Draw simple line icons as `path` layers (stroke 4–5, round caps and joins) inside a rounded tile, rather than a letter in a circle.
 - **Kinetic type.** Animate headlines word by word (`split`) rather than as one block, with the `rise` or `blur` preset and a 3–5 frame stagger; keep one split style through a video.

package/skills/ove-agent/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: ove-agent
+description: Autonomous AI motion graphics director that generates, compiles, and self-corrects broadcast-quality React video components from a plain-text brief. Supports vertical reel auto-detection, brand pack tokens, visual self-healing review, and multi-provider LLM backends.
+---
+
+# `ove agent` — Autonomous Video Agent
+
+The `ove agent` command runs an autonomous AI loop that:
+
+1. **Generates** a complete `video.tsx` React component from your brief using an LLM provider.
+2. **Compiles** it with esbuild via the `buildReact` helper.
+3. **Self-corrects** on compiler errors (up to 3 total attempts), feeding the error back to the LLM.
+4. **Visual self-healing**: after a successful compile, runs `ove review` on 3 still frames (20%, 50%, 80% of duration) and loops back to the LLM if design errors (text cut, off-frame, overlapping text) are found.
+5. **Renders** the final MP4 with headless Chromium (unless `--no-render` is passed).
+
+Auto-detects vertical reel format when the brief contains keywords: `reel`, `short`, `9:16`, `viral`, `tiktok`, `instagram`, `shorts`, `reels`, `vertical`.
+
+## Usage
+
+```sh
+ove agent "<brief>" [dir] [options]
+```
+
+## CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--url <website>` | Ingest brand colors, logo and value propositions from a website URL | None |
+| `--landscape` | Landscape 16:9 video for YouTube/Web (1920×1080) | Off (default: 9:16 reel) |
+| `--duration <sec>` | Length in seconds | `6` |
+| `--fps <number>` | Frames per second | `30` |
+| `--no-render` | Generate and compile React code only; skip MP4 rendering | Off |
+| `--no-plan` | Skip the route planner and always run the React agent loop | Off |
+| `--provider <name>` | AI provider: `nvidia`, `anthropic`, `groq` | Auto-detected |
+| `--model <id>` | Model ID override (passed to the selected provider) | Provider default |
+
+## Brand Pack API
+
+Pass brand tokens programmatically via the `brand` field in `AgentOptions` to lock the LLM to your design system:
+
+```ts
+import type { BrandPack } from '@ove/ai';
+
+export type BrandColor = {
+  primary: string;
+  secondary?: string;
+  accent?: string;
+  background?: string;
+  text?: string;
+};
+
+export type BrandFont = {
+  heading?: string;
+  body?: string;
+};
+
+export type BrandPack = {
+  colors?: BrandColor;
+  fonts?: BrandFont;
+  logo?: string;    // file path or URL
+  name?: string;    // brand name to include in copy
+  style?: string;   // free-text style notes e.g. "minimalist", "playful tech"
+};
+```
+
+When a brand pack is supplied, the agent appends a **Brand Tokens** section to its system prompt instructing the LLM to use *only* those colors and fonts.
+
+## Examples
+
+### 1. Reel Auto-Detection (keyword in brief)
+
+The brief contains "TikTok", so the agent auto-selects 9:16 vertical reel format with safe-zone rules:
+
+```sh
+ove agent "A viral TikTok promo for our new AI coding assistant — punchy, neon, fast cuts" ./my-reel
+```
+
+The agent will use 1080×1920, enforce safe zones (top 8%, bottom 18%, right 11%), and require `BentoGrid`, `KineticText`, `GlassCard`, and `AmbientGlow`.
+
+### 2. Brand Pack (programmatic API)
+
+Wire up brand tokens when calling `runVideoAgent` directly:
+
+```ts
+import { runVideoAgent } from '@ove/ai';
+import { createProvider } from '@ove/ai';
+import { buildReact } from '@ove/cli/build';
+
+const provider = createProvider({ provider: 'anthropic' });
+
+await runVideoAgent(provider, {
+  brief: 'Product launch video for Acme SaaS — showcase the dashboard speed',
+  dir: './acme-launch',
+  format: 'landscape',
+  durationSeconds: 10,
+  brand: {
+    name: 'Acme',
+    colors: {
+      primary: '#6366f1',
+      secondary: '#8b5cf6',
+      accent: '#38bdf8',
+      background: '#070a12',
+      text: '#f8fafc',
+    },
+    fonts: { heading: 'Inter', body: 'Inter' },
+    style: 'minimalist, modern SaaS, dark mode',
+  },
+  onProgress: msg => console.log(msg),
+}, buildReact);
+```
+
+### 3. Landscape Video (explicit flag)
+
+Force landscape 16:9 format regardless of brief content:
+
+```sh
+ove agent "Modern SaaS product demo showing 10x speed improvements" ./saas-demo --landscape --duration 12 --fps 30
+```
+
+After generation, preview and render manually:
+
+```sh
+ove still ./saas-demo/composition.json --allow-code --frame 30 --output preview.png
+ove review ./saas-demo/composition.json --output review.png
+ove render ./saas-demo/composition.json --allow-code --output out.mp4
+ove build ./saas-demo/video.tsx --output ./saas-demo/video.bundle.js
+```
+
+## Valid `ove` Commands Reference
+
+The following commands are available in the Open Video Engine CLI:
+
+- `ove agent` — Autonomous AI video agent (this skill)
+- `ove render` — Render a composition to MP4/WebM/GIF
+- `ove review` — Sample frames and check for design issues; produces a contact sheet
+- `ove build` — Compile a React video component with esbuild
+- `ove still` — Render a single frame as PNG
+
+## Notes
+
+- The agent uses up to 3 total attempts across both compile errors and visual review failures.
+- Visual self-healing only runs when `buildHelper` is provided (CLI mode); in standalone API mode it is skipped.
+- The `--no-plan` flag bypasses the route planner and always uses the React code loop.
+- Safe-zone auto-enforcement applies only when the reel format is auto-detected (not when `--landscape` is set explicitly).

package/skills/ove-code-video/SKILL.md

@@ -30,22 +30,30 @@ export default v;
 - Layers without an `id` get one (`text-1`); a repeated explicit id is an error. `v.variable`, `v.component`, `v.asset`, `v.export` set the other parts. `use('component', { values }, { x, y })` places a component.
 - Layer constructors: `text rect circle path image clip audio sfx group html lottie shader captions code use`.
 
-## 2. React components (your own files only)
+## 2. React components (see the dedicated `ove-react-video` skill for the full component kit)
 
-For Remotion-style videos: components that are pure functions of the frame.
+For Remotion-style videos: components that are pure functions of the frame with spring physics, glassmorphism, and kinetic typography.
 
 ```tsx
-import { AbsoluteFill, Series, interpolate, spring, useCurrentFrame, useVideoConfig } from 'open-video-engine/react';
+import { AbsoluteFill, Sequence, KineticText, GlassCard, AmbientGlow, Audio, useCurrentFrame, useVideoConfig } from 'open-video-engine/react';
 export const config = { id: 'promo', width: 1920, height: 1080, fps: 30, durationInFrames: 270, background: '#0b1020', props: { title: 'Hello' } };
-export const layers = [{ id: 'whoosh', type: 'audio', src: 'sfx:whoosh', startFrame: 4 }];   // optional plain OVE layers beside it
-export default function Promo({ title }) { const frame = useCurrentFrame(); /* ...return JSX... */ }
+export default function Promo({ title }) {
+  const frame = useCurrentFrame();
+  return (
+    <AbsoluteFill style={{ color: '#fff' }}>
+      <AmbientGlow />
+      <Sequence from={0} durationInFrames={90}>
+        <Audio src="sfx:whoosh" />
+        <GlassCard><KineticText text={title} /></GlassCard>
+      </Sequence>
+    </AbsoluteFill>
+  );
+}
 ```
 
 - `ove build promo.tsx` (needs `react`, `react-dom`, `esbuild` installed) writes `composition.json` and `promo.bundle.js`; render with `--allow-code`. Rebuild after every edit.
-- Available: `useCurrentFrame`, `useVideoConfig` (width, height, fps, durationInFrames), `Sequence` (from, durationInFrames), `Series` with `Series.Sequence`, `AbsoluteFill`, `interpolate`, `spring`, `Easing`, `random(seed)`. Inline styles, `<style>`, SVG and pure React libraries render; `useState`, effects, timers, canvas and iframes do not.
-- Everything must come from the frame and the props. `Math.random()`, `Date.now()` and network calls make frames differ or fail.
-- Pictures: declare each in `config.assets` ({ id, type: 'image', src }) and use `<img src="id">`. Fonts: Inter is built in; add other fonts as font assets.
-- No audio from components: add sound with exported `layers` (`sfx:…`, audio files, captions).
+- Audio and video: `<Audio src="sfx:whoosh" />` and `<Video src="..." />` are automatically scanned and promoted to native audio/video layers.
+- For complete guide, component library, and spring presets, read the **`ove-react-video`** skill.
 
 ## 3. The code layer: your own drawing every frame (trusted files only)
 

package/skills/ove-motion-graphics/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ove-motion-graphics
+description: Create viral modern motion graphics, bento grids, kinetic typography reels, code editor walk-throughs, and audio waveforms using spring physics and React.
+---
+
+# Modern Motion Graphics Guide (`@ove/react`)
+
+Open Video Engine provides a motion design toolkit matching top-tier Claude-style motion graphic reels and product release videos.
+
+---
+
+## 1. Design Aesthetics & Visual Foundations
+
+- **Canvas Background**: Deep dark tones (`#07080d`, `#0a0b12`, `#090d16`).
+- **Glow & Atmosphere**: Use `<AmbientGlow>` with 2-3 colorful radial orbs (`#6366f1` Indigo, `#a855f7` Purple, `#ec4899` Pink, `#06b6d4` Cyan) with 100px+ blur.
+- **Surface Elevation**: Frosted glassmorphism with `rgba(255, 255, 255, 0.05)`, `backdropFilter: blur(24px)`, and fine 1px border highlight `rgba(255, 255, 255, 0.12)`.
+- **Spring Physics over Linear Easing**: Always animate entrances using `springValue` presets:
+  - `'snappy'`: UI cards, bento containers, buttons (stiffness 180, damping 18)
+  - `'bouncy'`: Badges, icons, reaction elements (stiffness 150, damping 10)
+  - `'smooth'`: Camera moves, counter tickers (stiffness 90, damping 14)
+  - `'gentle'`: Background transitions, subtle drifting (stiffness 50, damping 12)
+
+---
+
+## 2. Motion Component Kit
+
+### Bento Grid & Cards
+```tsx
+import { BentoGrid, BentoCard, Badge } from '@ove/react';
+
+<BentoGrid columns={3} gap={20}>
+  <BentoCard 
+    colSpan={2} 
+    title="Real-Time Engine" 
+    subtitle="Ultra low-latency distributed frame synthesis"
+    badge={<Badge dotColor="#10b981">60 FPS</Badge>}
+    delay={10}
+  >
+    <div style={{ height: 120 }}>{/* card content */}</div>
+  </BentoCard>
+
+  <BentoCard title="Metrics" delay={18}>
+    <NumberTicker value={99.9} suffix="%" delay={22} decimals={1} />
+  </BentoCard>
+</BentoGrid>
+```
+
+### Kinetic Typography
+```tsx
+import { KineticText } from '@ove/react';
+
+// Word-by-word staggered spring reveal:
+<KineticText 
+  text="BUILD THE FUTURE OF VIDEO" 
+  delay={5} 
+  staggerDelay={4} 
+  preset="bouncy" 
+  style={{ fontSize: 64, fontWeight: 900, color: '#fff' }} 
+/>
+```
+
+### Typewriter Effect
+```tsx
+import { Typewriter } from '@ove/react';
+
+<Typewriter 
+  text="mr agent --prompt 'Build an AI video'" 
+  delay={15} 
+  speed={0.8} 
+  style={{ fontSize: 24, color: '#38bdf8' }} 
+/>
+```
+
+### Dynamic Audio Waveform
+```tsx
+import { Waveform } from '@ove/react';
+
+<Waveform bars={32} height={60} color="#6366f1" activeColor="#ec4899" speed={0.15} />
+```
+
+### Code Editor Window
+```tsx
+import { CodeEditor } from '@ove/react';
+
+<CodeEditor 
+  filename="pipeline.ts" 
+  code={`export const render = async () => {\n  const engine = new VideoEngine();\n  await engine.generate();\n};`} 
+  highlightLines={[2]} 
+  delay={10} 
+/>
+```
+
+---
+
+## 3. Viral Reel Structure (9:16 Vertical, 1080x1920)
+
+1. **Hook (0-2s / frames 0-60)**:
+   - High-energy kinetic headline with `<KineticText>`.
+   - Vibrant ambient glow with `<AmbientGlow>`.
+   - Status pill with `<Badge dot>NEW RELEASE</Badge>`.
+2. **Value & Feature Showcase (2-5s / frames 60-150)**:
+   - Bento box layout (`<BentoGrid>` + `<BentoCard>`) or mock UI window (`<DeviceFrame>` or `<CodeEditor>`).
+   - Dynamic metric counters (`<NumberTicker>`) or interactive visualizer (`<Waveform>`).
+3. **Call-to-Action (5-7s / frames 150-210)**:
+   - Centered payoff with glowing brand badge, website URL, and glowing CTA button.
+
+---
+
+## 4. Commands
+
+- `ove review video.tsx --output review.png`
+- `ove render video.tsx --output reel.mp4`
+- `ove agent --prompt "Build a kinetic typography reel for an AI launch"`

package/skills/ove-react-video/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: ove-react-video
+description: Design and build high-end motion graphics videos using React, TypeScript (TSX), Flexbox, spring physics, and @ove/react components. Use whenever the user wants to build a video with React, improve design quality, or create SaaS launch reels, kinetic typography, bento grids, or UI explainers.
+---
+
+# Designing Videos with React (`@ove/react`)
+
+Open Video Engine lets you build complete, broadcast-quality motion graphics videos as pure React components. 
+Instead of computing manual pixel coordinates in JSON, you write modern **TSX with Flexbox, CSS Grid, spring physics, glassmorphism, and live media**.
+
+---
+
+## 1. Quick Starter (`video.tsx`)
+
+Every React video is a default export component that accepts `props`, accompanied by an exported `config`:
+
+```tsx
+import { 
+  AbsoluteFill, 
+  Sequence, 
+  useCurrentFrame, 
+  useVideoConfig,
+  springValue,
+  KineticText,
+  GlassCard,
+  Badge,
+  NumberTicker,
+  AmbientGlow,
+  Audio
+} from 'open-video-engine/react';
+
+export const config = {
+  id: 'saas-launch',
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  durationInFrames: 180, // 6 seconds at 30 fps
+  background: '#090d16',
+  props: {
+    title: 'The Future of Video Production',
+    stat: 99.9,
+  }
+};
+
+export default function Video({ title, stat }: typeof config.props) {
+  const frame = useCurrentFrame();
+  const { fps, width, height } = useVideoConfig();
+
+  return (
+    <AbsoluteFill style={{ color: '#fff', fontFamily: 'Inter, system-ui, sans-serif' }}>
+      {/* 1. Atmospheric Ambient Lighting */}
+      <AmbientGlow 
+        orbs={[
+          { x: '25%', y: '20%', size: 700, color: '#6366f1', opacity: 0.28 },
+          { x: '80%', y: '80%', size: 800, color: '#ec4899', opacity: 0.22 },
+        ]} 
+      />
+
+      {/* 2. Scene 1: Kinetic Headline (Frames 0 to 90) */}
+      <Sequence from={0} durationInFrames={90}>
+        <Audio src="sfx:whoosh" volume={0.5} />
+        <AbsoluteFill style={{ alignItems: 'center', justifyContent: 'center', gap: 24, padding: 80 }}>
+          <Badge dotColor="#38bdf8" delay={4}>NEXT GEN ENGINE</Badge>
+          <h1 style={{ fontSize: 84, fontWeight: 800, letterSpacing: '-0.04em', margin: 0, textAlign: 'center' }}>
+            <KineticText text={title} delay={8} preset="bouncy" />
+          </h1>
+        </AbsoluteFill>
+      </Sequence>
+
+      {/* 3. Scene 2: Glassmorphic Metric Card (Frames 90 to 180) */}
+      <Sequence from={90} durationInFrames={90}>
+        <Audio src="sfx:ding" volume={0.6} />
+        <AbsoluteFill style={{ alignItems: 'center', justifyContent: 'center' }}>
+          <GlassCard delay={6} style={{ width: 560, display: 'flex', flexDirection: 'column', gap: 16 }}>
+            <span style={{ fontSize: 18, color: '#94a3b8', fontWeight: 600 }}>SYSTEM ACCURACY</span>
+            <div style={{ fontSize: 92, fontWeight: 900, color: '#38bdf8', letterSpacing: '-0.03em' }}>
+              <NumberTicker value={stat} decimals={1} suffix="%" delay={10} preset="smooth" />
+            </div>
+            <p style={{ margin: 0, color: '#cbd5e1', fontSize: 16, lineHeight: 1.5 }}>
+              Deterministic frame-accurate rendering powered by headless Chromium and React.
+            </p>
+          </GlassCard>
+        </AbsoluteFill>
+      </Sequence>
+    </AbsoluteFill>
+  );
+}
+```
+
+---
+
+## 2. Core Build Loop
+
+1. **Write or edit** `video.tsx`.
+2. **Build the bundle & composition**:
+   ```bash
+   ove build video.tsx
+   ```
+   * Compiles your React JSX with `esbuild`.
+   * Emits `video.bundle.js` and `composition.json`.
+3. **Inspect Still Frames**:
+   ```bash
+   ove still composition.json --frame 45 --output still-45.png
+   ove still composition.json --frame 135 --output still-135.png
+   ```
+4. **Visual Review Sheet** (samples frames across the whole video):
+   ```bash
+   ove review composition.json --output review.png
+   ```
+5. **Render High-Quality MP4**:
+   ```bash
+   ove render composition.json --allow-code --output out.mp4
+   ```
+   *(Note: React videos execute component code during headless rendering, so `--allow-code` is required).*
+
+---
+
+## 3. Motion Components Kit Reference
+
+Import directly from `open-video-engine/react` (or `@ove/react`):
+
+### `<AmbientGlow orbs={[...]} blur={100} />`
+Creates floating, organic gradient light orbs with continuous sine-wave drift in the background.
+* `orbs`: Array of `{ x, y, size, color, opacity, speed, phase }`.
+* Never leaves the canvas looking like a flat black box.
+
+### `<GlassCard delay={n} preset="snappy">`
+A frosted glass surface with spring entry:
+* `background: rgba(255, 255, 255, 0.05)`
+* `backdropFilter: blur(24px)`
+* `border: 1px solid rgba(255, 255, 255, 0.12)`
+* `boxShadow: 0 20px 50px rgba(0, 0, 0, 0.4)`
+
+### `<KineticText text="..." delay={0} staggerDelay={3} preset="bouncy" />`
+Staggers every word with natural spring physics:
+* `preset`: `'bouncy'` (fun pop), `'snappy'` (modern tech), `'smooth'` (editorial), or `'gentle'`.
+* `wordStyle`: Optional custom styling per word.
+
+### `<NumberTicker value={1250} decimals={0} prefix="$" suffix="/mo" delay={10} />`
+Smoothly animates numbers from 0 up to `value` using tabular numerals.
+
+### `<Badge dot={true} dotColor="#10b981" delay={4}>`
+SaaS status pill badge for kickers and category labels.
+
+### `<DeviceFrame title="Dashboard" url="app.ove.dev" delay={8}>`
+A sleek macOS browser window frame with traffic lights and URL bar.
+
+### `<ProgressBar value={0.75} color="#38bdf8" delay={5} />`
+Glowing horizontal progress bar with spring expansion.
+
+---
+
+## 4. Spring Physics & Animation Formulas
+
+### `springValue(options)`
+Evaluates spring damping physics directly from `frame`:
+
+```tsx
+const scale = springValue({ frame, fps, delay: 10, preset: 'bouncy', from: 0.8, to: 1.0 });
+const y = springValue({ frame, fps, delay: 10, preset: 'snappy', from: 40, to: 0 });
+const opacity = springValue({ frame, fps, delay: 10, from: 0, to: 1 });
+```
+
+**Preset Guide:**
+* `'bouncy'`: `{ damping: 10, stiffness: 120, mass: 0.8 }` — for titles, badges, and icon pop-ins.
+* `'snappy'`: `{ damping: 18, stiffness: 180, mass: 0.5 }` — for UI cards, device frames, buttons.
+* `'smooth'`: `{ damping: 20, stiffness: 90, mass: 1.0 }` — for charts, progress bars, tickers.
+* `'wobbly'`: `{ damping: 7, stiffness: 85, mass: 1.0 }` — playful overshoot.
+
+### `stagger(index, framesPerItem, startDelay)`
+Calculates the starting frame for staggered lists:
+```tsx
+const itemDelay = stagger(index, 4, 15);
+```
+
+---
+
+## 5. Media & Timing in React
+
+### Audio & Sound Effects
+Use `<Audio />` anywhere inside a `<Sequence>`. When the sequence starts, the sound plays automatically:
+```tsx
+<Sequence from={0} durationInFrames={60}>
+  <Audio src="sfx:whoosh" volume={0.6} />
+  {/* visual content */}
+</Sequence>
+```
+Supported sound effect presets: `sfx:whoosh`, `sfx:ding`, `sfx:click`, `sfx:pop`, `sfx:thump`, `sfx:tick`, `sfx:riser`.
+
+### Video Footage
+Use `<Video />` to place video clips under or over your components:
+```tsx
+<Video src="assets/background.mp4" layer="back" objectFit="cover" muted loop />
+```
+
+### Pictures & Fonts
+* Place images in `assets/` and declare them in `config.assets`.
+* Use `<Img src="assets/logo.png" />`.
+* Inter font is built in with all weights (300 to 900).
+
+---
+
+## 6. Pro Design Rules for AI Video Production
+
+1. **Always use Flexbox/Grid**: Never calculate absolute pixels like `left: 450px`. Let CSS Flexbox center and space cards cleanly.
+2. **Secondary Motion**: Never let a scene stay 100% still. Combine a fast spring entry (`frame 0-20`) with subtle continuous scale or drift (`interpolate(frame, [0, 90], [1, 1.04])`).
+3. **Typographic Hierarchy**:
+   * Kicker / Badge: 14-16px, uppercase, letterSpacing: `0.05em`.
+   * Headline: 64-96px, fontWeight: `800` or `900`, letterSpacing: `-0.04em`.
+   * Body / Caption: 18-24px, color: `#94a3b8`, lineHeight: `1.6`.
+4. **Pure Function Rule**: Every render MUST be a pure deterministic function of `frame`. Do NOT use `useState`, `setTimeout`, or `Math.random()`. Use `random('seed')` from `open-video-engine/react` for repeatable randomness.
+