@scenerok/cli 2.2.0

package/skills/remote/environments.md

@@ -0,0 +1,73 @@
+# Agent Runtime Environments
+
+SceneRok skills are shared across several runtimes. **Detect where you are running** before choosing tools, asking questions, or fetching docs.
+
+## Quick detection
+
+| Signal | Environment | Primary actions |
+| --- | --- | --- |
+| Embedded in SceneRok web editor; `patch_vidscript` tool available; no shell | **Web editor** | Patch in-place; use editor asset library URLs |
+| `scenerok` CLI on user's machine; file system access | **Desktop agent (CLI)** | `scenerok validate` / `render`; local asset paths |
+| ChatGPT Actions, OAuth to SceneRok, `openaiFileIdRefs` | **ChatGPT GPT** | `validateVidscript` → `renderVideo`; import uploads first |
+| Gemini Gem or Grok Skill; may lack HTTP tools | **Consumer chat (limited)** | Compose VidScript; user renders elsewhere if no API |
+| `scenerok-mcp` tools (`scenerok_validate_vidscript`, `scenerok_render_video`, …) or remote `https://mcp.scenerok.com/mcp` | **MCP host** | MCP tools instead of raw CLI |
+| Reading bundled `SKILL.md` only | **Router-only** | Fetch remote docs from index (next section) |
+
+When unsure, ask one clarifying question: *"Are we in the SceneRok editor, your terminal, or a chat app like ChatGPT?"*
+
+## Remote doc loading (router-only / desktop)
+
+1. Fetch `https://scenerok.com/.well-known/agent-skills/index.json`
+2. **Always load** `vidscript-strict.md` and `intent-router.md`
+3. Load `environments.md` (this file) on first turn
+4. Conditionally load catalogs per `intent-router.md`
+5. Offline: `scenerok skills sync` then read local skill directory
+6. Freshness: `scenerok skills check` · update: `scenerok skills update`
+
+Base URL: `https://scenerok.com/.well-known/agent-skills/{filename}`
+
+## Capability matrix
+
+| Capability | Web editor | CLI / MCP | ChatGPT Action | Gemini / Grok (no API) |
+| --- | --- | --- | --- | --- |
+| Edit VidScript in place | `patch_vidscript` | Write `.vid` / `.ts` file | Return script to user | Return script |
+| Validate | Editor API (VidScript) | `scenerok validate` (`.vid` or `.ts`) | `validateVidscript` (+ `language` for SDK) | Explain only |
+| Render | Editor UI / API (VidScript) | `scenerok render` (`.vid` or `.ts`) | `renderVideo` + poll | Instruct user |
+| Shell / ffprobe / sips | No | Yes | No | No |
+| Browse product URL | If browser tool | If browser tool | Limited | Limited |
+| User asset library | Yes (logged in) | Via URLs / uploads | Via `importOpenAIConversationFiles` | Ask for public URLs |
+| Ask brand questions | Yes (chat) | Yes (terminal) | Yes (chat) | Yes (chat) |
+| OAuth / API tokens | Session cookie | `scenerok auth login` | OAuth per user | Manual token fallback |
+
+## Environment-specific rules
+
+### Web editor
+- Do **not** instruct the user to run CLI commands — the editor validates and renders in-app.
+- Prefer `patch_vidscript` for small edits; full fenced `vidscript` blocks for rewrites.
+- Use asset URLs from the user's SceneRok library when shown in context.
+- Load `brand-setup.md` when colors/logo are unknown and the user is building a branded promo.
+
+### Desktop agent (CLI / Cursor / Claude Code / Codex)
+- Run `scenerok validate` before every render (`.vid` or `.ts`).
+- Prefer `@scenerok/sdk` for agent-authored complex scenes; VidScript for short human edits.
+- Probe local assets with `loadVideo` / media stdlib, or `file` / `ffprobe` / `sips` / `identify` before placement.
+- Install router: `scenerok skills install <platform> [--sync]`
+- Full offline bundle: `scenerok skills sync`
+
+### ChatGPT GPT
+- Load `consumer-chat-apps.md` and `chatgpt-gpt-instructions.md` for OAuth and file import.
+- Never use `/mnt/data/...` paths — import via `importOpenAIConversationFiles` first.
+- Always validate before render; poll `getRenderStatus` until complete.
+
+### Consumer chat without API (Gemini Gem, Grok Skill)
+- Compose and explain VidScript; tell the user to render via SceneRok web, CLI, or ChatGPT Action.
+- Load `gemini-gem-instructions.md` or `grok-skill.md` as appropriate.
+
+## What to ignore per environment
+
+| Instruction in other docs | Web editor | ChatGPT |
+| --- | --- | --- |
+| `scenerok render ...` | Use editor render | Use `renderVideo` action |
+| `scenerok auth login` | N/A (session) | OAuth instead |
+| Fetch remote skill URLs | Already inlined locally | Fetch if network tool exists |
+| Local file paths in VidScript | Use library HTTPS URLs | Use imported asset URLs |

