@scenerok/cli 2.2.0 → 2.4.0

package/skills/{remote → scenerok/references}/intent-router.md

@@ -1,8 +1,6 @@
 # SceneRok Intent Router
 
-Load after **`vidscript-strict.md`** and **`environments.md`** when the user wants a video.
-
-**Remote base:** `https://scenerok.com/.well-known/agent-skills/`
+Pick the workflow for a video request, then read only the references it lists.
 
 ## Step 0 — Detect environment
 
@@ -23,6 +21,7 @@ Defaults unless the user says otherwise:
 | Product URL + CTA + lifestyle b-roll | Product promo |
 | Tweet / Reddit / Spotify / follow card | Social proof card |
 | Multiple clips + cross-fades / whips | Scene montage |
+| User's own footage to cut, trim, speed up, layer, mask, grade, or mix | Edit existing footage |
 | Voiceover explainer | Narrated explainer |
 | PR / code walk / terminal | Code demo |
 
@@ -33,6 +32,7 @@ Defaults unless the user says otherwise:
 | **Product promo** | `ai-models.md`, `text-styles.md`, `music.md`, `workflow.md`, `brand-setup.md` (+ `sdk-guide.md` if TS) | `xai.imagine` / `await xai.genVideo(...)`, `motion.popIn` / `fadeIn`, `eleven.music` |
 | **Motion graphic** | `animations-picker.md` (+ `animations-catalog.md` if needed) | `animations.*` (VidScript HyperFrames; prefer VidScript for catalog blocks) |
 | **Social proof card** | `animations-picker.md` | `animations.x_post`, `reddit_post`, … (VidScript) |
+| **Edit existing footage** | `editing-actions.md` (+ `media-stdlib.md` to probe the clips, `transitions-catalog.md` for cuts) | `Trim` / `Speed` / `Loop` / `Crop` / `Mask` / `Overlay` / `Composite`, `blend:`, `duck_under:`, `filter "lut"` (VidScript only) |
 | **Scene montage** | `transitions-catalog.md`, `ai-models.md` (+ `sdk-guide.md` if TS loops) | `tr.dissolve` · SDK: `import tr from '@scenerok/transitions'` + `t[start][end] = tr.dissolve()` |
 | **Narrated explainer** | `tts.md`, `text-styles.md`, `music.md`, `workflow.md` (+ `sdk-guide.md` if TS) | `xai.tts` · `await xai.tts(...)` + `t.push(vo)` |
 | **Code demo / PR** | `animations-picker.md` (code rows) | `code_typing`, `code_diff` (VidScript) |
@@ -44,7 +44,7 @@ Defaults unless the user says otherwise:
 ## Staged routing
 
 1. **Classify** — workflow from table above
-2. **Choose authoring** — short/human → VidScript; complex/agent (loops, computed timing, multi-clip arithmetic) → `@scenerok/sdk` (`sdk-guide.md`)
+2. **Choose authoring** — VidScript by default and for every editing action (masks, blends, crops, ducking, LUTs, timecode); `@scenerok/sdk` (`sdk-guide.md`) only for loops or computed timing (it has none of the editing actions)
 3. **Load catalogs** — only what that workflow needs (conditional loading)
 4. **Name block or API** — VidScript: pick `animations.<fn>` from `animations-picker.md`. SDK: factories (`video` / `loadVideo`, `text`, `fadeIn`) + AI imports (`@scenerok/xai`, …)
 5. **Brand** — if promo and missing colors/logo, one message per `brand-setup.md`
@@ -57,21 +57,11 @@ Defaults unless the user says otherwise:
 
 - `animations.<fn>(...)` over hand-authored HTML when a block fits
 - Text/headline treatments: try `animations.text_*` (text-anim family) before `motion.*` primitives or custom HTML
-- `tr.<fn>()` for scene transitions; `filter "…"` for single-clip VFX
+- `tr.<fn>()` for scene transitions; `filter "…"` for grades and VFX
 - No matching block → `text` + `animate: motion.<primitive>`, or `animations.custom_html(...)` to author your own HTML/CSS + GSAP / Three.js / any seekable JS animation lib (full author contract + minimal template in `animations-catalog.md` → "Custom HTML")
 - Unverified blocks (`verified: no`) ship demo content — prefer verified families
 - Complex procedural timelines → TypeScript `@scenerok/sdk` (`sdk-guide.md`) instead of exploding VidScript
 
