@scenerok/cli 1.0.11 → 1.0.13

package/package.json

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

package/skills/shared/SKILL.md

@@ -37,7 +37,7 @@ input logo = "/uploads/logo.png"
 
 **Time Blocks** - Define what happens during a time range:
 ```vidscript
-[-] = hero                               # auto-append: starts after previous block
+[-] = hero                               # auto-append: starts at visual cursor
 hero.Trim(start: 0s, end: 5s)
 
 [- 3s] = text "Hello", style: title, color: "#FFF"   # auto-start, 3s duration
@@ -45,6 +45,8 @@ hero.Trim(start: 0s, end: 5s)
 [prev + 0.5s .. prev + 2s] = filter "glow"            # expression-based
 ```
 
+`[-]` timing is channel-aware. Visual blocks (`video`, `text`, filters, visual plugin calls, bare visual inputs) advance a visual playhead. Audio blocks (`audio`, `xai.tts`, `eleven.music`) advance an audio playhead. A 15s music bed or multiple TTS blocks do not delay the next `[-] = video ...` block; that video starts from the visual playhead. Mixed blocks advance both playheads, and `prev` follows the relevant channel for the block being compiled.
+
 **Video Operations** - Modify how video plays:
 ```vidscript
 hero.Trim(start: 0s, end: 5s)      # trim clip
@@ -80,35 +82,54 @@ output to "video.mp4", resolution: "1080x1920", fps: 30
 ### Package Imports
 
 ```vidscript
-import xai from "@scenerok/xai"                    # xAI image/video/tts
-import eleven from "@elevenlabs/music"          # ElevenLabs generative music
-import motion from "@scenerok/basic-animations" # text/video animation helpers
+import xai from "@scenerok/xai"                  # xAI image/video/tts
+import cf from "@scenerok/cloudflare"            # Cloudflare AI Gateway image/video models
+import eleven from "@elevenlabs/music"           # ElevenLabs generative music
+import motion from "@scenerok/basic-animations"  # text/video animation helpers
 ```
 
 ### Plugin Calls
 
 ```vidscript
 import xai from "@scenerok/xai"
+import cf from "@scenerok/cloudflare"
 import eleven from "@elevenlabs/music"
 import motion from "@scenerok/basic-animations"
 
