@koda-sl/baker-cli 0.81.1 → 0.90.1

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.
 
@@ -3263,6 +3263,8 @@ Reverse-engineer a video into a replication-grade blueprint: scene boundaries, t
 
 Over-length runs fail with a message that includes ready-to-use suggested windows, so the loop is self-correcting.
 
+> **Async execution.** Full-mode `video_deconstruct` is a multi-minute job, so the backend runs it as a durable background workflow rather than over a single long-lived HTTP request: the exec call returns immediately and the CLI transparently polls the job to completion. This is invisible to callers — the node's inputs, params, and outputs are unchanged — but it means a stalled provider can no longer drop the connection and cause a whole-node retry storm. (`mode:"index"` stays synchronous.)
+
 **Inputs**
 
 | Slot | Kind | Required | Accepted MIMEs |
@@ -3280,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**
 
@@ -3613,15 +3617,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.
+
+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. Tune sensitivity per video with **`--shot-threshold N`** (lower = more cuts). If `scenedetect` is unavailable it warns loudly and degrades to LLM-only boundaries.
+
+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`.
+
+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, and — exactly like a static ad — the **original extracted frame is kept LAST as a composition anchor** (the RECAST block + "ignore its brand/colors" legend stop it leaking identity). 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.
+
+**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.
 
-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).
+**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 (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."
+**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 (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.
+**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.
 
-**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.
+**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.
 
@@ -3646,7 +3662,7 @@ 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. |

package/dist/{chunk-NBNUNCY7.js → chunk-2E4H2GIJ.js}

@@ -770,13 +770,48 @@ function shouldRetry(err) {
 }
 
 // src/engine/client/backend-client.ts
+function isAsyncJob(res) {
+  return typeof res.job_id === "string";
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var JOB_POLL_INTERVAL_MS = 3e3;
+var JOB_POLL_MAX_MS = 20 * 60 * 1e3;
 var BackendClient = class {
   http;
   constructor(opts) {
     this.http = new HttpClient(opts);
   }
-  exec(req, signal) {
-    return this.http.postJson("/api/canvas/nodes/exec", req, signal);
+  async exec(req, signal) {
+    const res = await this.http.postJson("/api/canvas/nodes/exec", req, signal);
+    if (isAsyncJob(res)) {
+      return await this.pollJob(res.job_id, signal);
+    }
+    return res;
+  }
+  async pollJob(jobId, signal) {
+    const deadline = Date.now() + JOB_POLL_MAX_MS;
+    const path16 = `/api/canvas/jobs/${encodeURIComponent(jobId)}`;
+    while (true) {
+      if (signal?.aborted) {
+        throw new BackendHttpError({ kind: "network", cause: signal.reason ?? new Error("aborted") });
+      }
+      const job = await this.http.getJson(path16, signal);
+      if (job.status === "completed") return job.result;
+      if (job.status === "failed") {
+        throw new BackendHttpError({
+          kind: "provider",
+          status: job.error.status ?? 502,
+          provider: job.error.provider,
+          code: job.error.code ?? "provider_error",
+          message: job.error.message ?? "deconstruct failed",
+          retryable: job.error.retryable ?? false
+        });
+      }
+      if (Date.now() > deadline) {
+        throw new BackendHttpError({ kind: "timeout", message: `job ${jobId} did not finish in time` });
+      }
+      await sleep(JOB_POLL_INTERVAL_MS);
+    }
   }
   presignAssetUpload(sha256, mime, signal) {
     return this.http.postJson(
@@ -1189,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": {
@@ -1203,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" }
       }
     }
   },
@@ -2324,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;
@@ -3271,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";
@@ -3335,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;
@@ -3791,6 +3893,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 = [];
@@ -5582,6 +5687,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()
@@ -5970,4 +6085,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-NBNUNCY7.js.map
+//# sourceMappingURL=chunk-2E4H2GIJ.js.map