@scenerok/cli 1.0.12 → 1.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenerok/cli",
-  "version": "1.0.12",
+  "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
@@ -171,8 +173,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
 
@@ -128,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
 
@@ -157,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
@@ -450,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

@@ -107,6 +107,24 @@ 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