@scenerok/sdk 0.9.0 → 0.10.0

package/skills/scenerok/references/catalog-index.json

@@ -1,6 +1,6 @@
 {
   "schema": "https://scenerok.com/catalog-index/v1",
-  "generatedAt": "2026-10-06T17:39:55.472Z",
+  "generatedAt": "2026-10-07T17:24:47.269Z",
   "cdnBase": "https://assets-public.scenerok.com/catalog",
   "categories": [
     {

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

@@ -2,7 +2,7 @@
 
 Use **TypeScript + `@scenerok/sdk`** when the scene needs loops, branches, arithmetic timing, or data-driven composition. Keep **VidScript** for short human-authored promos and templates.
 
-Both paths emit the same `IRTimeline`. Preview and render (Pass 2) are unchanged.
+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
 
@@ -10,6 +10,7 @@ Both paths emit the same `IRTimeline`. Preview and render (Pass 2) are unchanged
 |--------|----------|
 | 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
 
@@ -35,53 +36,120 @@ export default async function main() {
 |------|---------|
 | `t[start][end] = value` | Preferred dual-index schedule |
 | `t.range(start, end, value)` | Explicit call (no Proxy) |
-| `t['-'] = value` / `t.push(value)` | Auto-append at playhead |
+| `t['-'] = value` / `t.push(value, duration?)` | Auto-append at the playhead |
 
-`start` / `end` accept numbers (seconds), `s(3)` / `ms(300)`, or strings (`'3s'`, `'1:30'`). Full JS arithmetic works.
+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`).
 
-No `video` / `text` keywords after `=` — factories return typed values and the runtime infers IR kind.
+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 duration through the media stdlib when `duration` is omitted:
+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 }))
 ```
 
-Use the sync `video(path, { duration })` / `audio(path, { duration })` factories when you already know the timing.
+## Values
 
-## Grid areas
+| 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) |
 
-Same CSS-grid regions as VidScript. Declare a grid on the timeline, then place text with `area:`:
+Values are immutable. Methods return a copy, so one clip can be cut many ways:
 
 ```ts
-import { timeline, text, s } from '@scenerok/sdk'
+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 }))
+```
 
-export default function main() {
-  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+| 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 |
 
-  t.grid({
-    rows: '20% 1fr 30%',
-    cols: '1fr 1fr',
-    areas: ['title title', 'left right', 'caption caption'],
-  })
+```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 }))
+```
 
-  t[0][s(3)] = text('BIG SALE', { size: 72, area: 'title' })
-  t[0][s(3)] = text('Left column', { size: 40, area: 'left' })
+A blend needs something below it in the window; nothing below is an error, as in VidScript.
 
-  return t.toIR()
+## 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
 ```
 
-Without `t.grid(...)`, `area: 'title' | 'stage' | 'lower-third' | 'caption'` uses the built-in social-video preset (portrait vs landscape). Explicit `x` / `y` / `maxWidth` / `maxHeight` override the area.
+`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.
 
-Helpers also available: `resolveGridAreas`, `defaultGridSpec`, `placeInArea`.
+## Grid areas
 
-Same semantics as VidScript `grid rows: ..., areas: [...]` — see `vidscript-guide.md` → 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` automatically:
+Same `@scenerok/transitions` package as VidScript. Schedule a transition window between abutting clips; `toIR()` binds `fromId` / `toId`:
 
 ```ts
 import { timeline, video } from '@scenerok/sdk'
@@ -89,28 +157,67 @@ import tr from '@scenerok/transitions'
 
 export default function main() {
   const t = timeline({ width: 1080, height: 1920, fps: 30 })
-
   t[0][5] = video('./a.mp4', { duration: 5 })
-  t[5][5.6] = tr.dissolve()
+  t[5][5.6] = tr.dissolve({ inOffset: 0.3, outOffset: 0.3 })
   t[5.6][10] = video('./b.mp4', { duration: 4.4 })
-
-  // Or auto-append with catalog default (0.6s):
-  // t.push(tr.push({ direction: 'right' }))
-
   return t.toIR()
 }
 ```
 
-Common options: `direction`, `ease`, `strength`, `mode` (`roll` | `freeze`). Full catalog: `transitions-catalog.md`.
+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:
+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:
 
-- `t.toIR()`, or
-- an `IRTimeline` object
+```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"
 
-`async main` is supported so you can `await loadVideo(...)`, `await getVideoLength(...)`, or `await grabFrame(...)`.
+[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
 
@@ -119,16 +226,6 @@ scenerok validate scene.ts
 scenerok render scene.ts --watch
 ```
 
-You can also **include** an SDK scene from VidScript:
-
-```vidscript fragment
-import intro from "./intro.ts"
-use intro at 0s .. 0s with {}
-output to "reel.mp4"
-```
-
-See `vidscript-guide.md` → Include TypeScript / JavaScript scenes.
-
 MCP:
 
 - `scenerok_validate_vidscript` with `language: "typescript"`
@@ -137,7 +234,7 @@ MCP:
 
 ## AI plugins (xAI / Cloudflare / ElevenLabs)
 
-Same packages as VidScript. Import them in TypeScript; the SceneRok compile host runs the real plugins and returns SDK `video` / `audio` nodes:
+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'
@@ -159,7 +256,7 @@ export default async function main() {
   t[0][clip.duration] = clip
   t[clip.duration][clip.duration + still.duration] = still
   t.push(vo)
-  t.push(bed)
+  t.push(bed.with({ volume: 0.3, duckUnder: vo }))
   return t.toIR()
 }
 ```
@@ -172,10 +269,13 @@ export default async function main() {
 
 Requires the same env secrets as VidScript (`XAI_API_KEY`, `ELEVENLABS_API_KEY`, Cloudflare AI Gateway credentials). Generation is billed on render the same way as VidScript plugins.
 
-## MVP limits
+## 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).
 
-- Prefer `getVideoLength(path)` from `@scenerok/stdlib` instead of hard-coding `duration:` when assets exist on disk
-- `--generate-assets` remains VidScript-only (SDK scripts generate assets during `scenerok render` when plugins are called)
+Import the TypeScript part into a `.vid` when a scene needs these.
 
 ## Media stdlib
 

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

@@ -231,26 +231,59 @@ 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 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:
+
+| 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 |
 
-Import a `@scenerok/sdk` scene (`.ts` / `.js`) into VidScript with the same default-import form as plugins, then `use` it like a timeline:
+```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
+}
+```
 
 ```vidscript fragment
-import intro from "./intro.ts"
-import bump from "./bump.js"
+import kit from "./kit.ts"
 
-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"
+[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: "1080x1920"
+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)