@scenerok/sdk 0.6.0 → 0.8.0

package/skills/scenerok/references/media-stdlib.md

@@ -0,0 +1,65 @@
+# Media standard library
+
+Shared Pass-1 host APIs for probing media and extracting frames. Available in **both** authoring languages.
+
+Prefer `loadVideo` / `loadAudio` from `@scenerok/sdk` when you only need duration for scheduling — they call the stdlib under the hood.
+
+## TypeScript (`@scenerok/stdlib` or `@scenerok/sdk`)
+
+```ts
+import { timeline, loadVideo, text, s } from '@scenerok/sdk'
+import { getVideoLength, grabFrame, getDimensions, getLoudness, beats } from '@scenerok/stdlib'
+
+export default async function main() {
+  const path = './hero.mp4'
+  const clip = await loadVideo(path) // fills duration via stdlib
+  const d = await getVideoLength(path)
+  const { width, height } = await getDimensions(path)
+  const loudness = await getLoudness(path)
+  const thumb = await grabFrame(path, d / 2, { width: 720 })
+
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  t[0][clip.duration] = clip
+  t[0][s(2)] = text(`${width}x${height}`, { size: 40, area: 'caption' })
+  t[0][beats(120, 4)] = text(`${loudness.integratedLufs} LUFS`, { size: 32, area: 'lower-third' })
+  // thumb is a data URL — schedule with video(thumb, { duration: 2 }) if needed
+  return t.toIR()
+}
+```
+
+## VidScript (`@scenerok/media`)
+
+```vidscript
+import media from "@scenerok/media"
+
+input hero = "./hero.mp4"
+let d = media.length(hero)
+let loudness = media.loudness(hero)
+let thumb = media.grabFrame(hero, d / 2)   # data URL of the middle frame, to look at
+
+[0s .. d] = video hero
+[d .. d + 2s] = hero.Trim(d / 2, d / 2 + 1s).Speed(0)   # hold the middle frame for 2 s
+```
+
+`media.length` returns a time value usable in arithmetic and `[start .. end]` ranges.
+`media.info(hero).duration` / `.width` work via property access on the data result.
+`media.loudness(hero).integratedLufs` returns measured loudness data from ffmpeg (`truePeakDb`, `loudnessRange`, and `duration` are also available).
+
+## API surface
+
+| Function | TS | VidScript | Returns |
+|----------|----|-----------|---------|
+| `getVideoLength` / `length` | yes | `media.length` | seconds |
+| `getAudioLength` | yes | `media.getAudioLength` | seconds |
+| `getMediaInfo` / `info` | yes | `media.info` | `{ duration, width, height, fps, hasAudio, kind, ... }` |
+| `getDimensions` / `dimensions` | yes | `media.dimensions` | `{ width, height }` |
+| `getFps` / `fps` | yes | `media.fps` | number \| null |
+| `hasAudio` | yes | `media.hasAudio` | boolean |
+| `getLoudness` / `loudness` | yes | `media.loudness` | `{ integratedLufs, truePeakDb, loudnessRange, duration }` |
+| `mediaKind` / `kind` | yes | `media.kind` | `video` \| `audio` \| `image` |
+| `grabFrame` | yes | `media.grabFrame` | data URL (or uploaded URL) |
+| `grabFrameAtFraction` | yes | `media.grabFrameAtFraction` | data URL |
+| `measureText` | yes | `media.measureText` | `{ width, height, lines }` |
+| `fitContain` / `fitCover` | yes | `media.fitContain` | `{ width, height, x, y }` |
+| `parseTime` / `timecode` / `beats` / `clampTime` | yes | yes | time helpers |
+

package/skills/scenerok/references/music.md

