@scenerok/cli 2.2.0 → 2.4.0

package/skills/{remote → scenerok/references}/vidscript-guide.md

@@ -2,12 +2,16 @@
 
 VidScript is a declarative DSL for composing short-form videos. Write a script, render an MP4.
 
+This is the grammar reference. For task-by-task editing (layering, masks, cuts, speed, sound mixing, grading, delivery), use `editing-actions.md`; for the rules agents most often break, `vidscript-strict.md`.
+
+Contents: Agent quick start · Program structure · Statements (input, output, let, import) · Time blocks · Including TypeScript scenes · Instructions (clips, text, grid areas, video methods, compositing, filters, motion blur, shaders, audio, plugin calls) · Reuse: functions and modules · Animations and effects · Expressions · Template placeholders · CLI commands · Best practices
+
 ## Agent quick start (read before composing)
 
 1. **Import every package function** — use `import xai from "@scenerok/xai"`, `import cf from "@scenerok/cloudflare"`, `import eleven from "@elevenlabs/music"`, and `import motion from "@scenerok/basic-animations"` before calling `xai.*`, `cf.*`, `eleven.*`, or `motion.*`.
 2. **Validate early** — `scenerok validate file.vid` (errors show as `Line N:C — message`).
 3. **Music package syntax** — `import eleven from "@elevenlabs/music"`, then call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`.
-4. **Copy working examples** — see `examples/system/` in this skill folder (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
+4. **Copy working examples** — `vidscript-sample.md`, and the `.vid` files in the `@scenerok/cli` package's `examples/system/` (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
 5. **Use URL assets selectively** — if the user gives a website or product URL and browser screenshot tools are available, you can capture above-fold screenshots, product images, app screenshots, and logos for VidScript `input` assets. Do not treat screenshots as mandatory or as the only visual source.
 6. **Probe asset type and dimensions** — before placing real assets, identify image vs video with `file`; inspect width, height, and duration with `ffprobe`, `sips`, or `identify`; then scale from the measured aspect ratio and set explicit `width`, `height`, `x`, and `y`.
 7. **Use still images directly** — `input` supports videos and images. Place still screenshots, logos, and product photos with `video image_input`; the renderer treats images as static clips for the block duration.
@@ -59,6 +63,15 @@ input logo = "./assets/logo.png"
 
 Supports HTTP(S) URLs, `/uploads/` paths, and local paths for video/image assets.
 
+A numbered image sequence is one input: the pattern names the frames, and `count:` says how many (a local compile can find it by probing). Optional `rate:` (frames per second, default the output fps) and `first:` (number of the first file, default 0):
+
+```vidscript
+input frames = "shots/shot.%04d.png", rate: 12, first: 1, count: 24
+[0s .. 2s] = frames
+```
+
+Place it by name like a video; `Trim`, `Speed`, and `Loop` work on it. `first:` and `count:` on a plain file are errors. `rate:` on a plain video file declares the footage's frame rate for a timeline at another rate (`input clip = "clip.mp4", rate: 23.976` in a 30 fps output; each output frame shows the source frame its time falls in). It is an error on audio or a still, never auto-applied from a probe, and a probed rate more than 0.1% off the declared one warns. On the render workers the pattern must be an `https` URL pattern (or a path on the worker).
+
 For ads based on a supplied URL, browser tools can capture real website visuals and save product images or logos when useful. Use screenshots sparingly: favor above-fold, cropped, or focused captures that remain legible at video size. Avoid full-page or long scrolling screenshots as backgrounds because their text will usually become unreadable.
 
 Website captures are optional grounding assets, not a ban on generated video. A strong ad may combine product/logo/app screenshots with generated lifestyle clips, motion backgrounds, transitions, and VidScript text primitives. Use generative clips when they improve storytelling, show context, or make the ad feel more polished.
@@ -75,6 +88,8 @@ identify asset.webp
 Use real videos as motion footage and still images as static clips. The `video` primitive accepts both; the renderer detects image vs video:
 
 ```vidscript
+import motion from "@scenerok/basic-animations"
+
 input screenshot = "assets/screenshots/homepage.png"
 [0s .. 4.5s] = video screenshot, width: 1080, height: 1920, x: 0, y: 0, animate: motion.fadeIn(0.35s)
 ```
@@ -99,14 +114,20 @@ output to "video.mp4", resolution: "1080x1920", fps: 30
 output to "reel.mp4", resolution: "720x1280", format: "mp4", codec: "h264", bitrate: "5M", background: "#0D0D0D"
 ```
 
