@scenerok/sdk 0.7.0 → 0.8.0

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

@@ -0,0 +1,44 @@
+# VidScript sample: a 13-second product promo
+
+A complete script to copy and adapt: two generated shots joined by a dissolve,
+titles in named areas, a voiceover, and a music bed that ducks under it.
+Validate it before rendering.
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+import tr from "@scenerok/transitions"
+
+# Copy lives in variables so it is easy to change.
+let product = "RokMilk"
+let hook = "Chocolate milkshake, ready in seconds"
+let cta = "Find it at your nearest grocery store"
+
+# Generated media is bound with let, so its real length is known.
+# Prompts never ask for text; all copy is added with `text` below.
+let kitchen = xai.imagine("Chocolate milk carton on a sunlit kitchen counter, cinematic lighting, shallow depth of field, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 6)
+let pour = xai.imagine("Slow pour of chocolate milkshake into a tall glass, macro, warm light, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 6)
+let vo = xai.tts("Meet RokMilk. Chocolate milkshake, ready in seconds. Find it at your nearest grocery store.", voice: "eve")
+let bed = eleven.music("Warm, upbeat acoustic bed for a food ad", duration: 13, instrumental: true)
+
+# Picture: each [-] starts where the previous visual block ended.
+[-] = kitchen
+[- 0.6s] = tr.dissolve()
+[-] = pour
+
+# Titles go in named areas, never at guessed coordinates.
+[0s .. 3s] = text product, style: title, area: "title", animate: motion.popIn(0.6s)
+[3s .. 7s] = text hook, area: "lower-third", animate: motion.riseIn(0.6s)
+[9s .. 12.6s] = text cta, area: "caption", animate: motion.fadeIn(0.5s)
+
+# Sound: the voiceover runs for its measured length; the bed ducks under it.
+[0s .. vo.duration] = audio vo
+[0s .. 13s] = audio bed, volume: 0.6, duck_under: vo, fade_out: 1.5s
+
+output to "rokmilk-promo.mp4", resolution: "1080x1920", fps: 30
+```
+
+To cut your own footage instead of generating it, replace the `let … =
+xai.imagine(…)` lines with `input` declarations and see `editing-actions.md`.
+The `@scenerok/cli` package ships more scripts in `examples/system/`.

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

@@ -0,0 +1,266 @@
+# VidScript v2 — Strict Agent Reference
+
+Follow these rules exactly. For a complete working script, see `vidscript-sample.md`; for cuts, layering, masks, audio mixing, and grading, see `editing-actions.md`.
+
+## Rule 1: Package imports are mandatory
+
+```vidscript
+import xai from "@scenerok/xai"
+import cf from "@scenerok/cloudflare"
+import eleven from "@elevenlabs/music"
+import motion from "@scenerok/basic-animations"
+```
+
+Without the owning import, calls like `xai.imagine`, `cf.video`, `xai.tts`, `eleven.music`, and `motion.fadeIn` fail validation.
+
+**Never** call package functions without importing the package alias first.
+
+## Rule 2: Use URL assets selectively
+
+A product or landing-page URL is optional source material. Capture focused, legible pieces (above-the-fold views, product shots, logos), never full-page screenshots as backgrounds, and don't invent claims. The full URL workflow is in `workflow.md`.
+
+## Rule 2.5: Probe real asset type and dimensions before placement
+
+Before writing `width`, `height`, `x`, or `y` for a real image/video/screenshot/logo, identify the asset type and inspect the actual dimensions and duration:
+
+```bash
+file asset.png
+ffprobe -v error -select_streams v:0 -show_entries stream=width,height,duration -of csv=p=0 asset.mp4
+sips -g pixelWidth -g pixelHeight asset.png
+identify asset.webp
+```
+
+Use real video files for motion footage and still image inputs for screenshots, logos, product photos, and brand marks. The `video` primitive accepts both videos and images; image inputs render as static clips for the block duration.
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+input screenshot = "assets/screenshots/homepage.png"
+[0s .. 4s] = video screenshot, width: 1080, height: 1920, x: 0, y: 0, animate: motion.fadeIn(0.35s)
+```
+
+Use measured aspect ratio and safe-area math. Do not guess sizes or blindly resize every asset to the same box. Center visuals with explicit pixel placement when possible:
+
+```text
+x = (outputWidth - scaledWidth) / 2
+y = safeAreaTop
+```
+
+Add entry motion to real assets, not only text. When a static visual needs a clean exit, split it:
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+input product = "assets/product.png"
+[0s .. 3.4s] = video product, width: 760, height: 615, x: 160, y: 300, animate: [motion.riseIn(0.6s, 70), motion.float(2.4s, 8)]
+[3.4s .. 4s] = video product, width: 760, height: 615, x: 160, y: 300, animate: motion.fadeOut(0.6s)
+```
+
+## Rule 3: Generated media prompts must forbid text
+
+AI-generated images and videos must not contain readable text. In every prompt for generated visual media, explicitly ask for no text, no words, no letters, no captions, no logos, no watermarks, and no readable UI copy. SceneRok has strong text primitives; all final titles, subtitles, offers, prices, feature labels, disclaimers, and CTAs must be added with VidScript `text` instructions instead of being baked into generated media.
+
+Good prompt pattern:
+
+```vidscript
+import xai from "@scenerok/xai"
+
+[-] = video xai.imagine("Clean cinematic product background, premium lighting, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 5)
+[0.5s .. 3s] = text "Launch offer", style: title, color: "#FFFFFF", area: "title", stroke: "#000000", stroke_width: 3
+```
+
+Invalid: asking the generator for signs, labels, packaging text, app UI text, title cards, lower thirds, prices, CTA buttons, or any readable copy.
+
+## Rule 4: Use registered plugin surfaces
+
+```vidscript
+import xai from "@scenerok/xai"
+import cf from "@scenerok/cloudflare"
+import eleven from "@elevenlabs/music"
+
+[- 4s] = video xai.image("Prompt here, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", resolution: "2k")
+[-] = video xai.imagine("Prompt here, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 5)
+[-] = video xai.imageToVideo("https://cdn.example.com/product.png", "Slow camera move around the product, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 6)
+[-] = video xai.referenceToVideo(["https://cdn.example.com/product.png", "https://cdn.example.com/person.png"], "Lifestyle scene using the referenced product and person, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 8)
+[-] = video xai.extendVideo("https://cdn.example.com/clip.mp4", "Continue the camera move, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", duration: 5)
+[-] = audio xai.tts("Voiceover line", voice: "eve")
+
+[-] = video cf.video("Prompt here, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", model: "pixverse/v6", aspect_ratio: "9:16", duration: 5, generate_audio: false)
+[-] = video cf.imageToVideo("https://cdn.example.com/product.png", "Animate the image, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", model: "runwayml/gen-4.5", aspect_ratio: "9:16", duration: 5)
+[0s .. 15s] = audio eleven.music("Warm premium music bed", duration: 15, instrumental: true)
+```
+
+Do not overuse one plugin function. Choose deliberately:
+
+| Need | Use |
+|------|-----|
+| Still image clip | `xai.image`, `xai.generateImage`, `cf.image`, `cf.generateImage` |
+| Text-to-video | `xai.imagine`, `xai.genVideo`, `cf.video`, `cf.imagine`, `cf.generateVideo` |
+| Animate one image/screenshot/product photo | `xai.imageToVideo`, `cf.imageToVideo` |
+| Guide with 1-7 reference images | `xai.referenceToVideo`, `cf.referenceToVideo` |
+| Continue a clip | `xai.extendVideo`, `cf.extendVideo` |
+| Voiceover | `xai.tts`, `xai.textToSpeech` |
+| Music bed | `eleven.music`, `eleven.generateMusic`, `eleven.composeMusic` |
+
+Use `imageToVideo` for one extracted screenshot/product/logo image and `referenceToVideo` for 1–7 reference images (xAI: prompt required, duration ≤ 10s). Cloudflare calls take an explicit `model:` and `aspect_ratio:`; models, signatures, and durations are in `ai-models.md` and the plugin table in `vidscript-guide.md`.
+
+xAI TTS voices are only `eve`, `ara`, `rex`, `sal`, and `leo`. ElevenLabs is music only (`eleven.music`, `eleven.generateMusic`, `eleven.composeMusic`); there is no `eleven.tts`. Ads, promos, tutorials, and reels should normally have a voiceover, a music bed, or both unless the user asks for silence.
+
+## Rule 4.5: `[-]` uses separate audio and visual playheads
+
+Use `[-]` freely for generated visual sequences even when audio is already scheduled. VidScript advances audio and visual auto blocks independently:
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+
+input family_image = "https://cdn.example.com/family.png"
+let bed = eleven.music("Warm family music", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
+[-] = video xai.imageToVideo(family_image, "Warm family moment, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 15)
+```
+
+The video starts at the visual playhead, usually `0s`; it is not pushed to `15s` by the audio bed. Audio blocks such as `[-] = audio xai.tts(...)` advance only the audio playhead. Visual blocks such as `[-] = video ...` and `[-] = text ...` advance only the visual playhead. A block containing both audio and visual instructions advances both.
+
+Use explicit ranges when you need exact synchronization, overlaps, or cuts. Do not avoid `[-]` solely because the script contains music or voiceover.
+
+## Rule 4.6: Never guess generated-asset durations
+
+Avoid — the real TTS length is unknown at write time, so a guessed window clips or overlaps:
+
+```vidscript avoid
+import xai from "@scenerok/xai"
+
+[0s .. 3s] = audio xai.tts("A sentence that may well run past three seconds", voice: "eve")
+[3s .. 6s] = audio xai.tts("This one starts while the first is still playing", voice: "eve")
+```
+
+Do this — assign with `let` and reference the measured `duration` (arithmetic allowed), or use `[-]` auto blocks:
+
+```vidscript
+import xai from "@scenerok/xai"
+
+let vo1 = xai.tts("First line", voice: "eve")
+let vo2 = xai.tts("Second line", voice: "eve")
+[0 .. vo1.duration] = audio vo1
+[vo1.duration + 0.3 .. vo1.duration + 0.3 + vo2.duration] = audio vo2
+```
+
+Exported timelines expose `.duration` the same way: `[scene1.duration .. scene1.duration + 4] = ...`.
+
+## Rule 4.7: Prefer `area:` over hand-picked text coordinates
+
+Built-in named regions work with no setup and guarantee the text fits its cell (wrap + shrink + bounds):
+
+```vidscript
+[0 .. 3] = text "BIG SALE", area: "title"
+[0 .. 3] = text "50% off this week", area: "lower-third"
+```
+
+Available by default: `title`, `stage`, `lower-third`, `caption`. Custom layouts: `grid rows: "20% 1fr 30%", areas: ["title", "stage", "caption"]` (CSS Grid semantics, `%`/`fr` tracks only). Explicit `x`/`y` still work and override the area — use them only when a region genuinely doesn't fit the design.
+
+**TypeScript SDK:** same regions via `t.grid({ rows, cols?, areas })` and `text(..., { area: 'title' })` — see `sdk-guide.md`.
+
+## Rule 5: Time ranges use `..`
+
+```vidscript
+[0s .. 5s] = text "Hello"
+```
+
+Not `[0s - 5s]`.
+
+## Rule 6: Text params stay on one line
+
+```vidscript
+[0.5s .. 3s] = text "Headline", font: "Inter", size: 64, color: "#FFFFFF", x: "50%", y: "30%", align: center
+```
+
+## Rule 7: Quote safety in prompts
+
+Escape quote characters inside prompt strings, e.g. `xai.imagine("Package labeled \"RokMilk\", no text, no watermark")`.
+
+## Rule 8: Audio syntax
+
+```vidscript
+import xai from "@scenerok/xai"
+import cf from "@scenerok/cloudflare"
+import eleven from "@elevenlabs/music"
+
+[-] = audio xai.tts("Spoken line", voice: "eve", speed: 1.0)
+
+# Direct music call, no trailing audio params.
+[0s .. 15s] = audio eleven.music("Soft premium ad music", duration: 15, instrumental: true)
+
+# Use a binding when you need volume or fades.
+let bed = eleven.music("Soft premium ad music", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
+```
+
+**Invalid:** `audio eleven.music("...", duration: 15), volume: 0.35` — trailing `, volume` after a direct plugin call is a parse error.
+
+**Invalid:** `eleven.generateMusic(...)` without `import eleven from "@elevenlabs/music"`.
+
+**Invalid:** `eleven.tts(...)` — not a registered function; use `xai.tts(...)`.
+
+**Invalid:** `cf.video(...)` without `import cf from "@scenerok/cloudflare"`.
+
+## Rule 9: Filters
+
+```vidscript
+[0s .. 15s] = filter "vignette", intensity: 0.3
+[0s .. 15s] = filter "saturation", amount: 1.12
+```
+
+Filters are optional finishing tools, not required ingredients. Use them only when they improve the visual result. Each filter has its own parameter name (`saturation` takes `amount`, `blur` takes `radius`); a wrong name is ignored without an error. The table is in `editing-actions.md` → Color and finishing.
+
+A `filter` line grades everything in its window. To grade one clip, add `target: clip` or write `clip.Filter("sepia", intensity: 0.6)`.
+
+## Rule 10: Always end with output
+
+```vidscript
+output to "video.mp4", resolution: "1080x1920", fps: 30
+```
+
+Do **not** use legacy `config { }` blocks — they are not part of VidScript v2.
+
+## Rule 11: Edits are values — place the result
+
+`Trim`, `Speed`, `Loop`, `Crop`, `Resize`, `Mask`, `Filter`, `Overlay`, and `Composite` return a new value. Place the result in one line:
+
+```vidscript
+input hero = "hero.mp4"
+input logo = "logo.png"
+[0s .. 4s] = hero.Trim(2s, 6s).Crop(420, 0, 1080, 1920)
+[4s .. 8s] = hero.Trim(6s, 10s).Overlay(logo.Resize(200, 200), x: 840, y: 60)
+```
+
+- A placed value lasts its own length (trimmed range ÷ speed × loops). Make the window that long.
+- Put one video over another with `Overlay`, `Composite`, or `blend:`. Two plain clips in the same window have no defined order.
+- `Mask` on its own line after the clip is placed is a compile error.
+- Frame counts are written `48 frame` and use the output fps (30 if `output` has none).
+
+All editing actions (masks, speed ramps, ducking, LUTs, timecode): `editing-actions.md`.
+
+## Animations (after import)
+
+```vidscript
+import motion from "@scenerok/basic-animations"
+
+[0s .. 2s] = text "Launch", x: "50%", y: "50%", animate: motion.popIn(0.7s)
+```
+
+Available: `fadeIn`, `fadeOut`, `slideX`, `slideY`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter`.
+
+## Validate before render
+
+```bash
+scenerok validate my-video.vid
+```
+
+Each error line includes `Line N:C — message` when the server returns location info.
+
+## Bundled examples
+
+The `@scenerok/cli` npm package ships working scripts in `examples/system/`: `minimal-text-reel.vid` (text only), `product-launch.vid` (your own video + text), `ecom-product-launch.vid` (generated product visuals + CTA), `3-tips-fitness.vid` (several `[-]` blocks), `rokmilk-chocolate-promo.vid` (15 s generated promo).
+
+Full grammar: `vidscript-guide.md`.

package/skills/scenerok/references/workflow.md

@@ -0,0 +1,71 @@
+# SceneRok Compose Workflow
+
+## Pipeline
+
+1. **Understand the goal** — promo, testimonial, meme, code demo, etc.
+2. **Choose authoring** — VidScript (`.vid`) by default and for every editing action; TypeScript `@scenerok/sdk` (`.ts`, `sdk-guide.md`) only for loops or computed timing
+3. **Plan the structure** — time blocks, durations, inputs
+4. **Gather assets** — URLs, local paths, generated clips, selective website screenshots
+5. **Probe asset type and dimensions** — `loadVideo` / media stdlib, or `file` / `ffprobe` / `sips` / `identify`; never guess
+6. **Use images directly when useful** — VidScript `video image_input`; SDK `video(path)` / `loadVideo`
+7. **Choose plugin modality** — still / t2v / i2v / ref2v / extend / TTS / music (`ai-models.md`, `tts.md`, `music.md`)
+8. **Compose** — measured dimensions, `area:` / `t.grid` for text, symbolic durations (`vo.duration` / returned node `.duration`), entry/exit beats
+9. **Validate** — `scenerok validate script.vid` or `scenerok validate scene.ts`
+10. **Deep-validate (VidScript)** — for scripts with TTS/generated media: `scenerok validate script.vid --generate-assets --report-json` (billed; assets cache for the render). SDK plugins generate during `scenerok render` instead. Fix `offCanvas`/`wasShrunk` text, `collisions`, and unintended `audio.overlaps`, then re-validate.
+11. **Render** — `scenerok render script.vid --watch` or `scenerok render scene.ts --watch`
+12. **Check the render** — `scenerok lint-video <render-id> --cost medium --json` (billed); fix and re-render if it reports problems. `scenerok render script.vid --validate` does render and check in one step
+13. **Deliver** — share download URL when complete
+
+## Website URL asset workflow
+
+When the user provides a product, company, landing page, or ecommerce URL:
+
+1. Visit the URL with a browser tool before composing.
+2. Capture screenshots sparingly — above-fold, product closeups, pricing cards. Avoid full-page backgrounds.
+3. Crop to the visual evidence needed.
+4. Save product images, logos, app screenshots when accessible.
+5. Probe saved asset dimensions before composing.
+6. Use stills as timeline inputs or feed into `xai.imageToVideo` / `xai.referenceToVideo` (VidScript or SDK).
+7. Combine real assets with generated clips, text, and music.
+8. Scale from measured aspect ratio; keep primary visuals in ~80–88% frame width for 9:16.
+9. Animate assets: `motion.popIn` / SDK `popIn`, `fadeIn`, `slideY`.
+10. Generative prompts must require **no text, logos, watermarks, or readable UI** in AI output — add copy with `text`.
+11. Do not invent product claims — extract from site or ask the user.
+
+## Best practices
+
+- VidScript: `[-]` for channel-aware auto-append; SDK: `t.push(...)` / `t['-'] = ...`
+- Never guess TTS/music durations — bind the result and use `.duration`
+- Never guess text coordinates — VidScript `area: "title"`; SDK `t.grid(...)` + `text(..., { area: 'title' })`
+- Named arguments (VidScript): `hero.Trim(start: 0s, end: 5s)`
+- 1080×1920 vertical (TikTok/Instagram); 1920×1080 horizontal (YouTube)
+- Hook in first 3 seconds; high-contrast text with stroke when needed
+- Each render costs tokens (renders + AI plugins)
+
+## CLI commands
+
+```bash
+scenerok auth login
+scenerok validate script.vid
+scenerok validate scene.ts
+scenerok render script.vid --watch
+scenerok render scene.ts --watch
+scenerok status <render-id>
+scenerok skills install <platform>   # installs the skill (SKILL.md + references)
+scenerok skills check [--json]       # is the installed copy current?
+scenerok skills update               # refresh it from scenerok.com
+```
+
+## Error handling
+
+If render fails: check `scenerok status <id>`, fix missing assets or syntax, re-render.
+
+## Sample video types
+
+- **Product promo** — hero + headline + CTA
+- **Social hook** — fast cuts, bold text
+- **Testimonial** — speaker clip + quote overlay
+- **Meme remix** — reaction clip + punchlines
+- **Title sequence** — background + glitch + typography
+
+For brand colors, logos, and accents see `brand-setup.md`. Ask the user only when your environment allows conversation and brand context is missing.