package/skills/remote/intent-router.md

@@ -0,0 +1,81 @@
+# SceneRok Intent Router
+
+Load after **`vidscript-strict.md`** and **`environments.md`** when the user wants a video.
+
+**Remote base:** `https://scenerok.com/.well-known/agent-skills/`
+
+## Step 0 — Detect environment
+
+Follow `environments.md`. Web editor → patch tool, no CLI. ChatGPT → Actions + file import. Desktop → CLI validate/render.
+
+## Disambiguation (≤2 questions)
+
+Defaults unless the user says otherwise:
+
+- **16:9** — YouTube, desktop, explainers
+- **9:16** — TikTok, Reels, Stories
+- **English** copy and VO
+- **3–15 s** social hooks · **15–60 s** promos
+
+| Signal | Workflow |
+| --- | --- |
+| Data/code/stats/maps, motion-first, <10 s | Motion graphic |
+| Product URL + CTA + lifestyle b-roll | Product promo |
+| Tweet / Reddit / Spotify / follow card | Social proof card |
+| Multiple clips + cross-fades / whips | Scene montage |
+| Voiceover explainer | Narrated explainer |
+| PR / code walk / terminal | Code demo |
+
+## Workflow → docs → APIs
+
+| Workflow | Load these slugs | Primary APIs (VidScript · SDK) |
+| --- | --- | --- |
+| **Product promo** | `ai-models.md`, `text-styles.md`, `music.md`, `workflow.md`, `brand-setup.md` (+ `sdk-guide.md` if TS) | `xai.imagine` / `await xai.genVideo(...)`, `motion.popIn` / `fadeIn`, `eleven.music` |
+| **Motion graphic** | `animations-picker.md` (+ `animations-catalog.md` if needed) | `animations.*` (VidScript HyperFrames; prefer VidScript for catalog blocks) |
+| **Social proof card** | `animations-picker.md` | `animations.x_post`, `reddit_post`, … (VidScript) |
+| **Scene montage** | `transitions-catalog.md`, `ai-models.md` (+ `sdk-guide.md` if TS loops) | `tr.dissolve` · SDK: `import tr from '@scenerok/transitions'` + `t[start][end] = tr.dissolve()` |
+| **Narrated explainer** | `tts.md`, `text-styles.md`, `music.md`, `workflow.md` (+ `sdk-guide.md` if TS) | `xai.tts` · `await xai.tts(...)` + `t.push(vo)` |
+| **Code demo / PR** | `animations-picker.md` (code rows) | `code_typing`, `code_diff` (VidScript) |
+| **Text animation / headline / stat** | `animations-picker.md` (text-anim rows) | `animations.text_*` (VidScript) · SDK kinetic: `text` + `fadeIn` / `popIn` |
+| **Kinetic title only** | `text-styles.md` (+ `sdk-guide.md` if TS) | `text` + `motion.*` · SDK: `text(..., { area })` + `.animate(fadeIn(...))` |
+| **Custom-authored animation (no block fits)** | `animations-catalog.md` → "Custom HTML" | `animations.custom_html` (VidScript) |
+| **Complex / data-driven timeline** | `sdk-guide.md`, `media-stdlib.md` | `@scenerok/sdk` — `timeline`, `t.grid`, `loadVideo`, AI plugins |
+
+## Staged routing
+
+1. **Classify** — workflow from table above
+2. **Choose authoring** — short/human → VidScript; complex/agent (loops, computed timing, multi-clip arithmetic) → `@scenerok/sdk` (`sdk-guide.md`)
+3. **Load catalogs** — only what that workflow needs (conditional loading)
+4. **Name block or API** — VidScript: pick `animations.<fn>` from `animations-picker.md`. SDK: factories (`video` / `loadVideo`, `text`, `fadeIn`) + AI imports (`@scenerok/xai`, …)
+5. **Brand** — if promo and missing colors/logo, one message per `brand-setup.md`
+6. **Probe assets** — dimensions / duration (`media-stdlib.md`, `loadVideo`, or CLI `ffprobe`)
+7. **Place text** — VidScript `area:` / `grid`; SDK `t.grid({...})` + `text(..., { area })`
+8. **Compose** — VidScript or SDK TS + validate
+9. **Render** — per environment (`environments.md`)
+
+## Reuse-first
+
+- `animations.<fn>(...)` over hand-authored HTML when a block fits
+- Text/headline treatments: try `animations.text_*` (text-anim family) before `motion.*` primitives or custom HTML
+- `tr.<fn>()` for scene transitions; `filter "…"` for single-clip VFX
+- No matching block → `text` + `animate: motion.<primitive>`, or `animations.custom_html(...)` to author your own HTML/CSS + GSAP / Three.js / any seekable JS animation lib (full author contract + minimal template in `animations-catalog.md` → "Custom HTML")
+- Unverified blocks (`verified: no`) ship demo content — prefer verified families
+- Complex procedural timelines → TypeScript `@scenerok/sdk` (`sdk-guide.md`) instead of exploding VidScript
+
+## Conditional loading
+
+- Skip `animations-catalog.md` unless you need full param tables
+- Skip `transitions-catalog.md` unless multiple clips or explicit transition ask
+- Always `vidscript-strict.md` before VidScript composition
+- Load `sdk-guide.md` before TypeScript SDK composition (scheduling, `t.grid`, AI plugin imports, `async main`)
+- Load `media-stdlib.md` when probing durations, grabbing frames, `loadVideo`, or layout-fitting assets
+- Load `ai-models.md` / `tts.md` / `music.md` for generative media in **either** language (examples cover both)
+- `vidscript-guide.md` only for grammar questions
+
+## Reference
+
+- Grammar: `vidscript-guide.md` or https://scenerok.com/.well-known/agent-skills/vidscript-guide.md
+- SDK: `sdk-guide.md` or https://scenerok.com/.well-known/agent-skills/sdk-guide.md
+- Media stdlib: `media-stdlib.md`
+- Machine-readable: `catalog-index.json`
+- Browse UI: https://scenerok.com/catalog