+Several `output` statements make several canvases (`compileVidscript` returns one IR each in `irs`; `ir` is the first). Each output is the whole script lowered against its own `resolution`, `fps`, and `background`, so percent positions and `grid` areas resolve per canvas. Every output needs its own path (two with the same path is a compile error). Where it renders: the headless renderer (`renderVidscriptOutputsToMP4`, local scripts) writes one file per output. Where it errors: the render queue (the web app, the CLI, and the API) delivers one artifact per render, so a script with more than one `output` is rejected with `N outputs are rendered … only one output per render is supported by the render queue yet` before anything is billed. Use one `output` for a hosted render.
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `resolution` | string | `"1080x1920"` | Width×Height or single number |
 | `fps` | number | `30` | Frames per second |
-| `format` | string | `"mp4"` | Container format |
-| `codec` | string | `"h264"` | Video codec |
+| `format` | string | `"mp4"` | Container format. Every render is MP4 today |
+| `codec` | string | `"h264"` | Video codec. Every render is H.264 today |
 | `bitrate` | string | `"5M"` | Encoding bitrate |
 | `background` | string | `"#000000"` | Background color hex |
+| `start_timecode` | string | none | Timecode of the first frame, `"HH:MM:SS:FF"` (non-drop-frame; the frame field must be below `fps`). Written to the mp4's timecode track |
+| `burn_in` | string | none | `"timecode"` draws the running timecode (from `start_timecode`, else `00:00:00:00`) onto the picture |
+| `allow_offline` | boolean | `false` | `true` renders an input whose file is missing at compile time (media probing on) as a "MEDIA OFFLINE" slate: a flat `#2b2b2b` frame labelled with the input name, over the clip's block or `Trim` length. `Resize`, `x`/`y`, `opacity` and `animate:` still apply; its sound is dropped with a warning; a transition at its seam is an error. Without it a missing local file is a compile error. Media that goes missing only at render time still fails the render |
+| `alpha` | boolean | `false` | Needs `format: "mov", codec: "prores"` or `format: "webm", codec: "vp9"`. No render path delivers alpha yet (renders are H.264 mp4), so `alpha: true` is a compile error for now |
 
 ### Variable Assignment
 
@@ -139,9 +160,10 @@ Time blocks are the core of VidScript. They define when instructions execute on
 ### Dynamic Playhead (recommended)
 
 ```vidscript
+input hero = "hero.mp4"
 [-] = hero                            # auto-append: starts at visual cursor
-[- 3s] = text "Title", size: 72       # auto-start, last 3 seconds 
-[- 2.5s] = filter "glow", intensity: 0.8
+[- 3s] = text "Title", size: 72       # auto-start, last 3 seconds
+[- 2.5s] = filter "vignette", intensity: 0.4
 ```
 
 VidScript keeps separate auto-playhead cursors for visual and audio content. Visual blocks (`video`, `text`, filters, shaders, visual plugin calls, and bare visual inputs) advance the visual cursor. Audio blocks (`audio`, `xai.tts`, `eleven.music`, and other audio plugin calls) advance the audio cursor. `[- duration]` advances the relevant cursor by the explicit duration.
@@ -163,19 +185,20 @@ The generated video above starts at the current visual cursor, usually `0s`, eve
 ### Explicit Range
 
 ```vidscript
+input hero = "hero.mp4"
 [0s .. 5s] = hero                      # absolute range
 [0.5s .. 3s] = text "Hello"            # explicit times
-[prev + 1s .. prev + 4s] = filter "glow"  # expression-based
+[prev + 1s .. prev + 4s] = filter "vignette"  # expression-based
 ```
 
 Use `..` (not `-`) as the range separator to avoid ambiguity with subtraction.
 
 ### Time Formats
 
-```vidscript
+```text
 5s           # 5 seconds
 300ms        # 300 milliseconds
-frame 90     # 90 frames at 30fps = 3 seconds  
+90 frame     # 90 frames at the output fps (default 30): 3 seconds
 0:30         # 30 seconds
 1:30:00      # 1 hour 30 minutes
 ```
@@ -186,7 +209,7 @@ frame 90     # 90 frames at 30fps = 3 seconds
 
 ```vidscript
 [- 2s] = text "Hello"                              # plays from cursor to cursor+2s