@@ -0,0 +1,50 @@
+# Generative Music
+
+`import eleven from "@elevenlabs/music"`
+
+```vidscript
+import eleven from "@elevenlabs/music"
+let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
+```
+
+Use `let bed = eleven.music(...)` then `audio bed, volume: ...` for fades. Do not call `eleven.tts`.
+
+## Examples
+
+**Drone underscore**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "drift", font: "Inter", size: 120, color: "#6B7280", align: "center", letter_spacing: 12
+[0s .. 3s] = audio eleven.music("dark ambient drone, minimal, cinematic tension, no percussion", duration: 3, force_instrumental: true)
+```
+
+**Padscape**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "ambient", font: "Inter", size: 140, color: "#9FB6FF", align: "center", letter_spacing: 8
+[0s .. 3s] = audio eleven.music("ambient cinematic padscape, slow evolving, contemplative", duration: 3, force_instrumental: true)
+```
+
+**4 s sting**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "▶", font: "Inter Black", size: 200, color: "#FFD23F", align: "center"
+[0s .. 3s] = audio eleven.music("short upbeat logo sting, claps, bright", duration: 3, force_instrumental: true)
+```
+
+**Bright brand cue**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "UPBEAT", font: "Inter Black", size: 180, color: "#FFFFFF", align: "center"
+[0s .. 3s] = audio eleven.music("uplifting corporate brand cue, claps, bright synth, optimistic", duration: 3, force_instrumental: true)
+```
+

package/skills/scenerok/references/sdk-guide.md

