@depths/waves 0.1.0 → 0.3.0

package/README.md

@@ -1,41 +1,147 @@
-# @depths/waves
+# @depths/waves (v0.3.0)
 
-`@depths/waves` is a TypeScript-first library for rendering videos from a JSON “intermediate representation” (IR).
+`@depths/waves` is a TypeScript-first library + CLI for rendering videos from a JSON "intermediate representation" (IR) using Remotion.
 
 The intended workflow is:
 
 1. An LLM (or a human) produces JSON that conforms to a schema (`VideoIRSchema`).
-2. The IR is validated (schema + semantics).
+2. The IR is validated (schema + semantics + registry contracts).
 3. The IR is rendered to an output video file (MP4 by default) using Remotion.
 
-This project is designed around explicitness:
+v0.2.0 introduced a shadcn-like catalog of higher-level "composite" components and a hybrid IR that supports:
 
-- You only render components that have been explicitly registered in a component registry.
-- Component props are validated with Zod before rendering.
-- Scene timing is validated for common authoring mistakes (gaps, overlaps, duration mismatches, children exceeding parent bounds).
+- **Segments (recommended for agents):** sequential scenes with optional overlaps ("transitions")
+- **Timeline (escape hatch):** explicit timed nodes with overlaps allowed
 
-## What you get (v0.1.0)
+v0.3.0 focuses on **seamless alignment + overlays**:
 
-- A stable IR format (currently `version: "1.0"`) for videos composed of scenes and components.
-- A component registry (`ComponentRegistry`) that maps `type` strings to React components + Zod props schemas + metadata.
-- A validator (`IRValidator`) with schema + semantic checks.
-- A rendering engine (`WavesEngine`) that bundles a Remotion project on the fly and renders to a media file.
-- Built-in primitives: `Scene`, `Text`, `Audio`.
-- Utilities to generate JSON Schemas for LLM prompting from registered component props.
+- **Layout-safe primitives:** components that use normal layout flow by default (no accidental `position: absolute`)
+- **Explicit layering primitives:** `Layers` + `Layer` for deterministic overlays (z-index, inset, opacity)
+- **Explicit positioning primitive:** `Frame` for deliberate `x/y/width/height` placement (breaking change: `Box` no longer supports `x/y`)
+- **Visual debugging workflow:** `waves stills` and `--debugBounds/--debugLabels` to inspect alignment issues without pixel tests
 
-## Why this exists
+## Table of contents
 