package/skills/remote/media-stdlib.md

@@ -0,0 +1,66 @@
+# Media standard library
+
+Shared Pass-1 host APIs for probing media and extracting frames. Available in **both** authoring languages.
+
+Prefer `loadVideo` / `loadAudio` from `@scenerok/sdk` when you only need duration for scheduling — they call the stdlib under the hood.
+
+## TypeScript (`@scenerok/stdlib` or `@scenerok/sdk`)
+
+```ts
+import { timeline, loadVideo, text, s } from '@scenerok/sdk'
+import { getVideoLength, grabFrame, getDimensions, getLoudness, beats } from '@scenerok/stdlib'
+
+export default async function main() {
+  const path = './hero.mp4'
+  const clip = await loadVideo(path) // fills duration via stdlib
+  const d = await getVideoLength(path)
+  const { width, height } = await getDimensions(path)
+  const loudness = await getLoudness(path)
+  const thumb = await grabFrame(path, d / 2, { width: 720 })
+
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  t[0][clip.duration] = clip
+  t[0][s(2)] = text(`${width}x${height}`, { size: 40, area: 'caption' })
+  t[0][beats(120, 4)] = text(`${loudness.integratedLufs} LUFS`, { size: 32, area: 'lower-third' })
+  // thumb is a data URL — schedule with video(thumb, { duration: 2 }) if needed
+  return t.toIR()
+}
+```
+
+## VidScript (`@scenerok/media`)
+
+```vidscript
+import media from "@scenerok/media"
+
+input hero = "./hero.mp4"
+let d = media.length(hero)
+let loudness = media.loudness(hero)
+let thumb = media.grabFrame(hero, d / 2)
+
+[0s .. d] = video hero
+[0s .. 2s] = video thumb, width: 400
+```
+
+`media.length` returns a time value usable in arithmetic and `[start .. end]` ranges.
+`media.info(hero).duration` / `.width` work via property access on the data result.
+`media.loudness(hero).integratedLufs` returns measured loudness data from ffmpeg (`truePeakDb`, `loudnessRange`, and `duration` are also available).
+
+## API surface
+
+| Function | TS | VidScript | Returns |
+|----------|----|-----------|---------|
+| `getVideoLength` / `length` | yes | `media.length` | seconds |
+| `getAudioLength` | yes | `media.getAudioLength` | seconds |
+| `getMediaInfo` / `info` | yes | `media.info` | `{ duration, width, height, fps, hasAudio, kind, ... }` |
+| `getDimensions` / `dimensions` | yes | `media.dimensions` | `{ width, height }` |
+| `getFps` / `fps` | yes | `media.fps` | number \| null |
+| `hasAudio` | yes | `media.hasAudio` | boolean |
+| `getLoudness` / `loudness` | yes | `media.loudness` | `{ integratedLufs, truePeakDb, loudnessRange, duration }` |
+| `mediaKind` / `kind` | yes | `media.kind` | `video` \| `audio` \| `image` |
+| `grabFrame` | yes | `media.grabFrame` | data URL (or uploaded URL) |
+| `grabFrameAtFraction` | yes | `media.grabFrameAtFraction` | data URL |
+| `measureText` | yes | `media.measureText` | `{ width, height, lines }` |
+| `fitContain` / `fitCover` | yes | `media.fitContain` | `{ width, height, x, y }` |
+| `parseTime` / `timecode` / `beats` / `clampTime` | yes | yes | time helpers |
+
+Implementation: `src/lib/media/stdlib/`. VidScript plugin: `src/plugins/media/`.