@@ -0,0 +1,201 @@
+# @scenerok/sdk — TypeScript authoring for complex scenes
+
+Use **TypeScript + `@scenerok/sdk`** when the scene needs loops, branches, arithmetic timing, or data-driven composition. Keep **VidScript** for short human-authored promos and templates.
+
+Both paths emit the same `IRTimeline`. Preview and render (Pass 2) are unchanged.
+
+## When to choose which
+
+| Signal | Language |
+|--------|----------|
+| Short promo, human edit, template placeholders | VidScript (`.vid`) |
+| Loop over clips, computed `start`/`end`, agent-authored complex timeline | TypeScript + `@scenerok/sdk` (`.ts`) |
+
+## Schedule syntax
+
+JavaScript has no `t[0, end]` dual key (comma operator collapses to one index). Use dual-index assignment:
+
+```ts
+import { timeline, loadVideo, text, audio, s, fadeIn } from '@scenerok/sdk'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  const scene1 = await loadVideo('./hero.mp4')
+
+  t[0][scene1.duration] = scene1.animate(fadeIn(s(0.4)))
+  t['0s']['3s'] = text('Hello', { size: 72 })
+  t[scene1.duration][scene1.duration + s(2)] = text('Next')
+  t.push(audio('./bed.mp3', { duration: 7, volume: 0.4 }))
+
+  return t.toIR()
+}
+```
+
+| Form | Meaning |
+|------|---------|
+| `t[start][end] = value` | Preferred dual-index schedule |
+| `t.range(start, end, value)` | Explicit call (no Proxy) |
+| `t['-'] = value` / `t.push(value)` | Auto-append at playhead |
+
+`start` / `end` accept numbers (seconds), `s(3)` / `ms(300)`, or strings (`'3s'`, `'1:30'`). Full JS arithmetic works.
+
+No `video` / `text` keywords after `=` — factories return typed values and the runtime infers IR kind.
+
+Use `loadVideo(path)` / `loadAudio(path)` to probe duration through the media stdlib when `duration` is omitted:
+
+```ts
+const clip = await loadVideo('./hero.mp4')
+t[0][clip.duration] = clip
+```
+
+Use the sync `video(path, { duration })` / `audio(path, { duration })` factories when you already know the timing.
+
+## Grid areas
+
+Same CSS-grid regions as VidScript. Declare a grid on the timeline, then place text with `area:`:
+
+```ts
+import { timeline, text, s } from '@scenerok/sdk'
+
+export default function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+
+  t.grid({
+    rows: '20% 1fr 30%',
+    cols: '1fr 1fr',
+    areas: ['title title', 'left right', 'caption caption'],
+  })
+
+  t[0][s(3)] = text('BIG SALE', { size: 72, area: 'title' })
+  t[0][s(3)] = text('Left column', { size: 40, area: 'left' })
+
+  return t.toIR()
+}
+```
+
+Without `t.grid(...)`, `area: 'title' | 'stage' | 'lower-third' | 'caption'` uses the built-in social-video preset (portrait vs landscape). Explicit `x` / `y` / `maxWidth` / `maxHeight` override the area.
+
+Helpers also available: `resolveGridAreas`, `defaultGridSpec`, `placeInArea`.
+
+Same semantics as VidScript `grid rows: ..., areas: [...]` — see `vidscript-guide.md` → Grid Areas.
+
+## Transitions
+
+Same `@scenerok/transitions` package as VidScript. Schedule a transition window between abutting clips; `toIR()` binds `fromId` / `toId` automatically:
+
+```ts
+import { timeline, video } from '@scenerok/sdk'
+import tr from '@scenerok/transitions'
+
+export default function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+
+  t[0][5] = video('./a.mp4', { duration: 5 })
+  t[5][5.6] = tr.dissolve()
+  t[5.6][10] = video('./b.mp4', { duration: 4.4 })
+
+  // Or auto-append with catalog default (0.6s):
+  // t.push(tr.push({ direction: 'right' }))
+
+  return t.toIR()
+}
+```
+
+Common options: `direction`, `ease`, `strength`, `mode` (`roll` | `freeze`). Full catalog: `transitions-catalog.md`.
+
+## Entry contract
+
+Export `default async function main()` (or sync `main`) that returns either:
+
+- `t.toIR()`, or
+- an `IRTimeline` object
+
+`async main` is supported so you can `await loadVideo(...)`, `await getVideoLength(...)`, or `await grabFrame(...)`.
+
+## Validate / render
+
+```bash
+scenerok validate scene.ts
+scenerok render scene.ts --watch
+```
+
+You can also **include** an SDK scene from VidScript:
+
+```vidscript fragment
+import intro from "./intro.ts"
+use intro at 0s .. 0s with {}
+output to "reel.mp4"
+```
+
+See `vidscript-guide.md` → Include TypeScript / JavaScript scenes.
+
+MCP:
+
+- `scenerok_validate_vidscript` with `language: "typescript"`
+- `scenerok_render_video` with `language: "typescript"`
+- `scenerok_get_sdk_guide` for this document
+
+## AI plugins (xAI / Cloudflare / ElevenLabs)
+
+Same packages as VidScript. Import them in TypeScript; the SceneRok compile host runs the real plugins and returns SDK `video` / `audio` nodes:
+
+```ts
+import { timeline } from '@scenerok/sdk'
+import xai from '@scenerok/xai'
+import cf from '@scenerok/cloudflare'
+import eleven from '@elevenlabs/music'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  const clip = await xai.genVideo('Cinematic drone over mountains', {
+    duration: 5,
+    aspect_ratio: '9:16',
+    resolution: '720p',
+  })
+  const still = await cf.image('Product on seamless backdrop', { aspect_ratio: '9:16' })
+  const vo = await xai.tts('Welcome to SceneRok', { voice: 'eve' })
+  const bed = await eleven.music('Warm lo-fi bed', { duration: 12 })
+
+  t[0][clip.duration] = clip
+  t[clip.duration][clip.duration + still.duration] = still
+  t.push(vo)
+  t.push(bed)
+  return t.toIR()
+}
+```
+
+| Package | Import | Key functions |
+|---------|--------|---------------|
+| `@scenerok/xai` | `import xai from '@scenerok/xai'` | `imagine`, `genVideo`, `image`, `imageToVideo`, `referenceToVideo`, `extendVideo`, `tts`, `listVoices` |
+| `@scenerok/cloudflare` | `import cf from '@scenerok/cloudflare'` | `video` / `imagine`, `image`, `imageToVideo`, `extendVideo`, `listModels` |
+| `@elevenlabs/music` | `import eleven from '@elevenlabs/music'` | `music`, `generateMusic`, `composeMusic` |
+
+Requires the same env secrets as VidScript (`XAI_API_KEY`, `ELEVENLABS_API_KEY`, Cloudflare AI Gateway credentials). Generation is billed on render the same way as VidScript plugins.
+
+## MVP limits
+
+- Prefer `getVideoLength(path)` from `@scenerok/stdlib` instead of hard-coding `duration:` when assets exist on disk
+- `--generate-assets` remains VidScript-only (SDK scripts generate assets during `scenerok render` when plugins are called)
+
+## Media stdlib
+
+```ts
+import { loadVideo, getVideoLength, grabFrame, beats } from '@scenerok/sdk'
+
+export default async function main() {
+  const clip = await loadVideo('./hero.mp4')
+  const d = await getVideoLength('./hero.mp4')
+  const thumb = await grabFrame('./hero.mp4', d / 2)
+  // ...
+}
+```
+
+Same functions are available in VidScript via `import media from "@scenerok/media"`.
+
+See `media-stdlib.md` and `ai-models.md` / `tts.md` / `music.md` for prompt guidance.
+
+## Related
+
+- VidScript grammar: `vidscript-guide.md`
+- Intent routing: `intent-router.md`
+- Package README: `packages/scenerok-sdk/README.md`