-Many “LLM → video” pipelines fail for one of these reasons:
+- [Concept (end-to-end)](#concept-end-to-end)
+  - [What problem this solves](#what-problem-this-solves)
+  - [Mental model](#mental-model)
+  - [Core building blocks](#core-building-blocks)
+  - [How segments + transitions work](#how-segments--transitions-work)
+  - [Validation model](#validation-model)
+  - [Rendering model](#rendering-model)
+- [Installation](#installation)
+- [CLI (agent workflow)](#cli-agent-workflow)
+- [IR v2.0 (authoring contract)](#ir-v20-authoring-contract)
+- [Components (primitives + composites)](#components-primitives--composites)
+- [Examples (composition recipes)](#examples-composition-recipes)
+- [Library API (quickstart)](#library-api-quickstart)
+- [Assets and paths (Windows/Linux)](#assets-and-paths-windowslinux)
+- [Rendering prerequisites](#rendering-prerequisites)
+- [Local CLI testing (before publishing)](#local-cli-testing-before-publishing)
+- [Contributing](#contributing)
 
-- The LLM output is not reliably validated and fails at render time.
-- The rendering system has hidden magic (implicit component inference, brittle conventions).
-- The model lacks a precise schema + component catalog to target.
+## Concept (end-to-end)
 
-Waves solves this by:
+### What problem this solves
 
-- Giving the model a JSON schema to follow.
-- Enforcing strict component registration and props validation.
-- Providing deterministic, testable semantic rules around timing.
+Remotion is a powerful way to render videos by writing React components. But for "LLM -> video" workflows, you need more than React:
+
+- A strict authoring contract (so the model can reliably output something valid)
+- Fast, deterministic validation (so failures happen before render time)
+- A component catalog (so the model composes using known building blocks)
+- A CLI (so an agent can drive the entire pipeline from a terminal)
+
+Waves is a thin, explicit layer over Remotion that provides exactly those pieces.
+
+### Mental model
+
+Think of Waves as a compiler + runtime:
+
+1) **Author**: you (or an agent) author a JSON IR document
+2) **Validate**: Waves validates schema + semantics + component props
+3) **Compile**: Waves compiles high-level authoring (segments) into a render-ready timeline
+4) **Render**: Waves invokes Remotion bundling + rendering to produce an MP4
+
+At render time, Waves is "just React + Remotion". The strictness lives earlier (IR + validation + registry contracts).
+
+### Core building blocks
+
+The codebase has a small number of core concepts:
+
+- **Video IR (`VideoIRSchema`)**: the JSON document format you author.
+  - v0.3.0 targets `version: "2.0"` only.
+  - You author exactly one of `segments[]` (recommended) or `timeline[]` (escape hatch).
+- **Component Registry (`ComponentRegistry`)**: a map from string `type` -> React component + Zod props schema + metadata.
+  - Only registered components can render.
+  - Props are validated with Zod and defaults are applied deterministically.
+- **Validator (`IRValidator`)**: validates:
+  - IR schema (Zod)
+  - semantic rules (timing bounds, duration math, transition overlap constraints)
+  - registry contracts (type exists, props valid, children allowed, etc.)
+- **Compiler (`compileToRenderGraph`)**: compiles authored IR into a normalized, timed representation used by rendering.
+  - In segments mode: inserts an internal `Segment` wrapper node for each segment and computes overlaps.
+  - In timeline mode: fills missing `timing` defaults (whole-video / whole-parent).
+- **Renderer (`WavesEngine`)**: bundles a temporary Remotion project and calls Remotion's renderer.
+  - It writes a temporary entrypoint, bundles, selects a composition, and renders media.
+
+### How segments + transitions work
+
+Segments are the recommended authoring style for agents because they reduce timing math:
+
+- Each segment has `durationInFrames` and a `root` node.
+- Segment start times are derived by order.
+- Optional overlaps are declared via `transitionToNext`.
+
+Waves compiles segments into a "render timeline" (a list of timed component nodes). Each segment becomes:
+
+- a root `Segment` node (internal; not shown in the LLM catalog)
+- whose child is the authored `root` node
+
+Why the internal `Segment` wrapper exists:
+
+- Overlap transitions are easiest to implement at the segment boundary.
+- The wrapper can apply fade/slide/zoom/clip effects for the first/last frames of a segment.
+- The wrapper receives both the "enter transition" (inferred from the previous segment's `transitionToNext`) and the "exit transition" (the current segment's `transitionToNext`).
+
+Overlap math:
+
+- Let segment `i` have duration `Di`.
+- Let overlap `Oi` be `segments[i].transitionToNext.durationInFrames` (only for segments that have a next segment).
+- Then the compiled start time is:
+  - `start(0) = 0`
+  - `start(i+1) = start(i) + Di - Oi`
+- The compiled video end must equal `video.durationInFrames`.
+
+### Validation model
+
+Waves tries to fail early with errors that are usable for an agent:
+
+1) **Schema validation** (Zod):
+   - ensures the IR has the expected structure (types, required fields, etc.)
+2) **Semantic validation**:
+   - validates segment overlap constraints (overlap cannot exceed either segment)
+   - validates that all timed nodes stay within their parent duration
+   - validates that the compiled timeline end equals `video.durationInFrames`
+3) **Registry validation**:
+   - unknown component types fail
+   - props fail if they don't match the component's Zod schema
+   - children fail if the component metadata forbids children (or requires a certain number)
+
+The validator applies Zod defaults into the IR node objects. This is intentional: it makes render-time props deterministic and reduces "undefined" cases inside components.
+
+### Rendering model
+
+Rendering is done by generating a tiny Remotion project on the fly:
+
+1) Waves validates + compiles the IR to a timed timeline.
+2) Waves writes a temporary `entry.tsx` that:
+   - registers the `WavesComposition` as the Remotion root
+   - embeds the compiled IR as JSON
+   - registers built-in components (and optional user `--register` modules)
+3) Waves calls `@remotion/bundler` to create a bundle.
+4) Waves calls `@remotion/renderer` to select the composition and render media.
+
+This means you do not need to maintain a separate Remotion project just to use Waves.
 
 ## Installation
 
@@ -49,387 +155,2120 @@ Peer dependencies (must be installed by the consumer):
 npm i react remotion
 ```
 
-Rendering prerequisites:
-
-- `ffmpeg` must be installed and available on the PATH.
-- A Chromium browser must be available to `@remotion/renderer` (Remotion’s renderer runs headless Chromium).
-
-## CLI / Agent workflow
-
-Waves ships a `waves` CLI so a locally running AI agent (or any terminal user) can:
-
-1) fetch a system prompt + JSON Schemas (the authoring contract)
-2) write a starter IR file
-3) validate the IR
-4) render an MP4 from the IR
-
-Install locally (recommended):
-
-```bash
-npm i -D @depths/waves
-```
-
-Run the CLI via the local bin:
-
-```bash
-npx waves --help
-```
-
-Or run without installing (one-off):
-
-```bash
-npx -y -p @depths/waves waves --help
-```
-
-### 1) Get the agent prompt + schemas
-
-Machine-readable payload (recommended for agents):
-
-```bash
-npx waves prompt --format json --out ./waves-prompt.json
-```
-
-Human-readable system prompt:
-
-```bash
-npx waves prompt --format text --out ./waves-system-prompt.txt
-```
-
-Schemas only:
-
-```bash
-npx waves schema --kind all --pretty --out ./waves-schemas.json
-```
-
-If you register custom components at module import time, include them with repeatable `--register`:
-
-```bash
-npx waves prompt --format json --register ./src/register-waves-components.ts
-```
-
-### 2) Write IR JSON
-
-```bash
-npx waves write-ir --template basic --pretty --out ./video.ir.json
-```
-
-### 3) Validate IR JSON
-
-```bash
-npx waves validate --in ./video.ir.json
-```
-
-Structured validation result:
-
-```bash
-npx waves validate --in ./video.ir.json --format json
-```
-
-### 4) Render MP4
-
-```bash
-npx waves render --in ./video.ir.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
-```
-
-If your IR references `"/assets/..."` paths, pass `--publicDir` and ensure the files exist at `${publicDir}/assets/...`:
-
-```bash
-npx waves render --in ./video.ir.json --out ./output.mp4 --publicDir ./public
-```
-
-### Exit codes
-
-- `0`: success
-- `1`: usage error (invalid flags/command)
-- `2`: validation failure (invalid JSON or IR validation errors)
-- `3`: render failure
-- `4`: I/O error (missing/unreadable/unwritable files)
-- `5`: internal error (bug)
-
-## Quickstart (one function)
-
-```ts
-import { renderVideo } from '@depths/waves';
+Node: see `package.json` engines (this repo targets Node 22+).
 
-await renderVideo(
-  {
-    version: '1.0',
-    video: { id: 'my-video', width: 1920, height: 1080, fps: 30, durationInFrames: 90 },
-    scenes: [
-      {
-        id: 'scene-1',
-        type: 'Scene',
-        timing: { from: 0, durationInFrames: 90 },
-        props: { background: { type: 'color', value: '#000000' } },
-        children: [
-          {
-            id: 'title',
-            type: 'Text',
-            timing: { from: 0, durationInFrames: 90 },
-            props: { content: 'Hello Waves', fontSize: 72, animation: 'fade' }
-          }
-        ]
-      }
-    ]
-  },
-  { outputPath: './output.mp4' }
-);
+## CLI (agent workflow)
+
+Waves ships a `waves` CLI so a locally running AI agent (or any terminal user) can:
+
+1) fetch a system prompt + JSON Schemas + catalog
+2) write a starter IR file
+3) validate the IR
+4) render an MP4 from the IR
+
+Install locally (recommended):
+
+```bash
+npm i -D @depths/waves
 ```
 
-## Core concepts
+Run via the local bin:
 
-### 1) IR (Intermediate Representation)
+```bash
+npx waves --help
+```
 
-The IR is plain JSON. At minimum, it includes:
+### Typical agent loop
 
-- `version`: currently `"1.0"`
-- `video`: dimensions, fps, total duration
-- `scenes`: an array of `Scene` components
+For an agent that can execute terminal commands, the recommended flow is:
 
-All timing is expressed in frames.
+1. `waves prompt --format json --out waves-prompt.json`
+2. Use `waves-prompt.json.systemPrompt` + `waves-prompt.json.schemas` + `waves-prompt.json.catalog` as the authoring contract for the model
+3. Have the model output a single JSON object (Video IR)
+4. Write that JSON to `video.v2.json`
+5. `waves validate --in video.v2.json` until it passes
+6. `waves render --in video.v2.json --out output.mp4 ...`
 
-### 2) Timing model
+### 1) Get the prompt payload (system prompt + schemas + catalog)
 
-- Every component has a `timing` object: `{ from, durationInFrames }`
-- Scenes are expected to be sequential:
-  - Scene 0 starts at frame 0
-  - Scene N starts exactly where Scene N-1 ends
-  - Sum of scene durations must equal `video.durationInFrames`
-- Child components (inside a `Scene`) must fit within the scene duration.
+Machine-readable payload (recommended for agents):
 
-### 3) Component registry
+```bash
+npx waves prompt --format json --pretty --out ./waves-prompt.json
+```
 
-Waves never renders arbitrary `type` strings. A component `type` must be registered:
+Human-readable system prompt:
 
-- `type`: a string identifier, e.g. `"Text"`
-- `component`: a React component to render
-- `propsSchema`: a Zod schema used to validate and coerce defaults
-- `metadata`: descriptions and examples useful for LLM prompting
+```bash
+npx waves prompt --format text --out ./waves-system-prompt.txt
+```
 
-### 4) Rendering engine
+Schemas only:
 
-Rendering is done through Remotion:
+```bash
+npx waves schema --kind all --pretty --out ./waves-schemas.json
+```
 
-1. Validate IR
-2. Generate a temporary Remotion entry point
-3. Bundle using `@remotion/bundler`
-4. Select the composition using `@remotion/renderer`
-5. Render the media to `outputPath`
+Component catalog (grouped by category):
 
-Important limitation (v0.1.0):
+```bash
+npx waves catalog
+npx waves catalog --format json --pretty --out ./waves-catalog.json
+```
 
-- `WavesEngine` currently requires using `globalRegistry` for rendering, because the generated Remotion bundle needs to register the same components at bundle-time.
+If you register custom components at module import time, include them with repeatable `--register`:
 
-## API reference
+```bash
+npx waves prompt --format json --register ./src/register-waves-components.ts
+npx waves schema --kind components --register ./src/register-waves-components.ts
+npx waves validate --in ./video.v2.json --register ./src/register-waves-components.ts
+```
 
-### `VideoIRSchema`
+Important notes on `--register`:
 
-Use this to validate IR generated by an LLM:
+- The value must be a Node-loadable module at runtime (typically a `.js`/`.mjs` file).
+- If you pass a path, prefer an absolute path or a relative path with `./`.
+- A registration module usually calls `globalRegistry.register(...)` to add custom components before validation/rendering.
+- Re-registering an existing `type` throws (registry types are unique).
 
-```ts
-import { VideoIRSchema } from '@depths/waves';
+### 2) Write IR JSON
 
-const parsed = VideoIRSchema.safeParse(maybeJson);
-if (!parsed.success) {
-  // parsed.error.issues
-}
+```bash
+npx waves write-ir --template basic --pretty --out ./video.v2.json
 ```
 
-### `IRValidator`
+### 3) Validate IR JSON
 
-Runs both schema validation and semantic checks:
+```bash
+npx waves validate --in ./video.v2.json
+```
 
-```ts
-import { IRValidator } from '@depths/waves';
+Structured validation result:
 
-const validator = new IRValidator();
-const result = validator.validate(maybeJson);
-if (!result.success) {
-  // result.errors: { path: string[]; message: string; code: string }[]
-}
+```bash
+npx waves validate --in ./video.v2.json --format json
 ```
 
-Semantic checks include:
+### 4) Render MP4
 
-- Scene duration sum matches `video.durationInFrames` (`DURATION_MISMATCH`)
-- Scene `from` frames are sequential (`TIMING_GAP_OR_OVERLAP`)
-- Child components do not exceed their parent duration (`COMPONENT_EXCEEDS_PARENT`)
+```bash
+npx waves render --in ./video.v2.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
+```
 
-### `ComponentRegistry` / `globalRegistry`
+If your IR references `"/assets/..."` paths, pass `--publicDir` and ensure the files exist at `${publicDir}/assets/...`:
 
-```ts
-import { ComponentRegistry, globalRegistry } from '@depths/waves';
+```bash
+npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public
 ```
 
-Typically you will use `globalRegistry` so that the rendering bundle can register and render the same types.
+### Exit codes
 
-### `registerBuiltInComponents()`
+- `0`: success
+- `1`: usage error (invalid flags/command)
+- `2`: validation failure (invalid JSON or IR validation errors)
+- `3`: render failure
+- `4`: I/O error (missing/unreadable/unwritable files)
+- `5`: internal error (bug)
 
-Registers built-in primitives (`Scene`, `Text`, `Audio`) into `globalRegistry`.
+### Command reference
 
-```ts
-import { registerBuiltInComponents } from '@depths/waves';
+This section documents every command and flag supported by the current CLI implementation (`src/cli.ts`).
+
+#### `waves --help` / `waves help`
+
+Prints a short help text.
+
+#### `waves --version`
+
+Prints the package version (e.g. `0.2.0`).
+
+#### `waves prompt`
+
+Outputs an "agent-ready" payload that includes:
+
+- `systemPrompt`: a full system prompt string
+- `schemas.videoIR`: JSON Schema for authoring IR (segments mode)
+- `schemas.components`: a JSON object keyed by component `type` containing props JSON Schemas + metadata
+- `catalog`: categories + items (flattened list for easier prompting / UI)
+
+Flags:
+
+- `--format text|json` (default `text`)
+- `--maxChars <n>` (text format only; truncates the prompt)
+- `--pretty` (json format only)
+- `--out <path>` (optional; writes the output to a file in addition to stdout)
+- `--register <module>` (repeatable)
 
-registerBuiltInComponents();
+Examples:
+
+```bash
+npx waves prompt --format json --pretty --out ./waves-prompt.json
+npx waves prompt --format text --maxChars 4000 --out ./waves-system-prompt.txt
 ```
 
-This function is idempotent: calling it multiple times does not double-register types.
+#### `waves schema`
 
-### `renderVideo()`
+Outputs JSON Schemas only.
 
-Convenience wrapper:
+Flags:
 
-- Registers built-ins
-- Constructs `WavesEngine(globalRegistry, new IRValidator())`
-- Calls `engine.render()`
+- `--kind video-ir|components|all` (default `all`)
+- `--pretty`
+- `--out <path>` (optional; writes output to a file in addition to stdout)
+- `--register <module>` (repeatable; affects `--kind components` and `all`)
 
-```ts
-import { renderVideo } from '@depths/waves';
+Examples:
 
-await renderVideo(ir, { outputPath: './out.mp4' });
+```bash
+npx waves schema --kind video-ir --pretty --out ./schema.video-ir.json
+npx waves schema --kind components --pretty --out ./schema.components.json
 ```
 
-### `WavesEngine`
+#### `waves catalog`
 
-Lower-level control:
+Prints the built-in component catalog grouped by category.
 
-```ts
-import { WavesEngine, globalRegistry, IRValidator, registerBuiltInComponents } from '@depths/waves';
+Flags:
+
+- `--format text|json` (default `text`)
+- `--pretty` (json format only)
+- `--out <path>` (optional; writes output to a file in addition to stdout)
+- `--includeInternal` (includes internal-only types such as `Segment`)
+- `--register <module>` (repeatable; adds additional registered types)
+
+Examples:
+
+```bash
+npx waves catalog
+npx waves catalog --format json --pretty --out ./waves-catalog.json
+```
+
+#### `waves write-ir`
+
+Writes a starter IR JSON file (always `version: "2.0"` segments mode).
+
+Flags:
+
+- `--template minimal|basic` (default `minimal`)
+- `--pretty`
+- `--out <path>` (required)
 
-registerBuiltInComponents();
-const engine = new WavesEngine(globalRegistry, new IRValidator());
-await engine.render(ir, {
-  outputPath: './out.mp4',
-  codec: 'h264',
-  crf: 18,
-  concurrency: 4
-});
+Examples:
+
+```bash
+npx waves write-ir --template minimal --pretty --out ./video.v2.json
+npx waves write-ir --template basic --pretty --out ./examples/basic.v2.json
 ```
 
-Options:
+#### `waves validate`
+
+Validates an IR JSON file.
+
+Flags:
 
-- `outputPath` (required): output file path
-- `codec`: one of `'h264' | 'h265' | 'vp8' | 'vp9'` (default: `h264`)
-- `crf`: quality parameter (lower is higher quality)
-- `concurrency`: number or percentage string supported by Remotion renderer
-- `publicDir`: optional directory for Remotion `staticFile()` assets
+- `--in <path>` (required)
+- `--format text|json` (default `text`)
+- `--pretty` (json format only)
+- `--register <module>` (repeatable)
 
-Advanced / internal:
+Behavior:
 
-- `rootDir`: temp directory root (defaults to `process.cwd()`)
-- `registrationModules`: module specifiers to import into the Remotion bundle before rendering (useful if you register custom components at module import time)
+- text format prints `ok` to stdout on success, otherwise prints a human-readable list to stderr and exits non-zero.
+- json format prints `{ "success": true }` or `{ "success": false, "errors": [...] }` to stdout.
+
+Examples:
+
+```bash
+npx waves validate --in ./video.v2.json
+npx waves validate --in ./video.v2.json --format json --pretty
+```
 
-## Asset handling
+#### `waves render`
+
+Renders an MP4 from an IR JSON file.
+
+Flags:
+
+- `--in <path>` (required)
+- `--out <path>` (required)
+- `--publicDir <path>` (optional; required if your IR uses `/assets/...` paths)
+- `--codec h264|h265|vp8|vp9` (optional; default `h264`)
+- `--crf <n>` (optional; forwarded to Remotion renderer)
+- `--concurrency <n|string>` (optional; forwarded to Remotion renderer)
+- `--debugBounds` (optional; draws debug outlines for every rendered node)
+- `--debugLabels` (optional; labels debug outlines with `type#id`)
+- `--register <module>` (repeatable)
+- `--pretty` (only affects the formatting of error JSON when render fails)
+
+Examples:
+
+```bash
+npx waves render --in ./video.v2.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
+npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public
+npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public --debugBounds --debugLabels
+```
 
-Waves supports two kinds of asset references in the IR:
+#### `waves stills`
 
-1. Remote URLs: `https://...` or `http://...`
-2. Absolute “public” paths: `/assets/foo.png`
+Renders a set of still images (single frames) from an IR JSON file. This is the recommended way to iterate on alignment and overlays without re-rendering full MP4s.
 
-For absolute paths:
+Flags:
 
-- `Scene`/`Audio` resolve them using Remotion’s `staticFile()` which expects a path relative to the `publicDir`.
-- Example: `src: "/assets/a.png"` becomes `staticFile("assets/a.png")`.
+- `--in <path>` (required)
+- `--outDir <path>` (required)
+- `--frames <csv>` (required; e.g. `"0,30,60"`)
+- `--publicDir <path>` (optional; required if your IR uses `/assets/...` paths)
+- `--imageFormat png|jpeg|webp` (optional; default `png`)
+- `--scale <n>` (optional; default `1`)
+- `--jpegQuality <n>` (optional; default `90`; only used when `--imageFormat jpeg`)
+- `--debugBounds` / `--debugLabels` (same as `waves render`)
+- `--register <module>` (repeatable)
 
-If you reference `"/assets/..."`, pass `publicDir` to `renderVideo()` / `engine.render()` and make sure the file exists at:
+Examples:
 
+```bash
+npx waves stills --in ./video.v2.json --outDir ./examples/_stills --frames "0,45,90" --publicDir ./public
+npx waves stills --in ./video.v2.json --outDir ./examples/_stills --frames "0,45,90" --publicDir ./public --debugBounds --debugLabels
 ```
-${publicDir}/assets/...
+
+## IR v2.0 (authoring contract)
+
+v0.3.0 targets `version: "2.0"` only.
+
+### Recommended: `segments[]` (high-level)
+
+In segments mode, you provide sequential segments and Waves compiles them into an explicit timed timeline. You usually do not need to specify `timing` on nodes.
+
+Key rules:
+
+- Segment overlap is controlled by `transitionToNext.durationInFrames`.
+- `transitionToNext` is only valid when there is a "next" segment (i.e. it is not allowed on the last segment).
+- The total video duration must match the compiled timeline end:
+  - `video.durationInFrames = sum(segment.durationInFrames) - sum(overlap)`
+  - where `overlap = transitionToNext.durationInFrames` for each segment that has a next segment.
+
+Minimal example:
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 60 },
+  "segments": [
+    {
+      "id": "scene-1",
+      "durationInFrames": 60,
+      "root": {
+        "id": "root",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#000000" } },
+        "children": [{ "id": "t1", "type": "Text", "props": { "content": "Hello" } }]
+      }
+    }
+  ]
+}
 ```
 
-## Built-in components (v0.1.0)
+Supported `transitionToNext.type` values (segment overlap transitions):
+
+- `FadeTransition`
+- `SlideTransition` (`props`: `{ direction: "left"|"right"|"up"|"down", distance?: number }`)
+- `ZoomTransition` (`props`: `{ type: "zoomIn"|"zoomOut" }`)
+- `WipeTransition` (`props`: `{ direction: "left"|"right"|"up"|"down"|"diagonal", softEdge?: boolean }`)
+- `CircularReveal` (`props`: `{ direction: "open"|"close", center?: { x: 0..1, y: 0..1 } }`)
 
-### `Scene`
+### Escape hatch: `timeline[]` (low-level)
 
-Container component for a segment of the video.
+In timeline mode you provide explicit timings. Each node's `timing` is relative to its parent sequence (nested timing is "local").
+
+Notes:
+
+- Root `timing` is optional; if omitted, Waves treats the node as spanning the full video duration.
+- Child `timing` is optional; if omitted, Waves treats the child as spanning the full parent duration.
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 60 },
+  "timeline": [
+    {
+      "id": "scene",
+      "type": "Scene",
+      "timing": { "from": 0, "durationInFrames": 60 },
+      "props": { "background": { "type": "color", "value": "#000000" } }
+    }
+  ]
+}
+```
+
+### Component nodes
+
+Nodes are structural (the IR does not hard-code component types):
+
+```ts
+type ComponentNode = {
+  id: string;
+  type: string; // must be registered at validate/render time
+  props?: Record<string, unknown>;
+  timing?: { from: number; durationInFrames: number };
+  children?: ComponentNode[];
+};
+```
+
+Validation uses the registry to enforce:
+
+- unknown component types (error)
+- props schemas (Zod validation, defaults applied)
+- whether a component can have `children` (metadata contract)
+
+## Components (primitives + composites)
+
+Waves renders only components that have been explicitly registered in the `ComponentRegistry`. Each component is defined by:
+
+- a **string type** (e.g. `"Scene"`, `"TypewriterText"`)
+- a **React component** implementation (Remotion primitives + CSS)
+- a **Zod props schema** (validation + defaults)
+- **metadata** (kind/category/description/LLM guidance/children contract)
+
+### Primitives vs composites
+
+- **Primitives** are low-level building blocks (layout, text, media). They are intentionally generic.
+- **Composites** are higher-level building blocks (shadcn-like) that encode common video patterns: titles, lower thirds, social cards, charts, transitions, etc.
+
+In general:
+
+- Prefer composites for agent-authored videos (less "design work" for the model).
+- Use primitives when you need precise control or to build new composites.
+
+### Categories and children contracts
+
+Each component is categorized (`text`, `layout`, `media`, `transition`, etc.) to help an agent choose the right tool.
+
+Some components can have nested `children` in the IR. This is controlled by metadata:
+
+- `acceptsChildren: true|false`
+- optional `minChildren` / `maxChildren` constraints
+
+If a component does not accept children and the IR provides `children`, validation fails before rendering.
+
+### Internal props: `__wavesDurationInFrames`
+
+At render time, Waves injects `__wavesDurationInFrames` into every component. This is the duration of the node's `Sequence`.
+
+This allows components to implement "in/out" animations without the author hand-computing timings.
+
+This prop is *not* part of the author-facing props schema and does not appear in the tables below.
+
+### Keeping docs in sync
+
+The tables below are generated from the live registry JSON Schemas to reduce drift.
+
+Regenerate after changing component props/metadata:
+
+```bash
+npm run build
+node scripts/generate-readme-components.mjs
+```
+
+<!-- BEGIN GENERATED: COMPONENTS -->
+
+<!-- generated by scripts/generate-readme-components.mjs; do not edit by hand -->
+
+### Components summary
+
+| Type | Kind | Category | Children | Internal | Description |
+| - | - | - | - | - | - |
+| `IntroScene` | composite | branding | no | no | Branded intro scene (logo + company name + optional tagline) |
+| `LogoReveal` | composite | branding | no | no | Logo intro animation (fade/scale/rotate/slide), optionally with a sound effect |
+| `OutroScene` | composite | branding | no | no | End screen with logo, message, optional CTA buttons and social handles |
+| `Watermark` | composite | branding | no | no | Persistent logo/text watermark in a corner |
+| `AnimatedCounter` | composite | data | no | no | Animated numeric counter (spring or linear), optionally with an icon and suffix |
+| `BarChart` | composite | data | no | no | Animated bar chart (vertical or horizontal) |
+| `LineGraph` | composite | data | no | no | Animated line graph (SVG) with draw/reveal modes |
+| `ProgressBar` | composite | data | no | no | Animated progress bar that fills over the component duration |
+| `ProgressRing` | composite | data | no | no | Circular progress indicator (SVG) that animates from 0 to percentage over duration |
+| `Image` | primitive | image | no | no | Full-frame image with object-fit options |
+| `ImageCollage` | composite | image | no | no | Collage of multiple images in a grid/stack/scatter layout with staggered entrances |
+| `ImageReveal` | composite | image | no | no | Reveals an image with wipe/expand/iris entrance effects |
+| `ImageSequence` | composite | image | no | no | Plays a numbered image sequence (frame-by-frame) |
+| `ImageWithCaption` | composite | image | no | no | Image with a caption strip (top/bottom) or overlay caption |
+| `KenBurnsImage` | composite | image | no | no | Slow zoom and pan (Ken Burns effect) for a still image |
+| `Box` | primitive | layout | yes | no | Flow container for layout and backgrounds (layout-safe) |
+| `CardStack` | composite | layout | no | no | Sequential stacked cards (2-5) with flip/slide/fade transitions |
+| `Frame` | primitive | layout | yes | no | Absolute-positioned container (x/y placement) |
+| `Grid` | primitive | layout | yes | no | Grid layout container with configurable rows/columns |
+| `GridLayout` | composite | layout | yes (1..∞) | no | Simple responsive grid layout for child components |
+| `Layer` | primitive | layout | yes (1..∞) | no | One overlay layer with explicit zIndex inside Layers |
+| `Layers` | primitive | layout | yes (1..∞) | no | Overlay container for stacking children (use Layer for zIndex) |
+| `Scene` | primitive | layout | yes | no | Scene container with a background and nested children |
+| `Segment` | primitive | layout | yes (1..1) | yes | Internal segment wrapper (used by v2 segments compiler) |
+| `Shape` | primitive | layout | no | no | Simple rect/circle shape for UI accents |
+| `SplitScreen` | composite | layout | yes (2..2) | no | Two-panel split screen layout |
+| `Stack` | primitive | layout | yes | no | Flexbox stack layout (row/column) with gap and alignment |
+| `ThirdLowerBanner` | composite | layout | no | no | Broadcast-style lower-third banner with name/title and optional avatar |
+| `Audio` | primitive | media | no | no | Plays an audio file with optional trimming and fade in/out |
+| `Video` | primitive | media | no | no | Full-frame video with object-fit options |
+| `VideoWithOverlay` | composite | media | no | no | Video background with an optional overlay (text/logo/gradient) |
+| `InstagramStory` | composite | social | no | no | Instagram story-style layout with profile header, text overlay, and optional sticker |
+| `TikTokCaption` | composite | social | no | no | TikTok-style captions with stroke and optional word highlighting |
+| `TwitterCard` | composite | social | no | no | Twitter/X post card layout with author header and optional image |
+| `YouTubeThumbnail` | composite | social | no | no | YouTube-style thumbnail layout (16:9) with bold title and optional face cutout |
+| `CountUpText` | composite | text | no | no | Counts from a start value to an end value with formatting options |
+| `GlitchText` | composite | text | no | no | Cyberpunk-style glitch text with RGB split jitter |
+| `KineticTypography` | composite | text | no | no | Rhythmic single-word kinetic typography driven by a timing array |
+| `OutlineText` | composite | text | no | no | Outlined title text with simple draw/fill animation |
+| `SplitText` | composite | text | no | no | Animated text where each word or letter enters with a staggered effect |
+| `SubtitleText` | composite | text | no | no | Caption/subtitle box with fade in/out and optional highlighted words |
+| `Text` | primitive | text | no | no | Displays animated text with positioning and animation options |
+| `TypewriterText` | composite | text | no | no | Character-by-character text reveal with optional blinking cursor |
+| `CircularReveal` | composite | transition | yes (1..∞) | no | Circular iris reveal/hide transition wrapper |
+| `FadeTransition` | composite | transition | yes (1..∞) | no | Fade in/out wrapper (used for segment transitions and overlays) |
+| `SlideTransition` | composite | transition | yes (1..∞) | no | Slide in/out wrapper (used for segment transitions and overlays) |
+| `WipeTransition` | composite | transition | yes (1..∞) | no | Directional wipe reveal/hide wrapper transition |
+| `ZoomTransition` | composite | transition | yes (1..∞) | no | Zoom in/out wrapper transition |
+
+### Components reference
+
+#### Category: `branding`
+
+##### `IntroScene`
+
+- kind: `composite`
+- category: `branding`
+- internal: `false`
+- children: `no`
+- description: Branded intro scene (logo + company name + optional tagline)
+- llmGuidance: Use as the first segment. Works best at 3-5 seconds. musicTrack can add ambience.
 
 Props:
 
