@scenerok/cli 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "SceneRok CLI - Create videos from your terminal and agent workflows",
   "type": "module",
   "bin": {

package/skills/scenerok/SKILL.md

@@ -23,8 +23,11 @@ validate it, render it, and check the rendered file.
 | Use for | Promos, reels, templates, and every editing action: masks, blends, crops, speed ramps, ducking, LUTs, timecode | Timelines built by code: loops over data, computed timing across many clips |
 | Start with | [vidscript-strict.md](references/vidscript-strict.md) | [sdk-guide.md](references/sdk-guide.md) |
 
-The SDK has no masks, blends, crops, ducking, or delivery settings. When a
-scene needs both, write it in VidScript and `import` the SDK scene into it.
+The SDK has the same values and placement (masks, blends, crops, groups,
+ducking, timecode); LUT files, caption files, several outputs, and offline
+media are VidScript only. A `.vid` can `import kit from "./kit.ts"` and place
+the module's exports (`[0s .. 3s] = kit.title`), so build data-driven parts in
+TypeScript and finish the edit in VidScript.
 
 ## Workflow
 

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

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

package/skills/scenerok/references/editing-actions.md

@@ -260,6 +260,18 @@ input b = "shot-b.mp4"
 output to "video.mp4", resolution: "1920x1080", fps: 24
 ```
 
+Timecode literals are `HH:MM:SS:FF@rate`, non-drop-frame (`;` is an error),
+FF below the rate, hours 0-23. Without `@rate` they use the literal output fps:
+
+```vidscript
+[00:00:01:12@24 .. 00:00:03:00@24] = text "1.5 s to 3 s"
+output to "video.mp4", resolution: "1920x1080", fps: 24
+```
+
+NTSC `fps:` values (23.976, 29.97, 47.952, 59.94, 119.88) are encoded at the
+exact `24000/1001` style rate, and block start/end times snap to whole frames
+of the output (`[0.1s .. 0.35s]` at 30 fps is frames 3 to 11).
+
 ### Transitions and handles
 
 Transitions come from `@scenerok/transitions` (full list in
@@ -295,6 +307,24 @@ input frames = "renders/shot.%04d.png", rate: 12, first: 1, count: 24
 `Trim`, `Speed`, and `Loop` work on it. For cloud renders the pattern must be
 an `https` URL pattern.
 
+### Mixed frame rates
+
+`rate:` on a plain video input says what frame rate the footage runs at, for a
+timeline at another rate. Each output frame shows the source frame its time falls
+in, so 23.976 footage in a 30 fps timeline repeats frames in a 2:3-like cadence
+and never skips one:
+
+```vidscript
+input clip = "clip.mp4", rate: 23.976
+[0s .. 4s] = clip.Trim(1s, 5s)
+output to "out.mp4", resolution: "1920x1080", fps: 30
+```
+
+Write it only when the footage rate differs from `fps`. It is an error on audio
+or a still image; `first:` and `count:` stay sequence-only. A probed rate is never
+applied for you: if the probe differs from the declared rate by more than 0.1%
+the compile warns and the declared rate wins. Audio is not conformed.
+
 ## Sound
 
 Every sound is an `audio` line with its own window, so J- and L-cuts need no
@@ -488,13 +518,25 @@ output to "master.mp4", resolution: "1920x1080", fps: 25, codec: "h264", bitrate
 `start_timecode` is `HH:MM:SS:FF` and its frame field must be below `fps`.
 `burn_in: "timecode"` draws the running timecode on the picture.
 
+### Offline media
+
+```vidscript
+input a = "shot-a.mp4"
+input b = "shot-b.mp4"   # not delivered yet
+[0s .. 4s] = a
+[4s .. 8s] = b
+output to "draft.mp4", resolution: "1920x1080", fps: 25, allow_offline: true
+```
+
+With `allow_offline: true`, an input whose file is missing at compile time becomes an offline clip (OTIO `MissingReference`): it keeps its place and source path, lasts the block or `Trim` length, and draws as a flat `#2b2b2b` slate labelled `MEDIA OFFLINE` and the input name. `Resize`, `x`/`y`, `opacity` and `animate:` still apply. Its sound is dropped with a warning, and a transition at its seam is an error. Without the option a missing local file is a compile error. Media that disappears only at render time still fails the render.
+
 ## What VidScript can't do yet
 
 Don't try to work around these. Tell the user when a request needs one.
 
 | Request | Today |
 | --- | --- |
-| Two aspect ratios from one script | One `output` per script; a second `output` line replaces the first. Write one script per format. |
+| Two aspect ratios from one script | Two `output` statements compile to two canvases, but only the local headless renderer renders both (one file per output). The render queue (web app, CLI, API) rejects a script with more than one `output` before billing, so write one script per format for a hosted render. |
 | Transparent video (alpha) | `alpha: true` is a compile error; renders are H.264 MP4. |
 | Multicam angle switching | No syntax. Cut between the angle clips with time blocks. |
 | Mixed frame rates | A timeline has one frame rate, the output `fps`. |

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

@@ -70,7 +70,7 @@ 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).
+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.
 
@@ -114,6 +114,8 @@ 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 |
@@ -124,6 +126,7 @@ output to "reel.mp4", resolution: "720x1280", format: "mp4", codec: "h264", bitr
 | `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
@@ -228,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)
 

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

@@ -237,7 +237,7 @@ input logo = "logo.png"
 - 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).
+- Frame counts are written `48 frame` and use the output fps (30 if `output` has none). Timecodes are `01:00:02:12@24` (`@rate` optional; non-drop-frame only). Block times snap to the output frame grid; NTSC fps (23.976, 29.97) encodes at the exact rational rate.
 
 All editing actions (masks, speed ramps, ducking, LUTs, timecode): `editing-actions.md`.