package/skills/scenerok/references/shaders-filters.md

@@ -0,0 +1,100 @@
+# Shaders and Filters
+
+## Built-in filters
+
+A `filter` line grades everything on screen during its window. Add `target: clip` (or use `clip.Filter(…)`) to grade one clip; see `editing-actions.md` → Color and finishing for which filters can target a clip, plus LUTs and CDL.
+
+```vidscript
+[0s .. 5s] = filter "vignette", intensity: 0.4
+[2s .. 4s] = filter "sepia", intensity: 0.6
+```
+
+| Filter | Typical use |
+| --- | --- |
+| `monochrome` | Desaturated / B&W look |
+| `sepia` | Warm vintage tone |
+| `blur` | Soft focus / depth |
+| `chromatic` | Lens aberration / glitch accent |
+| `glitch` | Digital distortion |
+| `vignette` | Edge darkening — finishing pass |
+| `contrast` | Punch up midtones |
+| `saturation` | Color intensity |
+| `brightness` | Exposure lift/drop |
+
+Use filters as optional finishing tools — do not add by default.
+
+## VFX filters
+
+Native VFX through the same `filter` keyword. They work on the whole frame in their window:
+
+```vidscript
+input clip = "clip.mp4"
+[0s .. 5s] = video clip
+[0s .. 2s] = filter "liquid_glass", intensity: 0.6
+```
+
+| Filter | Reach for it when… |
+| --- | --- |
+| `liquid_glass` | iOS-style glass morphism over footage |
+| `magnetic` | UI magnet / snap aesthetic |
+| `portal` | Sci-fi portal / warp hole |
+| `text_cursor` | Typing / terminal cursor overlay |
+
+## Custom shaders
+
+Author fragment GLSL in a `.glsl` file and import it — same idea as `animations.custom_html(src:)` for HTML, but via the first-class shader import:
+
+```vidscript
+import shader glow from "./shaders/glow.glsl"
+
+[0s .. 5s] = text "Hello"
+[0s .. 5s] = shader glow, intensity: 0.8
+```
+
+Also works with npm package paths under `node_modules`:
+
+```vidscript fragment
+import shader glow from "shader-pack/shaders/glow.glsl"
+```
+
+| Use | Keyword |
+| --- | --- |
+| Built-in / VFX from the library | `filter "name", …` |
+| Your own `.glsl` file | `import shader` + `shader name, …` |
+
+**Fragment contract** (EffectComposer post-process):
+
+- Fragment only — the engine supplies a shared vertex shader with `vUv`
+- Declare `uniform sampler2D tDiffuse` and sample it
+- Write `gl_FragColor`
+- VidScript params become uniforms by **exact name** (`intensity: 0.8` → `uniform float intensity`)
+- Optional: declare `uniform float uTime` and/or `uniform vec2 uResolution` — the renderer injects and updates them automatically
+
+```glsl
+uniform sampler2D tDiffuse;
+uniform float intensity;
+varying vec2 vUv;
+
+void main() {
+  vec4 texel = texture2D(tDiffuse, vUv);
+  gl_FragColor = texel * (1.0 + intensity);
+}
+```
+
+The compiler reads the file at compile time and embeds the GLSL into IR (`IRShaderEffect`). Relative paths resolve against the `.vid` directory (`workingDirectory` / `assetBaseDir`).
+
+## Scene transitions
+
+Scene transitions use `@scenerok/transitions` — see `transitions-catalog.md`. They blend **two** clips at window boundaries; filters grade the picture.
+
+```vidscript
+import tr from "@scenerok/transitions"
+
+input clip_a = "clip-a.mp4"
+input clip_b = "clip-b.mp4"
+[0s .. 5s]   = video clip_a
+[5s .. 5.6s] = tr.dissolve()
+[5.6s .. 10s] = video clip_b
+```
+
+Do not confuse `tr.dissolve()` (a blend between two clips) with `filter "vignette"` (a grade).

package/skills/scenerok/references/text-styles.md

