@scenerok/cli 2.2.0 → 2.3.0

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/{remote → scenerok/references}/sdk-guide.md

@@ -121,7 +121,7 @@ scenerok render scene.ts --watch
 
 You can also **include** an SDK scene from VidScript:
 
-```vidscript
+```vidscript fragment
 import intro from "./intro.ts"
 use intro at 0s .. 0s with {}
 output to "reel.mp4"
@@ -192,7 +192,7 @@ export default async function main() {
 
 Same functions are available in VidScript via `import media from "@scenerok/media"`.
 
-See `skills/remote/media-stdlib.md` and `ai-models.md` / `tts.md` / `music.md` for prompt guidance.
+See `media-stdlib.md` and `ai-models.md` / `tts.md` / `music.md` for prompt guidance.
 
 ## Related
 

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.