@scenerok/cli 1.0.12 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/cli",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "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
@@ -125,6 +127,8 @@ Available plugin APIs:
 | `@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:` |
 
+Cloudflare video calls share named parameters across providers: `model`, `aspect_ratio`, `duration`, `resolution` or `quality`, `generate_audio`, `negative_prompt`, `seed`, and `input` for model-specific overrides. Use `cf.imageToVideo(image, prompt, model: ..., aspect_ratio: "9:16", duration: ...)` when animating one source image. Common aspect values are `"9:16"` for vertical, `"16:9"` for wide, `"1:1"` for square, plus model-specific values such as `"4:3"`, `"3:4"`, and `"21:9"`. For Runway Gen-4.5, keep writing friendly `aspect_ratio` values; SceneRok translates them to Cloudflare's required `ratio` values such as `"720:1280"`.
+
 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. 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.
@@ -171,8 +175,8 @@ When the user provides a product, company, landing page, app store listing, or e
 
 ## 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

@@ -14,7 +14,8 @@ VidScript is a declarative DSL for composing short-form videos. Write a script,
 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. **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).
+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
 
@@ -25,12 +26,19 @@ VidScript is a declarative DSL for composing short-form videos. Write a script,
 | `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(...)` |
-| Parse error on imagine prompt | Remove nested `"` quotes inside the prompt string |
+| Prompt needs quoted words | Escape quotes inside strings, e.g. `"Package labeled \"AER-01\""` |
 
 ## Program Structure
 
 A VidScript program is a sequence of statements separated by newlines.
 
+Strings support common backslash escapes. Use `\n` inside a `text` string for an intentional rendered line break, and use `\"` or `\'` for quote characters inside the matching string delimiter.
+
+```vidscript
+[0s .. 3s] = text "RUN LIGHTER\nDAILY", line_height: 1.05
+let prompt = "Package labeled \"AER-01\", no text, no watermark"
+```
+
 ```vidscript
 # Single-line comment
 /* Multi-line
@@ -128,12 +136,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
 
@@ -157,7 +179,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
@@ -308,7 +330,7 @@ let bed = eleven.music("Warm premium launch bed", duration: 15, instrumental: tr
 | `@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.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`, `google/veo-3.1`, `google/veo-3.1-fast`, or `google/veo-3-fast`. |
 | `@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`. |
@@ -317,7 +339,16 @@ xAI TTS voices: `eve` for upbeat demos/announcements, `ara` for warm conversatio
 
 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.
+Cloudflare video calls accept these common signatures:
+
+| Function | Signature |
+|----------|-----------|
+| `cf.video` / `cf.generateVideo` / `cf.imagine` / `cf.genVideo` | `(prompt, model?, aspect_ratio?, duration?, resolution?/quality?, generate_audio?, negative_prompt?, seed?, input?)` |
+| `cf.imageToVideo` | `(image, prompt, model?, aspect_ratio?, duration?, resolution?/quality?, generate_audio?, negative_prompt?, seed?, input?)` |
+| `cf.referenceToVideo` | `([images...], prompt, model?, aspect_ratio?, duration?, resolution?/quality?, generate_audio?, input?)` |
+| `cf.extendVideo` | `(video, prompt, model?, duration?, aspect_ratio?, resolution?/quality?, input?)` |
+
+Use `aspect_ratio: "9:16"` for vertical output, `"16:9"` for wide, `"1:1"` for square, or model-supported values such as `"4:3"`, `"3:4"`, and `"21:9"`. For Runway models, keep writing friendly `aspect_ratio` values; SceneRok translates them to Cloudflare's required `ratio` values such as `"720:1280"` for vertical Gen-4.5. Prefer explicit `model:` when choosing Cloudflare so the intended provider is clear.
 
 **Invalid (will not validate):**
 
@@ -450,8 +481,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

@@ -101,12 +101,32 @@ Do not overuse one plugin function. Choose deliberately:
 | 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`.
+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.
+
+For Cloudflare calls, always prefer explicit `model:` and use `aspect_ratio: "9:16"` for vertical, `"16:9"` for wide, `"1:1"` for square, or model-supported values such as `"4:3"`, `"3:4"`, and `"21:9"`. `cf.imageToVideo(image, prompt, model: ..., aspect_ratio: ..., duration: ...)` accepts `aspect_ratio`; for Runway Gen-4.5, SceneRok translates `"9:16"` to Cloudflare's required `ratio: "720:1280"`. Useful models include `pixverse/v6`, `vidu/q3-turbo`, `runwayml/gen-4.5`, `minimax/hailuo-2.3`, `bytedance/seedance-2.0`, `google/veo-3.1`, `google/veo-3.1-fast`, `google/veo-3-fast`, `black-forest-labs/flux-2-pro-preview`, and `openai/gpt-image-2`. Veo models accept `duration: 4`, `duration: 4s`, or `duration: "4s"` — all forms snap to the supported 4s/6s/8s durations.
 
 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(...)`. 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 `..`
 
 ```vidscript
@@ -123,7 +143,7 @@ Not `[0s - 5s]`.
 
 ## Rule 7: Quote safety in prompts
 
-Use only straight `"` inside `xai.imagine("...")`. Do not nest quotes inside the prompt string (e.g. avoid `"RokMilk"` inside the prompt — say `labeled RokMilk` without extra quotes).
+Escape quote characters inside prompt strings, e.g. `xai.imagine("Package labeled \"RokMilk\", no text, no watermark")`.
 
 ## Rule 8: Audio syntax