@scenerok/sdk 0.6.0 → 0.8.0

package/README.md

@@ -8,6 +8,16 @@ TypeScript-first authoring SDK for SceneRok. Agents use this for **complex, data
 npm install @scenerok/sdk
 ```
 
+## Agent skill
+
+The package includes the scenerok agent skill at `skills/scenerok/` (`SKILL.md` plus `references/`): how to write, validate, and render SceneRok scenes in TypeScript or VidScript. Copy that directory into your agent's skills folder, for example:
+
+```bash
+cp -r node_modules/@scenerok/sdk/skills/scenerok ~/.claude/skills/
+```
+
+or install it with the CLI: `npx @scenerok/cli skills install claude`.
+
 ## Quick start
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TypeScript-first SceneRok authoring SDK — build IRTimeline for complex agent-authored scenes",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,9 +37,11 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {
+    "prebuild": "node ../../scripts/copy-scenerok-skill.mjs .",
     "build": "tsc -p tsconfig.json",
     "dev": "tsc --watch",
     "test": "node --import tsx --test src/**/*.test.ts"

package/skills/scenerok/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: scenerok
+description: >-
+  Writes, validates, and renders SceneRok videos from VidScript (.vid) or the
+  TypeScript @scenerok/sdk: promos, reels, explainers, social cards, motion
+  graphics, and edits of existing footage (trims, speed changes, picture-in-picture,
+  blend modes, masks, crops, color grades, LUTs, audio mixing and ducking, captions,
+  timecode). Use when the user wants to make or edit a video with SceneRok, or
+  mentions VidScript, a .vid file, @scenerok/sdk, the scenerok CLI, or the SceneRok
+  MCP tools.
+---
+
+# SceneRok
+
+SceneRok turns a script into an MP4. Write the script in VidScript or in
+TypeScript with `@scenerok/sdk`; both compile to the same timeline. Then
+validate it, render it, and check the rendered file.
+
+## Choose the language
+
+| | VidScript (`.vid`) | TypeScript (`@scenerok/sdk`, `.ts`) |
+| --- | --- | --- |
+| 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.
+
+## Workflow
+
+Copy this checklist into your notes and work through it:
+
+```text
+- [ ] 1. Identify the environment (web editor, CLI, ChatGPT, MCP, chat without tools)
+- [ ] 2. Classify the request; read only the references it needs (table below)
+- [ ] 3. Branded promo with unknown colors or logo: ask once
+- [ ] 4. Probe real assets: type, width, height, duration
+- [ ] 5. Write the script
+- [ ] 6. Validate. Fix every error and validate again until clean
+- [ ] 7. Uses TTS or generated media: deep-validate and fix the report (CLI only)
+- [ ] 8. Render
+- [ ] 9. Check the rendered MP4; fix and repeat from step 6 if it reports problems (CLI only)
+```
+
+With the CLI:
+
+```bash
+scenerok validate script.vid                                    # or scene.ts
+scenerok validate script.vid --generate-assets --report-json    # billed; VidScript only
+scenerok render script.vid --watch
+scenerok lint-video <render-id> --cost medium --json            # billed
+```
+
+`scenerok render script.vid --validate` renders and checks the MP4 in one step.
+
+The deep validation generates the real speech and media (cached for the
+render) and reports text that runs off-canvas or was shrunk (`offCanvas`,
+`wasShrunk`), overlapping elements (`collisions`), and voice-over-voice
+overlaps (`audio.overlaps`; music under voice is fine). The web editor,
+ChatGPT, and MCP have their own validate and render calls but no deep
+validation or MP4 check, and can't read local files:
+[environments.md](references/environments.md).
+
+## Rules that prevent most failures
+
+1. **Import before calling.** `import xai from "@scenerok/xai"`, then
+   `xai.tts(…)`. The same for `@scenerok/cloudflare`, `@elevenlabs/music`,
+   `@scenerok/basic-animations`, `@scenerok/animations`,
+   `@scenerok/transitions`, and `@scenerok/media`.
+2. **Never guess a duration.** Bind generated media and use its length:
+   `let vo = xai.tts(…)` then `[0 .. vo.duration] = audio vo`.
+3. **Never guess text coordinates.** Use `area: "title"` (also `stage`,
+   `lower-third`, `caption`, or your own `grid`).
+4. **No text in generated images or video.** Every prompt asks for no text,
+   letters, logos, or watermarks; put all copy in `text` lines.
+5. **Edits return values; place the result.**
+   `[0s .. 4s] = clip.Trim(2s, 6s).Crop(420, 0, 1080, 1920)`. Put one video
+   over another with `Overlay`, `Composite`, or `blend:`.
+6. **Use only documented syntax.** Don't invent functions or parameters. A
+   validation error names the problem; fix that line rather than rewriting the
+   script.
+
+## References
+
+Read the ones the task needs. Paths are relative to this file.
+
+| Task | Read |
+| --- | --- |
+| Any VidScript | [vidscript-strict.md](references/vidscript-strict.md) (always) |
+| Editing and compositing: trims, speed, reverse, freeze, picture-in-picture, blend modes, masks, crops, split screens, audio mixing and ducking, grading and LUTs, captions, timecode | [editing-actions.md](references/editing-actions.md) |
+| Full grammar | [vidscript-guide.md](references/vidscript-guide.md) |
+| A complete commented promo script | [vidscript-sample.md](references/vidscript-sample.md) |
+| TypeScript SDK | [sdk-guide.md](references/sdk-guide.md) |
+| Probing media, grabbing frames, beats | [media-stdlib.md](references/media-stdlib.md) |
+| Generated images and video | [ai-models.md](references/ai-models.md) |
+| Voiceover | [tts.md](references/tts.md) |
+| Music beds | [music.md](references/music.md) |
+| Animated blocks: lower thirds, code, social cards, text animations, custom HTML | [animations-picker.md](references/animations-picker.md), then [animations-catalog.md](references/animations-catalog.md) for every parameter |
+| Titles animated with motion primitives | [text-styles.md](references/text-styles.md) |
+| Scene transitions | [transitions-catalog.md](references/transitions-catalog.md) |
+| Filters, VFX, custom shaders | [shaders-filters.md](references/shaders-filters.md) |
+| A promo from a product URL | [workflow.md](references/workflow.md), [brand-setup.md](references/brand-setup.md) |
+| Which workflow fits the request | [intent-router.md](references/intent-router.md) |
+| Where you are running and what you can call | [environments.md](references/environments.md) |
+| Every catalog item as data | [catalog-index.json](references/catalog-index.json) |
+
+Without local files (for example, only this text was pasted into a chat),
+fetch any reference from
+`https://scenerok.com/.well-known/agent-skills/<filename>`. Setup guides for
+chat apps are there too: `consumer-chat-apps.md`,
+`chatgpt-gpt-instructions.md`, `gemini-gem-instructions.md`, `grok-skill.md`.
+Previews of every catalog item: https://scenerok.com/catalog.
+
+## Minimal VidScript
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+input hero = "https://cdn.example.com/clip.mp4"
+[0s .. 4s] = hero.Trim(1s, 5s)
+[0s .. 3s] = text "Hello", style: title, color: "#FFFFFF", area: "title", animate: motion.fadeIn(0.8s)
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+## Minimal SDK scene
+
+```ts
+import { timeline, text, s, fadeIn } from '@scenerok/sdk'
+
+export default function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  t.grid({
+    rows: '16% 1fr 18% 10%',
+    areas: ['title', 'stage', 'lower-third', 'caption'],
+  })
+  t[0][s(3)] = text('SceneRok', { size: 72, area: 'title' }).animate(fadeIn(s(0.4)))
+  t[3][5] = text('Text to video', { size: 40, area: 'lower-third' })
+  return t.toIR()
+}
+```
+
+Validate and render it like a `.vid`: `scenerok validate scene.ts`.
+
+## Keeping the skill current
+
+`scenerok skills check` compares the installed copy with scenerok.com;
+`scenerok skills update` downloads what changed.