-[-] = video xai.imagine("Cinematic product shot, premium lighting, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 5)
+[- 4s] = video xai.image("Premium product still on seamless studio background, 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("Cinematic product video, premium lighting, 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 premium 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 ad shot featuring 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", "Camera pulls back to reveal the full premium setup, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", duration: 5)
 [-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 
+# Cloudflare gives access to multiple image/video providers through one package.
+[-] = video cf.video("High-energy fashion product shot, handheld camera feel, 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 product with realistic parallax and soft studio lighting, 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)
+[- 4s] = video cf.image("Clean editorial product still, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", model: "black-forest-labs/flux-2-pro-preview", aspect_ratio: "9:16")
+
 # ElevenLabs music package functions require an import alias.
 let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
 [0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
 ```
 
-**Always** import the package that owns the function: `xai.*` from `@scenerok/xai`, `eleven.*` from `@elevenlabs/music`, and `motion.*` from `@scenerok/basic-animations`. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+**Always** import the package that owns the function: `xai.*` from `@scenerok/xai`, `cf.*` from `@scenerok/cloudflare`, `eleven.*` from `@elevenlabs/music`, and `motion.*` from `@scenerok/basic-animations`. Calls without import fail validation with `Unknown function 'xai.imagine'`.
+
+Use the full visual toolkit, not only `xai.imagine()`. Generate a still first with `xai.image(...)`, `xai.generateImage(...)`, `cf.image(...)`, or `cf.generateImage(...)` when a clean key visual is enough. Use `xai.imageToVideo(image, prompt, ...)` or `cf.imageToVideo(image, prompt, ...)` when you have one strong product/screenshot/logo image to animate. Use `xai.referenceToVideo([images...], prompt, ...)` or `cf.referenceToVideo([images...], prompt, ...)` when extracted objects, screenshots, product photos, people, packaging, or brand elements should guide the generated scene. Use `xai.extendVideo(...)` or `cf.extendVideo(...)` when an existing generated/user clip should continue.
+
+Available plugin APIs:
 
-Use the full xAI visual toolkit, not only `xai.imagine()`: use `xai.imageToVideo(image, prompt, ...)` when you have one strong product/screenshot/logo image to animate, and `xai.referenceToVideo([images...], prompt, ...)` when extracted objects, screenshots, product photos, people, packaging, or brand elements should guide the generated scene. Reference-to-video requires a prompt, accepts up to 7 reference images, and should stay at 10 seconds or less.
+| Package | Functions | Typical use |
+|---------|-----------|-------------|
+| `@scenerok/xai` | `image`, `generateImage`, `imagine`, `genVideo`, `imageToVideo`, `referenceToVideo`, `extendVideo` | Grok stills, text-to-video, image/reference-guided video, clip extension |
+| `@scenerok/xai` | `tts`, `textToSpeech`, `listVoices` | Spoken narration and voice lookup |
+| `@scenerok/cloudflare` | `image`, `generateImage`, `imagine`, `genVideo`, `generateVideo`, `video`, `imageToVideo`, `referenceToVideo`, `extendVideo`, `listModels`, `models` | Alternate providers/models through Cloudflare AI Gateway, including PixVerse, Vidu, Runway, MiniMax, Seedance, Veo, FLUX, GPT Image, Recraft |
+| `@elevenlabs/music` | `music`, `generateMusic`, `composeMusic` | Background music beds, theme music, instrumental loops |
+| `@scenerok/basic-animations` | `fadeIn`, `fadeOut`, `slideX`, `slideY`, `popIn`, `riseIn`, `swingIn`, `glitchIn`, `float`, `typewriter` | Motion descriptors for `animate:` |
 
 xAI TTS voice IDs: `eve` for demos/announcements/upbeat content, `ara` for warm conversational narration, `rex` for business/tutorial delivery, `sal` for balanced general narration, and `leo` for authoritative instructional narration.
 
-For ElevenLabs music, import `@elevenlabs/music` and call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Use `let bed = eleven.music(...)` followed by `audio bed, volume: ...` when you need volume or fades.
+For ElevenLabs music, import `@elevenlabs/music` and call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Use `let bed = eleven.music(...)` followed by `audio bed, volume: ...` when you need volume or fades. Do not call `eleven.tts(...)`; this repo currently exposes voiceover through `xai.tts(...)` / `xai.textToSpeech(...)`. Place voiceover as an `audio` block and do not leave ads silent unless the user asks for silent output.
 
 Read `vidscript-strict.md` for anti-patterns and `examples/system/*.vid` for copy-paste templates (installed with `scenerok skills install`).
 
@@ -127,10 +148,11 @@ input hero = "{{hero_clip}}"
 3. **Gather assets** — Video URLs, local paths, generated clips, and selective website screenshots/images; when the user provides a URL, browser screenshots are optional source material, not a requirement to build the whole video from screenshots
 4. **Probe asset type and dimensions** — Inspect every local or downloaded asset before placing it. Use `file` to identify image vs video, `ffprobe` for video/audio, `sips -g pixelWidth -g pixelHeight file` on macOS images, or `identify file` when ImageMagick is available.
 5. **Use images directly when useful** — VidScript `input` supports both videos and images. You can place a still image input with `video image_input`; the renderer detects the asset type and treats it as a static visual clip for the block duration.
-6. **Compose VidScript** — Write the full script using measured dimensions, aspect-ratio-preserving scale, centered/safe-area placement, and entry/exit animation beats for each visual asset
-7. **Validate** — Run `scenerok validate script.vid`
-8. **Render** — Run `scenerok render script.vid --watch`
-9. **Deliver** — Share the download URL when complete
+6. **Choose plugin modality deliberately** — still image, text-to-video, image-to-video, reference-to-video, video extension, TTS, and music are separate tools; use the one that matches the assets and story beat
+7. **Compose VidScript** — Write the full script using measured dimensions, aspect-ratio-preserving scale, centered/safe-area placement, entry/exit animation beats, and audio blocks when the video needs narration or a music bed
+8. **Validate** — Run `scenerok validate script.vid`
+9. **Render** — Run `scenerok render script.vid --watch`
+10. **Deliver** — Share the download URL when complete
 
 ## Website URL Asset Workflow
 
@@ -145,14 +167,14 @@ When the user provides a product, company, landing page, app store listing, or e
 7. Use captured assets as grounded proof points alongside other visual material. A good ad can combine product/logo/app screenshots, generated video clips, motion backgrounds, text primitives, and music.
 8. Scale assets from their measured aspect ratio to fit the output frame and safe areas. For 1080x1920 ads, keep primary visuals inside roughly 80-88% of frame width and reserve enough top/bottom room for text.
 9. Animate visual assets intentionally: use entry animations such as `motion.popIn`, `motion.riseIn`, or `motion.slideY`; use short exit fade/slide segments when a clean transition is needed.
-10. Generative visuals are encouraged when useful. Choose among `xai.imagine` for text-to-video, `xai.imageToVideo` to animate one extracted image/screenshot/product photo, and `xai.referenceToVideo` to guide a generated scene with up to 7 extracted visual references.
+10. Generative visuals are encouraged when useful. Choose among still generation (`xai.image`, `xai.generateImage`, `cf.image`, `cf.generateImage`), text-to-video (`xai.imagine`, `xai.genVideo`, `cf.video`, `cf.generateVideo`), image-to-video (`xai.imageToVideo`, `cf.imageToVideo`), reference-to-video (`xai.referenceToVideo`, `cf.referenceToVideo`), and clip extension (`xai.extendVideo`, `cf.extendVideo`).
 11. For every generated visual prompt, explicitly require a clean scene with no text, no words, no letters, no captions, no logos, no watermarks, and no readable UI copy. AI video generation often corrupts text; all final titles, offers, captions, CTAs, prices, and labels must be created with VidScript `text` primitives.
 12. Do not invent product claims. Extract copy, pricing, feature names, social proof, and CTA language from the site or ask the user.
 
 ## Best Practices
 
-- **Use dynamic timeblocks** — `[-]` auto-advances the cursor, reducing calculation errors
-- **Use `prev` for offsets** — `[prev + 0.5s .. prev + 2s]` for gaps between content
+- **Use dynamic timeblocks** — `[-]` auto-advances the relevant audio or visual cursor, reducing calculation errors
+- **Use `prev` for offsets** — `[prev + 0.5s .. prev + 2s]` for gaps between content in the same channel
 - **Named arguments for clarity** — `hero.Trim(start: 0s, end: 5s)` over `hero.Trim(0s, 5s)`
 - **Use website assets judiciously for URL-based ads** — browser screenshots, product images, app screenshots, and logos can ground the ad, but they are optional ingredients, not the whole recipe
 - **Avoid full-page screenshot backgrounds** — use above-fold, cropped, or focused screenshots that remain legible at video size; never rely on long website screenshots where the text becomes unreadable

package/skills/shared/vidscript-guide.md

@@ -4,22 +4,25 @@ VidScript is a declarative DSL for composing short-form videos. Write a script,
 
 ## Agent quick start (read before composing)
 
-1. **Import every package function** — use `import xai from "@scenerok/xai"`, `import eleven from "@elevenlabs/music"`, and `import motion from "@scenerok/basic-animations"` before calling `xai.*`, `eleven.*`, or `motion.*`.
+1. **Import every package function** — use `import xai from "@scenerok/xai"`, `import cf from "@scenerok/cloudflare"`, `import eleven from "@elevenlabs/music"`, and `import motion from "@scenerok/basic-animations"` before calling `xai.*`, `cf.*`, `eleven.*`, or `motion.*`.
 2. **Validate early** — `scenerok validate file.vid` (errors show as `Line N:C — message`).
 3. **Music package syntax** — `import eleven from "@elevenlabs/music"`, then call `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`.
 4. **Copy working examples** — see `examples/system/` in this skill folder (e.g. `minimal-text-reel.vid`, `ecom-product-launch.vid`, `rokmilk-chocolate-promo.vid`).
 5. **Use URL assets selectively** — if the user gives a website or product URL and browser screenshot tools are available, you can capture above-fold screenshots, product images, app screenshots, and logos for VidScript `input` assets. Do not treat screenshots as mandatory or as the only visual source.
 6. **Probe asset type and dimensions** — before placing real assets, identify image vs video with `file`; inspect width, height, and duration with `ffprobe`, `sips`, or `identify`; then scale from the measured aspect ratio and set explicit `width`, `height`, `x`, and `y`.
 7. **Use still images directly** — `input` supports videos and images. Place still screenshots, logos, and product photos with `video image_input`; the renderer treats images as static clips for the block duration.
-8. **Use the full xAI visual toolkit** — choose `xai.imagine` for text-to-video, `xai.imageToVideo` for animating one extracted image/screenshot/product photo, and `xai.referenceToVideo` for guiding a scene with up to 7 extracted references.
-9. **Generated media has no text** — prompts for AI-generated images/videos must explicitly ask for no text, no words, no letters, no captions, no logos, no watermarks, and no readable UI copy. Use VidScript `text` primitives for all final copy.
-10. **Strict rules** — see `vidscript-strict.md` for invalid patterns (bare `xai.imagine`, bare `eleven.music(...)` without import, trailing params after direct plugin calls, nested quotes in prompts).
+8. **Use the full media plugin toolkit** — choose still generation, text-to-video, image-to-video, reference-to-video, video extension, TTS, and music deliberately. Do not default to only `xai.imagine`.
+9. **Include audio when useful** — use `xai.tts` / `xai.textToSpeech` for narration and `eleven.music` / `eleven.generateMusic` / `eleven.composeMusic` for music beds.
+10. **Generated media has no text** — prompts for AI-generated images/videos must explicitly ask for no text, no words, no letters, no captions, no logos, no watermarks, and no readable UI copy. Use VidScript `text` primitives for all final copy.
+11. **Channel-aware `[-]` timing** — audio and visual auto blocks have separate playheads. A music bed or TTS sequence does not delay the next `[-] = video ...` block.
+12. **Strict rules** — see `vidscript-strict.md` for invalid patterns (bare `xai.imagine`, bare `cf.video(...)`, bare `eleven.music(...)` without import, trailing params after direct plugin calls, nested quotes in prompts).
 
 ### Common validation failures
 
 | Symptom | Fix |
 |---------|-----|
 | `Unknown function 'xai.imagine'` | Add `import xai from "@scenerok/xai"` at top |
+| `Unknown function 'cf.video'` | Add `import cf from "@scenerok/cloudflare"` at top |
 | `Unknown function 'fadeIn'` | Use `import motion from "@scenerok/basic-animations"` and call `motion.fadeIn(...)` |
 | `Expected ... but "," found` | Do not put `, volume:` after a direct plugin call. Use `let bed = eleven.music(...)`, then `audio bed, volume: ...` |
 | `Unknown function 'eleven.generateMusic'` | Add `import eleven from "@elevenlabs/music"` before calling `eleven.generateMusic(...)` |
@@ -112,6 +115,7 @@ Only default package imports are supported for callable packages. Call functions
 
 ```vidscript
 import xai from "@scenerok/xai"
+import cf from "@scenerok/cloudflare"
 import eleven from "@elevenlabs/music"
 import motion from "@scenerok/basic-animations"
 ```
@@ -125,12 +129,26 @@ Time blocks are the core of VidScript. They define when instructions execute on
 ### Dynamic Playhead (recommended)
 
 ```vidscript
-[-] = hero                            # auto-append: starts after previous block
+[-] = hero                            # auto-append: starts at visual cursor
 [- 3s] = text "Title", size: 72       # auto-start, last 3 seconds 
 [- 2.5s] = filter "glow", intensity: 0.8
 ```
 
-The playhead cursor (`prev`) tracks where the timeline is. Each `[-]` block advances the cursor by the block's content duration. `[- duration]` advances by an explicit duration.
+VidScript keeps separate auto-playhead cursors for visual and audio content. Visual blocks (`video`, `text`, filters, shaders, visual plugin calls, and bare visual inputs) advance the visual cursor. Audio blocks (`audio`, `xai.tts`, `eleven.music`, and other audio plugin calls) advance the audio cursor. `[- duration]` advances the relevant cursor by the explicit duration.
+
+This means a long audio bed or voiceover sequence does not push a following auto video block to the end of the audio:
+
+```vidscript
+import xai from "@scenerok/xai"
+import eleven from "@elevenlabs/music"
+
+input product = "https://cdn.example.com/product.png"
+let bed = eleven.music("Warm music bed", duration: 15, instrumental: true)
+[0s .. 15s] = audio bed, volume: 0.35
+[-] = video xai.imageToVideo(product, "Slow premium camera move", aspect_ratio: "9:16", duration: 6)
+```
+
+The generated video above starts at the current visual cursor, usually `0s`, even though the audio cursor already reaches `15s`. Mixed blocks containing both audio and visual instructions advance both cursors. The `prev` keyword resolves against the cursor for the block being compiled; for mixed timing it uses the current combined timeline position.
 
 ### Explicit Range
 
@@ -154,7 +172,7 @@ frame 90     # 90 frames at 30fps = 3 seconds
 
 ### The `prev` Keyword
 
-`prev` refers to the current playhead position — the end time of the previous block.
+`prev` refers to the current channel-aware playhead position for the block being compiled. In a visual block it follows the visual cursor; in an audio block it follows the audio cursor.
 
 ```vidscript
 [- 2s] = text "Hello"                              # plays from cursor to cursor+2s
@@ -268,14 +286,22 @@ Audio sources can be MP3 inputs, audio plugin results, or the embedded audio str
 
 ```vidscript
 import xai from "@scenerok/xai"
+import cf from "@scenerok/cloudflare"
 import eleven from "@elevenlabs/music"
 import motion from "@scenerok/basic-animations"
 
-[-] = video xai.imagine("Cinematic product shot, premium lighting, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", duration: 5)
+[- 4s] = video xai.image("Premium product still on seamless studio background, 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("Cinematic product video, premium lighting, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", aspect_ratio: "9:16", resolution: "720p", duration: 5)
 [-] = video xai.imageToVideo("https://cdn.example.com/product.png", "Slow premium 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 ad shot featuring 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", "Camera pulls back to reveal the full premium setup, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", duration: 5)
 [-] = audio xai.tts("Welcome to SceneRok", voice: "eve")
 
+# Cloudflare AI Gateway package.
+[-] = video cf.video("High-energy fashion product shot, 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 product with realistic parallax, 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)
+[- 4s] = video cf.image("Clean editorial product still, no text, no words, no letters, no captions, no logos, no watermark, no readable UI copy", model: "black-forest-labs/flux-2-pro-preview", aspect_ratio: "9:16")
+
 # ElevenLabs music package functions require an import alias.
 [0s .. 15s] = audio eleven.music("Warm premium launch bed", duration: 15, instrumental: true)
 
@@ -284,23 +310,37 @@ let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: tr
 [0s .. 15s] = audio bed, volume: 0.35, fade_out: 2s
 ```
 
-`@scenerok/xai` requires an explicit default import. ElevenLabs music validates as `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)` after `import eleven from "@elevenlabs/music"`. Plugin calls run at compile time; direct media plugin instructions cannot have trailing audio params, so use a `let` binding when you need `volume`, `fade_in`, or `fade_out`.
+`@scenerok/xai`, `@scenerok/cloudflare`, and `@elevenlabs/music` require explicit default imports. ElevenLabs music validates as `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)` after `import eleven from "@elevenlabs/music"`. Plugin calls run at compile time; direct media plugin instructions cannot have trailing audio params, so use a `let` binding when you need `volume`, `fade_in`, or `fade_out`.
 
-xAI visual functions:
+### Media Plugin API Reference
 
-| Function | Use when |
-|----------|----------|
-| `xai.imagine(prompt, ...)` | You need text-to-video from a clean prompt. |
-| `xai.imageToVideo(image, prompt, ...)` | You have one source image, screenshot, logo, product photo, data URI, or file id to animate. |
-| `xai.referenceToVideo([images...], prompt, ...)` | You have 1-7 reference images that should influence the generated scene without becoming the first frame. Requires a prompt; keep duration <= 10s. |
+| Package | Function | Use when |
+|---------|----------|----------|
+| `@scenerok/xai` | `xai.image(prompt, ...)`, `xai.generateImage(prompt, ...)` | Generate a still image clip. Use `resolution: "1k"` or `"2k"` and `duration` for how long the still stays on the timeline. |
+| `@scenerok/xai` | `xai.imagine(prompt, ...)`, `xai.genVideo(prompt, ...)` | Generate video from text. Use video resolutions such as `"480p"` or `"720p"`. |
+| `@scenerok/xai` | `xai.imageToVideo(image, prompt, ...)` | Animate one source image, screenshot, logo, product photo, data URI, file id, or `{ url }` object. |
+| `@scenerok/xai` | `xai.referenceToVideo([images...], prompt, ...)` | Guide a generated scene with 1-7 reference images. Requires a prompt; keep duration <= 10s. |
+| `@scenerok/xai` | `xai.extendVideo(video, prompt, ...)` | Continue an existing video clip by up to 10s. |
+| `@scenerok/xai` | `xai.tts(text, ...)`, `xai.textToSpeech(text, ...)` | Generate spoken narration. Voices: `eve`, `ara`, `rex`, `sal`, `leo`. |
+| `@scenerok/cloudflare` | `cf.image(prompt, ...)`, `cf.generateImage(prompt, ...)` | Generate stills through Cloudflare AI Gateway image models such as `black-forest-labs/flux-2-pro-preview`, `openai/gpt-image-2`, `xai/grok-imagine-image-quality`, or `recraft/recraftv4-pro`. |
+| `@scenerok/cloudflare` | `cf.video(prompt, ...)`, `cf.imagine(prompt, ...)`, `cf.genVideo(prompt, ...)`, `cf.generateVideo(prompt, ...)` | Generate text-to-video through models such as `pixverse/v6`, `vidu/q3-turbo`, `runwayml/gen-4.5`, `minimax/hailuo-2.3`, `bytedance/seedance-2.0`, or `google/veo-3.1`. |
+| `@scenerok/cloudflare` | `cf.imageToVideo(image, prompt, ...)`, `cf.referenceToVideo([images...], prompt, ...)`, `cf.extendVideo(video, prompt, ...)` | Use Cloudflare-backed image-guided, reference-guided, or extension modes when the selected model supports them. |
+| `@scenerok/cloudflare` | `cf.listModels()`, `cf.models()` | Return model metadata as data; useful for exploration, not for timeline media. |
+| `@elevenlabs/music` | `eleven.music(prompt, ...)`, `eleven.generateMusic(prompt, ...)`, `eleven.composeMusic(prompt, ...)` | Generate background music. Use a `let` binding if you need `volume`, `fade_in`, or `fade_out`. |
 
 xAI TTS voices: `eve` for upbeat demos/announcements, `ara` for warm conversational narration, `rex` for business/tutorial content, `sal` for balanced general delivery, and `leo` for authoritative instruction.
 
+Do not call `eleven.tts(...)`; the registered ElevenLabs package is `@elevenlabs/music` for music beds only. Use `xai.tts(...)` or `xai.textToSpeech(...)` for voiceover.
+
+Cloudflare video supports common named params such as `model`, `aspect_ratio`, `resolution`, `quality`, `duration`, `negative_prompt`, `seed`, `generate_audio`, `image`, `reference_images`, `reference_video`, and `input` for model-specific overrides. Prefer explicit `model:` when choosing Cloudflare so the intended provider is clear.
+
 **Invalid (will not validate):**
 
 ```vidscript
 [-] = video xai.imagine("...")                    # missing xAI import
+[0s .. 5s] = video cf.video("...")                # missing Cloudflare import
 [0s .. 15s] = audio eleven.generateMusic("...")   # missing `import eleven from "@elevenlabs/music"`
+[0s .. 5s] = audio eleven.tts("...")              # ElevenLabs TTS is not registered; use xai.tts
 [0s .. 15s] = audio eleven.music("..."), volume: 0.5      # trailing params after direct plugin call
 ```
 
@@ -425,8 +465,8 @@ scenerok secrets set ELEVENLABS_API_KEY=your-key
 
 ## Best Practices
 
-1. **Use dynamic timeblocks** — `[-]` auto-advances the cursor, reducing calculation errors
-2. **Use `prev` for offsets** — `[prev + 0.5s .. prev + 2s]` for gaps after previous content
+1. **Use dynamic timeblocks** — `[-]` auto-advances the relevant audio or visual cursor, reducing calculation errors
+2. **Use `prev` for offsets** — `[prev + 0.5s .. prev + 2s]` for gaps after previous content in the same channel
 3. **1080×1920 for vertical** (TikTok, Reels, Shorts), **1920×1080 for horizontal** (YouTube)
 4. **Hook viewers in the first 3 seconds** — place the most compelling content early
 5. **High-contrast text** — use `stroke` and `stroke_width` on text overlays over video

package/skills/shared/vidscript-strict.md

@@ -6,11 +6,12 @@ Follow these rules exactly. When in doubt, copy a file from `examples/system/` (
 
 ```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`, `xai.tts`, `eleven.music`, and `motion.fadeIn` fail validation.
+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.
 
@@ -20,7 +21,7 @@ When the user gives a product, company, ecommerce, landing page, or app URL and
 
 Do not use full-page or very long website screenshots as video backgrounds; their text is usually illegible at output size. Crop or frame screenshots to the specific visual proof point, and use them sparingly.
 
-Website screenshots are optional source material, not a requirement to build the whole video from screenshots. You may combine them with `xai.imagine`, `xai.imageToVideo`, `xai.referenceToVideo`, or other generative video plugins for lifestyle scenes, motion backgrounds, transitions, or product context. Do not invent claims; use website copy or ask the user.
+Website screenshots are optional source material, not a requirement to build the whole video from screenshots. You may combine them with still generation, text-to-video, image-to-video, reference-to-video, or extension plugins for lifestyle scenes, motion backgrounds, transitions, or product context. Do not invent claims; use website copy or ask the user.
 
 ## Rule 2.5: Probe real asset type and dimensions before placement
 
@@ -73,20 +74,56 @@ Invalid: asking the generator for signs, labels, packaging text, app UI text, ti
 
 ```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)
 ```
 
-Use `xai.imageToVideo` for one extracted screenshot/product/logo image. Use `xai.referenceToVideo` for 1-7 reference images when extracted objects should guide the generated shot; it requires a prompt and duration must be <= 10s.
+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. Use `referenceToVideo` for 1-7 reference images when extracted objects should guide the generated shot. xAI `referenceToVideo` requires a prompt and duration must be <= 10s. Prefer explicit `model:` for Cloudflare calls, e.g. `pixverse/v6`, `vidu/q3-turbo`, `runwayml/gen-4.5`, `minimax/hailuo-2.3`, `bytedance/seedance-2.0`, `google/veo-3.1`, `black-forest-labs/flux-2-pro-preview`, or `openai/gpt-image-2`.
 
 xAI TTS voices are only `eve`, `ara`, `rex`, `sal`, and `leo`.
 
-For ElevenLabs music, import `@elevenlabs/music` and use `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`.
+For ElevenLabs music, import `@elevenlabs/music` and use `eleven.music(...)`, `eleven.generateMusic(...)`, or `eleven.composeMusic(...)`. Do not call `eleven.tts(...)`; ElevenLabs TTS is not registered in VidScript today. Ads, promos, tutorials, and reels should normally include either `xai.tts` voiceover, an ElevenLabs music bed, or both unless the user asks for silent output.
+
+## 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 5: Time ranges use `..`
 
@@ -110,6 +147,7 @@ Use only straight `"` inside `xai.imagine("...")`. Do not nest quotes inside the
 
 ```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)
@@ -126,6 +164,10 @@ let bed = eleven.music("Soft premium ad music", duration: 15, instrumental: true
 
 **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