-- `background` (required):
-  - `{ type: "color", value: "#RRGGBB" }`
-  - `{ type: "image", value: "/assets/bg.png" | "https://..." }`
-  - `{ type: "video", value: "/assets/bg.mp4" | "https://..." }`
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "#000000" |  |
+| `companyName` | string | yes |  | minLength=1 |
+| `logoSrc` | string | yes |  | minLength=1 |
+| `musicTrack` | string | no |  |  |
+| `primaryColor` | string | yes | "#FFFFFF" |  |
+| `tagline` | string | no |  |  |
+
+##### `LogoReveal`
+
+- kind: `composite`
+- category: `branding`
+- internal: `false`
+- children: `no`
+- description: Logo intro animation (fade/scale/rotate/slide), optionally with a sound effect
+- llmGuidance: Use for intros/outros. Keep the logo high-contrast and centered. soundEffect can be a short sting.
 
-Children:
+Props:
 
-- Any registered components; typically `Text` and `Audio`.
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "#000000" |  |
+| `effect` | enum("fade" \| "scale" \| "rotate" \| "slide") | yes | "scale" |  |
+| `logoSrc` | string | yes |  | minLength=1 |
+| `soundEffect` | string | no |  |  |
 
-### `Text`
+##### `OutroScene`
 
-Animated text overlay.
+- kind: `composite`
+- category: `branding`
+- internal: `false`
+- children: `no`
+- description: End screen with logo, message, optional CTA buttons and social handles
+- llmGuidance: Use as the last segment. Keep CTAs <=3 for clarity.
 
 Props:
 