-[prev + 1s .. prev + 3s] = filter "glow"           # 1s after text ends, for 2s
+[prev + 1s .. prev + 3s] = text "World"            # 1s after "Hello" ends, for 2s
 ```
 
 ### Symbolic Durations (`asset.duration`)
@@ -208,40 +231,74 @@ let vo2 = xai.tts("Let's dive in", voice: "eve")
 - Exported timelines expose `.duration` too: `use scene1 at 0s .. 0s with {}` then `[scene1.duration .. scene1.duration + 4] = ...`. A `use` also advances the playhead past its content, so a following `[-]` block never overlaps it.
 - This replaces guessing: `[0s .. 5s] = audio xai.tts(...)` clips or overlaps when the real audio is longer. For simple back-to-back narration, consecutive `[-] = audio ...` blocks also never overlap.
 
-## Include TypeScript / JavaScript scenes
+## Import TypeScript modules
 
-Import a `@scenerok/sdk` scene (`.ts` / `.js`) into VidScript with the same default-import form as plugins, then `use` it like a timeline:
+`import kit from "./kit.ts"` (or `.js`) runs the module with `@scenerok/sdk` and binds its exports as a namespace, like a `.vid` module. Each export is a VidScript value of the matching kind:
 
-```vidscript
-import intro from "./intro.ts"
-import bump from "./bump.js"
+| TypeScript export | In VidScript |
+| --- | --- |
+| `video(…)`, `loadVideo(…)`, `imageSequence(…)` | a video value: `[0s .. 5s] = kit.hero`, `kit.hero.Trim(1s, 3s)` |
+| `image(…)` | an image value |
+| `text(…)` | a text value |
+| `audio(…)`, `loadAudio(…)` | an audio value: `[0s .. 10s] = audio kit.bed` |
+| `solid(…)`, `gap()`, `marker(…)` | the builtin values `solid()`, `gap()`, `marker()` return |
+| `timeline()` | a timeline value: flat when placed bare, one group with properties or methods |
+| a number, string, array, or plain object | that data: `color: kit.accent` |
+| a function returning any of the above | a function: `kit.lowerThird("Konkan", color: "#f50")` |
+| `export default` scene (`main()` returning `t.toIR()`) | `use kit at 0s .. 0s with {}`; `kit.duration` is its length |
 
-use intro at 0s .. 0s with {}
-use bump at intro.duration .. intro.duration with {}
-[intro.duration + bump.duration .. intro.duration + bump.duration + 2s] = text "Thanks", area: "caption"
+```ts
+// kit.ts
+import { timeline, video, image, text, solid, fadeIn } from '@scenerok/sdk'
+
+export const accent = '#ff5500'
+export const hero = video('beach.mp4', { duration: 12 }).trim(2, 8)
+export const logo = image('logo.png', { width: 200, height: 200, x: 40, y: 40 })
+export const title = text('Konkan Day 1', { size: 72, area: 'title', animate: fadeIn(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
+}
+```
 
-output to "reel.mp4", resolution: "1080x1920"
+```vidscript fragment
+import kit from "./kit.ts"
+
+[0s .. 6s] = kit.hero
+[0s .. 6s] = kit.logo, opacity: 0.9
+[1s .. 4s] = kit.title
+[3s .. 6s] = kit.lowerThird("Nidheesh", color: kit.accent), blend: "screen"
+use kit.lowerThird at 6s .. 9s with { color: "#00aa88" }
+
+output to "reel.mp4", resolution: "1920x1080"
 ```
 
 Rules:
-- The SDK file must export `default function main()` (or `module.exports = main` / `exports.main`) that returns `t.toIR()` or an `IRTimeline`.
-- `with { ... }` params are not supported on SDK scenes (no timeline parameters).
-- Relative paths only (`./` / `../`). The CLI uploads companion scene files automatically when you `scenerok validate` / `scenerok render` a `.vid`.
-- Prefer this when a complex loop/branch scene should sit inside a mostly-VidScript reel. For a fully TypeScript project, author the entry as `.ts` instead.
+- A `timeline()` with no size takes this script's output size and fps, so it lays out on the same canvas.
+- Exported values keep their own properties; placement properties override them (`kit.logo, opacity: 0.9`).
+- Place an audio export as `audio kit.bed`. In a `[-]` block a bare `kit.bed` starts at the picture playhead, because the block's channel is decided before the module runs.
+- Function calls pass positional arguments in order and named arguments as one trailing options object: `kit.lowerThird("A", color: "#f50")` calls `lowerThird("A", { color: "#f50" })`; `use kit.f at … with { … }` calls `f({ … })`. Arguments are data (strings, numbers, booleans, lists, objects); VidScript clips and timelines cannot be passed into TypeScript.
+- An exported promise is awaited (`export const clip = loadVideo("hero.mp4")`). Top-level `await` is not supported.
+- Filters, shaders, and transitions are not exportable values; use them inside an exported timeline, or as VidScript statements.
+- Relative paths only (`./` / `../`). The module is one file: the CLI uploads it with the `.vid`, so it cannot import other local files.
 
 ## Instructions (inside time blocks)
 