-## Conditional loading
-
-- Skip `animations-catalog.md` unless you need full param tables
-- Skip `transitions-catalog.md` unless multiple clips or explicit transition ask
-- Always `vidscript-strict.md` before VidScript composition
-- Load `sdk-guide.md` before TypeScript SDK composition (scheduling, `t.grid`, AI plugin imports, `async main`)
-- Load `media-stdlib.md` when probing durations, grabbing frames, `loadVideo`, or layout-fitting assets
-- Load `ai-models.md` / `tts.md` / `music.md` for generative media in **either** language (examples cover both)
-- `vidscript-guide.md` only for grammar questions
-
 ## Reference
 
 - Grammar: `vidscript-guide.md` or https://scenerok.com/.well-known/agent-skills/vidscript-guide.md

package/skills/{remote → scenerok/references}/media-stdlib.md

@@ -35,10 +35,10 @@ 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)
+let thumb = media.grabFrame(hero, d / 2)   # data URL of the middle frame, to look at
 
 [0s .. d] = video hero
-[0s .. 2s] = video thumb, width: 400
+[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.
@@ -63,4 +63,3 @@ let thumb = media.grabFrame(hero, d / 2)
 | `fitContain` / `fitCover` | yes | `media.fitContain` | `{ width, height, x, y }` |
 | `parseTime` / `timecode` / `beats` / `clampTime` | yes | yes | time helpers |
 
-Implementation: `src/lib/media/stdlib/`. VidScript plugin: `src/plugins/media/`.

package/skills/{remote → scenerok/references}/music.md

@@ -2,34 +2,15 @@
 
 `import eleven from "@elevenlabs/music"`
 
-### VidScript
-
 ```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
 ```
 
-### TypeScript SDK
-
-```ts
-import { timeline } from '@scenerok/sdk'
-import eleven from '@elevenlabs/music'
-
-export default async function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-  const bed = await eleven.music('Warm premium launch bed', {
-    duration: 15,
-    force_instrumental: true,
-  })
-  t.push(bed.with({ volume: 0.35, fadeOut: 2 }))
-  return t.toIR()
-}
-```
-
-Use a binding (`let bed` / `const bed`) when you need volume or fades. Do not call `eleven.tts` — use `xai.tts` for voiceover.
+Use `let bed = eleven.music(...)` then `audio bed, volume: ...` for fades. Do not call `eleven.tts`.
 
-## Examples (VidScript)
+## Examples
 
 **Drone underscore**
 

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

@@ -0,0 +1,301 @@
+# @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`, and the SDK follows VidScript's rules: a value placed with the same properties lowers to the same IR. 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`) |
+| Mostly an edit, with one data-driven part | VidScript that imports a `.ts` module ([below](#use-typescript-from-vidscript)) |
+
+## 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, duration?)` | Auto-append at the playhead |
+
+Times are numbers (seconds), `s(3)` / `ms(300)`, `t.frames(48)`, or strings: `'3s'`, `'300ms'`, `'1:30'`, `'48f'` (frames of the timeline's fps), `'01:00:00:00'` (timecode at the timeline's fps, or `'01:00:00:00@24'`). Full JS arithmetic works. Like VidScript, every window snaps to the timeline's frame grid; `fps: 23.976` and the other NTSC rates are exact (`ir.timeBase`).
+
+A video or audio value whose length is known ends when it stops playing, even inside a longer window. Without a known length it fills the window.
+
+Use `loadVideo(path)` / `loadAudio(path)` to probe the length through the media stdlib, or pass `duration` when you know it:
+
+```ts
+const clip = await loadVideo('./hero.mp4')
+t[0][clip.duration] = clip
+t.push(video('./b.mp4', { duration: 4 }))
+```
+
+## Values
+
+| Factory | VidScript | Notes |
+|---------|-----------|-------|
+| `video(src, opts)` / `loadVideo` | `input a = "a.mp4"` | `rate:` interprets the footage at a frame rate |
+| `imageSequence('shot.%04d.png', { count, rate?, first? })` | `input frames = "shot.%04d.png", count: …` | Plays `count / rate` seconds |
+| `image(src, opts)` | an image input | Fills its window; 3 s when pushed |
+| `text(content, opts)` | `text "…"` | `stagger: 'word' \| 'char'` for `typewriter()` |
+| `audio(src, opts)` / `loadAudio` | `audio x` | `trimStart`, `pan`, `duckUnder`, `loudness: 'ebu-r128'`, `animate: volumeRamp(…)` |
+| `solid(color, opts)` | `solid("#101820")` | Full frame unless sized; with `radius`/`corners` it is a shape matte |
+| `gap()` | `gap()` | `t.push(gap(), 2)` moves the playhead 2 s |
+| `marker(name, metadata?)` | `marker("act 2")` | `t[4][4] = marker('act 2')`; timeline data, never drawn |
+| `filter(name, params)` / `shader(glsl, params)` | `filter "glow"` | Grades the frame (inside a nested timeline: only that timeline) |
+
+Values are immutable. Methods return a copy, so one clip can be cut many ways:
+
+```ts
+const beach = video('./beach.mp4', { duration: 60 })
+t.push(beach.trim(10, 20).trim(2, 4))          // source 12–14 s: a second trim is relative to the first
+t.push(beach.trim(30, 36).speed(1.5).resize(960, 540))
+t.push(beach.trim(40, 44).crop(0, 0, 1280, 720).filter('sepia', { intensity: 0.6 }))
+```
+
+| Method | On | Meaning |
+|--------|----|---------|
+| `trim(start, end?)` | video, image, audio | Keep a source range |
+| `speed(x)` / `loop(n)` | video | Retiming; the value's `duration` follows |
+| `resize(w, h)` / `opacity(x)` | video, image, timeline | Drawn size, opacity |
+| `filter(name, params)` | video, image, timeline | Grade only this value (pointwise colour filters on clips) |
+| `crop(x, y, w, h)` | video, image, timeline | Source pixels from the top-left; a second crop is relative |
+| `mask(matte, { mode })` | video, image, timeline | `alpha` (default), `luma`, `inverted`; the matte is any picture |
+| `animate(…)` / `with({ … })` | all pictures | Add animations / merge options |
+
+## Placement properties
+
+Every picture takes the same options as a VidScript placement:
+
+| Option | Meaning |
+|--------|---------|
+| `x`, `y`, `width`, `height` | Top-left and drawn size in output pixels |
+| `area` | A grid area; explicit `x`/`y`/`width`/`height` win |
+| `opacity`, `rotation` | Constant opacity and rotation (degrees) over the window |
+| `radius`, `corners` | Rounded corners; four `[x, y]` corner pins (TL → TR → BR → BL) |
+| `blend` | `multiply`, `screen`, `overlay`, `difference`, `add`, `subtract`, `darken`, `lighten` over what is already placed in the window |
+| `motionBlur` | `true` or `{ shutter, samples }`: blurs the value's own `animate` motion |
+| `enabled` | `false` skips the placement |
+| `animate` | One animation or a list |
+
+```ts
+t[0][6] = video('./city.mp4')
+t[0][6] = video('./flare.mp4', { blend: 'screen', opacity: 0.7 })
+t[1][4] = image('./logo.png', { width: 240, height: 240, x: 60, y: 60, radius: 120 })
+t[0][6] = video('./portrait.mp4').mask(solid('#fff', { width: 800, height: 800, x: 560, y: 140, radius: 400 }))
+```
+
+A blend needs something below it in the window; nothing below is an error, as in VidScript.
+
+## Animations
+
+`fadeIn`, `fadeOut`, `slideY`, `slideX`, `scale`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter`, `rotate` — the same set and defaults as `@scenerok/basic-animations`. Any other type: `animation('kenBurns', { scale: 1 }, { scale: 1.1 }, 0)` (a duration of 0 spans the window). Gain automation on audio: `volumeRamp(0, 1, '2s')`.
+
+## Nested timelines and groups
+
+A timeline is a value. Placed bare, its items join the parent shifted to the window start — like VidScript `use`. A nested timeline without its own size takes its parent's canvas.
+
+```ts
+function card(title: string) {
+  const c = timeline({ name: 'card' })
+  c[0][3] = solid('#101820', { height: 200, y: 880, opacity: 0.85 })
+  c[0][3] = text(title, { size: 48, y: '88%' })
+  return c
+}
+
+t[2][5] = card('Konkan Day 1')                                   // flat
+t[6][9] = card('Day 2').opacity(0.8).place({ x: 40, y: -120 })      // one group
+t[9][12] = card('Day 3').filter('grayscale')                     // the grade covers only the card
+```
+
+`place(opts)`, `opacity`, `resize`, `filter`, `crop`, and `mask` draw the timeline as one `IRGroup`, as does a frame `filter` inside it. A group lasts for its window; a longer body is cut off. Transitions cannot be inside a group.
+
+## Grid areas
+
+Same CSS-grid regions as VidScript. Declare a grid on the timeline, then place with `area:` (text centres in the cell; videos, images, and solids fill it):
+
+```ts
+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)] = image('./shoe.png', { area: 'left' })
+```
+
+Without `t.grid(...)`, `area: 'title' | 'stage' | 'lower-third' | 'caption'` uses the built-in social-video preset (portrait vs landscape).
+
+## Transitions
+
+Same `@scenerok/transitions` package as VidScript. Schedule a transition window between abutting clips; `toIR()` binds `fromId` / `toId`:
+
+```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({ inOffset: 0.3, outOffset: 0.3 })
+  t[5.6][10] = video('./b.mp4', { duration: 4.4 })
+  return t.toIR()
+}
+```
+
+Common options: `direction`, `ease`, `strength`, `mode` (`roll` | `freeze`), and the handles `inOffset` / `outOffset` (source seconds read past each cut). Full catalog: `transitions-catalog.md`.
+
+## Output
+
+```ts
+timeline({
+  width: 1920, height: 1080, fps: 23.976,
+  output: { path: 'reel.mp4', startTimecode: '01:00:00:00', burnIn: 'timecode' },
+})
+```
+
+## Entry contract
+
+Export `default async function main()` (or sync `main`) that returns either `t.toIR()`, the timeline, or an `IRTimeline` object. `async main` lets you `await loadVideo(...)`, `await getVideoLength(...)`, or `await grabFrame(...)`.
+
+## Use TypeScript from VidScript
+
+A `.vid` can import a TypeScript module and place what it exports. Export values instead of (or beside) a default scene:
+
+```ts
+// kit.ts
+import { timeline, video, text, audio, solid } from '@scenerok/sdk'
+
+export const accent = '#ff5500'
+export const hero = video('beach.mp4', { duration: 12 }).trim(2, 8)
+export const title = text('Konkan Day 1', { size: 72, area: 'title' })
+export const bed = audio('bed.mp3', { duration: 30, volume: 0.4 })
+
+export function lowerThird(name: string, opts: { color?: string } = {}) {
+  const t = timeline()
+  t[0][3] = solid(opts.color ?? accent, { height: 160, y: 880 })
+  t[0][3] = text(name, { size: 48, y: '88%' })
+  return t
+}
+```
+
+```vidscript fragment
+import kit from "./kit.ts"
+
+[0s .. 6s] = kit.hero
+[1s .. 4s] = kit.title
+[0s .. 10s] = audio kit.bed
+[3s .. 6s] = kit.lowerThird("Nidheesh", color: kit.accent)
+
+output to "reel.mp4", resolution: "1920x1080"
+```
+
+- `timeline()` without a size takes the importing script's output size and fps.
+- Named arguments reach a function as one trailing options object; `use kit.lowerThird at 6s .. 9s with { color: "#0a8" }` calls `lowerThird({ color: "#0a8" })`.
+- A default-exported scene still works: `use kit at 0s .. 0s with {}`, and `kit.duration` is its length.
+- Filters, shaders, and transitions are not exportable values; use them inside an exported timeline.
+- The module is one file (the CLI uploads it next to the `.vid`); top-level `await` is not supported, but an exported promise is awaited.
+
+See `vidscript-guide.md` → Import TypeScript modules.
+
+## Validate / render
+
+```bash
+scenerok validate scene.ts
+scenerok render scene.ts --watch
+```
+
+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` values (a generated clip with sound brings its sound along; set its level with `volume`):
+
+```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.with({ volume: 0.3, duckUnder: vo }))
+  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.
+
+## VidScript only
+
+- `filter "lut", file: "look.cube"` and `captions("talk.srt")` read files at compile time.
+- Several `output` statements (two canvases) and `allow_offline: true`.
+- `--generate-assets` (SDK scripts generate assets during `scenerok render` when plugins are called).
+
+Import the TypeScript part into a `.vid` when a scene needs these.
+
+## 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/{remote → scenerok/references}/shaders-filters.md

@@ -2,7 +2,7 @@
 
 ## Built-in filters
 
-Apply on a time block with the clip active:
+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
@@ -23,11 +23,12 @@ Apply on a time block with the clip active:
 
 Use filters as optional finishing tools — do not add by default.
 
-## VFX filters (single-clip)
+## VFX filters
 
-Native VFX via `filter` keyword on one clip:
+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
 ```