-- `content` (required)
-- `fontSize` (default `48`)
-- `color` (default `#FFFFFF`)
-- `position` (default `"center"`) — `"top" | "center" | "bottom" | "left" | "right"`
-- `animation` (default `"fade"`) — `"none" | "fade" | "slide" | "zoom"`
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "#000000" |  |
+| `ctaButtons` | array<object> | no |  | maxItems=3 |
+| `logoSrc` | string | yes |  | minLength=1 |
+| `message` | string | yes | "Thank You" |  |
+| `socialHandles` | array<object> | no |  | maxItems=4 |
 
-### `Audio`
+##### `Watermark`
 
-Audio playback. Supports remote URLs or `staticFile()` assets.
+- kind: `composite`
+- category: `branding`
+- internal: `false`
+- children: `no`
+- description: Persistent logo/text watermark in a corner
+- llmGuidance: Use subtle opacity (0.3-0.6). bottomRight is standard.
 
 Props:
 
-- `src` (required)
-- `volume` (default `1`)
-- `startFrom` (default `0`) — trims from the beginning in frames
-- `fadeIn` (default `0`) — fade-in duration in frames
-- `fadeOut` (default `0`) — fade-out duration in frames
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `color` | string | yes | "#FFFFFF" |  |
+| `opacity` | number | yes | 0.5 | min=0.1, max=1 |
+| `position` | enum("topLeft" \| "topRight" \| "bottomLeft" \| "bottomRight") | yes | "bottomRight" |  |
+| `size` | number | yes | 60 | min=30, max=150 |
+| `src` | string | no |  |  |
+| `text` | string | no |  |  |
+| `type` | enum("logo" \| "text") | yes | "logo" |  |
 
-Notes:
+#### Category: `data`
+
+##### `AnimatedCounter`
+
+- kind: `composite`
+- category: `data`
+- internal: `false`
+- children: `no`
+- description: Animated numeric counter (spring or linear), optionally with an icon and suffix
+- llmGuidance: Use for big stats. animationType="spring" feels natural. suffix for units (%, K, M).
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `animationType` | enum("spring" \| "linear") | yes | "spring" |  |
+| `color` | string | yes | "#FFFFFF" |  |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 96 | min=8, max=300 |
+| `fontWeight` | integer | yes | 700 | min=100, max=900 |
+| `from` | number | yes | 0 |  |
+| `icon` | string | no |  |  |
+| `suffix` | string | no |  |  |
+| `to` | number | yes | 100 |  |
+
+##### `BarChart`
+
+- kind: `composite`
+- category: `data`
+- internal: `false`
+- children: `no`
+- description: Animated bar chart (vertical or horizontal)
+- llmGuidance: Use 2-6 bars. Provide maxValue to lock scale across multiple charts.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `data` | array<object> | yes |  | minItems=2, maxItems=8 |
+| `maxValue` | number | no |  |  |
+| `orientation` | enum("horizontal" \| "vertical") | yes | "vertical" |  |
+| `showGrid` | boolean | yes | false |  |
+| `showValues` | boolean | yes | true |  |
+
+##### `LineGraph`
+
+- kind: `composite`
+- category: `data`
+- internal: `false`
+- children: `no`
+- description: Animated line graph (SVG) with draw/reveal modes
+- llmGuidance: Use 5-20 points. animate="draw" traces the line; animate="reveal" wipes it left-to-right.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `animate` | enum("draw" \| "reveal") | yes | "draw" |  |
+| `color` | string | yes | "#00FF00" |  |
+| `data` | array<object> | yes |  | minItems=2, maxItems=50 |
+| `fillArea` | boolean | yes | false |  |
+| `showDots` | boolean | yes | true |  |
+| `strokeWidth` | number | yes | 3 | min=1, max=10 |
+
+##### `ProgressBar`
+
+- kind: `composite`
+- category: `data`
+- internal: `false`
+- children: `no`
+- description: Animated progress bar that fills over the component duration
+- llmGuidance: Use for loading/countdowns. showPercentage=true is helpful for clarity.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "rgba(255,255,255,0.2)" |  |
+| `color` | string | yes | "#00FF00" |  |
+| `height` | number | yes | 10 | min=5, max=50 |
+| `label` | string | no |  |  |
+| `position` | enum("top" \| "bottom") | yes | "bottom" |  |
+| `showPercentage` | boolean | yes | true |  |
+
+##### `ProgressRing`
+
+- kind: `composite`
+- category: `data`
+- internal: `false`
+- children: `no`
+- description: Circular progress indicator (SVG) that animates from 0 to percentage over duration
+- llmGuidance: Use for completion and goals. size 160-260 is typical. showLabel displays the percentage.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "rgba(255,255,255,0.2)" |  |
+| `color` | string | yes | "#00FF00" |  |
+| `percentage` | number | yes |  | min=0, max=100 |
+| `showLabel` | boolean | yes | true |  |
+| `size` | number | yes | 200 | min=100, max=500 |
+| `strokeWidth` | number | yes | 20 | min=5, max=50 |
+
+#### Category: `image`
+
+##### `Image`
+
+- kind: `primitive`
+- category: `image`
+- internal: `false`
+- children: `no`
+- description: Full-frame image with object-fit options
+- llmGuidance: Use Image for pictures and backgrounds. Use fit="cover" for full-bleed, fit="contain" to avoid cropping.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `borderRadius` | number | yes | 0 | min=0 |
+| `fit` | enum("cover" \| "contain") | yes | "cover" |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `src` | string | yes |  | minLength=1 |
+
+##### `ImageCollage`
+
+- kind: `composite`
+- category: `image`
+- internal: `false`
+- children: `no`
+- description: Collage of multiple images in a grid/stack/scatter layout with staggered entrances
+- llmGuidance: Use 2-6 images for best results. layout="grid" is clean; "scatter" is energetic.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `images` | array<object> | yes |  | minItems=2, maxItems=9 |
+| `layout` | enum("grid" \| "stack" \| "scatter") | yes | "grid" |  |
+| `stagger` | integer | yes | 5 | min=2, max=10 |
+
+##### `ImageReveal`
+
+- kind: `composite`
+- category: `image`
+- internal: `false`
+- children: `no`
+- description: Reveals an image with wipe/expand/iris entrance effects
+- llmGuidance: Use wipe for directional reveals, expand for subtle pop-in, iris for circular mask openings.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `direction` | enum("left" \| "right" \| "top" \| "bottom" \| "center") | yes | "left" |  |
+| `revealType` | enum("wipe" \| "expand" \| "iris") | yes | "wipe" |  |
+| `src` | string | yes |  | minLength=1 |
+
+##### `ImageSequence`
+
+- kind: `composite`
+- category: `image`
+- internal: `false`
+- children: `no`
+- description: Plays a numbered image sequence (frame-by-frame)
+- llmGuidance: Use for exported sprite sequences. basePath can be /assets/seq and filePattern like img_{frame}.png.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `basePath` | string | yes |  | minLength=1 |
+| `filePattern` | string | yes | "frame_{frame}.png" |  |
+| `fps` | integer | yes | 30 | min=1, max=120 |
+| `frameCount` | integer | yes |  | max=9007199254740991 |
+
+##### `ImageWithCaption`
+
+- kind: `composite`
+- category: `image`
+- internal: `false`
+- children: `no`
+- description: Image with a caption strip (top/bottom) or overlay caption
+- llmGuidance: Use overlay for quotes/testimonials over photos. Use bottom for standard captions.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `caption` | string | yes |  | maxLength=200 |
+| `captionPosition` | enum("top" \| "bottom" \| "overlay") | yes | "bottom" |  |
+| `captionStyle` | object | no |  | additionalProperties=false |
+| `src` | string | yes |  | minLength=1 |
+
+##### `KenBurnsImage`
+
+- kind: `composite`
+- category: `image`
+- internal: `false`
+- children: `no`
+- description: Slow zoom and pan (Ken Burns effect) for a still image
+- llmGuidance: Classic documentary-style motion. startScale 1 -> endScale 1.2 is subtle; add panDirection for extra movement.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `endScale` | number | yes | 1.2 | min=1, max=2 |
+| `panAmount` | number | yes | 50 | min=0, max=100 |
+| `panDirection` | enum("none" \| "left" \| "right" \| "up" \| "down") | yes | "none" |  |
+| `src` | string | yes |  | minLength=1 |
+| `startScale` | number | yes | 1 | min=1, max=2 |
+
+#### Category: `layout`
+
+##### `Box`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Flow container for layout and backgrounds (layout-safe)
+- llmGuidance: Use Box as a container inside Grid/Stack. Box participates in layout flow. For x/y positioning, use Frame.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | no |  |  |
+| `borderRadius` | number | yes | 0 | min=0 |
+| `height` | number | no |  |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `padding` | number | yes | 0 | min=0 |
+| `width` | number | no |  |  |
+
+##### `CardStack`
+
+- kind: `composite`
+- category: `layout`
+- internal: `false`
+- children: `no`
+- description: Sequential stacked cards (2-5) with flip/slide/fade transitions
+- llmGuidance: Use for steps/features. displayDuration is frames per card.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `cards` | array<object> | yes |  | minItems=2, maxItems=5 |
+| `displayDuration` | integer | yes | 90 | min=30, max=150 |
+| `transition` | enum("flip" \| "slide" \| "fade") | yes | "flip" |  |
+
+##### `Frame`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Absolute-positioned container (x/y placement)
+- llmGuidance: Use Frame for precise pixel placement (x/y). Use Box for normal layout flow inside Grid/Stack.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | no |  |  |
+| `borderRadius` | number | yes | 0 | min=0 |
+| `height` | number | no |  |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `padding` | number | yes | 0 | min=0 |
+| `width` | number | no |  |  |
+| `x` | number | yes | 0 |  |
+| `y` | number | yes | 0 |  |
+
+##### `Grid`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Grid layout container with configurable rows/columns
+- llmGuidance: Use Grid for photo collages and dashboards. Provide exactly rows*columns children when possible.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `align` | enum("start" \| "center" \| "end" \| "stretch") | yes | "stretch" |  |
+| `columns` | integer | yes | 2 | min=1, max=12 |
+| `gap` | number | yes | 24 | min=0 |
+| `justify` | enum("start" \| "center" \| "end" \| "stretch") | yes | "stretch" |  |
+| `padding` | number | yes | 0 | min=0 |
+| `rows` | integer | yes | 1 | min=1, max=12 |
+
+##### `GridLayout`
+
+- kind: `composite`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Simple responsive grid layout for child components
+- llmGuidance: Use for dashboards and collages. 2x2 is a good default for 4 items.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `columns` | integer | yes | 2 | min=1, max=4 |
+| `gap` | number | yes | 20 | min=0, max=50 |
+| `padding` | number | yes | 40 | min=0, max=100 |
+| `rows` | integer | yes | 2 | min=1, max=4 |
+
+##### `Layer`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: One overlay layer with explicit zIndex inside Layers
+- llmGuidance: Use Layer inside Layers to control stacking. Put exactly one child in a Layer (recommended).
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `inset` | number | yes | 0 | min=0 |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `pointerEvents` | enum("none" \| "auto") | yes | "none" |  |
+| `zIndex` | integer | yes | 0 | min=-9007199254740991, max=9007199254740991 |
+
+##### `Layers`
 