-Multiple instructions in the same time block go on separate lines:
+Each line places one thing. Several lines can share a window:
 
 ```vidscript
-[0s .. 5s] = hero
-hero.Trim(start: 0s, end: 5s)
-hero.Speed(factor: 1.5)
+input hero = "hero.mp4"
+[0s .. 5s] = hero.Trim(0s, 7.5s).Speed(1.5)
+[0s .. 5s] = text "Hello", area: "title"
 ```
 
 ### Clip Reference
 
 ```vidscript
+input hero = "hero.mp4"
 [-] = hero              # just play the input clip
 ```
 
@@ -268,7 +325,7 @@ hero.Speed(factor: 1.5)
 | `align` | string | `left`, `center`, `right`. Default: `center` |
 | `line_height` | number | Line height multiplier for multi-line text. Default: 1.2 |
 | `letter_spacing` | number | Extra letter spacing in pixels. Default: 0 |
-| `rotation` | number | Rotation in degrees. Positive = clockwise. Default: 0 |
+| `rotation` | number | Rotation in degrees. Positive turns text clockwise (video turns the other way). Default: 0 |
 | `opacity` | number | Opacity 0–1. Default: 1 |
 | `stroke` | string | Outline color |
 | `stroke_width` | number | Outline thickness |
@@ -276,7 +333,8 @@ hero.Speed(factor: 1.5)
 | `shadow_blur` | number | Shadow blur radius |
 | `shadow_offset_x` | number | Shadow horizontal offset |
 | `shadow_offset_y` | number | Shadow vertical offset |
-| `animation` | string | Parsed but not yet rendered |
+| `anchor` | string | Point the text rotates and positions around, e.g. `"top-left"` |
+| `stagger` | string | `"word"` or `"char"`: reveal the text piece by piece over its `animate:` |
 
 Params are optional and comma-separated. Params can be on the same line as the content.
 
@@ -311,21 +369,58 @@ t[0][s(3)] = text('Left column', { area: 'left' })
 
 ### Video Methods
 
-```vidscript
-hero.Trim(start: 0s, end: 5s)         # trim clip (positional: hero.Trim(0s, 5s))
-hero.Resize(width: 720, height: 1280)  # resize (positional: hero.Resize(720, 1280))
-hero.Speed(factor: 1.5)                # playback rate
-hero.Loop(count: 3)                    # loop count
-hero.Opacity(value: 0.5, duration: 2s) # opacity with duration
-```
+Methods are operations on values. Capitalised names are methods; lowercase names are
+properties (`hero.duration`). A method returns **a new value** — chain them, or bind
+the result with `let`:
 
