@koda-sl/baker-cli 0.82.0 → 0.91.0

package/README.md

@@ -2620,7 +2620,7 @@ Pick a `source` discriminator and declare the kind you expect. See [Ingestion](#
 
 **Outputs:** `asset` → `<params.expect>` / content-determined (URL strategy table) or extension-inferred (path).
 
-**Path-source notes:** the canvas is **not portable** to another machine without the file. Cache key folds the file's `mtime:size`, so editing the file invalidates the cache automatically. Supported extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `avif`, `svg`, `mp4`, `webm`, `mov`, `m4v`, `mp3`, `wav`, `m4a`, `ogg`, `flac`, `json`, `txt`, `md`, `markdown`, `html`/`htm`, `csv`, `ttf`, `otf`, `woff`, `woff2`. Unknown extensions fall back to magic-byte sniffing for common image formats (and an SVG content sniff), else `kind_mismatch`. **SVG (`expect: "image"`) is rasterized to a transparent PNG on ingest** — brand logos are usually SVG, and image-generation models can't read SVG markup, so it's upscaled (longest edge near 2048px) with transparency preserved and the resulting asset carries `metadata.rasterized_from: "svg"`.
+**Path-source notes:** the canvas is **not portable** to another machine without the file. Cache key folds the file's `mtime:size`, so editing the file invalidates the cache automatically. Supported extensions: `png`, `jpg`/`jpeg`, `webp`, `gif`, `avif`, `svg`, `mp4`, `webm`, `mov`, `m4v`, `mp3`, `wav`, `m4a`, `ogg`, `flac`, `json`, `txt`, `md`, `markdown`, `html`/`htm`, `csv`, `ttf`, `otf`, `woff`, `woff2`. Unknown extensions fall back to magic-byte sniffing for common image formats (and an SVG content sniff), else `kind_mismatch`. **SVG (`expect: "image"`) is rasterized to a transparent PNG on ingest** — brand logos are usually SVG, and image-generation models can't read SVG markup, so it's upscaled (longest edge near 2048px) with transparency preserved and the resulting asset carries `metadata.rasterized_from: "svg"`. **Video (`expect: "video"`) duration is probed from the file's ISO-BMFF (`mp4`/`mov`/`m4v`) header** and stamped as the canonical `duration_ms` (and `metadata.duration_ms`); other containers (e.g. `webm`) leave it unset. Downstream `video_deconstruct` uses this declared duration to size its ingest-poll timeout and preflight — without it those fall back to worst-case budgets and a single deconstruct step can hit the action time limit.
 
 **Cost:** 0 engine credits for direct fetch + yt-dlp + local file. Handinger charges per scrape.
 
@@ -3282,6 +3282,8 @@ Over-length runs fail with a message that includes ready-to-use suggested window
 | `max_scenes` | number | no | `20` (full ≤3 min) / `40` (longer) / `60` (index) | 1–60; extra cuts merge into the last scene |
 | `focus` | string | no | — | extra extraction emphasis (e.g. `"overlay typography"`) |
 | `start_s` / `end_s` | number | no | whole video | analysis window (absolute seconds) for chunking long videos; window ≤480s |
+| `shot_cuts` | number[] | no | — | real visual shot-cut timestamps (absolute seconds); scene boundaries snap onto them and any scene spanning one is split, so a scene's frames never straddle a hard cut. `scaffold-video` detects these with PySceneDetect and passes them automatically |
+| `max_clip_s` | number | no | — | the video model's per-clip ceiling (seconds); a shot longer than this is split into equal continuation sub-scenes that share their splice (full-length, seamless — no truncation), each tagged `continues_previous`. `scaffold-video` passes Seedance's 15 |
 
 **Outputs**
 
@@ -3358,9 +3360,10 @@ Place and mix several audio clips onto one timeline — a music bed plus timed v
 
 | Name | Type | Required | Notes |
 |---|---|---|---|
-| `tracks` | array | yes | `[{slot, start_s, gain_db?}]` — `slot` matches a wired input; `start_s` is absolute seconds; `gain_db` ducks (e.g. `-12` for a music bed) |
+| `tracks` | array | yes | `[{slot, start_s, gain_db?}]` — `slot` matches a wired input; `start_s` is absolute seconds; `gain_db` sets the static level (e.g. `-20` for a music bed) |
 | `total_ms` | number | no | pins the final length (pad/trim) |
 | `output_format` | enum | no | `mp3` (default) / `wav` / `m4a` |
+| `duck` | object | no | sidechain-duck one track under others: `{ track, against: [...], threshold?, ratio?, attack?, release? }` — the `track` (music) drops while any `against` track (voice) carries signal and recovers in the gaps |
 
 **Outputs** — `audio`. **Cost** — free (local). Requires `ffmpeg`.
 
@@ -3615,15 +3618,27 @@ Validate, then execute the graph. Blocks until done. Logs one line per node. Ret
 Turn a reference video into a **runnable, self-validated reproduction canvas** in one command — the video counterpart of `scaffold-static-ad`. It runs **billed passes** up front:
 
 1. **`video_deconstruct`** (`~google/gemini-pro-latest`, full mode) — reverse-engineers the video into a scene-by-scene blueprint + word-level transcript, written next to the canvas as **`prompt.json`**. Each scene's `start_frame_prompt`/`end_frame_prompt` are inlined into the frame nodes (see below); `prompt.json` then rides along as the shared **global style reference** (palette, cast cohesion) and as provenance.
-2. **recurring-element selection** (`~google/gemini-flash-latest`) — picks only the **recurring, identity-critical** elements (each `global.cast` person, a recurring animal, a showcased product, the brand logo) and the scene indices each appears in. One real reference image grounds each element across **every** frame it appears in, so the same actor stays consistent the whole video.
+2. **recurring-element selection** (`~google/gemini-flash-latest`) — picks only the **recurring, identity-critical** elements (each `global.cast` person, a recurring animal, a showcased product, the brand logo) and the scene indices each appears in. One real reference image grounds each element across **every** frame it appears in, so the same actor stays consistent the whole video. This selection runs as a **second pass over a slimmed blueprint** (cast/branding + each scene's frame prompts only) — a long ad's full blueprint can exceed the engine's inline-prompt limit, so the heavy per-scene detail (dialogue, overlays, transcript) the selector never reads is dropped before the prompt.
 
-It then scaffolds the full pipeline: per scene, two **static-ad-grade frames** (`image_generate` with its **own self-contained `params.prompt`** — edit a frame node to change only that frame; `prompt.json` is wired as a demoted shared-style `target_blueprint`, a per-element reference legend, the real extracted frame as a composition anchor) → `video_generate` (Seedance first/last-frame, fed an ultra-detailed motion brief composed from the scene's action, camera, dialogue, and transcript; duration snapped to the nearest allowed clip length).
+Before the deconstruct it runs a **local shot-cut pass** on the source file with **[PySceneDetect](https://www.scenedetect.com)** (`scenedetect` CLI, `detect-content` — the battle-tested HSV content detector, installed in the canvas sandbox) and passes the cut timestamps as `video_deconstruct`'s `shot_cuts`. The deconstruct snaps its scene boundaries onto those real cuts and **splits any scene that spans one**, so a scene's frames can never straddle a hard cut (the failure where a scene's start frame was the couch and its end frame the b-roll). Two knobs tuned for fast social ads: the content **threshold defaults to 18** (PySceneDetect's own default of 27 misses soft reframes) and the **minimum scene length is dropped to 0.25s** (its default ~0.6s merges away rapid montage flashes) — so super-fast cuts survive and become cheap still-holds downstream. The threshold is **adaptive**: if the first pass looks like a continuous shot shredded into many close micro-cuts (a talking-head selfie's natural motion), it re-runs at PySceneDetect's own default of 27 and trusts that — real montage cuts survive it, motion artifacts don't. Pinning **`--shot-threshold N`** disables the re-check (lower = more cuts). The backend additionally coalesces residual same-shot slivers. If `scenedetect` is unavailable it warns loudly and degrades to LLM-only boundaries.
 
-**Sequenced audio.** Dialogue is a back-and-forth on one absolute timeline, so each **contiguous same-speaker turn** becomes its own `tts` placed at its real `start_s` — turns alternate and never stack (the earlier design concatenated each speaker's whole monologue at their earliest timestamp, so two voices played in parallel for the entire video). Each speaker is locked to one shared `voice_select` voice; a `sound_effect` per SFX and a `music` bed (styled after the AudD-identified track when available, ducked under the voices, and started at the reference's `music.starts_at_s` rather than always at 0) round out the mix (`audio_timeline`). The final mux normalizes the soundtrack to **−14 LUFS (stereo)** so the output plays loud in every player — the raw mix is quiet mono, which reads as "no sound."
+A shot longer than the video model's per-clip ceiling (Seedance's 15s, passed as `video_deconstruct`'s `max_clip_s`) is split into equal **continuation sub-scenes** that share their splice boundary exactly — so a long shot is reproduced in **full** (no truncation) and joins seamlessly. Each sub-scene carries `continues_previous`.
 
-**Native talking heads (no post-hoc lip-sync).** Seedance 2.0 generates lip-synced speech **natively** — a scene with a **single on-camera speaker** (a `dialogue.speaker` that maps to a `global.cast` member, when `global.voiceover.mode` isn't pure `voiceover`/`none`) puts the line in the clip's prompt with `generate_audio`, so lips and voice are generated together (no `video_lipsync`/veed). Each native clip's audio is then re-voiced through `audio_voice_convert` (ElevenLabs Voice Changer) to **one brand voice** so every scene sounds like the same person, timing preserved so the lips stay matched. Off-camera narration keeps a sequenced `tts` per turn; scenes with two on-camera speakers stay native-per-clip and are flagged for you to split or pick a primary.
+It then scaffolds the full pipeline like an **editing timeline**: each clip gets a **static-ad-grade start AND end keyframe** (`image_generate`, each with its **own self-contained `params.prompt`** — edit a frame node to change only that frame; `prompt.json` wired as the **authoritative shared `target_blueprint`**, plus a per-element reference legend). Each keyframe is **fully recast** to the dropped `el_*` reference images. For a frame with **no person/animal** the original extracted frame is kept LAST as a pure composition anchor; for any frame **with a face it is dropped entirely** (it leaked the source person's identity — the hook used to render the reference woman, not our actor), so the recast `el_*`/actor-sheet is the sole identity reference. Both keyframes feed `video_generate` (`first_frame`+`last_frame`, so Seedance interpolates real in-shot motion; ultra-detailed motion brief; duration snapped to the nearest allowed clip length). Every keyframe grounds **only on its own extracted frame + `el_*` slots** — no reference to any other generated frame — so all images render **in parallel** (no cascade). Source-frame URLs are **deduped** (each ingested once). `--frames reuse` wires the real source frame straight in.
 
-**Native-audio drift guard.** Seedance paces a spoken line to fill the clip, so each native clip is generated **long enough for the estimated speech** (≈150 wpm) — not just the visual scene length — and its audio is extracted at the **full line length** rather than hard-trimmed to the scene, so a line that runs a beat long isn't cut mid-word (it continues over the next scene as natural VO). `metadata.video.talking_scenes` records each scene's `scene_s` vs `est_speech_s` so you can spot a line that overruns its cut.
+**Composited scenes (split-screen / picture-in-picture / keyed presenter).** Real ads aren't always one full-frame shot — a frame can be **persistently divided** (b-roll on top, a presenter talking on the bottom) or **layer a presenter** over background footage (boxed in a corner, or green-screen keyed). The deconstruct now reports this per scene as `scene.composition` (`layout: split_screen | pip | keyed_overlay`, with one `region` per stream — each its own clean-plate frame + motion brief, the talking-head region flagged `is_presenter`). The scaffold reproduces a composited scene by building **one clip per region** (`s<i>_r0_*`, `s<i>_r1_*`, …) and compositing them with ffmpeg: a split-screen `vstack`/`hstack` (stack direction read from the region **panels**, so a top/bottom split always stacks vertically), or a picture-in-picture `overlay` of the presenter inset at its corner. A **keyed** presenter is first cut to transparency by `video_background_remove` (`s<i>_key`), then overlaid. The presenter region carries the native lip-synced voice; b-roll/render panels stay silent. To change a layout, edit `composition` in `prompt.json` and re-scaffold, or hand-edit the `s<i>_composite` ffmpeg args. Plain full-frame scenes (the default) are unaffected.
+
+**Montage flashes held as stills.** A rapid-cut beat shorter than ~2s with no spoken line is a **flash** — Seedance's shortest clip is 4s, so generating one (then trimming away most of it) burns credits for motion no viewer perceives. The scaffold instead **holds one keyframe as a still** for the scene length (a cheap ffmpeg loop, no billed `video_generate`), same look at a fraction of the cost. Talking/ambient beats keep a real clip (they need motion + native audio).
+
+**The phrase model (voice cut at pauses, not at visual cuts).** The voice is grouped into **phrases** — runs of continuous speech with no real pause, which may span several visual scenes. A phrase is voiced ONCE (so a sentence the deconstruct split at a visual cut never breaks mid-word): if the speaker is **shown** anywhere in the phrase it's a single Seedance clip (`s<anchor>_clip`, native lip-sync + audio) re-voiced to the brand voice; if the speaker is **never shown** it's one ElevenLabs `tts` read. The picture is then assembled **scene by scene**: a scene that shows the speaker **slices its window** out of the phrase clip (`s<i>_seg`, an ffmpeg `-ss`/`-t` cut — video and audio come from the *same* clip, so lip-sync holds), and a **b-roll cutaway** gets its own silent clip while the phrase's voice plays underneath. "Shown" is decided by the **presenter element's per-scene presence**, not just who's speaking — a scene where a cast member narrates over b-roll (their element absent) is treated as a cutaway, so the talking head never appears where the original cut away. A presenter run longer than the 15s Seedance ceiling **splits at a scene boundary** into contiguous takes (each its own clip + convert), so a sliced window never reads past its clip. A b-roll cutaway *inside* a phrase lands at an **approximate** time (Seedance exposes no word timing) — nudge the scene boundary if it's off its beat.
+
+**A starting point, not a locked render.** The canvas mirrors the reference's structure to give you a faithful scaffold, but `metadata.todo.full_flexibility` makes explicit that the agent has **full editing freedom**: add / delete / reorder / split / merge scenes, re-prompt any frame or motion brief, change a scene's layout (full-frame ↔ composite), or rewrite any line — the content-addressed cache re-bills only what changes, and `baker canvas validate` re-checks timing/lip-sync after any edit.
+
+**Sequenced audio.** Dialogue is a back-and-forth on one absolute timeline, so each **contiguous same-speaker turn** becomes its own `tts` placed at its real `start_s` — turns alternate and never stack (the earlier design concatenated each speaker's whole monologue at their earliest timestamp, so two voices played in parallel for the entire video). Each speaker is locked to one shared `voice_select` voice; a `sound_effect` per SFX and a `music` bed (conditioned on the **ad's own script + emotional arc** so the bed supports the message, styled after the AudD-identified track when available, ducked under the voices, and started at the reference's `music.starts_at_s` rather than always at 0) round out the mix (`audio_timeline`). The final mux normalizes the soundtrack to **−14 LUFS (stereo)** so the output plays loud in every player — the raw mix is quiet mono, which reads as "no sound."
+
+**Native talking heads + one voice per person (no post-hoc lip-sync).** Seedance 2.0 generates lip-synced speech **natively** — a presenter phrase puts the full phrase in the clip's prompt with `generate_audio`, so lips and voice are generated together (no `video_lipsync`/veed). Each presenter phrase's audio is extracted and re-voiced through a **per-phrase** `audio_voice_convert` (ElevenLabs Voice Changer; one per phrase keeps each ≤15s clip under the converter's length cap) to the brand voice — timing preserved so the lips stay matched. There is **ONE voice per person**: a single `voice_select` is reused for all that person's phrases, and the deconstruct's `voiceover` label folds into the sole on-camera presenter (so on-camera and off-camera narration are the same voice, not two). A scene with **two on-camera speakers** can't be one clip — both lines become `tts` over a plain scene clip.
+
+**Timing-faithful clip + extract (no overlap).** Each phrase clip is generated to its **coverage window** (the deconstruct's real scene/line timing, capped at 15s) and its converted voice is extracted to the **spoken window** (pause to pause) — *not* padded to a word-count estimate. Padding past the window was what ran the voice the clip's whole length and overlapped the next phrase; trusting the deconstruct's timing keeps consecutive phrases back-to-back and lets Seedance pace the quoted text to fit. `metadata.video.talking_scenes` still records each phrase's `scene_s` vs `est_speech_s` so you can spot a line whose words overrun its window and widen it by hand.
 
 **Timeline-accurate picture.** Seedance can't render under 4s, so each clip is generated at the smallest allowed duration ≥ the scene length and then **trimmed back to the exact scene duration** before concat. This keeps the concatenated picture on the same timeline as the absolute-timed audio — without it, short scenes balloon to 4s, the spine runs far longer than the soundtrack, and every line plays over the wrong (slowed) scene so the lips never match. Frames are also prompted as **clean text-free plates** (no baked captions/lower-thirds/tickers/logos-as-text) so the overlay layer is the single source of on-screen text.
 
@@ -3648,9 +3663,8 @@ baker canvas run ./reference-ad.video.canvas.json
 | Flag | Default | Effect |
 |---|---|---|
 | `--out <path>` | `<video-dir>/<name>.video.canvas.json` | Where to write the canvas (composition is copied alongside). |
-| `--frames <mode>` | `generate` | `generate` regenerates frames anchored on the originals; `reuse` wires the real extracted frames straight into the clips (faithful, cheaper). |
+| `--frames <mode>` | `generate` | `generate` emits ONE recast keyframe per scene (the original frame is dropped so the dropped `el_*` assets drive identity); `reuse` wires the real extracted first+last frames straight into the clips (faithful, cheaper, no recast). |
 | `--ambient` | off | Give silent **b-roll** scenes native diegetic ambient (Seedance `generate_audio`), mixed deep under the music bed. Talking scenes already carry voice; check levels don't muddy the mix before keeping it. |
-| `--actor-sheets` | off | Lock a recast **person/animal that recurs across ≥2 scenes** to ONE multi-view turnaround (`image_reference_sheet`) that every frame grounds on — the strongest cross-scene identity lock. Costs extra credits per sheet; a fused sheet can over-polish, so eyeball it. |
 | `--max-scenes <n>` | all source scenes | **Cost lever that reduces fidelity** — caps the deconstruct, MERGING away every scene beyond the cap (fewer cuts, lost beats). Prints a warning when set; omit it to reproduce every scene. |
 | `--language <code>` | auto | Transcript/dialogue language hint (e.g. `fr`, `en`). |
 | `--focus <text>` | — | Known provenance/emphasis to ground the deconstruct. |
@@ -3661,6 +3675,8 @@ baker canvas run ./reference-ad.video.canvas.json
 
 Each scene is captured in a **shoot mode** — `ugc_selfie` (talking heads, the default look), `ugc_broll`, `studio_product` (pack shot), `lifestyle_cinematic`, or `screen_ui`. The scaffold derives one per scene (UGC by default; the cinematic and screen lanes are opt-in) and bakes its capture block into the frame and a camera default into the clip; override per scene with a `shoot_mode` field in `prompt.json`. Capture aesthetic + depth-of-field follow the mode (UGC stays flat; studio/lifestyle allow shallow DoF). Clips also carry **diegetic native audio** — the scene's own ambience described in the Seedance prompt, never music (the music bed is a separate, ducked track); set a scene's `ambient` field to steer it.
 
+**Automatic by default (no flags).** A recast **person/pet recurring across ≥2 scenes** is always locked to ONE multi-view turnaround (`image_reference_sheet`) every frame grounds on. An **app/website/chat screen** is never sent to the video model — the scaffold drops the scene to a clean talking-head and seeds a phone-mockup PIP stub to fill with a real `baker images screenshot` or brand HTML block (Seedance garbles UI and a split leaves a seam). The **music bed is instrumental** (the script is never fed to the music model — it would sing over the voice), enters only after the hook, and is **sidechain-ducked** under the voice. **Word-synced TikTok captions** are wired off the deconstruct transcript whenever the ad has speech. Seeded overlays are pushed **off the subject's face** (dead-center → bottom band).
+
 The two scaffold passes are billed (the full `video_deconstruct` is the heavy one); **running** the result then generates many image/video/audio assets and is not free. Defaults to vertical 1080×1920 overlays — copy + edit the composition for other aspect ratios. For on-brand overlay type, drop `brand-bold.otf`/`brand-regular.otf` into the copied `video-overlay-composition/` dir (wired via `@font-face`, with a system fallback). Richer transcription (punctuated words + paragraphs) is available via the deconstruct's `transcriber: "deepgram"` param when `DEEPGRAM_API_KEY` is set.
 
 #### `baker canvas scaffold-static-ad <image> [flags]`

package/canvas/video-overlay-composition/index.html

@@ -64,12 +64,33 @@
       }
       .ov.fe { font-size: 30px; font-weight: 600; opacity: 0.9; }
 
+      /* SAFE ZONES — a 9:16 talking-head's FACE fills the vertical CENTER band. Keep
+         graphics in the TOP band (≤360px) or BOTTOM band (≥1400px); never park a caption
+         dead-center over the face. The scaffold already pushes center placements to the
+         bottom, but if you hand-place, respect the bands. */
+
+      /* COLLISION-SAFE TOP BAR — wrap co-timed top items (logo + trust badge + …) in ONE
+         .top-bar so they pack side-by-side with a gap and never overlap. Example:
+           <div class="top-bar" data-start="0" data-dur="30">
+             <img class="brandmark" src="logo.svg"><span class="trust">★ 4,5/5</span>
+           </div> */
+      .top-bar {
+        position: absolute; top: 70px; left: 56px; right: 56px;
+        display: flex; align-items: center; gap: 20px; flex-wrap: wrap;
+      }
+
+      /* STAGGER — give a group `data-stagger="0.12"` and its direct children reveal one
+         after another (e.g. coverage chips appearing as each is spoken), not as a clump. */
+      .chips { display: flex; flex-wrap: wrap; gap: 14px; justify-content: center; max-width: 92%; }
+
       /* 9-grid position helpers (absolute). Tweak the insets or add your own. */
       .pos-top-left      { top: 90px; left: 56px; text-align: left; }
       .pos-top-center    { top: 90px; left: 50%; transform: translateX(-50%); }
       .pos-top-right     { top: 90px; right: 56px; text-align: right; }
       .pos-mid-left,
       .pos-center-left   { top: 50%; left: 56px; transform: translateY(-50%); text-align: left; }
+      /* Center = the face. Kept only for non-talking-head plates; the scaffold remaps
+         seeded center overlays to the bottom band so they never cover the subject. */
       .pos-center,
       .pos-mid-center    { top: 50%; left: 50%; transform: translate(-50%,-50%); }
       .pos-mid-right,
@@ -115,26 +136,31 @@
         const els = Array.from(document.querySelectorAll('#overlay-root [data-start]'));
 
         // Generic timeline: show each element at data-start, hide at start+data-dur,
-        // with an optional canned entrance from data-anim. No styling decisions here —
+        // with an optional canned entrance from data-anim. With data-stagger="<sec>" the
+        // element's DIRECT CHILDREN reveal one-by-one (e.g. coverage chips landing on the
+        // word each is spoken) instead of as a single clump. No styling decisions here —
         // the look lives entirely in the CSS/markup above.
         for (const el of els) {
           const at = parseFloat(el.getAttribute('data-start') || '0') || 0;
           const dur = parseFloat(el.getAttribute('data-dur') || '2.5') || 2.5;
           const anim = el.getAttribute('data-anim') || '';
+          const stagger = parseFloat(el.getAttribute('data-stagger') || '0') || 0;
           // Preserve any positioning transform the CSS set (translate(...)).
           const baseTransform = getComputedStyle(el).transform;
           const tx = baseTransform && baseTransform !== 'none' ? baseTransform : '';
 
+          // Stagger animates the children; otherwise the element itself enters.
+          const targets = stagger > 0 && el.children.length ? Array.from(el.children) : el;
           tl.set(el, { visibility: 'visible' }, at);
           if (anim === 'pop') {
-            tl.fromTo(el, { opacity: 0, scale: 0.7 }, { opacity: 1, scale: 1, duration: 0.3, ease: 'back.out(1.7)' }, at);
+            tl.fromTo(targets, { opacity: 0, scale: 0.7 }, { opacity: 1, scale: 1, duration: 0.3, ease: 'back.out(1.7)', stagger }, at);
           } else if (anim === 'slide_up') {
-            tl.fromTo(el, { opacity: 0, yPercent: 30 }, { opacity: 1, yPercent: 0, duration: 0.3, ease: 'power2.out' }, at);
+            tl.fromTo(targets, { opacity: 0, yPercent: 30 }, { opacity: 1, yPercent: 0, duration: 0.3, ease: 'power2.out', stagger }, at);
           } else if (anim === 'slide_down') {
-            tl.fromTo(el, { opacity: 0, yPercent: -30 }, { opacity: 1, yPercent: 0, duration: 0.3, ease: 'power2.out' }, at);
+            tl.fromTo(targets, { opacity: 0, yPercent: -30 }, { opacity: 1, yPercent: 0, duration: 0.3, ease: 'power2.out', stagger }, at);
           } else {
             // Default / any unrecognized data-anim value: a plain fade.
-            tl.fromTo(el, { opacity: 0 }, { opacity: 1, duration: 0.25, ease: 'power1.out' }, at);
+            tl.fromTo(targets, { opacity: 0 }, { opacity: 1, duration: 0.25, ease: 'power1.out', stagger }, at);
           }
           tl.to(el, { opacity: 0, duration: 0.2 }, Math.max(at + 0.2, at + dur));
           tl.set(el, { visibility: 'hidden' }, at + dur + 0.21);

package/dist/{chunk-KIL2ZJST.js → chunk-LMVDA3EZ.js}

@@ -1224,7 +1224,12 @@ var MODEL_REGISTRY = {
         focus: { kind: "string" },
         start_s: { kind: "number", min: 0 },
         end_s: { kind: "number", min: 0 },
-        transcriber: { kind: "string", enum: ["groq", "deepgram"] }
+        max_clip_s: { kind: "number", min: 1, max: 60 },
+        transcriber: { kind: "string", enum: ["groq", "deepgram"] },
+        // Real visual shot-cut timestamps (seconds) from local PySceneDetect;
+        // scene boundaries snap onto them so frames never straddle a hard cut.
+        // Shape (number[]) is enforced by the node + backend Zod schemas.
+        shot_cuts: { kind: "json" }
       }
     },
     "~google/gemini-pro-latest": {
@@ -1238,7 +1243,10 @@ var MODEL_REGISTRY = {
         focus: { kind: "string" },
         start_s: { kind: "number", min: 0 },
         end_s: { kind: "number", min: 0 },
-        transcriber: { kind: "string", enum: ["groq", "deepgram"] }
+        max_clip_s: { kind: "number", min: 1, max: 60 },
+        transcriber: { kind: "string", enum: ["groq", "deepgram"] },
+        // See gemini-flash-latest above — local PySceneDetect shot-cut timestamps.
+        shot_cuts: { kind: "json" }
       }
     }
   },
@@ -2359,8 +2367,9 @@ function estimateCredits(ctx) {
 function talkingSceneSatisfied(ctx, entry, scene) {
   const nodes = ctx.canvas.nodes;
   if (typeof entry === "object" && "voice_convert_node" in entry) {
+    const nativeClipRe = new RegExp(`^s${scene}(_r\\d+)?_clip$`);
     const clipNativeAudio = nodes.some(
-      (n) => n.id === `s${scene}_clip` && n.type === "video_generate" && n.params?.generate_audio === true
+      (n) => nativeClipRe.test(n.id) && n.type === "video_generate" && n.params?.generate_audio === true
     );
     const converted = nodes.some((n) => n.id === entry.voice_convert_node && n.type === "audio_voice_convert");
     return clipNativeAudio && converted;
@@ -3306,6 +3315,48 @@ function sniffImageMime(buf) {
   }
   return null;
 }
+function findBoxPayload(buf, start, end, type) {
+  let offset = start;
+  while (offset + 8 <= end) {
+    let size = buf.readUInt32BE(offset);
+    const boxType = buf.toString("ascii", offset + 4, offset + 8);
+    let headerLen = 8;
+    if (size === 1) {
+      if (offset + 16 > end) return null;
+      size = Number(buf.readBigUInt64BE(offset + 8));
+      headerLen = 16;
+    } else if (size === 0) {
+      size = end - offset;
+    }
+    if (size < headerLen || offset + size > end) return null;
+    if (boxType === type) return { start: offset + headerLen, end: offset + size };
+    offset += size;
+  }
+  return null;
+}
+var MVHD_DURATION_UNKNOWN = 4294967295;
+function mp4DurationMs(bytes) {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const moov = findBoxPayload(buf, 0, buf.length, "moov");
+  if (!moov) return void 0;
+  const mvhd = findBoxPayload(buf, moov.start, moov.end, "mvhd");
+  if (!mvhd) return void 0;
+  const version = buf[mvhd.start];
+  const tsOffset = mvhd.start + 4 + (version === 1 ? 16 : 8);
+  if (version === 1) {
+    if (tsOffset + 12 > mvhd.end) return void 0;
+    const timescale2 = buf.readUInt32BE(tsOffset);
+    const duration2 = buf.readBigUInt64BE(tsOffset + 4);
+    if (timescale2 === 0 || duration2 === 0n) return void 0;
+    return Math.round(Number(duration2) / timescale2 * 1e3);
+  }
+  if (version !== 0) return void 0;
+  if (tsOffset + 8 > mvhd.end) return void 0;
+  const timescale = buf.readUInt32BE(tsOffset);
+  const duration = buf.readUInt32BE(tsOffset + 4);
+  if (timescale === 0 || duration === 0 || duration === MVHD_DURATION_UNKNOWN) return void 0;
+  return Math.round(duration / timescale * 1e3);
+}
 function inferKindFromMime(mime) {
   if (mime.startsWith("image/")) return "image";
   if (mime.startsWith("video/")) return "video";
@@ -3370,20 +3421,36 @@ async function execLocalFile(params, ctx) {
     outMime = "image/png";
     ctx.log(`ingest: rasterized SVG -> PNG (${outBytes.length}B)`);
   }
-  return await uploadAndIngest({
+  const durationMs = probeVideoDurationMs(params.expect, outBytes, ctx);
+  const ref = await uploadAndIngest({
     bytes: outBytes,
     kind: params.expect,
     mime: outMime,
-    metadata: {
-      source_path: absPath,
-      strategy: "local_file",
-      ingested_at: (/* @__PURE__ */ new Date()).toISOString(),
-      file_size: stats.size,
-      original_filename: path3.basename(absPath),
-      ...mime === SVG_MIME ? { rasterized_from: "svg" } : {}
-    },
+    metadata: localFileMetadata({ absPath, fileSize: stats.size, mime, durationMs }),
     ctx
   });
+  return withProbedDuration(ref, durationMs);
+}
+function probeVideoDurationMs(expect, bytes, ctx) {
+  if (expect !== "video") return void 0;
+  const durationMs = mp4DurationMs(bytes);
+  if (durationMs !== void 0) ctx.log(`ingest: probed video duration ${durationMs}ms`);
+  return durationMs;
+}
+function localFileMetadata(args) {
+  return {
+    source_path: args.absPath,
+    strategy: "local_file",
+    ingested_at: (/* @__PURE__ */ new Date()).toISOString(),
+    file_size: args.fileSize,
+    original_filename: path3.basename(args.absPath),
+    ...args.mime === SVG_MIME ? { rasterized_from: "svg" } : {},
+    ...args.durationMs !== void 0 ? { duration_ms: args.durationMs } : {}
+  };
+}
+function withProbedDuration(ref, durationMs) {
+  if (durationMs === void 0 || ref.kind !== "video") return ref;
+  return { ...ref, duration_ms: durationMs };
 }
 var YT_DLP_BIN = "yt-dlp";
 var YT_DLP_TIMEOUT_MS = 10 * 60 * 1e3;
@@ -3786,19 +3853,56 @@ var Track = z6.object({
   /** Optional level adjustment in dB (negative ducks, e.g. a music bed at -12). */
   gain_db: z6.number().optional()
 }).strict();
+var DuckSpec = z6.object({
+  track: z6.string().min(1),
+  against: z6.array(z6.string().min(1)).min(1),
+  threshold: z6.number().min(0).max(1).optional(),
+  ratio: z6.number().min(1).max(20).optional(),
+  attack: z6.number().min(0.01).optional(),
+  release: z6.number().min(0.01).optional()
+}).strict();
 var AudioTimelineParams = z6.object({
   tracks: z6.array(Track).min(1),
   /** Final track length in ms — pads short / trims long. Defaults to the natural mix length. */
   total_ms: z6.number().int().positive().optional(),
-  output_format: z6.enum(["mp3", "wav", "m4a"]).optional()
+  output_format: z6.enum(["mp3", "wav", "m4a"]).optional(),
+  /** Optional sidechain duck of one track under others (e.g. music under voice). */
+  duck: DuckSpec.optional()
 }).strict();
 var AudioTimelineInputs = z6.record(z6.string(), z6.unknown());
 var AudioTimelineOutputs = z6.object({ audio: z6.custom() }).strict();
+function applyDuck(params, labelFor, filterChains) {
+  const duck = params.duck;
+  if (!duck) return;
+  const trackIdx = params.tracks.findIndex((t) => t.slot === duck.track);
+  const keyIdxs = duck.against.map((s) => params.tracks.findIndex((t) => t.slot === s)).filter((i) => i >= 0);
+  if (trackIdx < 0 || keyIdxs.length === 0) return;
+  const keyLabels = [];
+  for (const ki of keyIdxs) {
+    const base = labelFor[ki];
+    filterChains.push(`[${base}]asplit=2[${base}m][${base}k]`);
+    labelFor[ki] = `${base}m`;
+    keyLabels.push(`[${base}k]`);
+  }
+  let keyOut = keyLabels[0];
+  if (keyLabels.length > 1) {
+    filterChains.push(`${keyLabels.join("")}amix=inputs=${keyLabels.length}:normalize=0[duckkey]`);
+    keyOut = "[duckkey]";
+  }
+  const th = duck.threshold ?? 0.03;
+  const ra = duck.ratio ?? 8;
+  const at = duck.attack ?? 5;
+  const re = duck.release ?? 300;
+  filterChains.push(
+    `[${labelFor[trackIdx]}]${keyOut}sidechaincompress=threshold=${th}:ratio=${ra}:attack=${at}:release=${re}[ducked]`
+  );
+  labelFor[trackIdx] = "ducked";
+}
 function buildAudioTimelineArgs(params) {
   const fmt = params.output_format ?? "mp3";
   const inputArgs = [];
   const filterChains = [];
-  const mixLabels = [];
+  const labelFor = [];
   params.tracks.forEach((track, i) => {
     inputArgs.push("-i", `{{in.${track.slot}}}`);
     const delayMs = Math.round(track.start_s * 1e3);
@@ -3806,8 +3910,10 @@ function buildAudioTimelineArgs(params) {
     if (track.gain_db !== void 0) steps.push(`volume=${track.gain_db}dB`);
     const label = `a${i}`;
     filterChains.push(`[${i}:a]${steps.join(",")}[${label}]`);
-    mixLabels.push(`[${label}]`);
+    labelFor[i] = label;
   });
+  applyDuck(params, labelFor, filterChains);
+  const mixLabels = labelFor.map((l) => `[${l}]`);
   let graph = `${filterChains.join(";")};${mixLabels.join("")}amix=inputs=${params.tracks.length}:normalize=0`;
   if (params.total_ms !== void 0) {
     const totalS = params.total_ms / 1e3;
@@ -3818,7 +3924,7 @@ function buildAudioTimelineArgs(params) {
 }
 var audioTimelineNode = defineNode({
   id: "audio_timeline",
-  version: "1.0.0",
+  version: "1.1.0",
   category: "audio",
   location: "local",
   summary: "Place and mix several audio clips onto one timeline: each track starts at a given second (optionally level-adjusted in dB), then they're combined into a single track. Built for laying a music bed plus timed voiceover lines and sound effects under a video.",
@@ -3826,6 +3932,9 @@ var audioTimelineNode = defineNode({
   inputs: AudioTimelineInputs,
   params: AudioTimelineParams,
   outputs: AudioTimelineOutputs,
+  // The mixed timeline is an audio asset — declare it so strictly-typed consumers
+  // (e.g. audio_voice_convert reading a merged per-speaker track) resolve its kind.
+  outputKinds: { audio: "audio" },
   cost: () => ({ credits: 0, seconds_estimate: 10 }),
   validateExtra({ rawParams, rawInputs }) {
     const issues = [];
@@ -3840,6 +3949,21 @@ var audioTimelineNode = defineNode({
         });
       }
     });
+    const duck = parsed.data.duck;
+    if (duck) {
+      const slots = new Set(parsed.data.tracks.map((t) => t.slot));
+      if (!slots.has(duck.track)) {
+        issues.push({ path: "params.duck.track", message: `duck.track "${duck.track}" is not one of the tracks` });
+      }
+      duck.against.forEach((s, k) => {
+        if (!slots.has(s)) {
+          issues.push({ path: `params.duck.against[${k}]`, message: `duck.against "${s}" is not one of the tracks` });
+        }
+        if (s === duck.track) {
+          issues.push({ path: `params.duck.against[${k}]`, message: "a track cannot duck against itself" });
+        }
+      });
+    }
     return issues;
   },
   async cacheKeyExtras() {
@@ -5617,6 +5741,16 @@ var videoDeconstructNode = delegated({
     focus: z29.string().optional(),
     start_s: z29.number().min(0).optional(),
     end_s: z29.number().positive().optional(),
+    // Real visual shot-cut timestamps (absolute seconds), detected locally with
+    // ffmpeg before the deconstruct. The backend SNAPS its LLM scene boundaries
+    // onto these and SPLITS any scene that spans one, so a scene's frames never
+    // straddle a hard cut. `scaffold-video` populates this; omit for LLM-only cuts.
+    shot_cuts: z29.array(z29.number().min(0)).max(200).optional(),
+    // The video model's per-clip ceiling (seconds). A shot longer than this is
+    // split into seamless continuation sub-scenes (shared splice frame), so long
+    // shots reproduce in full instead of being truncated. `scaffold-video` sets
+    // the Seedance ceiling (15); omit to disable length splitting.
+    max_clip_s: z29.number().positive().max(60).optional(),
     // Transcript provider for the blueprint's dialogue/transcript. Default
     // Groq Whisper; "deepgram" routes to Nova-3 so words carry punctuation.
     transcriber: z29.enum(["groq", "deepgram"]).optional()
@@ -6005,4 +6139,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-KIL2ZJST.js.map
+//# sourceMappingURL=chunk-LMVDA3EZ.js.map