-- `fadeIn`/`fadeOut` are implemented via a `volume(frame)` curve.
-- The engine passes an internal prop `__wavesDurationInFrames` so `fadeOut` can compute its end.
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Overlay container for stacking children (use Layer for zIndex)
+- llmGuidance: Use Layers to stack background/content/overlays. Prefer Layer children with explicit zIndex.
 
-## LLM integration
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `overflow` | enum("visible" \| "hidden") | yes | "visible" |  |
+
+##### `Scene`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Scene container with a background and nested children
+- llmGuidance: Use Scene to define a segment of the video. Scene timings must be sequential with no gaps. Put Text and Audio as children.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `background` | oneOf(object \| object \| object) | yes |  |  |
+
+##### `Segment`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `true`
+- children: `yes (1..1)`
+- description: Internal segment wrapper (used by v2 segments compiler)
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `enterTransition` | object | no |  | additionalProperties=false |
+| `exitTransition` | object | no |  | additionalProperties=false |
+
+##### `Shape`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `no`
+- description: Simple rect/circle shape for UI accents
+- llmGuidance: Use Shape for lines, badges, and simple UI blocks. Use circle for dots and rings.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `fill` | string | yes | "#FFFFFF" |  |
+| `height` | number | yes | 100 |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `shape` | enum("rect" \| "circle") | yes | "rect" |  |
+| `strokeColor` | string | no |  |  |
+| `strokeWidth` | number | yes | 0 | min=0 |
+| `width` | number | yes | 100 |  |
+| `x` | number | yes | 0 |  |
+| `y` | number | yes | 0 |  |
+
+##### `SplitScreen`
+
+- kind: `composite`
+- category: `layout`
+- internal: `false`
+- children: `yes (2..2)`
+- description: Two-panel split screen layout
+- llmGuidance: Provide exactly 2 children. Use orientation="vertical" for left/right and "horizontal" for top/bottom.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `dividerColor` | string | no |  |  |
+| `gap` | number | yes | 48 | min=0 |
+| `orientation` | enum("vertical" \| "horizontal") | yes | "vertical" |  |
+| `padding` | number | yes | 80 | min=0 |
+| `split` | number | yes | 0.5 | min=0.1, max=0.9 |
+
+##### `Stack`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Flexbox stack layout (row/column) with gap and alignment
+- llmGuidance: Use Stack to arrange child components in a row or column without manual positioning.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `align` | enum("start" \| "center" \| "end" \| "stretch") | yes | "center" |  |
+| `direction` | enum("row" \| "column") | yes | "column" |  |
+| `gap` | number | yes | 24 | min=0 |
+| `justify` | enum("start" \| "center" \| "end" \| "between") | yes | "center" |  |
+| `padding` | number | yes | 0 | min=0 |
+
+##### `ThirdLowerBanner`
+
+- kind: `composite`
+- category: `layout`
+- internal: `false`
+- children: `no`
+- description: Broadcast-style lower-third banner with name/title and optional avatar
+- llmGuidance: Use for speaker introductions. name = big label, title = smaller subtitle. showAvatar + avatarSrc for profile image.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `accentColor` | string | yes | "#FF0000" |  |
+| `avatarSrc` | string | no |  |  |
+| `backgroundColor` | string | yes | "rgba(0,0,0,0.8)" |  |
+| `name` | string | yes |  | maxLength=50 |
+| `primaryColor` | string | yes | "#FFFFFF" |  |
+| `secondaryColor` | string | yes | "#CCCCCC" |  |
+| `showAvatar` | boolean | yes | false |  |
+| `title` | string | yes |  | maxLength=100 |
+
+#### Category: `media`
+
+##### `Audio`
+
+- kind: `primitive`
+- category: `media`
+- internal: `false`
+- children: `no`
+- description: Plays an audio file with optional trimming and fade in/out
+- llmGuidance: Use for background music or sound effects. Prefer short clips for SFX. Use fadeIn/fadeOut (in frames) for smoother audio starts/ends.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `fadeIn` | integer | yes | 0 | min=0, max=9007199254740991 |
+| `fadeOut` | integer | yes | 0 | min=0, max=9007199254740991 |
+| `src` | string | yes |  |  |
+| `startFrom` | integer | yes | 0 | min=0, max=9007199254740991 |
+| `volume` | number | yes | 1 | min=0, max=1 |
+
+##### `Video`
+
+- kind: `primitive`
+- category: `media`
+- internal: `false`
+- children: `no`
+- description: Full-frame video with object-fit options
+- llmGuidance: Use Video for B-roll. Keep videos short and muted unless you intentionally want audio.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `borderRadius` | number | yes | 0 | min=0 |
+| `fit` | enum("cover" \| "contain") | yes | "cover" |  |
+| `muted` | boolean | yes | true |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `src` | string | yes |  | minLength=1 |
+
+##### `VideoWithOverlay`
+
+- kind: `composite`
+- category: `media`
+- internal: `false`
+- children: `no`
+- description: Video background with an optional overlay (text/logo/gradient)
+- llmGuidance: Use gradient overlay to improve text readability. Set volume=0 to mute.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `overlay` | object | no |  | additionalProperties=false |
+| `playbackRate` | number | yes | 1 | min=0.5, max=2 |
+| `src` | string | yes |  | minLength=1 |
+| `volume` | number | yes | 1 | min=0, max=1 |
+
+#### Category: `social`
+
+##### `InstagramStory`
+
+- kind: `composite`
+- category: `social`
+- internal: `false`
+- children: `no`
+- description: Instagram story-style layout with profile header, text overlay, and optional sticker
+- llmGuidance: Best with 1080x1920 (9:16). Use backgroundImage + short text + optional sticker for mobile-style content.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "#000000" |  |
+| `backgroundImage` | string | no |  |  |
+| `musicTrack` | string | no |  |  |
+| `profilePic` | string | no |  |  |
+| `sticker` | enum("none" \| "poll" \| "question" \| "countdown") | yes | "none" |  |
+| `text` | string | no |  | maxLength=100 |
+| `username` | string | no |  |  |
+
+##### `TikTokCaption`
+
+- kind: `composite`
+- category: `social`
+- internal: `false`
+- children: `no`
+- description: TikTok-style captions with stroke and optional word highlighting
+- llmGuidance: Always keep strokeWidth>=2 for readability. highlightStyle="word" or "bounce" makes captions feel dynamic.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `color` | string | yes | "#FFFFFF" |  |
+| `fontSize` | number | yes | 48 | min=12, max=120 |
+| `highlightStyle` | enum("word" \| "bounce" \| "none") | yes | "word" |  |
+| `maxWidthPct` | number | yes | 0.92 | min=0.1, max=1 |
+| `position` | enum("center" \| "bottom") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
+| `strokeColor` | string | yes | "#000000" |  |
+| `strokeWidth` | number | yes | 3 | min=0, max=10 |
+| `text` | string | yes |  | maxLength=150 |
+
+##### `TwitterCard`
+
+- kind: `composite`
+- category: `social`
+- internal: `false`
+- children: `no`
+- description: Twitter/X post card layout with author header and optional image
+- llmGuidance: Use for announcements/testimonials. Keep tweet short for readability.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `author` | string | yes |  | minLength=1 |
+| `avatarSrc` | string | no |  |  |
+| `handle` | string | yes |  | minLength=1 |
+| `image` | string | no |  |  |
+| `timestamp` | string | no |  |  |
+| `tweet` | string | yes |  | maxLength=280 |
+| `verified` | boolean | yes | false |  |
+
+##### `YouTubeThumbnail`
+
+- kind: `composite`
+- category: `social`
+- internal: `false`
+- children: `no`
+- description: YouTube-style thumbnail layout (16:9) with bold title and optional face cutout
+- llmGuidance: Use 1280x720 video size. Keep title short and high-contrast. style="bold" is classic thumbnail.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `accentColor` | string | yes | "#FF0000" |  |
+| `backgroundImage` | string | yes |  | minLength=1 |
+| `style` | enum("bold" \| "minimal" \| "dramatic") | yes | "bold" |  |
+| `subtitle` | string | no |  | maxLength=40 |
+| `thumbnailFace` | string | no |  |  |
+| `title` | string | yes |  | maxLength=60 |
 