-Arguments can be positional or named using `:`.
+```vidscript
+input beach = "beach.mp4"
+let hero = beach.Trim(2s, 8s).Speed(1.5)
+[0s .. 4s] = hero, opacity: 0.9
+[4s .. 8s] = beach.Trim(0s, 2s).Loop(2).Resize(720, 1280)
+[8s .. 10s] = beach.Opacity(0.5).Filter("sepia", intensity: 0.8)
+[10s .. 12s] = beach.Crop(0, 0, 640, 360)
+let framed = beach.Mask(solid("#fff", radius: 120, width: 800, height: 500), mode: "luma")
+[12s .. 14s] = framed
+```
+
+| Method | Arguments | Result |
+|--------|-----------|--------|
+| `Trim(start, end)` | source times | Plays that source range |
+| `Speed(factor)` | number | Playback rate; negative reverses, `0` holds a frame |
+| `Loop(count)` | number | Repeats the range `count` times |
+| `Resize(width, height)` | pixels | Display size |
+| `Opacity(value)` | 0–1 | Opacity |
+| `Filter(name, …params)` | filter name | A grade on this value only |
+| `Crop(x, y, width, height)` | source pixels from the top-left | The rectangle, filling the display size |
+| `Mask(matte, mode?)` | any picture; `"alpha"`, `"luma"`, `"inverted"` | Drawn through the matte |
+| `Overlay(other, x?, y?, opacity?)` | a picture value | `other` on top at a position |
+| `Composite(other, mode?, x?, y?, opacity?)` | a picture value, a blend mode | `other` blended on top |
+
+Arguments can be positional or named (`hero.Trim(start: 0s, end: 5s)`).
+
+A second `Trim` is relative to the first: `a.Trim(10s, 20s).Trim(2s, 4s)` plays 12–14 s. A second `Crop` is relative to the first the same way.
+`Crop` keeps the display size, so the rectangle is scaled to fill it; `Resize` to the rectangle's aspect avoids stretching.
+The `Mask` matte is any picture value — a `solid` with `radius:` or `corners:` for a shape, `text(…)`, a function, or another clip (a track matte) — drawn in the same frame at the same local time.
+Place a masked value (`[0s .. 4s] = a.Mask(…)`); a `Mask` line after the clip is placed, an unknown mode, a masked clip as a
+`Composite` side, and a cropped clip inside a transition are compile errors.
+`audio x` places a sound — an audio file, or a video's own sound (`audio a.Trim(1s, 3s)`);
+`video` on an audio file is an error.
+
+A placed value lasts its own length (range ÷ |speed| × loops), so make its window that long.
+Each placement is its own value: `[0s .. 4s] = a.Trim(0s, 4s)` and `[4s .. 6s] = a.Trim(10s, 12s)` are two independent cuts.
+
+A method on its own line right after `[…] = hero` (the legacy spelling) still edits the clip that time block placed. Outside a time block it rebinds the name:
+`bg.Loop(count: 3)` makes `bg` the looped clip for later placements.
 
 ### Compositing
 
 ```vidscript
-hero.Overlay(logo, x: 50, y: 100, opacity: 0.8)
-hero.Composite(overlay, x: 0, y: 0, opacity: 0.5, mode: "screen")
+input hero = "hero.mp4"
+input logo = "logo.png"
+input texture = "light-leak.mp4"
+[0s .. 4s] = hero.Overlay(logo, x: 50, y: 100, opacity: 0.8)
+[4s .. 8s] = hero.Composite(texture, x: 0, y: 0, opacity: 0.5, mode: "screen")
 ```
 
 | Param | Type | Description |
@@ -333,16 +428,36 @@ hero.Composite(overlay, x: 0, y: 0, opacity: 0.5, mode: "screen")
 | `x` | number | Horizontal offset |
 | `y` | number | Vertical offset |
 | `opacity` | number | 0–1 transparency |
-| `mode` | string | Blend mode for Composite |
+| `mode` | string | Blend mode for Composite: `normal`, `multiply`, `screen`, `overlay`, `difference`, `add`, `subtract`, `darken`, `lighten` |
+
+The other side can be a clip name, or a value: a function's picture, a `solid(…)`, a
+`text(…)`, or a trimmed clip. A clip joins as a composite layer; anything else draws as a
+group blended with `mode` (`x`, `y`, and `opacity` place that group). A composite is itself
+a target, so layers stack: `let ab = a.Composite(b, mode: "screen")` then
+`[0s .. 4s] = ab.Composite(card("x"), mode: "multiply")`. Both sides must overlap in time.
 
 ### Filters
 
 ```vidscript
-[- 2s] = filter "glow", intensity: 0.8
+input hero = "hero.mp4"
+[0s .. 5s] = hero
+[0s .. 2s] = filter "chromatic", offset: 0.01
 [0s .. 5s] = filter "vignette", intensity: 0.3
+[0s .. 5s] = filter "contrast", amount: 1.2, target: hero
 ```
 
-Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignette`, `contrast`, `saturation`, `brightness`.
+Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignette`, `contrast`, `saturation`, `brightness`, plus `lut` and `cdl` (below and in `editing-actions.md`) and the VFX in `shaders-filters.md`. A `filter` line grades everything in its window; `target: clip` grades one clip.
+
+**LUT.** `filter "lut", file: "look.cube"` applies a 3D `.cube` look to the frame, to one clip with `target:`, or to a function body's picture. The compiler reads the file (relative to the `.vid`, 512 KB at most, up to 33 points per axis) and embeds the table, so render workers need nothing else. The lookup runs on sRGB-encoded values with 8-bit trilinear interpolation. `Filter("lut")` as a method is an error; use the statement.
+
+### Motion blur
+
+`motion_blur: true` or `motion_blur: { shutter: 180, samples: 8 }` on a video/image placement or a placed function averages `samples` sub-frames across the shutter angle (above 0, up to 360; samples 2 to 64) of that item's own `animate:` motion. Each sample is another render of the frame, so a frame with a blurred item costs `samples` times as much. It does not re-sample the video's own frames, does not blur a group's moving children (set it on them), and is an error on text, solids, captions, audio, and a clip at a transition.
+
+```vidscript
+input hero = "hero.mp4"
+[0s .. 2s] = hero, animate: { type: "slideX", from: { x: 0 }, to: { x: 900 } }, motion_blur: { shutter: 360, samples: 16 }
+```
 
 ### Shaders
 
@@ -359,7 +474,8 @@ Fragment must sample `tDiffuse`, write `gl_FragColor`, and declare uniforms matc
 ### Audio
 
 ```vidscript
-audio music, volume: 0.5, fade_in: 1s, fade_out: 2s
+input music = "music.mp3"
+[0s .. 15s] = audio music, volume: 0.5, fade_in: 1s, fade_out: 2s
 ```
 
 Audio sources can be MP3 inputs, audio plugin results, or the embedded audio stream from an input video. Video inputs are visually silent unless you explicitly add `audio clip`. Plugin-generated audio (TTS, music, and probed native audio on generated video clips) is EBU R128 loudness-normalized during render to about -16 LUFS; `volume` is a relative gain applied after that. Ordinary imported audio/video is not auto-normalized.
@@ -369,6 +485,13 @@ Audio sources can be MP3 inputs, audio plugin results, or the embedded audio str
 | `volume` | number | Relative gain (0–1+). For generated audio, applied after loudness normalization. |
 | `fade_in` | number | Fade-in duration (seconds) |
 | `fade_out` | number | Fade-out duration (seconds) |
+| `trim_start` | number | Start this many seconds into the file |
+| `pan` | number | -1 (left) to 1 (right) |
+| `duck_under` | name | Lower this track while the named track plays |
+| `loudness` | string | `"ebu-r128"` normalizes an imported file |
+| `animate` | object | `{ type: "volume", from: { volume: 0 }, to: { volume: 1 } }` automates the level |
+
+Mixing recipes (J- and L-cuts, ducking, automation): `editing-actions.md` → Sound.
 
 ### Plugin Calls
 
@@ -433,7 +556,7 @@ Use `aspect_ratio: "9:16"` for vertical output, `"16:9"` for wide, `"1:1"` for s
 
 **Invalid (will not validate):**
 
-```vidscript
+```vidscript invalid
 [-] = video xai.imagine("...")                    # missing xAI import
 [0s .. 5s] = video cf.video("...")                # missing Cloudflare import
 [0s .. 15s] = audio eleven.generateMusic("...")   # missing `import eleven from "@elevenlabs/music"`