package/skills/scenerok/references/ai-models.md

@@ -0,0 +1,64 @@
+# AI Models — Video and Image Generation
+
+## Modality picker
+
+| Intent | API | When |
+| --- | --- | --- |
+| Clean still / key visual | `xai.image(...)` · `cf.image(...)` | Product shot, poster frame |
+| Text-to-video | `xai.imagine(...)` · `xai.genVideo(...)` · `cf.video(...)` | B-roll, lifestyle, cinematic |
+| Animate one image | `xai.imageToVideo(img, prompt, ...)` · `cf.imageToVideo(...)` | Product photo → motion |
+| Multi-reference scene | `xai.referenceToVideo([imgs], prompt, ...)` | Brand elements guide scene |
+| Extend existing clip | `xai.extendVideo(...)` · `cf.extendVideo(...)` | Continue generated clip |
+
+**Always import:** `import xai from "@scenerok/xai"` and/or `import cf from "@scenerok/cloudflare"`.
+
+Generative prompts must require: no text, no words, no letters, no captions, no logos, no watermarks, no readable UI copy.
+
+## Examples
+
+### Grok genVideo()
+
+Explicit duration, resolution, and aspect ratio for text-to-video.
+
+**Landscape 8 s**
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[- 3s] = video xai.genVideo("Timelapse of clouds over desert mesas, wide cinematic, anamorphic flare", duration: 3, aspect_ratio: "16:9", resolution: "720p")
+
+[prev .. prev + 0.8s] = text "genVideo()", font: "Inter Bold", size: 44, color: "#FFFFFF", shadow_blur: 10, align: "center", y: "88%"
+```
+
+**Vertical 6 s reel**
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[- 3s] = video xai.genVideo("Drone shot over a futuristic city at sunset, lens flare, cinematic", duration: 3, aspect_ratio: "9:16", resolution: "720p")
+```
+
+### Grok imagine()
+
+One-call text-to-video. Default 5 s, 720p, 9:16.
+
+**Ocean drone**
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[- 3s] = video xai.imagine("Slow aerial drone over turquoise ocean waves, golden hour, cinematic", aspect_ratio: "16:9", resolution: "720p")
+
+[prev .. prev + 0.8s] = text "imagine()", font: "Inter Bold", size: 48, color: "#FFFFFF", align: "center", y: "85%"
+```
+
+**Street market**
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[- 3s] = video xai.imagine("A neon-lit street market at night, cinematic, volumetric light", aspect_ratio: "9:16", resolution: "720p")
+
+[prev .. prev + 0.8s] = text "Grok imagine()", font: "Inter Bold", size: 56, color: "#FFFFFF", shadow_color: "#000000", shadow_blur: 12, position: "bottom", align: "center"
+```
+