-### Generating a prompt schema for the model
+#### Category: `text`
+
+##### `CountUpText`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Counts from a start value to an end value with formatting options
+- llmGuidance: Use for metrics. format="currency" adds $, format="percentage" multiplies by 100 and adds %.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `color` | string | yes | "#FFFFFF" |  |
+| `decimals` | integer | yes | 0 | min=0, max=4 |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 72 | min=8, max=240 |
+| `fontWeight` | integer | yes | 700 | min=100, max=900 |
+| `format` | enum("integer" \| "decimal" \| "currency" \| "percentage") | yes | "integer" |  |
+| `from` | number | yes | 0 |  |
+| `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `prefix` | string | no |  |  |
+| `suffix` | string | no |  |  |
+| `to` | number | yes | 100 |  |
+
+##### `GlitchText`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Cyberpunk-style glitch text with RGB split jitter
+- llmGuidance: Use for tech/error moments. intensity 1-3 subtle, 7-10 extreme. glitchDuration is frames at start.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `color` | string | yes | "#FFFFFF" |  |
+| `content` | string | yes |  | maxLength=100 |
+| `fontFamily` | string | yes | "monospace" |  |
+| `fontSize` | number | yes | 72 | min=8, max=240 |
+| `glitchDuration` | integer | yes | 10 | min=5, max=30 |
+| `intensity` | integer | yes | 5 | min=1, max=10 |
+| `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+
+##### `KineticTypography`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Rhythmic single-word kinetic typography driven by a timing array
+- llmGuidance: Provide timing frames for when each word appears. Use emphasis="giant" sparingly for impact.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `color` | string | yes | "#FFFFFF" |  |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 48 | min=12, max=140 |
+| `timing` | array<integer> | yes |  | minItems=1 |
+| `transition` | enum("fade" \| "scale" \| "slideLeft" \| "slideRight") | yes | "scale" |  |
+| `words` | array<object> | yes |  | minItems=1, maxItems=50 |
+
+##### `OutlineText`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Outlined title text with simple draw/fill animation
+- llmGuidance: Use for bold titles. animation="draw" emphasizes the outline; animation="fill" reveals the fill color.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `animation` | enum("draw" \| "fill") | yes | "draw" |  |
+| `content` | string | yes |  | maxLength=50 |
+| `fillColor` | string | yes | "#000000" |  |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 96 | min=8, max=240 |
+| `fontWeight` | integer | yes | 800 | min=100, max=900 |
+| `outlineColor` | string | yes | "#FFFFFF" |  |
+| `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `strokeWidth` | number | yes | 3 | min=1, max=10 |
+
+##### `SplitText`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Animated text where each word or letter enters with a staggered effect
+- llmGuidance: Use for titles. splitBy="word" is best for phrases; splitBy="letter" is dramatic for short words.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `animation` | enum("fade" \| "slideUp" \| "slideDown" \| "scale" \| "rotate") | yes | "slideUp" |  |
+| `color` | string | yes | "#FFFFFF" |  |
+| `content` | string | yes |  | maxLength=200 |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 48 | min=8, max=200 |
+| `maxWidthPct` | number | yes | 0.9 | min=0.1, max=1 |
+| `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
+| `splitBy` | enum("word" \| "letter") | yes | "word" |  |
+| `stagger` | integer | yes | 3 | min=1, max=10 |
+
+##### `SubtitleText`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Caption/subtitle box with fade in/out and optional highlighted words
+- llmGuidance: Use for narration/captions. highlightWords helps emphasize key terms.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | yes | "rgba(0,0,0,0.7)" |  |
+| `color` | string | yes | "#FFFFFF" |  |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 36 | min=12, max=80 |
+| `highlightWords` | array<string> | no |  |  |
+| `maxWidth` | number | yes | 800 | min=200, max=1200 |
+| `padding` | number | yes | 20 | min=0, max=80 |
+| `position` | enum("top" \| "bottom") | yes | "bottom" |  |
+| `text` | string | yes |  | maxLength=200 |
+
+##### `Text`
+
+- kind: `primitive`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Displays animated text with positioning and animation options
+- llmGuidance: Use for titles, subtitles, captions. Keep content under 100 characters for readability. Position "center" works best for titles.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `animation` | enum("none" \| "fade" \| "slide" \| "zoom") | yes | "fade" |  |
+| `color` | string | yes | "#FFFFFF" |  |
+| `content` | string | yes |  |  |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 48 |  |
+| `maxWidthPct` | number | yes | 0.9 | min=0.1, max=1 |
+| `position` | enum("top" \| "center" \| "bottom" \| "left" \| "right") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
+| `textAlign` | enum("left" \| "center" \| "right") | yes | "center" |  |
+
+##### `TypewriterText`
+
+- kind: `composite`
+- category: `text`
+- internal: `false`
+- children: `no`
+- description: Character-by-character text reveal with optional blinking cursor
+- llmGuidance: Use for dramatic reveals and terminal-style text. speed ~1-2 is readable; 3-5 is fast.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `color` | string | yes | "#FFFFFF" |  |
+| `content` | string | yes |  | maxLength=500 |
+| `cursorColor` | string | yes | "#FFFFFF" |  |
+| `fontFamily` | string | yes | "Inter" |  |
+| `fontSize` | number | yes | 48 | min=8, max=200 |
+| `maxWidthPct` | number | yes | 0.9 | min=0.1, max=1 |
+| `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
+| `showCursor` | boolean | yes | true |  |
+| `speed` | number | yes | 2 | min=0.5, max=5 |
+
+#### Category: `transition`
+
+##### `CircularReveal`
+
+- kind: `composite`
+- category: `transition`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Circular iris reveal/hide transition wrapper
+- llmGuidance: direction="open" reveals from center, direction="close" hides to a point. center controls origin.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `center` | object | no |  | additionalProperties=false |
+| `direction` | enum("open" \| "close") | yes | "open" |  |
+| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
+
+##### `FadeTransition`
+
+- kind: `composite`
+- category: `transition`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Fade in/out wrapper (used for segment transitions and overlays)
+- llmGuidance: Use for gentle transitions. durationInFrames ~30 is standard.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `easing` | enum("linear" \| "easeIn" \| "easeOut" \| "easeInOut") | yes | "easeInOut" |  |
+| `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
+
+##### `SlideTransition`
+
+- kind: `composite`
+- category: `transition`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Slide in/out wrapper (used for segment transitions and overlays)
+- llmGuidance: Use for more dynamic transitions. direction controls where content enters from.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `direction` | enum("left" \| "right" \| "up" \| "down") | yes | "left" |  |
+| `distance` | integer | yes | 160 | min=1, max=2000 |
+| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
+
+##### `WipeTransition`
+
+- kind: `composite`
+- category: `transition`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Directional wipe reveal/hide wrapper transition
+- llmGuidance: Use as a more stylized reveal. softEdge can make it feel less harsh.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `direction` | enum("left" \| "right" \| "up" \| "down" \| "diagonal") | yes | "right" |  |
+| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
+| `softEdge` | boolean | yes | false |  |
+
+##### `ZoomTransition`
+
+- kind: `composite`
+- category: `transition`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Zoom in/out wrapper transition
+- llmGuidance: Use for energetic cuts. type="zoomIn" feels punchy; type="zoomOut" feels calmer.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `durationInFrames` | integer | yes | 30 | min=10, max=60 |
+| `phase` | enum("in" \| "out" \| "inOut") | yes | "inOut" |  |
+| `type` | enum("zoomIn" \| "zoomOut") | yes | "zoomIn" |  |
+
+<!-- END GENERATED: COMPONENTS -->
+
+## Examples (composition recipes)
+
+The `examples/` directory contains validated IR JSON files you can use as starting points.
+
+Quick validate:
+
+```bash
+npx waves validate --in examples/basic.v2.json
+```
+
+Validate all examples:
+
+```powershell
+Get-ChildItem examples -Filter *.v2.json | ForEach-Object { npx waves validate --in $_.FullName }
+```
+
+Render (writes an MP4; `examples/*.mp4` are gitignored):
+
+```bash
+npx waves render --in examples/basic.v2.json --out examples/basic.v2.mp4 --codec h264 --crf 28 --concurrency 1
+```
+
+If an example references `/assets/...`, you must provide those files and pass `--publicDir`:
+
+```bash
+npx waves render --in examples/intro-stats-outro.v2.json --out examples/intro-stats-outro.v2.mp4 --publicDir ./public
+```
+
+### Example 0: basic starter (segments + composites)
+
+File: `examples/basic.v2.json`
+
+This is the default starter IR used by `waves write-ir --template basic`. It demonstrates:
+
+- segments mode (recommended)
+- a segment-to-segment overlap via `transitionToNext`
+- text composites (`SplitText`, `TypewriterText`)
+- an overlay composite (`Watermark`)
+
+```json
+{
+  "version": "2.0",
+  "video": {
+    "id": "main",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "durationInFrames": 165
+  },
+  "segments": [
+    {
+      "id": "scene-1",
+      "durationInFrames": 90,
+      "transitionToNext": {
+        "type": "FadeTransition",
+        "durationInFrames": 15
+      },
+      "root": {
+        "id": "root",
+        "type": "Scene",
+        "props": {
+          "background": { "type": "color", "value": "#000000" }
+        },
+        "children": [
+          {
+            "id": "title",
+            "type": "SplitText",
+            "props": {
+              "content": "Waves v0.3.0",
+              "fontSize": 96,
+              "splitBy": "word",
+              "stagger": 3,
+              "animation": "slideUp"
+            }
+          },
+          {
+            "id": "subtitle",
+            "type": "TypewriterText",
+            "props": {
+              "content": "Seamless alignment + overlays",
+              "fontSize": 48,
+              "position": "bottom",
+              "speed": 1.5
+            }
+          },
+          {
+            "id": "wm",
+            "type": "Watermark",
+            "props": {
+              "type": "text",
+              "text": "@depths.ai",
+              "position": "bottomRight",
+              "opacity": 0.4,
+              "size": 60
+            }
+          }
+        ]
+      }
+    },
+    {
+      "id": "scene-2",
+      "durationInFrames": 90,
+      "root": {
+        "id": "root-2",
+        "type": "Scene",
+        "props": {
+          "background": { "type": "color", "value": "#0B1220" }
+        },
+        "children": [
+          {
+            "id": "lower-third",
+            "type": "ThirdLowerBanner",
+            "props": { "name": "Waves", "title": "v0.3.0 - Alignment + overlays", "accentColor": "#3B82F6" }
+          },
+          {
+            "id": "count",
+            "type": "AnimatedCounter",
+            "props": { "from": 0, "to": 35, "suffix": " components", "fontSize": 96, "color": "#FFFFFF" }
+          },
+          {
+            "id": "wm-2",
+            "type": "Watermark",
+            "props": { "type": "text", "text": "waves", "position": "topLeft", "opacity": 0.25, "size": 52 }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Example 1: primitives-only layout
+
+File: `examples/primitives-card.v2.json`
+
+This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 150 },
+  "segments": [
+    {
+      "id": "card",
+      "durationInFrames": 150,
+      "root": {
+        "id": "scene",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "children": [
+          { "id": "accent", "type": "Shape", "props": { "shape": "rect", "x": 180, "y": 200, "width": 12, "height": 680, "fill": "#3B82F6", "opacity": 1 } },
+          {
+            "id": "panel",
+            "type": "Frame",
+            "props": { "x": 192, "y": 200, "width": 1548, "height": 680, "padding": 0, "backgroundColor": "rgba(255,255,255,0.06)", "borderRadius": 36, "opacity": 1 },
+            "children": [
+              {
+                "id": "panel-grid",
+                "type": "Grid",
+                "props": { "columns": 2, "rows": 2, "gap": 28, "padding": 64, "align": "stretch", "justify": "stretch" },
+                "children": [
+                  {
+                    "id": "tile-1",
+                    "type": "Box",
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "children": [
+                      { "id": "t1", "type": "Text", "props": { "content": "Primitives", "fontSize": 64, "position": "center", "animation": "fade" } }
+                    ]
+                  },
+                  {
+                    "id": "tile-2",
+                    "type": "Box",
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "children": [
+                      { "id": "t2", "type": "Text", "props": { "content": "Box + Grid", "fontSize": 54, "position": "center", "animation": "slide" } }
+                    ]
+                  },
+                  {
+                    "id": "tile-3",
+                    "type": "Box",
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "children": [
+                      { "id": "t3", "type": "Text", "props": { "content": "Shape", "fontSize": 54, "position": "center", "animation": "zoom" } }
+                    ]
+                  },
+                  {
+                    "id": "tile-4",
+                    "type": "Box",
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "children": [
+                      { "id": "t4", "type": "Text", "props": { "content": "Text", "fontSize": 54, "position": "center", "animation": "fade" } }
+                    ]
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            "id": "footer",
+            "type": "Text",
+            "props": {
+              "content": "This entire layout is built from primitives only.",
+              "fontSize": 34,
+              "position": "bottom",
+              "animation": "fade",
+              "color": "#C7D2FE"
+            }
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Segment overlap math (how Example 2 works)
+
+When authoring segments with overlaps, the total end time is:
+
+`sum(segments[i].durationInFrames) - sum(segments[i].transitionToNext.durationInFrames)`
+
+Example 2 has 4 segments:
+
+- segment durations: 90 + 90 + 90 + 90 = 360
+- overlap durations: 15 + 15 + 15 = 45
+- video duration: 360 - 45 = 315 (must match `video.durationInFrames`)
+
+### Example 2: segment transitions showcase
+
+File: `examples/transitions-showcase.v2.json`
+
+This example shows how to chain segments with overlaps using `transitionToNext`.
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 315 },
+  "segments": [
+    {
+      "id": "s1",
+      "durationInFrames": 90,
+      "transitionToNext": { "type": "FadeTransition", "durationInFrames": 15 },
+      "root": {
+        "id": "scene-1",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#000000" } },
+        "children": [
+          { "id": "title-1", "type": "SplitText", "props": { "content": "FadeTransition", "fontSize": 100, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "center" } },
+          { "id": "wm-1", "type": "Watermark", "props": { "type": "text", "text": "waves", "position": "bottomRight", "opacity": 0.35, "size": 60 } }
+        ]
+      }
+    },
+    {
+      "id": "s2",
+      "durationInFrames": 90,
+      "transitionToNext": { "type": "SlideTransition", "durationInFrames": 15, "props": { "direction": "left", "distance": 120 } },
+      "root": {
+        "id": "scene-2",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "children": [
+          { "id": "title-2", "type": "SplitText", "props": { "content": "SlideTransition", "fontSize": 96, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "center" } },
+          { "id": "subtitle-2", "type": "TypewriterText", "props": { "content": "direction=left, distance=120", "fontSize": 44, "position": "bottom", "speed": 1.6, "showCursor": true } }
+        ]
+      }
+    },
+    {
+      "id": "s3",
+      "durationInFrames": 90,
+      "transitionToNext": { "type": "WipeTransition", "durationInFrames": 15, "props": { "direction": "diagonal", "softEdge": true } },
+      "root": {
+        "id": "scene-3",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#111827" } },
+        "children": [
+          { "id": "title-3", "type": "SplitText", "props": { "content": "WipeTransition", "fontSize": 96, "splitBy": "word", "stagger": 3, "animation": "scale", "position": "center" } },
+          { "id": "subtitle-3", "type": "TypewriterText", "props": { "content": "direction=diagonal, softEdge=true", "fontSize": 44, "position": "bottom", "speed": 1.6, "showCursor": false } }
+        ]
+      }
+    },
+    {
+      "id": "s4",
+      "durationInFrames": 90,
+      "root": {
+        "id": "scene-4",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#000000" } },
+        "children": [
+          { "id": "title-4", "type": "SplitText", "props": { "content": "Done", "fontSize": 120, "splitBy": "letter", "stagger": 2, "animation": "rotate", "position": "center" } },
+          { "id": "wm-4", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": 0.4, "size": 60 } }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Example 3: data dashboard
+
+File: `examples/data-dashboard.v2.json`
+
+This example uses data composites inside a `Grid`:
+
+- `ProgressRing`
+- `BarChart`
+- `LineGraph`
+- `ProgressBar`
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 180 },
+  "segments": [
+    {
+      "id": "dashboard",
+      "durationInFrames": 180,
+      "root": {
+        "id": "scene",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "children": [
+          {
+            "id": "grid",
+            "type": "Grid",
+            "props": { "columns": 2, "rows": 2, "gap": 36, "padding": 90, "align": "stretch", "justify": "stretch" },
+            "children": [
+              { "id": "ring", "type": "ProgressRing", "props": { "percentage": 72, "size": 260, "color": "#22C55E", "showLabel": true } },
+              {
+                "id": "bars",
+                "type": "BarChart",
+                "props": {
+                  "orientation": "vertical",
+                  "showValues": true,
+                  "showGrid": true,
+                  "data": [
+                    { "label": "A", "value": 32, "color": "#3B82F6" },
+                    { "label": "B", "value": 56, "color": "#22C55E" },
+                    { "label": "C", "value": 18, "color": "#F59E0B" },
+                    { "label": "D", "value": 44, "color": "#EF4444" }
+                  ]
+                }
+              },
+              {
+                "id": "line",
+                "type": "LineGraph",
+                "props": {
+                  "color": "#60A5FA",
+                  "strokeWidth": 4,
+                  "showDots": true,
+                  "fillArea": true,
+                  "animate": "draw",
+                  "data": [
+                    { "x": 0, "y": 10 },
+                    { "x": 1, "y": 16 },
+                    { "x": 2, "y": 12 },
+                    { "x": 3, "y": 22 },
+                    { "x": 4, "y": 18 },
+                    { "x": 5, "y": 28 }
+                  ]
+                }
+              },
+              { "id": "progress", "type": "ProgressBar", "props": { "label": "Rendering", "position": "bottom", "height": 16, "color": "#A855F7", "showPercentage": true } }
+            ]
+          },
+          { "id": "title", "type": "SplitText", "props": { "content": "Data composites", "fontSize": 86, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "top" } }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Example 4: vertical social-style video (9:16)
+
+File: `examples/social-vertical.v2.json`
+
+This example uses:
+
+- `InstagramStory` (story UI)
+- `TikTokCaption` (caption UI)
+- a `CircularReveal` segment overlap transition
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1080, "height": 1920, "fps": 30, "durationInFrames": 225 },
+  "segments": [
+    {
+      "id": "ig",
+      "durationInFrames": 120,
+      "transitionToNext": { "type": "CircularReveal", "durationInFrames": 15, "props": { "direction": "open", "center": { "x": 0.5, "y": 0.45 } } },
+      "root": {
+        "id": "ig-root",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#000000" } },
+        "children": [
+          { "id": "ig", "type": "InstagramStory", "props": { "backgroundColor": "#0B1220", "username": "depths.ai", "text": "Waves v0.3.0 ships seamless alignment + overlays", "sticker": "poll" } }
+        ]
+      }
+    },
+    {
+      "id": "tt",
+      "durationInFrames": 120,
+      "root": {
+        "id": "tt-root",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "children": [
+          { "id": "caption", "type": "TikTokCaption", "props": { "text": "Composites make LLM video authoring dramatically easier", "position": "bottom", "highlightStyle": "bounce", "fontSize": 58, "strokeWidth": 4 } },
+          { "id": "wm", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "topRight", "opacity": 0.35, "size": 72 } }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Example 5: intro -> stats -> outro (assets)
+
+File: `examples/intro-stats-outro.v2.json`
+
+This example uses branding + layout + data composites:
+
+- `IntroScene` (requires `logoSrc` and `companyName`)
+- `ThirdLowerBanner`, `AnimatedCounter`, `BarChart`
+- `OutroScene` (requires `logoSrc`)
+
+It references `/assets/logo.svg` style paths; supply those files and pass `--publicDir`.
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 360 },
+  "segments": [
+    {
+      "id": "intro",
+      "durationInFrames": 120,
+      "transitionToNext": { "type": "FadeTransition", "durationInFrames": 15 },
+      "root": {
+        "id": "intro-scene",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#000000" } },
+        "children": [
+          { "id": "intro", "type": "IntroScene", "props": { "logoSrc": "/assets/logo.svg", "companyName": "Depths AI", "tagline": "Waves v0.3.0", "backgroundColor": "#000000", "primaryColor": "#FFFFFF" } }
+        ]
+      }
+    },
+    {
+      "id": "stats",
+      "durationInFrames": 150,
+      "transitionToNext": { "type": "SlideTransition", "durationInFrames": 15, "props": { "direction": "up", "distance": 140 } },
+      "root": {
+        "id": "stats-scene",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#0B1220" } },
+        "children": [
+          { "id": "lower-third", "type": "ThirdLowerBanner", "props": { "name": "Waves", "title": "Composite components", "accentColor": "#22C55E" } },
+          { "id": "counter", "type": "AnimatedCounter", "props": { "from": 0, "to": 44, "suffix": " types", "fontSize": 110, "color": "#FFFFFF", "animationType": "spring" } },
+          { "id": "bars", "type": "BarChart", "props": { "orientation": "horizontal", "showValues": true, "showGrid": false, "data": [ { "label": "Primitives", "value": 10, "color": "#3B82F6" }, { "label": "Composites", "value": 34, "color": "#22C55E" } ] } }
+        ]
+      }
+    },
+    {
+      "id": "outro",
+      "durationInFrames": 120,
+      "root": {
+        "id": "outro-scene",
+        "type": "Scene",
+        "props": { "background": { "type": "color", "value": "#000000" } },
+        "children": [
+          {
+            "id": "outro",
+            "type": "OutroScene",
+            "props": {
+              "logoSrc": "/assets/logo.svg",
+              "message": "Thanks for watching",
+              "backgroundColor": "#000000",
+              "ctaButtons": [
+                { "text": "Star", "icon": "*" },
+                { "text": "Follow", "icon": "->" }
+              ],
+              "socialHandles": [
+                { "platform": "twitter", "handle": "@depths_ai" },
+                { "platform": "youtube", "handle": "@depths-ai" }
+              ]
+            }
+          },
+          { "id": "wm", "type": "Watermark", "props": { "type": "text", "text": "@depths.ai", "position": "bottomRight", "opacity": 0.25, "size": 64 } }
+        ]
+      }
+    }
+  ]
+}
+```
+
+### Example 6: timeline mode (global audio)
+
+File: `examples/timeline-global-audio.v2.json`
+
+This example uses `timeline[]` to place a global `Audio` track as a root node spanning the entire video.
+
+This is a common reason to choose timeline mode over segments mode: you want "global layers" (audio, watermarks, overlays) that span multiple scenes without duplicating them in each segment.
+
+```json
+{
+  "version": "2.0",
+  "video": { "id": "main", "width": 1920, "height": 1080, "fps": 30, "durationInFrames": 150 },
+  "timeline": [
+    {
+      "id": "scene",
+      "type": "Scene",
+      "timing": { "from": 0, "durationInFrames": 150 },
+      "props": { "background": { "type": "color", "value": "#0B1220" } },
+      "children": [
+        { "id": "title", "type": "SplitText", "props": { "content": "Timeline mode", "fontSize": 96, "splitBy": "word", "stagger": 3, "animation": "slideUp", "position": "top" } },
+        { "id": "subtitle", "type": "TypewriterText", "props": { "content": "Audio spans the whole video", "fontSize": 44, "position": "bottom", "speed": 1.4, "showCursor": false } }
+      ]
+    },
+    {
+      "id": "music",
+      "type": "Audio",
+      "timing": { "from": 0, "durationInFrames": 150 },
+      "props": { "src": "/assets/music.wav", "volume": 0.6, "fadeIn": 12, "fadeOut": 12 }
+    }
+  ]
+}
+```
+
+## Library API (quickstart)
 
 ```ts
-import { globalRegistry, registerBuiltInComponents } from '@depths/waves';
+import { renderVideo } from '@depths/waves';
+
+await renderVideo(
+  {
+    version: '2.0',
+    video: { id: 'main', width: 1920, height: 1080, fps: 30, durationInFrames: 60 },
+    segments: [
+      {
+        id: 'scene-1',
+        durationInFrames: 60,
+        root: {
+          id: 'root',
+          type: 'Scene',
+          props: { background: { type: 'color', value: '#000000' } },
+          children: [{ id: 't1', type: 'Text', props: { content: 'Hello' } }]
+        }
+      }
+    ]
+  },
+  { outputPath: './output.mp4', publicDir: './public' }
+);
+```
+
+## Assets and paths (Windows/Linux)
+
+In IR JSON, asset paths must be either:
+
+- a full URL (`https://...`), or
+- a `/assets/...` path (leading slash) that is resolved relative to `--publicDir` / `publicDir`.
+
+On Windows:
+
+- Prefer forward slashes in IR (`/assets/foo.png`), not `C:\\...` paths.
+- If you pass Windows paths to the CLI (e.g. `--out`), quote them if they contain spaces.
+
+## Rendering prerequisites
+
+Waves uses `@remotion/renderer` (Remotion 4.x). Remotion runs headless Chromium; if a compatible browser isn't available, it may download one automatically (or you can configure browser paths via Remotion). Remotion 4 also ships its own ffmpeg binary, so you typically do not need `ffmpeg` installed on your PATH.
+
+## Local CLI testing (before publishing)
+
+From the `waves/` package directory:
+
+```bash
+npm install
+npm run build
+node dist/cli.js --help
+node dist/cli.js write-ir --template basic --pretty --out examples/basic.v2.json
+node dist/cli.js validate --in examples/basic.v2.json
+node dist/cli.js render --in examples/basic.v2.json --out examples/basic.v2.mp4 --codec h264 --crf 28 --concurrency 1
+```
+
+To test the installed experience:
 