@@ -441,20 +564,92 @@ Use `aspect_ratio: "9:16"` for vertical output, `"16:9"` for wide, `"1:1"` for s
 [0s .. 15s] = audio eleven.music("..."), volume: 0.5      # trailing params after direct plugin call
 ```
 
-## Animations, Effects & Rendering (v2)
+## Reuse: values, functions, and modules
+
+Anything that can be placed is a value: an input, a plugin result, `text(…)` / `audio(…)` /
+`solid(…)`, a method chain, or a function call. A time block places one.
+
+### Functions
+
+```vidscript
+export fn lowerThird(title: string, color: string = "#ff5500") -> video {
+  [- 2s] = text title, color: color, size: 48
+}
+
+[0s .. 2s] = lowerThird("Konkan Day 1")
+[2s .. 4s] = lowerThird(title: "Day 2", color: "#00ff00")
+
+# one-liners: fn … = expression
+fn label(s: string) -> text = text(s, size: 24)
+```
+
+| Form | Meaning |
+|------|---------|
+| `fn name(params) -> kind { … }` | Block body: places items when called and placed |
+| `fn name(params) -> kind = expr` | Expression body: returns that value |
+| `export fn …` | Exported (callable through an imported namespace) |
+| `export timeline name(…) { … }` | Same as `export fn name(…) -> timeline { … }` |
+
+Return kinds: `video`, `image`, `text`, `audio`, `timeline`. `-> video` is a closed unit
+(place it with properties — `[0s .. 4s] = card("A"), x: 40, opacity: 0.5, blend: "screen"` — or
+chain `.Opacity()`, `.Resize()`, `.Filter()`, `.Crop()`, `.Mask()` and it draws as one item);
+`-> timeline` is open, its items join the caller. A `filter` or `shader` without `target:`
+inside a function or timeline body grades that unit's picture, not the whole frame.
+
+Arguments are checked at the call: a wrong kind, an unknown or missing parameter, too
+many arguments, or a value of the wrong kind is a compile error naming the parameter.
+Optional parameters take `name: kind = default`.
 
-VidScript v2 uses a **minimal-grammar, plugin-first** architecture. The compiler lowers VidScript into `IRTimeline` — the single contract shared by browser preview and final render.
+`use card at 0s .. 2s with { title: "A" }` is exactly `[0s .. 2s] = card(title: "A")` —
+the same IR.
 
-User-facing extension uses two parameters on any text or video surface:
+### Modules
+
+```vidscript
+import brand from "./brand.vid"     # another .vid file's exports
+
+[0s .. 2s] = brand.lowerThird("Hello")
+[0s .. 2s] = text "x", color: brand.accent
+use brand.card at 2s .. 4s with { title: "B" }
+```
 
-- `animate:` — motion over time (plugin calls or object descriptors)
-- `effects:` — post-processing filters with optional animated params
+`brand.vid` exports with `export fn lowerThird(title: string) -> video { … }`,
+`export timeline card(title: string) { … }`, and `export const accent = "#ff5500"`.
+
+### Builtin values
+
+```vidscript
+[0s .. 2s] = solid("#1a2b3c", opacity: 0.8)   # flat-colour rectangle
+[2s .. 3s] = gap()                            # transparent gap (advances the cursor)
+[4s .. 4s] = marker("act 2")                  # named instant (timeline data, not rendered)
+[0s .. 8s] = captions("talk.srt", size: 32)   # one text layer per SRT cue
+```
+
+Any visual value takes the same placement properties: `x`, `y`, `width`, `height`,
+`opacity`, `rotation`, `radius`, `corners`, `area`, `blend`, `animate`, `enabled`.
+`blend: "screen"` on a clip lowers to a composite layer over whatever is below the placement;
+on text, a solid, or a function it draws as a group with that blend. A blend needs something
+below it in the same window, or it is a compile error. More than 4 nested groups, or more
+than 16 alive at once, is a compile warning (each group renders into its own GPU target).
+`volume:` on a generated clip with its own sound sets that sound's level.
+
+### Names must resolve
+
+An unquoted word is only allowed where a value is an enumeration (`align: center`,
+`position: top`, `style: title`, `mode: screen`). Everywhere else an unresolved name is
+`Unknown variable 'titel'`. Quote strings; pass real variables.
+
+## Animations and effects
+
+`animate:` moves any text or picture over time, with `motion.*` calls or object descriptors. Filters are separate `filter` lines (above), and can be animated too.
 
 ### animate: parameter
 
 ```vidscript
 import motion from "@scenerok/basic-animations"
 
+input hero = "hero.mp4"
+input app_screen = "app-screen.png"
 [0s .. 3s] = text "Hello", x: "50%", y: "50%", animate: motion.fadeIn(0.8s)
 
 [-] = video hero, animate: [motion.fadeIn(0.5s), motion.slideY(-40, 0, 1.2s)]
@@ -473,17 +668,19 @@ import motion from "@scenerok/basic-animations"
 }
 ```
 
-Compiler lowers `animate:` into `IRMotionTrack[]` (property-path keyframes). Legacy `IRAnimation` descriptors are adapted at runtime for backward compatibility.
+Easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeOutBack`, `spring`. A list of objects with absolute `start` / `end` chains segments on one property (a path with more than two points); `keyframes:` is not supported and is silently dropped.
 
-### effects: parameter
+### Animated filters
 
 ```vidscript
+import motion from "@scenerok/basic-animations"
+
 [0s .. 5s] = filter "vignette", intensity: 0.4
 
 [0s .. 5s] = filter "glitch", intensity: 0.5, animate: motion.fadeIn(1s)
 ```
 
-Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignette`, `contrast`, `saturation`, `brightness`. Filters are optional finishing tools; use them only when they improve the composition.
+Filters are optional finishing tools; use them only when they improve the composition. Parameter names per filter: `editing-actions.md` → Color and finishing.
 
 ### Animation functions (`@scenerok/basic-animations`)
 
@@ -500,24 +697,12 @@ Built-in filters: `monochrome`, `sepia`, `blur`, `chromatic`, `glitch`, `vignett
 | `motion.float(duration?, amp?)` | Gentle vertical bob |
 | `motion.typewriter(duration?)` | Character reveal |
 
-### Render architecture (contributors)
-
-Implemented registry-based rendering. See `plan-v1/35-render-subsystem-architecture.md`.
-
-| Registry | Path | Add via |
-|----------|------|---------|
-| Motion | `src/lib/motion/registry.ts` | `registerEasing`, `registerMotionBehavior` |
-| Surface | `src/render/surfaces/registry.ts` | `registerSurfaceRenderer` |
-| Effect | `src/render/effects/registry.ts` | `registerEffect` or `src/shaders/library.ts` |
-| Engine | `src/render/engine/index.ts` | `createRenderEngine` backends |
-
-For SceneRok platform engineering, load the **`scenerok-development`** skill (`.agents/skills/scenerok-development/`).
-
 ## Expressions
 
 Used in time specs, `let` values, and function arguments:
 
 ```vidscript
+let title_text = "Launch"
 let x = 5s                    # Time literals
 let y = x * 2                 # Arithmetic
 let prompt = "Scene: " + title_text  # String concatenation
@@ -533,7 +718,7 @@ Operators: `+`, `-`, `*`, `/` with standard precedence.
 [- 3s] = text "{{headline | Default Text}}", color: "{{color | #FFFFFF}}"
 ```
 
-Placeholders are filled before parsing via `fillPlaceholders()`.
+Templates fill each `{{name | default}}` before the script compiles; outside a template the default is used.
 
 ## CLI Commands
 
@@ -556,8 +741,6 @@ scenerok status <render-id>
 # Install agent skills
 scenerok skills install <platform>
 
-# Set API secrets for plugins
-scenerok secrets set ELEVENLABS_API_KEY=your-key
 ```
 
 ## Best Practices

package/skills/scenerok/references/vidscript-sample.md

@@ -0,0 +1,44 @@
+# VidScript sample: a 13-second product promo
+
+A complete script to copy and adapt: two generated shots joined by a dissolve,
+titles in named areas, a voiceover, and a music bed that ducks under it.
+Validate it before rendering.
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+import tr from "@scenerok/transitions"
+
+# Copy lives in variables so it is easy to change.
+let product = "RokMilk"
+let hook = "Chocolate milkshake, ready in seconds"
+let cta = "Find it at your nearest grocery store"
+
+# Generated media is bound with let, so its real length is known.
+# Prompts never ask for text; all copy is added with `text` below.
+let kitchen = xai.imagine("Chocolate milk carton on a sunlit kitchen counter, cinematic lighting, shallow depth of field, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 6)
+let pour = xai.imagine("Slow pour of chocolate milkshake into a tall glass, macro, warm light, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 6)
+let vo = xai.tts("Meet RokMilk. Chocolate milkshake, ready in seconds. Find it at your nearest grocery store.", voice: "eve")
+let bed = eleven.music("Warm, upbeat acoustic bed for a food ad", duration: 13, instrumental: true)
+
+# Picture: each [-] starts where the previous visual block ended.
+[-] = kitchen
+[- 0.6s] = tr.dissolve()
+[-] = pour
+
+# Titles go in named areas, never at guessed coordinates.
+[0s .. 3s] = text product, style: title, area: "title", animate: motion.popIn(0.6s)
+[3s .. 7s] = text hook, area: "lower-third", animate: motion.riseIn(0.6s)
+[9s .. 12.6s] = text cta, area: "caption", animate: motion.fadeIn(0.5s)
+
+# Sound: the voiceover runs for its measured length; the bed ducks under it.
+[0s .. vo.duration] = audio vo
+[0s .. 13s] = audio bed, volume: 0.6, duck_under: vo, fade_out: 1.5s
+
+output to "rokmilk-promo.mp4", resolution: "1080x1920", fps: 30
+```
+
+To cut your own footage instead of generating it, replace the `let … =
+xai.imagine(…)` lines with `input` declarations and see `editing-actions.md`.
+The `@scenerok/cli` package ships more scripts in `examples/system/`.