@@ -52,7 +53,7 @@ import shader glow from "./shaders/glow.glsl"
 
 Also works with npm package paths under `node_modules`:
 
-```vidscript
+```vidscript fragment
 import shader glow from "shader-pack/shaders/glow.glsl"
 ```
 
@@ -84,14 +85,16 @@ The compiler reads the file at compile time and embeds the GLSL into IR (`IRShad
 
 ## Scene transitions
 
-Scene transitions use `@scenerok/transitions` — see `transitions-catalog.md`. They blend **two** clips at window boundaries; filters operate on **one** clip.
+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()` (two-texture blend) with `filter "vignette"` (single-clip post).
+Do not confuse `tr.dissolve()` (a blend between two clips) with `filter "vignette"` (a grade).

package/skills/{remote → scenerok/references}/text-styles.md

@@ -1,43 +1,23 @@
 # Text Styles and Motion Primitives
 
-`import motion from "@scenerok/basic-animations"` — use with `animate:` on VidScript `text` blocks.
-
-In **TypeScript SDK**, use the built-in motion helpers from `@scenerok/sdk` (`fadeIn`, `fadeOut`, `slideY`, `slideX`, `scale`, `popIn`) and place text with `area` / `t.grid` (see `sdk-guide.md`).
+`import motion from "@scenerok/basic-animations"` — use with `animate:` on `text` blocks.
 
 ## Motion primitives
 
-| Primitive | Suits | Phase | SDK helper |
-| --- | --- | --- | --- |
-| `motion.fadeIn` | subtle entrance | entry | `fadeIn(s(0.4))` |
-| `motion.fadeOut` | ending / cut-to-black | exit | `fadeOut(s(0.4))` |
-| `motion.slideX` | horizontal reveal | entry | `slideX(...)` |
-| `motion.slideY` | vertical rise / fall | entry | `slideY(...)` |
-| `motion.popIn` | impact / hero reveal | entry | `popIn(...)` |
-| `motion.riseIn` | title build-up | entry | — (VidScript) |
-| `motion.swingIn` | playful entrance | entry | — (VidScript) |
-| `motion.glitchIn` | energetic entrance | entry | — (VidScript) |
-| `motion.float` | idle ambient drift | idle | — (VidScript) |
-| `motion.typewriter` | technical typing reveal | entry | — (VidScript) |
-
-## Grid areas (both languages)
-
-Prefer named regions over hand-picked `x`/`y`:
-
-```vidscript
-[0 .. 3] = text "BIG SALE", area: "title", animate: motion.popIn(0.8)
-```
-
-```ts
-import { timeline, text, s, popIn } from '@scenerok/sdk'
-
-const t = timeline({ width: 1080, height: 1920, fps: 30 })
-t.grid({ rows: '16% 1fr 18% 10%', areas: ['title', 'stage', 'lower-third', 'caption'] })
-t[0][s(3)] = text('BIG SALE', { size: 72, area: 'title' }).animate(popIn(s(0.8)))
-```
-
-Built-in areas (no grid declaration): `title`, `stage`, `lower-third`, `caption`.
-
-## Examples (VidScript)
+| 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
 

package/skills/{remote → scenerok/references}/transitions-catalog.md

@@ -9,6 +9,8 @@ A transition window `[Ts .. Te]` binds the clip active at **Ts** (from) and **Te
 ```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