-registerBuiltInComponents();
-const componentCatalog = globalRegistry.getJSONSchemaForLLM();
+```bash
+npm link
+waves --help
 ```
 
-This returns an object keyed by component type, including:
+## Contributing
 
-- A JSON Schema describing the component’s props
-- The component’s metadata (description, examples, etc.)
+This repository is intentionally "boring": most of the value lives in strict schemas, a strict registry, and a growing component catalog.
 
-### Typical prompt rules (recommended)
+### Dev setup
 
-When you prompt a model, include rules like:
+From `internal_tools/waves/`:
 
-- All timing is in frames (`fps` defaults to 30)
-- Total scene durations must equal `video.durationInFrames`
-- Scene start frames must be sequential with no gaps/overlaps
-- Asset paths are either full URLs or absolute paths like `/assets/foo.png`
+```bash
+npm install
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
 
-## Troubleshooting
+The build emits ESM into `dist/`. Most CLI tests execute the built CLI via `node dist/cli.js` (so you catch packaging issues).
+
+### Repository layout (where to look)
+
+- `src/cli.ts`: the CLI (`waves <command> ...`)
+- `src/llm/prompt.ts`: system prompt + prompt payload (schemas + catalog)
+- `src/ir/schema.ts`: IR v2.0 Zod schemas (authoring + full IR)
+- `src/ir/migrations.ts`: compiler (`compileToRenderGraph`) from authored IR -> render timeline
+- `src/core/registry.ts`: component registry + JSON Schema export for LLM use
+- `src/core/validator.ts`: schema + semantics + registry validation
+- `src/core/engine.ts`: "engine" that validates, compiles, bundles, renders
+- `src/remotion/WavesComposition.tsx`: Remotion root composition that renders the compiled IR
+- `src/components/primitives/*`: low-level building blocks (`Scene`, `Text`, `Box`, etc.)
+- `src/components/composites/*`: higher-level components built from primitives
+- `src/components/registry.ts`: built-in registration of all primitives + composites
+- `scripts/generate-readme-components.mjs`: generates the component/props tables inside this README
+
+### Adding a new component (the shadcn-like flow)
+
+1) Implement a React component in `src/components/primitives/` or `src/components/composites/`.
+2) Define:
+   - a Zod props schema (export as `XPropsSchema`)
+   - a metadata object (`XComponentMetadata`) describing:
+     - `kind`: `primitive` or `composite`
+     - `category`: one of the known categories (layout, media, text, transition, data, social, branding, etc.)
+     - `description`: one-line description
+     - `llmGuidance`: (optional) short "how to use" hint for agents
+     - children contract: `acceptsChildren`, `minChildren`, `maxChildren`
+3) Register it in `src/components/registry.ts` via `globalRegistry.register({ type, component, propsSchema, metadata })`.
+4) Add tests:
+   - registry/schema tests: `tests/unit/components-registry.test.ts` (or adjacent unit tests)
+   - validator tests if the component introduces new timing or child-contract semantics
+5) Rebuild + re-generate README component docs:
 
-### Rendering fails with browser/Chromium errors
+```bash
+npm run build
+node scripts/generate-readme-components.mjs
+```
 
-Remotion renders using headless Chromium. Ensure a compatible Chromium is available to `@remotion/renderer`.
+6) Run the full gates:
 
-### Rendering fails with ffmpeg errors
+```bash
+npm test
+npm run typecheck
+npm run lint
+```
+
+### Updating the component docs block in README
+
+The "Components (primitives + composites)" section is generated from the registry so it never drifts.
+
+The generator updates only the block between:
 
-Install `ffmpeg` and ensure it is on the PATH.
+- `<!-- BEGIN GENERATED: COMPONENTS -->`
+- `<!-- END GENERATED: COMPONENTS -->`
 
-### Unknown component type
+Regenerate after any component/props changes:
+
+```bash
+npm run build
+node scripts/generate-readme-components.mjs
+```
 
-If the engine throws “Unknown component type”:
+### Adding or changing CLI commands
 
-- Ensure you called `registerBuiltInComponents()`
-- If it’s a custom component, ensure it is registered into `globalRegistry`
+The CLI is implemented as a small argument parser in `src/cli.ts` (no heavy CLI framework) to keep packaging deterministic.
 
-### Props validation errors
+When adding commands:
 
-Props are validated using the registered Zod schema. Defaults are applied by Zod on parse.
+1) update `formatHelp()`
+2) update `main()` command handler
+3) add CLI unit tests under `tests/unit/cli-*.test.ts`
+4) ensure the command works from the built output (`node dist/cli.js ...`)
 
-## License notes
+### Notes on renders in CI/tests
 
-- This package is MIT licensed (see `LICENSE`).
-- Remotion has separate licensing terms; ensure you comply with Remotion’s license for your use case.
+The integration test `tests/integration/render.test.ts` is "best-effort": it tries to render a tiny video and writes to a temp folder.
+If Remotion rendering fails due to missing browser binaries or other environment limitations, fix the environment rather than weakening the test.