package/skills/remote/music.md

@@ -0,0 +1,69 @@
+# Generative Music
+
+`import eleven from "@elevenlabs/music"`
+
+### VidScript
+
+```vidscript
+import eleven from "@elevenlabs/music"
+let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
+```
+
+### TypeScript SDK
+
+```ts
+import { timeline } from '@scenerok/sdk'
+import eleven from '@elevenlabs/music'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  const bed = await eleven.music('Warm premium launch bed', {
+    duration: 15,
+    force_instrumental: true,
+  })
+  t.push(bed.with({ volume: 0.35, fadeOut: 2 }))
+  return t.toIR()
+}
+```
+
+Use a binding (`let bed` / `const bed`) when you need volume or fades. Do not call `eleven.tts` — use `xai.tts` for voiceover.
+
+## Examples (VidScript)
+
+**Drone underscore**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "drift", font: "Inter", size: 120, color: "#6B7280", align: "center", letter_spacing: 12
+[0s .. 3s] = audio eleven.music("dark ambient drone, minimal, cinematic tension, no percussion", duration: 3, force_instrumental: true)
+```
+
+**Padscape**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "ambient", font: "Inter", size: 140, color: "#9FB6FF", align: "center", letter_spacing: 8
+[0s .. 3s] = audio eleven.music("ambient cinematic padscape, slow evolving, contemplative", duration: 3, force_instrumental: true)
+```
+
+**4 s sting**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "▶", font: "Inter Black", size: 200, color: "#FFD23F", align: "center"
+[0s .. 3s] = audio eleven.music("short upbeat logo sting, claps, bright", duration: 3, force_instrumental: true)
+```
+
+**Bright brand cue**
+
+```vidscript
+import eleven from "@elevenlabs/music"
+
+[0s .. 3s] = text "UPBEAT", font: "Inter Black", size: 180, color: "#FFFFFF", align: "center"
+[0s .. 3s] = audio eleven.music("uplifting corporate brand cue, claps, bright synth, optimistic", duration: 3, force_instrumental: true)
+```
+

package/skills/remote/sdk-guide.md

@@ -0,0 +1,201 @@
+# @scenerok/sdk — TypeScript authoring for complex scenes
+
+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.
+
+## When to choose which
+
+| Signal | Language |
+|--------|----------|
+| Short promo, human edit, template placeholders | VidScript (`.vid`) |
+| Loop over clips, computed `start`/`end`, agent-authored complex timeline | TypeScript + `@scenerok/sdk` (`.ts`) |
+
+## Schedule syntax
+
+JavaScript has no `t[0, end]` dual key (comma operator collapses to one index). Use dual-index assignment:
+
+```ts
+import { timeline, loadVideo, text, audio, s, fadeIn } from '@scenerok/sdk'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  const scene1 = await loadVideo('./hero.mp4')
+
+  t[0][scene1.duration] = scene1.animate(fadeIn(s(0.4)))
+  t['0s']['3s'] = text('Hello', { size: 72 })
+  t[scene1.duration][scene1.duration + s(2)] = text('Next')
+  t.push(audio('./bed.mp3', { duration: 7, volume: 0.4 }))
+
+  return t.toIR()
+}
+```
+
+| Form | Meaning |
+|------|---------|
+| `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 |
+
+`start` / `end` accept numbers (seconds), `s(3)` / `ms(300)`, or strings (`'3s'`, `'1:30'`). Full JS arithmetic works.
+
+No `video` / `text` keywords after `=` — factories return typed values and the runtime infers IR kind.
+
+Use `loadVideo(path)` / `loadAudio(path)` to probe duration through the media stdlib when `duration` is omitted:
+
+```ts
+const clip = await loadVideo('./hero.mp4')
+t[0][clip.duration] = clip
+```
+
+Use the sync `video(path, { duration })` / `audio(path, { duration })` factories when you already know the timing.
+
+## Grid areas
+
+Same CSS-grid regions as VidScript. Declare a grid on the timeline, then place text with `area:`:
+
+```ts
+import { timeline, text, s } from '@scenerok/sdk'
+
+export default function main() {
+  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)] = text('Left column', { size: 40, area: 'left' })
+
+  return t.toIR()
+}
+```
+
+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.
+
+Helpers also available: `resolveGridAreas`, `defaultGridSpec`, `placeInArea`.
+
+Same semantics as VidScript `grid rows: ..., areas: [...]` — see `vidscript-guide.md` → Grid Areas.
+
+## Transitions
+
+Same `@scenerok/transitions` package as VidScript. Schedule a transition window between abutting clips; `toIR()` binds `fromId` / `toId` automatically:
+
+```ts
+import { timeline, video } from '@scenerok/sdk'
+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.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`.
+
+## Entry contract
+
+Export `default async function main()` (or sync `main`) that returns either:
+
+- `t.toIR()`, or
+- an `IRTimeline` object
+
+`async main` is supported so you can `await loadVideo(...)`, `await getVideoLength(...)`, or `await grabFrame(...)`.
+
+## Validate / render
+
+```bash
+scenerok validate scene.ts
+scenerok render scene.ts --watch
+```
+
+You can also **include** an SDK scene from VidScript:
+
+```vidscript
+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"`
+- `scenerok_render_video` with `language: "typescript"`
+- `scenerok_get_sdk_guide` for this document
+
+## 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:
+
+```ts
+import { timeline } from '@scenerok/sdk'
+import xai from '@scenerok/xai'
+import cf from '@scenerok/cloudflare'
+import eleven from '@elevenlabs/music'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  const clip = await xai.genVideo('Cinematic drone over mountains', {
+    duration: 5,
+    aspect_ratio: '9:16',
+    resolution: '720p',
+  })
+  const still = await cf.image('Product on seamless backdrop', { aspect_ratio: '9:16' })
+  const vo = await xai.tts('Welcome to SceneRok', { voice: 'eve' })
+  const bed = await eleven.music('Warm lo-fi bed', { duration: 12 })
+
+  t[0][clip.duration] = clip
+  t[clip.duration][clip.duration + still.duration] = still
+  t.push(vo)
+  t.push(bed)
+  return t.toIR()
+}
+```
+
+| Package | Import | Key functions |
+|---------|--------|---------------|
+| `@scenerok/xai` | `import xai from '@scenerok/xai'` | `imagine`, `genVideo`, `image`, `imageToVideo`, `referenceToVideo`, `extendVideo`, `tts`, `listVoices` |
+| `@scenerok/cloudflare` | `import cf from '@scenerok/cloudflare'` | `video` / `imagine`, `image`, `imageToVideo`, `extendVideo`, `listModels` |
+| `@elevenlabs/music` | `import eleven from '@elevenlabs/music'` | `music`, `generateMusic`, `composeMusic` |
+
+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
+
+- 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)
+
+## Media stdlib
+
+```ts
+import { loadVideo, getVideoLength, grabFrame, beats } from '@scenerok/sdk'
+
+export default async function main() {
+  const clip = await loadVideo('./hero.mp4')
+  const d = await getVideoLength('./hero.mp4')
+  const thumb = await grabFrame('./hero.mp4', d / 2)
+  // ...
+}
+```
+
+Same functions are available in VidScript via `import media from "@scenerok/media"`.
+
+See `skills/remote/media-stdlib.md` and `ai-models.md` / `tts.md` / `music.md` for prompt guidance.
+
+## Related
+
+- VidScript grammar: `vidscript-guide.md`
+- Intent routing: `intent-router.md`
+- Package README: `packages/scenerok-sdk/README.md`

