@scenerok/cli 2.2.0 → 2.3.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. `rate:`, `first:`, `count:` on a plain file are errors. 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)
 ```
@@ -103,10 +118,13 @@ output to "reel.mp4", resolution: "720x1280", format: "mp4", codec: "h264", bitr
 |--------|------|---------|-------------|
 | `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 |
+| `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 +157,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 +182,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 +206,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`)
@@ -212,7 +232,7 @@ let vo2 = xai.tts("Let's dive in", voice: "eve")
 
 Import a `@scenerok/sdk` scene (`.ts` / `.js`) into VidScript with the same default-import form as plugins, then `use` it like a timeline:
 
-```vidscript
+```vidscript fragment
 import intro from "./intro.ts"
 import bump from "./bump.js"
 
@@ -231,17 +251,18 @@ Rules:
 
 ## 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 +289,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 +297,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 +333,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 +392,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 +438,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 +449,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 +520,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 +528,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`.
+
+`use card at 0s .. 2s with { title: "A" }` is exactly `[0s .. 2s] = card(title: "A")` —
+the same IR.
+
+### 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" }
+```
+
+`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.
 
-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.
+### Names must resolve
 
-User-facing extension uses two parameters on any text or video surface:
+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.
 
-- `animate:` — motion over time (plugin calls or object descriptors)
-- `effects:` — post-processing filters with optional animated params
+## 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 +632,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 +661,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 +682,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 +705,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/`.

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

@@ -1,6 +1,6 @@
 # VidScript v2 — Strict Agent Reference
 
-Follow these rules exactly. When in doubt, fetch `vidscript-sample.md` from https://scenerok.com/.well-known/agent-skills/ or run `scenerok skills sync` for local copies.
+Follow these rules exactly. For a complete working script, see `vidscript-sample.md`; for cuts, layering, masks, audio mixing, and grading, see `editing-actions.md`.
 
 ## Rule 1: Package imports are mandatory
 
@@ -17,11 +17,7 @@ Without the owning import, calls like `xai.imagine`, `cf.video`, `xai.tts`, `ele
 
 ## Rule 2: Use URL assets selectively
 
-When the user gives a product, company, ecommerce, landing page, or app URL and you have browser/screenshot capability, you can visit the page and capture useful visual evidence. Favor above-fold screenshots, product views, app screenshots, pricing/offer cards, testimonials, and detectable logos or brand marks.
-
-Do not use full-page or very long website screenshots as video backgrounds; their text is usually illegible at output size. Crop or frame screenshots to the specific visual proof point, and use them sparingly.
-
-Website screenshots are optional source material, not a requirement to build the whole video from screenshots. You may combine them with still generation, text-to-video, image-to-video, reference-to-video, or extension plugins for lifestyle scenes, motion backgrounds, transitions, or product context. Do not invent claims; use website copy or ask the user.
+A product or landing-page URL is optional source material. Capture focused, legible pieces (above-the-fold views, product shots, logos), never full-page screenshots as backgrounds, and don't invent claims. The full URL workflow is in `workflow.md`.
 
 ## Rule 2.5: Probe real asset type and dimensions before placement
 
@@ -37,6 +33,8 @@ identify asset.webp
 Use real video files for motion footage and still image inputs for screenshots, logos, product photos, and brand marks. The `video` primitive accepts both videos and images; image inputs render as static clips for the block duration.
 
 ```vidscript
+import motion from "@scenerok/basic-animations"
+
 input screenshot = "assets/screenshots/homepage.png"
 [0s .. 4s] = video screenshot, width: 1080, height: 1920, x: 0, y: 0, animate: motion.fadeIn(0.35s)
 ```
@@ -53,6 +51,7 @@ Add entry motion to real assets, not only text. When a static visual needs a cle
 ```vidscript
 import motion from "@scenerok/basic-animations"
 