package/skills/scenerok/references/animations-catalog.md

@@ -0,0 +1,226 @@
+# Animations Catalog
+
+All `animations.<fn>(...)` blocks from `@scenerok/animations`. Total: **77** entries.
+
+```vidscript
+import animations from "@scenerok/animations"
+```
+
+| fn | family | verified | defaultDuration | params |
+| --- | --- | --- | --- | --- |
+| `app_showcase` | other | yes | 6s | positional: `imageUrl` · named: `imageUrl, userName, userRole, tagline, accentColor` |
+| `apple_money_count` | other | yes | 5s | positional: `amount` · named: `amount, currency, accentColor` |
+| `blend_caption` | lower-third | yes | 5s | positional: `text` · named: `text, color` |
+| `blue_sweater_intro_video` | other | yes | 12s | positional: `creatorName` · named: `headline, creatorName, creatorHandle, creatorBio, avatarUrl` |
+| `code_3d_extrude` | code-anim | yes | 8s | positional: `code` · named: `code, lang, theme, filename` |
+| `code_diff` | code-anim | yes | 6s | positional: `from, to` · named: `from, to, lang, theme` |
+| `code_highlight` | code-anim | yes | 5s | positional: `code` · named: `code, lang, theme, filename` |
+| `code_morph` | code-anim | yes | 7s | positional: `from, to` · named: `from, to, lang, theme` |
+| `code_particle_assemble` | code-anim | yes | 8s | positional: `code` · named: `code, lang, theme, filename` |
+| `code_scroll` | code-anim | yes | 6s | positional: `code` · named: `code, lang, theme, filename` |
+| `code_shader_dissolve` | code-anim | yes | 7s | positional: `code` · named: `code, lang, theme, filename` |
+| `code_snippet_apple_terminal_basic` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_clear_dark` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_clear_light` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_grass` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_homebrew` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_man_page` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_novel` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_ocean` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_pro` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_red_sands` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_silver_aerogel` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_apple_terminal_solid_colors` | code-snippet | yes | 12s | positional: `command` · named: `command, output, prompt, title` |
+| `code_snippet_dark_2026` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_dark_modern` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_dark_plus` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_flight` | code-snippet | yes | 6s | positional: `code` · named: `code, lang, theme, filename` |
+| `code_snippet_high_contrast` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_high_contrast_light` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_light_2026` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_light_modern` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_light_plus` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_monokai` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_solarized_light` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_visual_studio_dark` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_snippet_visual_studio_light` | code-snippet | yes | 11s | positional: `code` · named: `code, filename, lang` |
+| `code_typing` | code-anim | yes | 5s | positional: `code` · named: `code, lang, theme, filename` |
+| `instagram_follow` | social-card | yes | 5s | positional: `displayName, handle` · named: `displayName, handle, followers, avatarUrl, url` |
+| `ios26_liquid_glass` | other | yes | 15s | positional: `(none)` · named: `(none)` |
+| `liquid_glass_context_menu` | other | yes | 8s | positional: `fileName` · named: `fileName, fileMeta` |
+| `liquid_glass_media_controls` | other | yes | 8s | positional: `trackTitle` · named: `trackTitle, artist` |
+| `liquid_glass_notification` | other | yes | 8s | positional: `title` · named: `title, body, messageText` |
+| `liquid_glass_widgets` | other | yes | 8s | positional: `showcaseTitle` · named: `showcaseTitle, showcaseDescription` |
+| `logo_outro` | brand | yes | 6s | positional: `tagline` · named: `tagline, url, logoUrl, brand, accent` |
+| `lower_third` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle` |
+| `lower_third_bild` | lower-third | yes | 8s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_accent_underline` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_bold_block` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_clean_bar` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_color_block` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_dark_card` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_kicker_name` | lower-third | yes | 5s | positional: `kicker, title` · named: `kicker, title, accent` |
+| `lt_mask_reveal` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_side_rule` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_soft_pill` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `lt_stack_bars` | lower-third | yes | 5s | positional: `title, subtitle` · named: `title, subtitle, accent, bg` |
+| `macos_notification` | social-card | yes | 5s | positional: `appName, title` · named: `appName, timeLabel, title, body` |
+| `macos_tahoe_liquid_glass` | other | yes | 15s | positional: `windowTitle` · named: `wallpaperUrl, windowTitle, toastBody, weatherLocation` |
+| `news_ticker` | social-card | yes | 7s | positional: `headline` · named: `desk, time, label, headline, headlineAccent, ticker` |
+| `reddit_post` | social-card | yes | 5s | positional: `subreddit, title` · named: `subreddit, author, title, body, votes` |
+| `spotify_card` | social-card | yes | 5s | positional: `track, artist` · named: `track, artist` |
+| `text_counter_stat` | text-anim | yes | 5s | positional: `value, label` · named: `value, label, prefix, suffix, color, accent` |
+| `text_glitch_title` | text-anim | yes | 5s | positional: `text` · named: `text, color` |
+| `text_gradient_sweep` | text-anim | yes | 5s | positional: `text` · named: `text, from, to` |
+| `text_kinetic_words` | text-anim | yes | 5s | positional: `text` · named: `text, color, accent` |
+| `text_line_stack` | text-anim | yes | 5s | positional: `line1, line2` · named: `line1, line2, line3, color, accent` |
+| `text_neon_flicker` | text-anim | yes | 5s | positional: `text` · named: `text, color` |
+| `text_scramble_decode` | text-anim | yes | 5s | positional: `text` · named: `text, color, accent` |
+| `text_typewriter_quote` | text-anim | yes | 5s | positional: `text, author` · named: `text, author, color, accent` |
+| `text_word_cascade` | text-anim | yes | 5s | positional: `text` · named: `text, color, accent` |
+| `tiktok_follow` | social-card | yes | 5s | positional: `displayName, handle` · named: `displayName, handle, followers, avatarUrl, url` |
+| `ui_3d_reveal` | other | yes | 13s | positional: `heroTitle` · named: `heroTitle, outroUrl` |
+| `vfx_iphone_device` | other | yes | 15s | positional: `imageUrl` · named: `imageUrl` |
+| `vpn_youtube_spot` | other | yes | 7s | positional: `headlineLine1` · named: `headlineLine1, headlineLine2, subtext, appTitle, appSubtitle` |
+| `x_post` | social-card | yes | 5s | positional: `displayName, handle` · named: `displayName, handle, body, hashtag, timestamp` |
+| `yt_lower_third` | lower-third | yes | 5s | positional: `channel, subscribers` · named: `channel, subscribers, avatarUrl` |
+
+## Unverified blocks
+
+Blocks with `verified: no` vendor upstream demo content and may ignore user params. `scenerok validate` warns but does not error.
+
+## Text animation blocks (`text-anim` family)
+
+Hand-authored, fully parameterized text/typography animations — staggered word reveals,
+scramble decode, kinetic word-per-beat typography, gradient sweeps, typed quotes, masked
+line stacks, count-up stats, RGB-split glitch, and neon flicker. All are transparent
+overlays (composite over video/scenes), honor every param, and scale to any output size.
+Prefer these over hand-authoring when a headline/caption/stat treatment fits; see the
+`text-anim` rows in `animations-picker.md` for intent mapping.
+
+## Custom HTML (bring your own animation)
+
+`animations.custom_html(...)` renders **your own HTML/CSS/JS** through the same HyperFrames
+pipeline as the catalog blocks. Use it when no catalog block fits and you want to hand-author
+an animation (or an agent generates one) using standard web tech.
+
+```vidscript
+import animations from "@scenerok/animations"
+
+# Each call takes exactly ONE source:
+[0s .. 5s] = animations.custom_html(html: "<!doctype html>...")     # inline HTML
+[5s .. 10s] = animations.custom_html(src: "https://cdn.example.com/intro.html")  # remote URL
+[10s .. 15s] = animations.custom_html(src: "./anim/hero.html")        # local file
+[15s .. 20s] = animations.custom_html(src: "scenerok://asset/123")    # uploaded asset
+
+# Sizing, timing, and author params. designWidth/designHeight: native authoring size
+# (default = output size). timelineId: default "custom-html". Any other named arg
+# (title, accent) is forwarded to window.__BLOCK.
+[20s .. 24s] = animations.custom_html(src: "scenerok://asset/123", designWidth: 1920, designHeight: 1080, timelineId: "my-anim", title: "Q3 Launch", accent: "#3b82f6")
+```
+
+Reserved named args (consumed by custom_html, NOT forwarded to `__BLOCK`): `src, html, mode,
+designWidth, designHeight, width, height, fit, duration, timelineId, zBand, x, y, opacity,
+responsive`. Every other named arg is forwarded to `window.__BLOCK[name]` (values become strings).
+
+### Author contract (required)
+
+Custom HTML is mounted in a **sandboxed cross-origin iframe** and driven one frame at a time.
+Your HTML MUST:
+
+1. Render on a **transparent** background, sized to its declared design dimensions
+   (e.g. `html,body { width:1920px; height:1080px; background:transparent; }`).
+2. Register a **paused** GSAP timeline at `window.__timelines['<timelineId>']` (default
+   `custom-html`). The host calls `tl.seek(t, false)` per frame.
+3. Treat `window.__HF_DURATION` (seconds) as "stay PAUSED — I am in the seek-driven host".
+   Auto-play only when it is `undefined`: `if (typeof window.__HF_DURATION === "undefined") tl.play();`.
+4. Read author params from `window.__BLOCK` (e.g. `window.__BLOCK.title`).
+5. Load libraries from the pinned allowlist below (or inline their source). GSAP + Three.js
+   are allowlisted; anything else must be pasted inline in a `<script>` tag.
+
+### Allowlisted libraries (loadable via `<script src>` / `<link>`)
+
+| Library | Pinned URL |
+| --- | --- |
+| GSAP | `https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js` |
+| Three.js (jsdelivr) | `https://cdn.jsdelivr.net/npm/three@0.147.0/build/three.min.js` (+ `examples/js/…`) |
+| Three.js (cdnjs) | `https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js` |
+| Google Fonts | `https://fonts.googleapis.com/css2?family=…` (files from `fonts.gstatic.com`) |
+
+Any **seekable** library works if you register it at `window.__timelines[id]` with a
+`.seek(seconds, false)` method. anime.js needs a unit adapter: `window.__timelines={x:{seek:t=>anim.seek(t*1000)}}`.
+Purely rAF-loop libraries with no time-scrubbing will NOT render frame-by-frame.
+
+### Minimal working template (GSAP)
+
+Copy-paste starting point that satisfies the whole contract — agents authoring custom
+animations should start from this skeleton and only change the markup, styles, and tweens:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=1920, height=1080" />
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 1920px; height: 1080px; overflow: hidden; background: transparent; }
+    #hero { position: absolute; inset: 0; display: flex; align-items: center;
+            justify-content: center; font: 900 160px system-ui; color: #fff; }
+  </style>
+</head>
+<body>
+  <div id="hero"></div>
+  <script>
+    (function () {
+      // 1. Params arrive via window.__BLOCK (every extra named arg, stringified).
+      var B = window.__BLOCK || {};
+      document.getElementById('hero').textContent = B.title || 'Hello';
+
+      // 2. Build a PAUSED timeline; the host drives it with tl.seek(t, false) per frame.
+      window.__timelines = window.__timelines || {};
+      var tl = gsap.timeline({ paused: true });
+      tl.from('#hero', { opacity: 0, y: 80, duration: 0.8, ease: 'power3.out' }, 0);
+      tl.to('#hero', { letterSpacing: '12px', duration: 4, ease: 'none' }, 0.4);
+
+      // Optional: window.__HF_DURATION (seconds) = the mounted [start .. end] window,
+      // injected before this script runs — use it to pace beats across the full window.
+
+      window.__timelines['custom-html'] = tl;  // key must match timelineId (default 'custom-html')
+
+      // 3. Standalone preview only — inside the host __HF_DURATION exists, stay paused.
+      if (typeof window.__HF_DURATION === 'undefined') tl.play();
+    })();
+  </script>
+</body>
+</html>
+```
+
+Gotchas: CSS `animation`/`transition` run on the wall clock and are NOT seek-driven — frames
+render wrong or frozen; drive every visual change through the registered timeline (use finite
+`repeat:` counts for loops, never `repeat: -1` — an infinite timeline breaks seeking). Avoid
+`Math.random()` per frame unless keyed off seek time — the same `t` must always draw the same
+frame (renders can revisit frames out of order).
+
+### Security constraints
+
+- Cross-origin sandboxed: author JS cannot reach the parent page, other surfaces, or the canvas.
+- Strict CSP: `connect-src 'none'` — no `fetch`/`XHR`/`WebSocket` at runtime. Pass data via
+  `__BLOCK` params. Images from `data:`/`https:`. External `<script src>` blocked except the
+  allowlist above (inline other libraries). DRACO-compressed glTF unsupported (decoder fetch blocked).
+- `mode: "inline"` is not supported (cannot be sandboxed) — it is a compile error. Blend/backdrop
+  overlays stay catalog-only.
+- Max HTML size 512 KB.
+
+## Usage
+
+```vidscript
+import animations from "@scenerok/animations"
+
+[0s .. 6s] = animations.code_typing("const x = 1;")
+[0s .. 5s] = animations.text_word_cascade("Make videos from plain text", accent: "#60a5fa")
+[5s .. 9s] = animations.text_counter_stat("12500", "Downloads", suffix: "+")
+```
+
+See `animations-picker.md` for intent-based selection. Preview samples: https://scenerok.com/catalog#animations

package/skills/scenerok/references/animations-picker.md

@@ -0,0 +1,88 @@
+# Animation Block Picker
+
+`import animations from "@scenerok/animations"` surfaces the vendored HyperFrames block catalog as positionable, time-windowed VidScript surfaces. Each `animations.<fn>(...)` call resolves to a `hyperframes` IR surface; no LLM runs at render time.
+
+**Reuse-first:** prefer `animations.<fn>(...)` over hand-authoring composition HTML. Full per-fn param shapes: `animations-catalog.md`.
+
+## Intent → `animations.<fn>(...)`
+
+| Intent | Family | `animations.<fn>(…)` | Positional args (in order) |
+| --- | --- | --- | --- |
+| typing / live code walk | code-anim | `code_typing` | `code`, `lang`, `theme`, `filename` |
+| scroll through a file | code-anim | `code_scroll` | `code`, `lang`, `theme` |
+| spotlight a line | code-anim | `code_highlight` | `code`, `lang`, `theme` |
+| 3D extrude / shader dissolve / particle title | code-anim | `code_3d_extrude` · `code_shader_dissolve` · `code_particle_assemble` | `code`, `theme` |
+| assemble snippets in flight | code-anim | `code_snippet_flight` | `code`, `theme` |
+| before/after code change | code-anim | `code_morph` · `code_diff` | `from`, `to`, `lang`, `theme` |
+| themed VS Code window | code-snippet | 24 `code_snippet_*` themes | `code`, `filename` |
+| Apple Terminal command + output | code-snippet | 12 `code_snippet_apple_terminal_*` | `command`, `output`, `prompt`, `title` |
+| broadcast name / title bar | lower-third | `lt_clean_bar` · `lt_accent_underline` · `lt_kicker_name` · `lt_mask_reveal` · `lt_stack_bars` | `title`, `subtitle`, `accent?` |
+| lower-third with kicker | lower-third | `lt_kicker_name` · `lt_side_rule` | `kicker`, `title`, `accent?` |
+| YouTube channel card | lower-third | `yt_lower_third` | `channel`, `subscribers`, `avatarUrl?` |
+| Bild-style brand accent | lower-third | `lower_third_bild` | `title`, `subtitle`, `accent?` |
+| inline text over footage | text-overlay | `lower_third` · `blend_caption` | inline `{{title}}` / `{{subtitle}}` tokens |
+| X / Twitter post | social-card | `x_post` | `displayName`, `handle`, `body?`, `hashtag?`, `timestamp?` |
+| Reddit thread | social-card | `reddit_post` | `subreddit`, `title`, `body?`, `author?`, `votes?` |
+| TikTok / Instagram follow | social-card | `tiktok_follow` · `instagram_follow` | `displayName`, `handle`, `avatarUrl?`, `url?` |
+| Spotify now-playing | social-card | `spotify_card` | `track`, `artist` |
+| macOS notification | social-card | `macos_notification` | `appName`, `title`, `body?`, `timeLabel?` |
+| news ticker / headline crawl | social-card | `news_ticker` | `headline`, `headlineAccent?`, `ticker?`, `desk?`, `time?` |
+| logo outro / brand sting | brand | `logo_outro` | `tagline`, `url?`, `brand?` (`"scenerok"` preset) or `logoUrl?`, `accent?` |
+| staggered word-reveal headline | text-anim | `text_word_cascade` | `text`, `color?`, `accent?` (accent tints last word) |
+| matrix-style decode / decrypt title | text-anim | `text_scramble_decode` | `text`, `color?`, `accent?` |
+| word-per-beat kinetic typography | text-anim | `text_kinetic_words` | `text` (space-separated words), `color?`, `accent?` |
+| animated gradient headline | text-anim | `text_gradient_sweep` | `text`, `from?`, `to?` (gradient colors) |
+| typed quote with attribution | text-anim | `text_typewriter_quote` | `text`, `author`, `color?`, `accent?` |
+| 2–3 line masked title stack | text-anim | `text_line_stack` | `line1`, `line2`, `line3?`, `accent?` |
+| count-up stat / metric | text-anim | `text_counter_stat` | `value`, `label`, `prefix?`, `suffix?`, `accent?` |
+| RGB-split glitch title | text-anim | `text_glitch_title` | `text`, `color?` |
+| neon sign flicker-on | text-anim | `text_neon_flicker` | `text`, `color?` (glow color) |
+| punchy kinetic title (no block) | kinetic-type | (use `text` + `motion.*` — see `text-styles.md`) | — |
+| no catalog block fits / author your own animation (HTML+CSS with GSAP, Three.js, or any seekable JS lib) | custom | `custom_html` | `src` or `html` — author contract, allowlisted libraries, and a minimal GSAP template in `animations-catalog.md` → "Custom HTML" |
+
+Param resolution: **named > positional > default**.
+
+## Gotchas
+
+| Block / family | Issue | Fix |
+| --- | --- | --- |
+| `code_diff` | Line indices may be 0-based in adapter | Match sample in `animations-catalog.md` |
+| Unverified blocks | `scenerok validate` warns `verified:false` | Accept demo render or switch to verified family |
+| Maps / liquid-glass / app-showcase | Ignore user params | Use for demo aesthetic only, or hand-author |
+| Adapter blocks | No inline audio/text siblings | Put `audio`, `text`, `filter` on separate time blocks |
+| `logo_outro` | Renders upstream demo's Figma-style mark when no logo param given | Pass `brand: "scenerok"` or `logoUrl: "<image url>"` |
+
+## Two-phase compose recipe
+
+**Part 1 — classify (before probing assets):**
+
+1. Decide intent family from the table above.
+2. Pick `animations.<fn>` (or `text` + `motion.*` for kinetic-type).
+3. Note param values from the user request.
+4. Draft time blocks: `[<start>s .. <end>s] = animations.<fn>(...)`.
+
+**Part 2 — compose (after probing assets):**
+
+1. Probe assets (logo, avatar, code) — never guess dimensions.
+2. Resolve params: named override positional; defaults fill the rest.
+3. Emit VidScript call.
+4. Adjacent `audio`, `text`, `filter` on **separate** time blocks.
+5. Run `scenerok validate script.vid`.
+
+## Demo script
+
+```vidscript
+import animations from "@scenerok/animations"
+import tr from "@scenerok/transitions"
+output to "demo.mp4", resolution: "1920x1080", fps: 30
+
+[0s .. 6s]   = animations.code_typing("let abc = 23; abc += 10; console.log(abc);")
+[6s .. 6.6s] = tr.dissolve()
+[6.6s .. 13s] = animations.code_morph("const a = 1", "const a = 2")
+[13s .. 19s] = animations.code_typing(code: "const z = 5;", duration: 6, filename: "app.ts", theme: "monokai")
+[19s .. 24s] = animations.lt_clean_bar("Ada Lovelace", "Engineer", accent: "#00ff00")
+[24s .. 29s] = animations.x_post("SceneRok", "@scenerok", body: "Shipped adapters.", hashtag: "#v1")
+[29s .. 34s] = animations.news_ticker("Tech Desk", time: "15:30 UTC",
+                                       headline: "SceneRok ships", headlineAccent: "53 verified blocks",
+                                       ticker: "Verified count: 53/78\nBeta opens July")
+```

package/skills/scenerok/references/brand-setup.md

@@ -0,0 +1,71 @@
+# Brand Setup for Agents
+
+Collect brand context **only when it improves the video** and **only when your runtime allows asking the user or discovering assets**. Never block composition on a long questionnaire.
+
+## When to ask (vs infer)
+
+| Situation | Action |
+| --- | --- |
+| User gave product/company URL + you can browse | Extract colors, logo, hero imagery from the site first |
+| User mentioned a brand by name with no assets | Ask for logo URL and primary color (one message, ≤3 fields) |
+| Template has `color` placeholders | Use template defaults; offer to customize |
+| Motion graphic / code demo with no brand | Skip brand questions |
+| User already specified hex colors / logo | Use as-is; do not re-ask |
+
+**Ask at most one short brand message** with combined fields, not a multi-step wizard.
+
+## What to collect (priority order)
+
+1. **Primary brand color** — hex, e.g. `#6366F1` (for text `color:`, lower-third `accent:`, animation `accentColor:`)
+2. **Logo** — HTTPS URL or uploaded asset (editor library / ChatGPT import / local path on CLI)
+3. **Secondary / text color** — default white `#FFFFFF` on dark or dark `#0F172A` on light
+4. **Font preference** — only if user cares; default `Inter` / system stacks in examples
+5. **Tagline or CTA** — for promos and `logo_outro`
+
+## Where brand lands in VidScript
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+import animations from "@scenerok/animations"
+
+input logo = "https://cdn.example.com/brand-logo.png"
+
+let brandColor = "#6366F1"
+
+[0s .. 3s] = text "Launch Week", color: brandColor, style: title, animate: motion.popIn(0.6s)
+[3s .. 8s] = animations.lt_clean_bar("Product Name", "Tagline here", accent: brandColor)
+[8s .. 14s] = animations.logo_outro("Thanks for watching", url: "scenerok.com", logoUrl: logo)
+```
+
+Use `accent`, `accentColor`, and `color` params consistently across text and animation blocks.
+
+**`logo_outro` branding:** without `logoUrl` or `brand`, the outro renders the upstream demo's colorful Figma-style mark — never ship that on a branded video. Pass `logoUrl:` (user's logo image) or `brand: "scenerok"` (built-in SceneRok preset, also tints the glow), plus `accent:` to override the glow color.
+
+## Per-environment collection
+
+| Environment | How to get brand assets |
+| --- | --- |
+| **Web editor** | Ask in chat; user can upload to asset library and paste URLs into script |
+| **CLI / desktop agent** | Ask in terminal; accept local paths; user may run `scenerok auth login` for cloud assets |
+| **ChatGPT** | Ask in conversation; user uploads logo/screenshot → `importOpenAIConversationFiles` → use returned `asset.url` |
+| **URL-only (no uploads)** | Screenshot logo from site; probe dimensions before placement |
+
+## Website-derived brand (preferred when URL given)
+
+1. Visit the URL (browser tool or user-provided screenshots).
+2. Note dominant accent from buttons, links, or hero — sample one hex.
+3. Save logo and product stills; **probe width/height** before composing.
+4. Do not invent claims, pricing, or testimonials — extract or ask.
+
+See `workflow.md` for the full URL asset pipeline.
+
+## Defaults when user declines
+
+- Accent: `#6366F1` (SceneRok indigo) or high-contrast pair white on `#0B1020`
+- No logo: kinetic `text` + `motion.popIn` instead of `logo_outro`
+- Music: neutral instrumental bed from `music.md`
+
+## Privacy
+
+- Do not paste API tokens or OAuth secrets into VidScript or chat logs.
+- Use only assets the user provided or that are public on their stated URL.