package/skills/remote/shaders-filters.md

@@ -0,0 +1,97 @@
+# Shaders and Filters
+
+## Built-in filters
+
+Apply on a time block with the clip active:
+
+```vidscript
+[0s .. 5s] = filter "vignette", intensity: 0.4
+[2s .. 4s] = filter "sepia", intensity: 0.6
+```
+
+| Filter | Typical use |
+| --- | --- |
+| `monochrome` | Desaturated / B&W look |
+| `sepia` | Warm vintage tone |
+| `blur` | Soft focus / depth |
+| `chromatic` | Lens aberration / glitch accent |
+| `glitch` | Digital distortion |
+| `vignette` | Edge darkening — finishing pass |
+| `contrast` | Punch up midtones |
+| `saturation` | Color intensity |
+| `brightness` | Exposure lift/drop |
+
+Use filters as optional finishing tools — do not add by default.
+
+## VFX filters (single-clip)
+
+Native VFX via `filter` keyword on one clip:
+
+```vidscript
+[0s .. 5s] = video clip
+[0s .. 2s] = filter "liquid_glass", intensity: 0.6
+```
+
+| Filter | Reach for it when… |
+| --- | --- |
+| `liquid_glass` | iOS-style glass morphism over footage |
+| `magnetic` | UI magnet / snap aesthetic |
+| `portal` | Sci-fi portal / warp hole |
+| `text_cursor` | Typing / terminal cursor overlay |
+
+## Custom shaders
+
+Author fragment GLSL in a `.glsl` file and import it — same idea as `animations.custom_html(src:)` for HTML, but via the first-class shader import:
+
+```vidscript
+import shader glow from "./shaders/glow.glsl"
+
+[0s .. 5s] = text "Hello"
+[0s .. 5s] = shader glow, intensity: 0.8
+```
+
+Also works with npm package paths under `node_modules`:
+
+```vidscript
+import shader glow from "shader-pack/shaders/glow.glsl"
+```
+
+| Use | Keyword |
+| --- | --- |
+| Built-in / VFX from the library | `filter "name", …` |
+| Your own `.glsl` file | `import shader` + `shader name, …` |
+
+**Fragment contract** (EffectComposer post-process):
+
+- Fragment only — the engine supplies a shared vertex shader with `vUv`
+- Declare `uniform sampler2D tDiffuse` and sample it
+- Write `gl_FragColor`
+- VidScript params become uniforms by **exact name** (`intensity: 0.8` → `uniform float intensity`)
+- Optional: declare `uniform float uTime` and/or `uniform vec2 uResolution` — the renderer injects and updates them automatically
+
+```glsl
+uniform sampler2D tDiffuse;
+uniform float intensity;
+varying vec2 vUv;
+
+void main() {
+  vec4 texel = texture2D(tDiffuse, vUv);
+  gl_FragColor = texel * (1.0 + intensity);
+}
+```
+
+The compiler reads the file at compile time and embeds the GLSL into IR (`IRShaderEffect`). Relative paths resolve against the `.vid` directory (`workingDirectory` / `assetBaseDir`).
+
+## Scene transitions
+
+Scene transitions use `@scenerok/transitions` — see `transitions-catalog.md`. They blend **two** clips at window boundaries; filters operate on **one** clip.
+
+```vidscript
+import tr from "@scenerok/transitions"
+
+[0s .. 5s]   = video clip_a
+[5s .. 5.6s] = tr.dissolve()
+[5.6s .. 10s] = video clip_b
+```
+
+Do not confuse `tr.dissolve()` (two-texture blend) with `filter "vignette"` (single-clip post).