@@ -0,0 +1,88 @@
+# Text Styles and Motion Primitives
+
+`import motion from "@scenerok/basic-animations"` — use with `animate:` on `text` blocks.
+
+## Motion primitives
+
+| Primitive | Suits | Phase |
+| --- | --- | --- |
+| `motion.fadeIn` | subtle entrance | entry |
+| `motion.fadeOut` | ending / cut-to-black | exit |
+| `motion.slideX` | horizontal reveal | entry |
+| `motion.slideY` | vertical rise / fall | entry |
+| `motion.popIn` | impact / hero reveal | entry |
+| `motion.riseIn` | title build-up | entry |
+| `motion.swingIn` | playful entrance | entry |
+| `motion.glitchIn` | energetic entrance | entry |
+| `motion.float` | idle ambient drift | idle |
+| `motion.typewriter` | technical typing reveal | entry |
+
+## Examples
+
+### Bold hero headline
+
+Large sans-serif with shadow and fade entrance/exit.
+
+**Center pop** — popIn entrance on a dark canvas.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 3s] = text "SCENEROK", font: "Inter Black", size: 200, color: "#7CFAC7", align: "center", letter_spacing: 6, animate: [motion.popIn(0.8), motion.fadeOut(0.5)]
+```
+
+**Bottom-anchored** — position: "bottom", motion.fadeIn + fadeOut.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 3s] = text "Make videos from text.", font: "Inter Bold", size: 96, color: "#FFFFFF", position: "bottom", align: "center", shadow_color: "#000000", shadow_blur: 16, x: "50%", y: -180, animate: [motion.fadeIn(0.6), motion.fadeOut(0.6)]
+```
+
+### Motion presets
+
+Composable motion.fadeIn, popIn, and float descriptors.
+
+**Fade in + out** — motion.fadeIn(0.5) + motion.fadeOut(0.5).
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 3s] = text "FADE", font: "Inter Black", size: 220, color: "#FFFFFF", align: "center", animate: [motion.fadeIn(0.5), motion.fadeOut(0.5)]
+```
+
+**Pop + float** — popIn(0.7) then float(2.2, 12).
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 3s] = text "POP", font: "Inter Black", size: 220, color: "#FFD7A0", align: "center", animate: [motion.popIn(0.7), motion.float(2.2, 12)]
+```
+
+### Typewriter reveal
+
+motion.typewriter() reveals characters one at a time.
+
+**Slow sans** — Inter, white, longer typewriter duration.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 3s] = text "Type. Render. Ship.", font: "Inter", size: 72, color: "#FFFFFF", align: "center", animate: [motion.typewriter(1.8), motion.fadeOut(0.4)]
+```
+
+**Mono terminal** — JetBrains Mono, mint green on black.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 3s] = text "build videos from text.", font: "JetBrains Mono", size: 58, color: "#7CFAC7", align: "center", animate: [motion.typewriter(1.6), motion.fadeOut(0.3)]
+```
+
+Kinetic titles with no HyperFrames block → `text` + `animate: motion.<primitive>`.
+
+Richer pre-built text treatments (staggered word reveals, scramble decode, kinetic
+word-per-beat typography, gradient sweeps, typed quotes, count-up stats, glitch, neon) →
+`animations.text_*` blocks — see the `text-anim` rows in `animations-picker.md`.
+Fully custom text animation (your own HTML/CSS/GSAP) → `animations.custom_html` in
+`animations-catalog.md`.

package/skills/scenerok/references/transitions-catalog.md