+input product = "assets/product.png"
 [0s .. 3.4s] = video product, width: 760, height: 615, x: 160, y: 300, animate: [motion.riseIn(0.6s, 70), motion.float(2.4s, 8)]
 [3.4s .. 4s] = video product, width: 760, height: 615, x: 160, y: 300, animate: motion.fadeOut(0.6s)
 ```
@@ -64,8 +63,10 @@ AI-generated images and videos must not contain readable text. In every prompt f
 Good prompt pattern:
 
 ```vidscript
+import xai from "@scenerok/xai"
+
 [-] = video xai.imagine("Clean cinematic product background, premium lighting, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 5)
-[0.5s .. 3s] = text "Launch offer", style: title, color: "#FFFFFF", x: "50%", y: "30%", stroke: "#000000", stroke_width: 3
+[0.5s .. 3s] = text "Launch offer", style: title, color: "#FFFFFF", area: "title", stroke: "#000000", stroke_width: 3
 ```
 
 Invalid: asking the generator for signs, labels, packaging text, app UI text, title cards, lower thirds, prices, CTA buttons, or any readable copy.
@@ -101,13 +102,9 @@ Do not overuse one plugin function. Choose deliberately:
 | Voiceover | `xai.tts`, `xai.textToSpeech` |
 | Music bed | `eleven.music`, `eleven.generateMusic`, `eleven.composeMusic` |
 
-Use `imageToVideo` for one extracted screenshot/product/logo image. Use `referenceToVideo` for 1-7 reference images when extracted objects should guide the generated shot. xAI `referenceToVideo` requires a prompt and duration must be <= 10s.
+Use `imageToVideo` for one extracted screenshot/product/logo image and `referenceToVideo` for 1–7 reference images (xAI: prompt required, duration ≤ 10s). Cloudflare calls take an explicit `model:` and `aspect_ratio:`; models, signatures, and durations are in `ai-models.md` and the plugin table in `vidscript-guide.md`.
 
-For Cloudflare calls, always prefer explicit `model:` and use `aspect_ratio: "9:16"` for vertical, `"16:9"` for wide, `"1:1"` for square, or model-supported values such as `"4:3"`, `"3:4"`, and `"21:9"`. `cf.imageToVideo(image, prompt, model: ..., aspect_ratio: ..., duration: ...)` accepts `aspect_ratio`; for Runway Gen-4.5, SceneRok translates `"9:16"` to Cloudflare's required `ratio: "720:1280"`. Useful models include `pixverse/v6`, `vidu/q3-turbo`, `runwayml/gen-4.5`, `minimax/hailuo-2.3`, `bytedance/seedance-2.0`, `google/veo-3.1`, `google/veo-3.1-fast`, `google/veo-3-fast`, `black-forest-labs/flux-2-pro-preview`, and `openai/gpt-image-2`. Veo models accept `duration: 4`, `duration: 4s`, or `duration: "4s"` — all forms snap to the supported 4s/6s/8s durations.
-
-xAI TTS voices are only `eve`, `ara`, `rex`, `sal`, and `leo`.
-
-For ElevenLabs music, import `@elevenlabs/music` and use `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Do not call `eleven.tts(...)`; ElevenLabs TTS is not registered in VidScript today. Ads, promos, tutorials, and reels should normally include either `xai.tts` voiceover, an ElevenLabs music bed, or both unless the user asks for silent output.
+xAI TTS voices are only `eve`, `ara`, `rex`, `sal`, and `leo`. ElevenLabs is music only (`eleven.music`, `eleven.generateMusic`, `eleven.composeMusic`); there is no `eleven.tts`. Ads, promos, tutorials, and reels should normally have a voiceover, a music bed, or both unless the user asks for silence.
 
 ## Rule 4.5: `[-]` uses separate audio and visual playheads
 
@@ -129,16 +126,20 @@ Use explicit ranges when you need exact synchronization, overlaps, or cuts. Do n
 
 ## Rule 4.6: Never guess generated-asset durations
 
-Invalid — the real TTS length is unknown at write time, so a guessed window clips or overlaps:
+Avoid — the real TTS length is unknown at write time, so a guessed window clips or overlaps:
+
+```vidscript avoid
+import xai from "@scenerok/xai"
 
-```vidscript
 [0s .. 3s] = audio xai.tts("A sentence that may well run past three seconds", voice: "eve")
 [3s .. 6s] = audio xai.tts("This one starts while the first is still playing", voice: "eve")
 ```
 
-Valid — assign with `let` and reference the measured `duration` (arithmetic allowed), or use `[-]` auto blocks:
+Do this — assign with `let` and reference the measured `duration` (arithmetic allowed), or use `[-]` auto blocks:
 
 ```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
@@ -207,10 +208,12 @@ let bed = eleven.music("Soft premium ad music", duration: 15, instrumental: true
 
 ```vidscript
 [0s .. 15s] = filter "vignette", intensity: 0.3
-[0s .. 15s] = filter "saturation", value: 1.12
+[0s .. 15s] = filter "saturation", amount: 1.12
 ```
 
-Filters are optional finishing tools, not required ingredients. Use them only when they improve the visual result. `saturation` uses `value`, not `intensity`.
+Filters are optional finishing tools, not required ingredients. Use them only when they improve the visual result. Each filter has its own parameter name (`saturation` takes `amount`, `blur` takes `radius`); a wrong name is ignored without an error. The table is in `editing-actions.md` → Color and finishing.
+
+A `filter` line grades everything in its window. To grade one clip, add `target: clip` or write `clip.Filter("sepia", intensity: 0.6)`.
 
 ## Rule 10: Always end with output
 
@@ -220,6 +223,24 @@ output to "video.mp4", resolution: "1080x1920", fps: 30
 
 Do **not** use legacy `config { }` blocks — they are not part of VidScript v2.
 
+## Rule 11: Edits are values — place the result
+
+`Trim`, `Speed`, `Loop`, `Crop`, `Resize`, `Mask`, `Filter`, `Overlay`, and `Composite` return a new value. Place the result in one line:
+
+```vidscript
+input hero = "hero.mp4"
+input logo = "logo.png"
+[0s .. 4s] = hero.Trim(2s, 6s).Crop(420, 0, 1080, 1920)
+[4s .. 8s] = hero.Trim(6s, 10s).Overlay(logo.Resize(200, 200), x: 840, y: 60)
+```
+
+- A placed value lasts its own length (trimmed range ÷ speed × loops). Make the window that long.
+- Put one video over another with `Overlay`, `Composite`, or `blend:`. Two plain clips in the same window have no defined order.
+- `Mask` on its own line after the clip is placed is a compile error.
+- Frame counts are written `48 frame` and use the output fps (30 if `output` has none).
+
+All editing actions (masks, speed ramps, ducking, LUTs, timecode): `editing-actions.md`.
+
 ## Animations (after import)
 
 ```vidscript
@@ -240,12 +261,6 @@ Each error line includes `Line N:C — message` when the server returns location
 
 ## Bundled examples
 
-| File | Use case |
-|------|----------|
-| `minimal-text-reel.vid` | Text-only, no API keys |
-| `product-launch.vid` | User video input + text + vignette |
-| `ecom-product-launch.vid` | xAI product visuals + CTA |
-| `3-tips-fitness.vid` | Multiple `[-]` blocks + xAI per segment |
-| `rokmilk-chocolate-promo.vid` | 15s generated-video promo pattern |
+The `@scenerok/cli` npm package ships working scripts in `examples/system/`: `minimal-text-reel.vid` (text only), `product-launch.vid` (your own video + text), `ecom-product-launch.vid` (generated product visuals + CTA), `3-tips-fitness.vid` (several `[-]` blocks), `rokmilk-chocolate-promo.vid` (15 s generated promo).
 
-Full grammar: `vidscript-guide.md` or https://scenerok.com/.well-known/agent-skills/vidscript-guide.md
+Full grammar: `vidscript-guide.md`.