@koda-sl/baker-cli 0.116.0 → 0.118.0

package/dist/cli.js

@@ -9,10 +9,11 @@ import {
   createEngineFromEnv,
   defaultRegistry,
   describeFailureReason,
+  elementMentionKeywords,
   generateCatalog,
   resolveConcurrency,
   validateCanvasDeep
-} from "./chunk-ZWMMCLJ4.js";
+} from "./chunk-MF34WJ7M.js";
 
 // src/cli.ts
 import { defineCommand as defineCommand157, runMain } from "citty";
@@ -13623,6 +13624,16 @@ function isLikelyOverSegmented(cuts, opts = {}) {
   const median = gaps.length % 2 ? gaps[mid] : (gaps[mid - 1] + gaps[mid]) / 2;
   return median < maxMedianGap;
 }
+function mergeRecheckCuts(firstPass, recheck, isolationS = 0.75) {
+  const kept = [...new Set(recheck)].sort((a, b) => a - b);
+  const extras = [...new Set(firstPass)].filter((c) => kept.every((k) => Math.abs(k - c) >= isolationS)).sort((a, b) => a - b);
+  const isolated = extras.filter((c, i) => {
+    const prev = extras[i - 1];
+    const next = extras[i + 1];
+    return (prev === void 0 || c - prev >= isolationS) && (next === void 0 || next - c >= isolationS);
+  });
+  return [.../* @__PURE__ */ new Set([...kept, ...isolated])].sort((a, b) => a - b);
+}
 function timecodeToSeconds(tc) {
   const m = tc.trim().match(/^(\d+):(\d{1,2}):(\d{1,2}(?:\.\d+)?)$/);
   if (!m) return null;
@@ -13676,12 +13687,13 @@ async function detectSceneCutsPySceneDetect(filePath, opts = {}) {
   const timeoutMs = opts.timeout_ms ?? 12e4;
   const cuts = await runSceneDetectOnce(filePath, threshold, minSceneLenS, timeoutMs);
   if (!pinned && isLikelyOverSegmented(cuts)) {
-    return await runSceneDetectOnce(
+    const rechecked = await runSceneDetectOnce(
       filePath,
       PYSCENEDETECT_RECHECK_THRESHOLD,
       PYSCENEDETECT_RECHECK_MIN_SCENE_LEN_S,
       timeoutMs
     );
+    return mergeRecheckCuts(cuts, rechecked);
   }
   return cuts;
 }
@@ -13819,9 +13831,22 @@ function videoResolutionParam(videoModel, resolution) {
   return { resolution: resolution ?? DEFAULT_VIDEO_RESOLUTION };
 }
 var WORDS_PER_SECOND = 2.5;
+function wordCount(text) {
+  return text.trim().split(/\s+/).filter(Boolean).length;
+}
 function estSpeechS(text) {
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return words / WORDS_PER_SECOND;
+  return wordCount(text) / WORDS_PER_SECOND;
+}
+var OBSERVED_WPS_MIN = 1;
+var OBSERVED_WPS_MAX = 6;
+function estSpeechWindowS(text, startS, endS) {
+  const words = wordCount(text);
+  const window = (endS ?? 0) - (startS ?? 0);
+  if (words > 0 && window > 0.3) {
+    const wps = words / window;
+    if (wps >= OBSERVED_WPS_MIN && wps <= OBSERVED_WPS_MAX) return window;
+  }
+  return estSpeechS(text);
 }
 var NARRATOR_SPEAKERS = /* @__PURE__ */ new Set([
   "voiceover",
@@ -14007,7 +14032,13 @@ var DialogueLine = z11.object({
   start_s: z11.number().optional(),
   end_s: z11.number().optional(),
   delivery: z11.string().optional(),
-  voice_description: z11.string().optional()
+  voice_description: z11.string().optional(),
+  // DECON-supplied: is this speaker's FACE visibly speaking in THIS scene? Element
+  // presence alone can't answer that — a founder pictured in a polaroid close-up is
+  // "present" yet the line is voiceover, and treating it as on-camera produced a
+  // native Seedance lip-sync clip of a still photograph. `false` pins the line to
+  // the VO path; absent keeps the presence-based decision (old blueprints).
+  on_camera: z11.boolean().optional()
 }).loose();
 var Sfx = z11.object({
   at_s: z11.number().optional(),
@@ -14023,6 +14054,22 @@ var CompositionRegion = z11.object({
   is_presenter: z11.boolean().optional(),
   // The cast id shown/speaking in this region (routes lip-sync + element refs).
   cast_ref: z11.string().optional(),
+  // What the region's content IS: camera | screen_capture | static_graphic |
+  // generated. Authoritative for routing when present (regex-over-prose fallback
+  // otherwise): screen_capture/static_graphic are rebuilt from REAL surfaces on the
+  // overlay layer, never AI-generated.
+  kind: z11.string().optional(),
+  // Opaque id naming the SPECIFIC on-screen document/note/app-state this
+  // screen_capture region shows. Two scenes share it only when they show the SAME
+  // recording continuing (scrolling/typing/waiting within it) — a genuinely
+  // DIFFERENT document/note/recording (a source video splicing two screen captures)
+  // gets a different id. Breaks a persistent-layout run into separate surface stubs
+  // instead of asking the operator for one screenshot that can't cover both.
+  surface_id: z11.string().optional(),
+  // Camera bubble(s)/inset(s) embedded INSIDE this region's surface (a Loom-style
+  // presenter bubble inside a screen recording) — video-in-video the reproduction
+  // must re-composite, not paint into the surface.
+  nested: z11.array(z11.object({}).loose()).optional(),
   summary: z11.string().optional(),
   frame_prompt: z11.string().optional(),
   motion_prompt: z11.string().optional()
@@ -14076,6 +14123,11 @@ var Scene = z11.object({
   sfx: z11.array(Sfx).optional(),
   overlays: z11.array(z11.unknown()).optional(),
   floating_elements: z11.array(z11.unknown()).optional(),
+  // DECON-supplied: how much the picture itself moves within the shot. Gates the
+  // flash-hold optimization — a sub-2s b-roll flash with REAL subject motion
+  // (pouring, spreading, hands working) must stay a real clip; freezing it turns
+  // a montage into a slideshow. Absent (old blueprints) keeps the cheap still.
+  motion_level: z11.enum(["static", "subtle", "dynamic"]).optional(),
   transcript_slice: z11.array(TranscriptWord).optional(),
   start_frame_asset: FrameAsset,
   end_frame_asset: FrameAsset,
@@ -14315,6 +14367,33 @@ function buildElementSlots(elements) {
 function slotsForFrame(slots, sceneIndex, edge) {
   return slots.filter((s) => s.presence.get(sceneIndex)?.has(edge));
 }
+var MENTION_WIRED_TYPES = /* @__PURE__ */ new Set(["logo", "badge"]);
+function promptMentionsSlot(prompt, slot) {
+  return elementMentionKeywords(slot).some(
+    (w) => new RegExp(`\\b${w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i").test(prompt)
+  );
+}
+function edgePromptText(scene, edge) {
+  const regionPrompts = (compositeRegionsOf(scene) ?? []).map((r) => r.frame_prompt ?? "").filter(Boolean).join("\n");
+  const own = (edge === "start" ? scene.start_frame_prompt : scene.end_frame_prompt) ?? "";
+  return [own, regionPrompts].join("\n").trim();
+}
+function extendPresenceByPromptMentions(slots, blueprint) {
+  const extendable = slots.filter((s) => MENTION_WIRED_TYPES.has(s.type.toLowerCase()));
+  if (extendable.length === 0) return;
+  blueprint.scenes.forEach((scene, i) => {
+    for (const edge of EDGES) {
+      const text = edgePromptText(scene, edge);
+      if (!text) continue;
+      for (const slot of extendable) {
+        if (!promptMentionsSlot(text, slot)) continue;
+        const set = slot.presence.get(i) ?? /* @__PURE__ */ new Set();
+        set.add(edge);
+        slot.presence.set(i, set);
+      }
+    }
+  });
+}
 var ACTOR_SHEET_MODEL = "google/gemini-3-pro-image-preview";
 var SHEET_SUBJECT_TYPE = {
   person: "person",
@@ -14497,21 +14576,94 @@ function seedanceAudioLine(scene, mode, audio, nativeLine) {
   }
   return null;
 }
-function buildSeedancePrompt(scene, sceneIndex, present, mode, audio, nativeLine, nativeLang) {
-  const loc = (s) => nativeLine ? localizeNumeralsForNative(s, nativeLang) : s;
+var FLOAT_STOP_WORDS = /* @__PURE__ */ new Set([
+  "with",
+  "across",
+  "around",
+  "above",
+  "below",
+  "over",
+  "under",
+  "screen",
+  "frame",
+  "scene",
+  "video",
+  "element",
+  "elements",
+  "graphic",
+  "overlay",
+  "animated",
+  "floating",
+  "small",
+  "large",
+  "white",
+  "black",
+  "color",
+  "colored"
+]);
+function floatTokens(desc) {
+  return desc.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 4 && !FLOAT_STOP_WORDS.has(w));
+}
+function scrubFloatSentences(text, floatDescs) {
+  if (floatDescs.length === 0 || !text) return text;
+  const tokenSets = floatDescs.map((d) => new Set(floatTokens(d)));
+  const kept = text.split(/(?<=[.!?])\s+/).filter((sentence) => {
+    const words = new Set(floatTokens(sentence));
+    return !tokenSets.some((ts) => {
+      let hits = 0;
+      for (const w of words) if (ts.has(w)) hits++;
+      return hits >= 2;
+    });
+  }).join(" ").trim();
+  return kept;
+}
+function sceneFloatDescs(scene) {
+  const floats = z11.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+  if (!floats.success) return [];
+  return floats.data.map((f) => f.description?.trim() ?? "").filter(Boolean);
+}
+function visualBriefParts(scene, sceneIndex, plate) {
   const parts = [];
-  const summary = scene.summary?.trim();
-  parts.push(summary ? `Scene ${sceneIndex + 1}: ${loc(summary)}` : `Scene ${sceneIndex + 1}`);
-  if (scene.action_detail) parts.push(`Action: ${loc(scene.action_detail)}`);
+  const floats = sceneFloatDescs(scene);
+  const scrub = (s) => {
+    if (!s) return s;
+    const out = scrubFloatSentences(s, floats);
+    return out || void 0;
+  };
+  const summary = scrub((plate ? plate.summary : scene.summary)?.trim());
+  parts.push(summary ? `Scene ${sceneIndex + 1}: ${summary}` : `Scene ${sceneIndex + 1}`);
+  const action = !plate ? scrub(scene.action_detail) : void 0;
+  if (action) parts.push(`Action: ${action}`);
   const cm = scene.camera_motion;
   if (cm) {
     const camera = [cm.movement, cm.detail].filter(Boolean).join(" \u2014 ");
     if (camera) parts.push(`Camera: ${camera}`);
   }
-  if (scene.motion_prompt) parts.push(`Motion: ${loc(scene.motion_prompt)}`);
-  if (present.length > 0) {
+  const motion = scrub(plate ? plate.motion_prompt : scene.motion_prompt);
+  if (motion) parts.push(`Motion: ${motion}`);
+  const uiFloats = floats.filter((d) => UI_SURFACE_RE.test(d));
+  const fxFloats = floats.filter((d) => !UI_SURFACE_RE.test(d));
+  if (plate || uiFloats.length > 0) {
     parts.push(
-      `Keep these consistent with their references: ${present.map((s) => `${s.label} (${s.description ?? s.type})`).join("; ")}`
+      "NEVER render any screen, phone, app, website, or UI element \u2014 this clip is the clean background plate; the screen surface is composited on top later as a separate real layer."
+    );
+  }
+  if (fxFloats.length > 0) {
+    parts.push(
+      "NEVER render floating decorative elements \u2014 no hearts, sparkles, confetti, badges, stickers, icons, or particle effects. They are composited later as a separate real overlay layer; the picture stays clean of them."
+    );
+  }
+  return parts;
+}
+function buildSeedancePrompt(scene, sceneIndex, present, mode, audio, nativeLine, nativeLang, uiRouted) {
+  const loc = (s) => nativeLine ? localizeNumeralsForNative(s, nativeLang) : s;
+  const routed = uiRouted ?? (compositeRegionsOf(scene) !== null && isUiOnlyComposite(compositeRegionsOf(scene) ?? []));
+  const plate = routed ? compositePlateRegion(scene) ?? {} : null;
+  const parts = visualBriefParts(scene, sceneIndex, plate);
+  const refs = plate ? present.filter((s) => !UI_SURFACE_RE.test(s.description ?? "")) : present;
+  if (refs.length > 0) {
+    parts.push(
+      `Keep these consistent with their references: ${refs.map((s) => `${s.label} (${s.description ?? s.type})`).join("; ")}`
     );
   }
   if (nativeLine) {
@@ -14642,7 +14794,8 @@ function emitSceneClip(i, scene, present, mode, nativeTurn, ambientBroll, frames
       mode,
       Boolean(nativeTurn) || ambientBroll,
       nativeTurn?.text,
-      opts.nativeLang
+      opts.nativeLang,
+      opts.uiRouted
     ),
     duration: lengths.genDur,
     ...videoResolutionParam(opts.videoModel, opts.resolution),
@@ -14671,12 +14824,59 @@ function emitSceneClip(i, scene, present, mode, nativeTurn, ambientBroll, frames
 var COMPOSITE_LAYOUTS = /* @__PURE__ */ new Set(["split_screen", "pip", "keyed_overlay"]);
 var UI_SURFACE_RE = /\b(?:app|ui|web ?site|web ?page|website|browser|chat|interface|mock-?up|in[- ]?app|dashboard|app screen|phone screen|screen[- ]?(?:recording|capture|grab|share))\b/i;
 function regionIsUiSurface(r) {
-  return UI_SURFACE_RE.test(`${r.panel ?? ""} ${r.summary ?? ""} ${r.frame_prompt ?? ""}`);
+  const kind = (r.kind ?? "").trim().toLowerCase();
+  if (kind === "screen_capture" || kind === "static_graphic") return true;
+  if (kind === "camera") return false;
+  return UI_SURFACE_RE.test(`${r.panel ?? ""} ${r.summary ?? ""}`);
 }
 function isUiOnlyComposite(regions) {
   const ui = regions.filter(regionIsUiSurface).length;
   return ui >= 1 && regions.length - ui <= 1;
 }
+function compositeRegionsOf(scene) {
+  const comp = scene.composition;
+  const layout = (comp?.layout ?? "").toLowerCase();
+  if (!COMPOSITE_LAYOUTS.has(layout)) return null;
+  const regions = (comp?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
+  return regions.length >= 2 ? regions : null;
+}
+function compositePlateRegion(scene) {
+  const regions = compositeRegionsOf(scene);
+  if (!regions) return null;
+  return regions.find((r) => r.is_presenter) ?? regions.find((r) => !regionIsUiSurface(r)) ?? null;
+}
+function uiRoutedSceneSet(input) {
+  return new Set(uiRoutedRuns(input).flat());
+}
+function uiRoutedRuns(input) {
+  const blueprint = VideoBlueprint.parse(input);
+  const info = blueprint.scenes.map((scene) => {
+    const regions = compositeRegionsOf(scene);
+    if (!regions) return null;
+    const comp = scene.composition;
+    const panels = regions.map((r) => (r.panel ?? "").toLowerCase()).sort().join(",");
+    const surfaceIds = regions.filter(regionIsUiSurface).map((r) => (r.surface_id ?? "").trim()).filter(Boolean).sort().join(",");
+    const sig = surfaceIds ? `sid:${surfaceIds}` : `${(comp?.layout ?? "").toLowerCase()}|${(comp?.split_axis ?? "").toLowerCase()}|${panels}`;
+    return { sig, ui: isUiOnlyComposite(regions) };
+  });
+  const runs = [];
+  let run = [];
+  const flushRun = () => {
+    if (run.some((i) => info[i]?.ui)) runs.push(run);
+    run = [];
+  };
+  info.forEach((inf, i) => {
+    if (!inf) {
+      flushRun();
+      return;
+    }
+    const prev = i > 0 ? info[i - 1] : null;
+    if (!prev || prev.sig !== inf.sig) flushRun();
+    run.push(i);
+  });
+  flushRun();
+  return runs;
+}
 function sceneIsFullScreenUi(scene, present) {
   if (scene.narrative_role?.trim() === "cta") return false;
   const hasCast = present.some((s) => {
@@ -14710,14 +14910,11 @@ function screenStillArgs(durationS, dims) {
     "{{out.video}}"
   ];
 }
-function layeredComposition(scene) {
-  const comp = scene.composition;
-  const layout = (comp?.layout ?? "").toLowerCase();
-  if (!COMPOSITE_LAYOUTS.has(layout)) return null;
-  const regions = (comp?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
-  if (regions.length < 2) return null;
-  if (isUiOnlyComposite(regions)) return null;
-  return { layout, regions, comp: comp ?? {} };
+function layeredComposition(scene, uiRouted) {
+  const regions = compositeRegionsOf(scene);
+  if (!regions) return null;
+  if (uiRouted) return null;
+  return { layout: (scene.composition?.layout ?? "").toLowerCase(), regions, comp: scene.composition ?? {} };
 }
 function splitAxisOf(comp, regions) {
   const panels = regions.map((r) => (r.panel ?? "").toLowerCase());
@@ -14808,7 +15005,7 @@ function buildCompositeScene(layout, regions, comp, scene, i, present, mode, nat
     const bgIdx = regions.findIndex((_, k) => k !== presIdx);
     const bgRef = regionRefs[bgIdx >= 0 ? bgIdx : 0];
     let presRef = regionRefs[presIdx >= 0 ? presIdx : 1];
-    if (layout === "keyed_overlay" && presIdx >= 0) {
+    if (layout === "keyed_overlay") {
       const keyId = `s${i}_key`;
       nodes.push({ id: keyId, type: "video_background_remove", inputs: { video: presRef }, params: {} });
       presRef = `$ref:${keyId}.video`;
@@ -14909,6 +15106,67 @@ function emitScreenScene(i, scene, lengths, out, outAr, nodes, clips) {
   });
   clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
 }
+function sceneIsAllGraphic(scene) {
+  const regions = (scene.composition?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
+  if (regions.length === 0 || regions.some((r) => (r.kind ?? "").toLowerCase() === "camera")) return false;
+  return regions.some((r) => (r.kind ?? "").toLowerCase() === "static_graphic");
+}
+function sceneIsFullFrameGraphic(scene) {
+  return sceneIsAllGraphic(scene);
+}
+function fullFrameGraphicScenes(blueprint) {
+  const scenes = blueprint.scenes;
+  const graphic = new Set(scenes.flatMap((s, i) => sceneIsFullFrameGraphic(s) ? [i] : []));
+  const blocked = (s) => {
+    const regions = (s.composition?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
+    if (regions.some((r) => (r.kind ?? "").toLowerCase() === "camera")) return true;
+    return (s.dialogue ?? []).some((d) => d.on_camera === true);
+  };
+  let changed = true;
+  while (changed) {
+    changed = false;
+    scenes.forEach((s, i) => {
+      if (graphic.has(i)) return;
+      const chainsToPrev = s.continues_previous && graphic.has(i - 1);
+      const next = scenes[i + 1];
+      const chainsToNext = Boolean(next?.continues_previous) && graphic.has(i + 1);
+      if ((chainsToPrev || chainsToNext) && !blocked(s)) {
+        graphic.add(i);
+        changed = true;
+      }
+    });
+  }
+  return graphic;
+}
+function emitGraphicScene(i, scene, lengths, out, outAr, surfaceIngests, nodes, clips) {
+  const regions = (scene.composition?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
+  const surfaceId = regions.find((r) => r.surface_id)?.surface_id;
+  let refId = surfaceId ? surfaceIngests.get(surfaceId) : void 0;
+  if (!refId) {
+    const label = commentSafe((scene.summary || scene.start_frame_prompt || "the designed panel").slice(0, 120));
+    refId = `s${i}_graphic_ref`;
+    nodes.push({
+      id: refId,
+      type: "ingest",
+      params: {
+        source: "path",
+        path: `[TODO: supply the REAL designed graphic for "${label}" \u2014 NEVER AI-generate a designed panel (its typography/wordmarks garble). Rebuild it as brand HTML in video-overlay-composition (the scene's text/logos are already seeded there), export the design from the brand kit, or source stock art; text rides the overlay layer, not this plate]`,
+        expect: "image"
+      }
+    });
+    if (surfaceId) surfaceIngests.set(surfaceId, refId);
+  }
+  nodes.push({
+    id: `s${i}_clip`,
+    type: "ffmpeg",
+    inputs: { frame: `$ref:${refId}.asset` },
+    params: {
+      args: screenStillArgs(lengths.trimTarget, canvasDims(outAr)),
+      outputs: { video: { kind: "video", ext: "mp4" } }
+    }
+  });
+  clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
+}
 var BRAND_CARD_RE = /\b(?:solid|plain|flat|brand|logo|wordmark|end[- ]?card|cta card|title card|colou?r background|background colou?r)\b/i;
 function sceneIsBrandCard(scene, present, isCta) {
   if (!isCta) return false;
@@ -15149,8 +15407,12 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
         speaker: sp,
         // Shown = a cast member speaking AND their element is actually on screen
         // here (not a cutaway). A b-roll cutaway mid-phrase fails this and gets
-        // its own clip while the phrase voice plays under it.
-        shown: isOnCameraSpeaker(raw, casts, cameraOn) && !multiSpeaker.has(sceneIndex) && presenterPresent(sp, sceneIndex),
+        // its own clip while the phrase voice plays under it. An explicit
+        // deconstruct voiceover stamp (`on_camera: false`) wins over element
+        // presence — a speaker pictured in a photo is "present" but not talking.
+        // An all-graphic composition (no camera region) is voiceover by
+        // definition: nobody is on screen to lip-sync.
+        shown: l.on_camera !== false && !sceneIsAllGraphic(scene) && isOnCameraSpeaker(raw, casts, cameraOn) && !multiSpeaker.has(sceneIndex) && presenterPresent(sp, sceneIndex),
         start,
         // Real speech end. When the deconstruct gives no end_s, estimate it from
         // the words — NOT the scene end (which would fabricate continuity across
@@ -15248,7 +15510,8 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     shootMode: mode,
     ingestCache: env.ingestCache
   };
-  const first = buildFrameRef(
+  const chained = anchorScene.continues_previous && out.phraseEnd?.scene === anchor - 1 ? out.phraseEnd.ref : void 0;
+  const first = chained ?? buildFrameRef(
     "start",
     anchorScene.start_frame_asset?.url,
     anchorScene.start_frame_prompt,
@@ -15275,7 +15538,16 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
   const genDur = ceilToSeedance(phraseLen);
   const clipParams = {
     model: env.opts.videoModel,
-    prompt: buildSeedancePrompt(anchorScene, anchor, present, mode, true, phrase.text, env.ttsLanguageCode),
+    prompt: buildSeedancePrompt(
+      anchorScene,
+      anchor,
+      present,
+      mode,
+      true,
+      phrase.text,
+      env.ttsLanguageCode,
+      env.uiRouted.has(anchor)
+    ),
     duration: genDur,
     ...videoResolutionParam(env.opts.videoModel, env.opts.resolution),
     generate_audio: true
@@ -15287,6 +15559,7 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     inputs: { first_frame: first, last_frame: last },
     params: clipParams
   });
+  out.phraseEnd = { ref: last, scene: lastShown };
   const clipRef = `$ref:s${anchor}_clip.video`;
   const speechOffset = Math.max(0, phrase.start_s - clipStart);
   const extractLen = Math.min(Math.max(0.5, phrase.end_s - phrase.start_s), Math.max(0.5, genDur - speechOffset));
@@ -15321,7 +15594,8 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     scene: anchor,
     voice_convert_node: convId,
     scene_s: Math.round(phraseLen * 100) / 100,
-    est_speech_s: Math.round(estSpeechS(phrase.text) * 100) / 100
+    est_speech_s: Math.round(estSpeechWindowS(phrase.text, phrase.start_s, phrase.end_s) * 100) / 100,
+    speech_words: wordCount(phrase.text)
   });
   for (const s of phrase.shownScenes) {
     const sc = env.blueprint.scenes[s];
@@ -15379,7 +15653,8 @@ function emitCompositeInTimeline(composite, scene, i, isLast, env, canonical, en
       scene: i,
       voice_convert_node: `${voiceNode}_conv`,
       scene_s: Math.round(sceneDurationS(scene) * 100) / 100,
-      est_speech_s: Math.round(estSpeechS(text) * 100) / 100
+      est_speech_s: Math.round(estSpeechWindowS(text, start, end) * 100) / 100,
+      speech_words: wordCount(text)
     });
   }
   const mode = sceneShootMode(scene, present, nativeTurn, env.cameraOn, env.casts);
@@ -15471,6 +15746,10 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     shootMode: mode,
     ingestCache: env.ingestCache
   };
+  if (!env.reuse && env.graphicScenes.has(i)) {
+    emitGraphicScene(i, scene, lengths, lengths.out, env.outAr, env.surfaceIngests, nodes, out.clips);
+    return void 0;
+  }
   if (!env.reuse && sceneIsFullScreenUi(scene, present)) {
     emitScreenScene(i, scene, lengths, lengths.out, env.outAr, nodes, out.clips);
     return void 0;
@@ -15480,7 +15759,7 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     emitBrandCardScene(i, lengths, lengths.out, env.outAr, brandPlateColor(env.blueprint), nodes, out.clips);
     return void 0;
   }
-  if (!ambientBroll && lengths.dur <= FLASH_HOLD_MAX_S) {
+  if (!ambientBroll && lengths.dur <= FLASH_HOLD_MAX_S && scene.motion_level !== "dynamic") {
     emitFlashHold(i, scene, env.slots, ctx, lengths, lengths.out, env.outAr, nodes, out.clips);
     return void 0;
   }
@@ -15515,7 +15794,8 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
       genAr: env.genAr,
       videoModel: env.opts.videoModel,
       resolution: env.opts.resolution,
-      nativeLang: env.ttsLanguageCode
+      nativeLang: env.ttsLanguageCode,
+      uiRouted: env.uiRouted.has(i)
     },
     nodes
   );
@@ -15536,10 +15816,11 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
 }
 function buildTimeline(blueprint, slots, opts, nodes) {
   const reuse = opts.frames === "reuse";
+  const uiRouted = uiRoutedSceneSet(blueprint);
   const compositeScenes = /* @__PURE__ */ new Set();
   if (!reuse) {
     blueprint.scenes.forEach((s, i) => {
-      if (layeredComposition(s)) compositeScenes.add(i);
+      if (layeredComposition(s, uiRouted.has(i))) compositeScenes.add(i);
     });
   }
   const canonical = collapseVoiceover(blueprint);
@@ -15555,6 +15836,9 @@ function buildTimeline(blueprint, slots, opts, nodes) {
     cameraOn: onCameraDialogue(blueprint),
     casts: castIdSet(blueprint),
     ingestCache: /* @__PURE__ */ new Map(),
+    uiRouted,
+    graphicScenes: fullFrameGraphicScenes(blueprint),
+    surfaceIngests: /* @__PURE__ */ new Map(),
     ttsLanguageCode: deriveTtsLanguageCode(blueprint)
   };
   const out = {
@@ -15583,7 +15867,7 @@ function buildTimeline(blueprint, slots, opts, nodes) {
   const lastIndex = blueprint.scenes.length - 1;
   let prevEndFrame;
   blueprint.scenes.forEach((scene, i) => {
-    const composite = compositeScenes.has(i) ? layeredComposition(scene) : null;
+    const composite = compositeScenes.has(i) ? layeredComposition(scene, uiRouted.has(i)) : null;
     if (composite) {
       emitCompositeInTimeline(
         composite,
@@ -15780,9 +16064,42 @@ function sourceHint(fe) {
       return `baker images icon "${desc}"`;
   }
 }
-function floatingStub(fe, sceneStart) {
-  const at = fe.appears_at_s ?? sceneStart;
-  const dur = fe.duration_s ?? 2.5;
+function floatKey(fe) {
+  return [
+    (fe.kind ?? "element").toLowerCase(),
+    (fe.brand_name || fe.what_it_represents || fe.description || "").toLowerCase().trim(),
+    positionClass(fe.position)
+  ].join("|");
+}
+function floatIsRoutedSurface(fe, sceneIsUiRouted) {
+  return sceneIsUiRouted && (fe.kind ?? "").toLowerCase() === "ui_element" && UI_SURFACE_RE.test(fe.description ?? "");
+}
+function addFloatDetection(windows, fe, at, end) {
+  const wins = windows.get(floatKey(fe)) ?? [];
+  const last = wins[wins.length - 1];
+  if (last && at <= last.end + OVERLAY_REDETECT_GAP_S) {
+    last.end = Math.max(last.end, end);
+    return;
+  }
+  wins.push({ fe, at, end });
+  windows.set(floatKey(fe), wins);
+}
+function collectFloatWindows(blueprint, uiRouted) {
+  const windows = /* @__PURE__ */ new Map();
+  blueprint.scenes.forEach((scene, i) => {
+    const sceneStart = scene.start_s ?? 0;
+    const floats = z11.array(FloatingElement).safeParse(scene.floating_elements ?? []);
+    if (!floats.success) return;
+    for (const fe of floats.data) {
+      const at = fe.appears_at_s ?? sceneStart;
+      const dur = fe.duration_s ?? 2.5;
+      if (floatIsRoutedSurface(fe, uiRouted.has(i)) || dur < OVERLAY_MIN_DUR_S) continue;
+      addFloatDetection(windows, fe, at, at + dur);
+    }
+  });
+  return [...windows.values()].flat().sort((a, b) => a.at - b.at);
+}
+function floatingStub(fe, at, dur) {
   const kind = commentSafe(fe.kind ?? "element");
   const label = commentSafe(fe.brand_name || fe.what_it_represents || fe.description || fe.kind || "element");
   const hint = commentSafe(sourceHint(fe));
@@ -15792,27 +16109,49 @@ function floatingStub(fe, sceneStart) {
     `<img class="ov clip ${positionClass(fe.position)}" src="your-${slug}.png" data-start="${at}" data-dur="${dur}" alt="" /> -->`
   ].join("\n");
 }
-function uiPipStub(scene) {
-  const comp = scene.composition;
-  const layout = (comp?.layout ?? "").toLowerCase();
-  if (!COMPOSITE_LAYOUTS.has(layout)) return "";
-  const regions = (comp?.regions ?? []).filter((r) => Boolean(r) && typeof r === "object");
-  if (regions.length < 2 || !isUiOnlyComposite(regions)) return "";
-  const ui = regions.find(regionIsUiSurface);
-  const at = scene.start_s ?? 0;
-  const dur = Math.max(0.5, Math.round(((scene.end_s ?? at + 2.5) - at) * 100) / 100);
+function uiSurfaceStub(blueprint, run) {
+  const scenes = run.map((i) => blueprint.scenes[i]).filter((s) => Boolean(s));
+  if (scenes.length === 0) return "";
+  const first = scenes[0];
+  const last = scenes[scenes.length - 1];
+  const surfaceOf = (scene) => {
+    const regions = compositeRegionsOf(scene) ?? [];
+    return regions.find(regionIsUiSurface) ?? regions.find((r) => !r.is_presenter);
+  };
+  const ui = scenes.map(surfaceOf).find(Boolean);
+  const at = first.start_s ?? 0;
+  const end = last.end_s ?? at + 2.5;
+  const dur = Math.max(0.5, Math.round((end - at) * 100) / 100);
   const label = commentSafe(ui?.summary || ui?.frame_prompt || ui?.panel || "the app screen");
-  return [
-    `<!-- PHONE UI @ ${at}s for ${dur}s \u2014 the app/site screen this scene shows: ${label}.`,
+  const states = scenes.length > 1 ? scenes.map((s) => {
+    const beat = surfaceOf(s)?.summary || s.summary || "\u2026";
+    return `       @ ${s.start_s ?? 0}s \u2014 ${commentSafe(beat)}`;
+  }) : [];
+  const isGraphic = scenes.some((s) => (compositeRegionsOf(s) ?? []).some((r) => r.kind === "static_graphic"));
+  const sourcing = isGraphic ? [
+    "     Build it as a REAL designed panel, NEVER AI-generate its text/typography:",
+    "       hand-build a brand-accurate HTML block in this composition (restyle the seeded",
+    "       overlay text, or `npx hyperframes add <block>` for a ready-made card),",
+    "     \u2014 OR drop the design asset (export it from the brand kit) as panel.png here;",
+    "     then nest it as a timed clip:"
+  ] : [
     "     Build it as a REAL surface, NEVER AI: capture the live page \u2014",
     "       baker images screenshot https://<brand-domain>/<path>  (image-library skill)",
     "     \u2014 OR hand-build a brand-accurate HTML screen; then frame it in a phone mockup:",
     "       npx hyperframes add phone-scroll   (writes compositions/phone-scroll.html)",
-    "     drop the screenshot as screenshot.png in this dir and nest it as a PIP clip:",
+    "     drop the screenshot as screenshot.png in this dir and nest it as a PIP clip:"
+  ];
+  const kindLabel = isGraphic ? "GRAPHIC PANEL" : "PHONE UI";
+  const noun = isGraphic ? "the designed graphic panel this window shows" : "the app/site screen this window shows";
+  return [
+    `<!-- ${kindLabel} @ ${at}s for ${dur}s \u2014 ${noun}: ${label}.`,
+    ...states.length > 0 ? ["     ONE continuous surface; its states over the window:", ...states] : [],
+    ...sourcing,
     `     <div class="clip" data-composition-src="compositions/phone-scroll.html" data-start="${at}" data-duration="${dur}" data-track-index="2" data-width="1080" data-height="1920"></div> -->`
   ].join("\n");
 }
-function buildOverlayHtml(input) {
+var CAPTION_ROLE_RE = /^(?:caption|captions|subtitle|subtitles|karaoke)$/i;
+function buildOverlayHtml(input, opts = {}) {
   const blueprint = VideoBlueprint.parse(input);
   const blocks = [
     [
@@ -15831,33 +16170,15 @@ function buildOverlayHtml(input) {
       "     Positions: edit the .pos-* classes or add your own. -->"
     ].join("\n")
   ];
-  const ovParts = mergeCaptions(blueprint).map((e) => overlayElement(e.ov, e.at, Math.round((e.end - e.at) * 1e3) / 1e3)).filter(Boolean);
+  const ovParts = mergeCaptions(blueprint).filter((e) => !(opts.captionsActive && CAPTION_ROLE_RE.test(e.ov.role ?? ""))).map((e) => overlayElement(e.ov, e.at, Math.round((e.end - e.at) * 1e3) / 1e3)).filter(Boolean);
   if (ovParts.length > 0) blocks.push(ovParts.join("\n"));
-  const seenFloats = /* @__PURE__ */ new Map();
-  const keepFloat = (fe, sceneStart) => {
-    const at = fe.appears_at_s ?? sceneStart;
-    const dur = fe.duration_s ?? 2.5;
-    if (dur < OVERLAY_MIN_DUR_S) return false;
-    const key = [
-      (fe.kind ?? "element").toLowerCase(),
-      (fe.brand_name || fe.what_it_represents || fe.description || "").toLowerCase().trim(),
-      positionClass(fe.position)
-    ].join("|");
-    const lastEnd = seenFloats.get(key);
-    if (lastEnd !== void 0 && at <= lastEnd + OVERLAY_REDETECT_GAP_S) {
-      seenFloats.set(key, Math.max(lastEnd, at + dur));
-      return false;
-    }
-    seenFloats.set(key, at + dur);
-    return true;
-  };
-  for (const scene of blueprint.scenes) {
-    const sceneStart = scene.start_s ?? 0;
-    const floats = z11.array(FloatingElement).safeParse(scene.floating_elements ?? []);
-    const parts = (floats.success ? floats.data.filter((fe) => keepFloat(fe, sceneStart)).map((fe) => floatingStub(fe, sceneStart)) : []).filter(Boolean);
-    const pip = uiPipStub(scene);
-    if (pip) parts.push(pip);
-    if (parts.length > 0) blocks.push(parts.join("\n"));
+  const runs = uiRoutedRuns(blueprint);
+  const uiRouted = new Set(runs.flat());
+  const floatParts = collectFloatWindows(blueprint, uiRouted).map((w) => floatingStub(w.fe, w.at, Math.round((w.end - w.at) * 100) / 100)).filter(Boolean);
+  if (floatParts.length > 0) blocks.push(floatParts.join("\n"));
+  for (const run of runs) {
+    const stub = uiSurfaceStub(blueprint, run);
+    if (stub) blocks.push(stub);
   }
   return blocks.join("\n\n");
 }
@@ -15932,6 +16253,7 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
     params: { source: "path", path: opts.blueprintPath ?? "./prompt.json", expect: "json" }
   });
   const slots = buildElementSlots(elements);
+  extendPresenceByPromptMentions(slots, blueprint);
   slots.forEach((slot, i) => {
     nodes.push({
       id: slot.id,
@@ -15945,7 +16267,7 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
   let videoNode = "spine";
   const overlays = blueprint.scenes.flatMap((s) => s.overlays ?? []);
   const floating = blueprint.scenes.flatMap((s) => s.floating_elements ?? []);
-  const hasUiPip = blueprint.scenes.some((s) => uiPipStub(s) !== "");
+  const hasUiPip = uiRoutedRuns(blueprint).length > 0;
   if (overlays.length > 0 || floating.length > 0 || hasUiPip) {
     nodes.push({
       id: "overlaid",
@@ -16328,7 +16650,10 @@ function collectClipAdvisories(scene, i, out) {
   const window = sceneDurationS(scene);
   if (window > SEEDANCE_SAFE_MAX_S)
     out.oversize.push({ scene: i, scene_s: round22(window), clip_s: ceilToSeedance(window) });
-  const speech = (scene.dialogue ?? []).reduce((s, line) => s + (line.line ? estSpeechS(line.line) : 0), 0);
+  const speech = (scene.dialogue ?? []).reduce(
+    (s, line) => s + (line.line ? estSpeechWindowS(line.line, line.start_s, line.end_s) : 0),
+    0
+  );
   if (speech > window * OVERSTUFF_RATIO)
     out.overstuffed.push({ scene: i, scene_s: round22(window), est_speech_s: round22(speech) });
 }
@@ -16517,7 +16842,7 @@ async function detectShotCutsBestEffort(videoPath, threshold) {
       process.stderr.write(`Shot-cut detection skipped (${msg}); using LLM boundaries.
 `);
     }
-    return [];
+    return void 0;
   }
 }
 function fail2(code, message) {
@@ -16546,7 +16871,7 @@ function buildDeconstructCanvas(videoPath, deconstructModel, opts) {
   if (typeof opts.maxScenes === "number") deconstructParams.max_scenes = opts.maxScenes;
   if (opts.language) deconstructParams.language = opts.language;
   if (opts.focus) deconstructParams.focus = opts.focus;
-  if (opts.shotCuts && opts.shotCuts.length > 0) deconstructParams.shot_cuts = opts.shotCuts;
+  if (opts.shotCuts) deconstructParams.shot_cuts = opts.shotCuts;
   deconstructParams.max_clip_s = SEEDANCE_DURATIONS[SEEDANCE_DURATIONS.length - 1];
   return {
     schema: "baker-canvas/1",
@@ -16697,7 +17022,7 @@ var scaffoldVideoCommand = defineCommand87({
     await cp(SHIPPED_COMPOSITION_DIR, compositionDest, { recursive: true });
     await stampCompositionDims(compositionDest, outDims);
     const indexPath = path9.join(compositionDest, "index.html");
-    const overlayHtml = buildOverlayHtml(blueprint);
+    const overlayHtml = buildOverlayHtml(blueprint, { captionsActive: Boolean(transcript) });
     const indexHtml = await readFile6(indexPath, "utf8");
     const injected = indexHtml.replace("<!--OVERLAYS-->", () => overlayHtml);
     if (injected === indexHtml && overlayHtml.trim()) {
@@ -16729,15 +17054,31 @@ var scaffoldVideoCommand = defineCommand87({
       return fail2("scaffold", e instanceof Error ? e.message : String(e));
     }
     const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(canvas, outDir), defaultRegistry());
+    if (!validation.ok) {
+      const meta = canvas.metadata;
+      const todo = meta.todo ?? {};
+      todo.blocking_validation_issues = validation.issues;
+      meta.todo = todo;
+    }
+    await writeFile2(outPath, `${JSON.stringify(canvas, null, 2)}
+`, "utf8");
     if (!validation.ok) {
       process.stderr.write(
-        `${JSON.stringify({ ok: false, error: { code: "validation", issues: validation.issues } }, null, 2)}
+        `${JSON.stringify(
+          {
+            ok: false,
+            error: { code: "validation", issues: validation.issues },
+            canvas_path: outPath,
+            prompt_path: blueprintPath,
+            note: "The canvas WAS written despite the blocking issue(s) \u2014 fix them in place, then `baker canvas validate` before running."
+          },
+          null,
+          2
+        )}
 `
       );
       process.exit(2);
     }
-    await writeFile2(outPath, `${JSON.stringify(canvas, null, 2)}
-`, "utf8");
     await ensureGitignore(process.cwd(), ["canvas/", ".context/"]);
     process.stdout.write(
       `${JSON.stringify(