@@ -0,0 +1,57 @@
+# Transitions Catalog
+
+All `tr.<fn>(...)` scene transitions from `@scenerok/transitions`. Total: **29** shaders.
+
+## Binding semantics
+
+A transition window `[Ts .. Te]` binds the clip active at **Ts** (from) and **Te** (to):
+
+```vidscript
+import tr from "@scenerok/transitions"
+
+input clip_a = "clip-a.mp4"
+input clip_b = "clip-b.mp4"
+[0s .. 5s]   = video clip_a
+[5s .. 5.6s] = tr.dissolve()
+[5.6s .. 10s] = video clip_b
+```
+
+Common params: `direction`, `ease`, `strength`, `mode`.
+
+| fn | shader | defaultDuration |
+| --- | --- | --- |
+| `dissolve` | `dissolve` | 0.6s |
+| `push` | `push` | 0.6s |
+| `cover` | `cover` | 0.6s |
+| `radial` | `radial` | 0.6s |
+| `grid` | `grid` | 0.6s |
+| `scale` | `scale` | 0.6s |
+| `cube` | `cube` | 0.6s |
+| `blur` | `blur` | 0.6s |
+| `distortion` | `distortion` | 0.6s |
+| `destruction` | `destruction` | 0.6s |
+| `light` | `light` | 0.6s |
+| `mechanical` | `mechanical` | 0.6s |
+| `wipe` | `wipe` | 0.6s |
+| `cinematic_zoom` | `cinematic_zoom` | 0.6s |
+| `whip_pan` | `whip_pan` | 0.6s |
+| `light_leak` | `light_leak` | 0.6s |
+| `flash` | `flash` | 0.6s |
+| `warp_morph` | `warp_morph` | 0.6s |
+| `domain_warp` | `domain_warp` | 0.6s |
+| `chromatic_split` | `chromatic_split` | 0.6s |
+| `lens` | `lens` | 0.6s |
+| `glitch` | `glitch` | 0.6s |
+| `swirl` | `swirl` | 0.6s |
+| `thermal` | `thermal` | 0.6s |
+| `ripple` | `ripple` | 0.6s |
+| `iris` | `iris` | 0.6s |
+| `burn` | `burn` | 0.6s |
+| `shatter` | `shatter` | 0.6s |
+| `liquid` | `liquid` | 0.6s |
+
+## VFX filters (single-clip)
+
+See `shaders-filters.md` for `filter "liquid_glass"`, `magnetic`, `portal`, `text_cursor`.
+
+Preview: https://scenerok.com/catalog#transitions

package/skills/scenerok/references/tts.md

@@ -0,0 +1,64 @@
+# Text-to-Speech
+
+`import xai from "@scenerok/xai"` — voiceover via `audio xai.tts(...)`.
+
+Voice IDs: `eve` (upbeat), `ara` (warm), `rex` (business), `sal` (balanced), `leo` (authoritative).
+```vidscript
+import xai from "@scenerok/xai"
+let vo = xai.tts("Welcome to SceneRok", voice: "eve")
+[0 .. vo.duration] = audio vo
+```
+
+**Never guess a TTS window.** You cannot know the audio length while writing the script. Either assign with `let` and use `vo.duration` in time expressions (measured from the generated file), or use `[-] = audio xai.tts(...)` blocks, which auto-size and never overlap each other. Guessed ranges like `[0s .. 3s] = audio xai.tts("long sentence...")` clip or collide when the real audio runs longer.
+
+Chain multiple lines with symbolic arithmetic:
+
+```vidscript
+import xai from "@scenerok/xai"
+let vo1 = xai.tts("First line", voice: "eve")
+let vo2 = xai.tts("Second line", voice: "eve")
+[0 .. vo1.duration] = audio vo1
+[vo1.duration + 0.3 .. vo1.duration + 0.3 + vo2.duration] = audio vo2
+[0 .. vo1.duration] = text "First headline", area: "title"   # visual spans the narration
+```
+
+## Examples
+
+Catalog samples below use fixed example windows; in real scripts prefer `vo.duration` or `[-]` blocks as shown above.
+
+**Leo — launch** — Product launch energy.
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[0s .. 3s] = text "GO.", font: "Inter Black", size: 240, color: "#FF3B3B", align: "center"
+[0s .. 3s] = audio xai.tts("Ship it. Right now.", voice: "leo")
+```
+
+**Rex — countdown** — Punchy three-beat hook.
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[0s .. 3s] = text "Drop it.", font: "Inter Black", size: 198, color: "#FFD23F", align: "center"
+[0s .. 3s] = audio xai.tts("Three. Two. One. Drop it.", voice: "rex")
+```
+
+**Ara — short line** — Single sentence under a headline.
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[0s .. 3s] = text "Listen.", font: "Inter", size: 120, color: "#9FB6FF", align: "center"
+[0s .. 3s] = audio xai.tts("One line of voice-over, baked into the mix.", voice: "ara")
+```
+
+**Eve — narrative** — Long-form explanatory copy.
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[0s .. 3s] = text "Voice from text.", font: "Inter Bold", size: 64, color: "#FFFFFF", align: "center"
+[0s .. 3s] = audio xai.tts("Vidscript turns plain text into a fully rendered video. No timeline editing required.", voice: "eve")
+```
+