package/skills/{remote → scenerok/references}/tts.md

@@ -1,38 +1,20 @@
 # Text-to-Speech
 
-`import xai from "@scenerok/xai"` — voiceover via `xai.tts(...)`.
+`import xai from "@scenerok/xai"` — voiceover via `audio xai.tts(...)`.
 
 Voice IDs: `eve` (upbeat), `ara` (warm), `rex` (business), `sal` (balanced), `leo` (authoritative).
-Catalog samples may use `Marin`, `Hudson` — check `xai.listVoices()` for current IDs.
-
-### VidScript
-
 ```vidscript
 import xai from "@scenerok/xai"
 let vo = xai.tts("Welcome to SceneRok", voice: "eve")
 [0 .. vo.duration] = audio vo
 ```
 
-### TypeScript SDK
-
-```ts
-import { timeline, text, s } from '@scenerok/sdk'
-import xai from '@scenerok/xai'
-
-export default async function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
-  const vo = await xai.tts('Welcome to SceneRok', { voice: 'eve' })
-  t.push(vo)
-  t[0][vo.duration] = text('Welcome', { size: 64, area: 'title' })
-  return t.toIR()
-}
-```
-
-**Never guess a TTS window.** You cannot know the audio length while writing the script. VidScript: assign with `let` and use `vo.duration`, or `[-] = audio xai.tts(...)`. SDK: `await xai.tts(...)` then use `vo.duration` / `t.push(vo)`. Guessed ranges like `[0s .. 3s] = audio xai.tts("long sentence...")` clip or collide when the real audio runs longer.
+**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
@@ -40,7 +22,7 @@ let vo2 = xai.tts("Second line", voice: "eve")
 [0 .. vo1.duration] = text "First headline", area: "title"   # visual spans the narration
 ```
 
-## Examples (VidScript)
+## Examples
 
 Catalog samples below use fixed example windows; in real scripts prefer `vo.duration` or `[-]` blocks as shown above.