@koda-sl/baker-cli 0.123.0-dev.70bf43ce4 → 0.123.0-dev.8e4328629

package/dist/cli.js

@@ -5,6 +5,7 @@ import {
   IMAGE_GENERATE_MODELS,
   LayerExecutionError,
   MODEL_REGISTRY,
+  REF_PREFIX,
   SEEDANCE_DURATIONS,
   ValidationError,
   collectAssetRefLikes,
@@ -14,13 +15,14 @@ import {
   elementMentionKeywords,
   generateCatalog,
   isPersistedAssetRef,
+  parseRefExpr,
   requireCredentialsFromEnv,
   resolveConcurrency,
   sha256Hex,
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-VSVGPYJK.js";
+} from "./chunk-43KBQLP5.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -855,7 +857,6 @@ var LINKEDIN_LIMITS = {
     choiceOptionsMax: 30,
     choiceOptionTextMax: 100,
     thankYouMessageMax: 300,
-    privacyPolicyTextMax: 2e3,
     legalDisclaimerMax: 2e3,
     consentsMax: 5,
     // Campaign Manager caps disclosure checkboxes at 5
@@ -1450,7 +1451,6 @@ var leadFormFields = {
   /** Form language, e.g. { country: "US", language: "en" }. Defaults to the account locale on LinkedIn. */
   locale: z2.object({ country: z2.string().length(2), language: z2.string().length(2) }).optional(),
   privacyPolicyUrl: httpsUrlSchema,
-  privacyPolicyText: z2.string().max(LEAD.privacyPolicyTextMax).optional(),
   questions: z2.array(leadFormQuestionSchema).min(1).max(LEAD.questionsMax),
   consents: z2.array(leadFormConsentSchema).max(LEAD.consentsMax).optional(),
   hiddenFields: z2.array(leadFormHiddenFieldSchema).max(LEAD.hiddenFieldsMax).optional(),
@@ -9390,7 +9390,7 @@ var leadFormsCreateCommand = defineCommand38({
 Required: name, headline (\u226460), privacyPolicyUrl, questions[] (\u226412; playbook: \u22644 for completion).
 Each question is a predefined profile field ({ name, predefinedField: "EMAIL" }) or a custom question ({ name, questionType: "MULTIPLE_CHOICE", options: [...] }; \u22643 custom).
 Best-practice fields the preview will nudge for if missing: 1-3 qualifying questions, consents[] (disclosure checkboxes), thankYou.message + thankYou.landingUrl|appointmentUrl.
-Also supported: locale, formImageId|formImageUrn, privacyPolicyText, hiddenFields[], legalDisclaimer, thankYou.cta. Example: baker ads linkedin lead-forms create --file form.json`
+Also supported: locale, formImageId|formImageUrn, hiddenFields[], legalDisclaimer, thankYou.cta. Example: baker ads linkedin lead-forms create --file form.json`
   },
   args: {
     ...accountArgs,
@@ -14439,23 +14439,28 @@ function isResolvableRelative(value) {
   return typeof value === "string" && value.length > 0 && !value.includes("[TODO") && !path2.isAbsolute(value);
 }
 
-// src/commands/canvas/run-record.ts
-import path3 from "path";
-var MAX_RUN_NODES = 200;
-var MAX_OUTPUTS_PER_NODE = 10;
-var MAX_FINAL_OUTPUTS = 10;
+// src/commands/canvas/node-preview.ts
 var MAX_PARAMS_PREVIEW_LENGTH = 4e3;
-function paramsPreviewFromParams(params) {
-  if (params === void 0 || params === null) return void 0;
-  const text = humanParamText(params, "prompt") ?? humanParamText(params, "source") ?? compactJson(params);
-  if (!text) return void 0;
-  return text.length > MAX_PARAMS_PREVIEW_LENGTH ? `${text.slice(0, MAX_PARAMS_PREVIEW_LENGTH - 1)}\u2026` : text;
-}
-function humanParamText(params, key) {
+var SPEC_KEYS = [
+  "model",
+  "aspect_ratio",
+  "image_size",
+  "resolution",
+  "duration",
+  "subject_type",
+  "font_size",
+  "expect",
+  "source",
+  "path",
+  "url"
+];
+var BODY_KEYS = ["prompt", "text", "subject_description"];
+function scalarField(params, key) {
   const value = params[key];
+  if (typeof value === "number") return String(value);
   if (typeof value !== "string") return void 0;
   const trimmed = value.trim();
-  return trimmed && !trimmed.startsWith("$ref:") ? trimmed : void 0;
+  return trimmed && !trimmed.startsWith(REF_PREFIX) ? trimmed : void 0;
 }
 function compactJson(params) {
   try {
@@ -14465,6 +14470,32 @@ function compactJson(params) {
     return void 0;
   }
 }
+function cap(text) {
+  return text.length > MAX_PARAMS_PREVIEW_LENGTH ? `${text.slice(0, MAX_PARAMS_PREVIEW_LENGTH - 1)}\u2026` : text;
+}
+function nodeParamsPreview(params, deps) {
+  const refsLine = deps && deps.length > 0 ? `refs: ${deps.join(", ")}` : void 0;
+  if (!params || typeof params !== "object") return refsLine;
+  const record = params;
+  const spec = [];
+  for (const key of SPEC_KEYS) {
+    const value = scalarField(record, key);
+    if (value !== void 0) spec.push(`${key}: ${value}`);
+  }
+  if (refsLine) spec.push(refsLine);
+  const body = BODY_KEYS.map((key) => scalarField(record, key)).find(Boolean);
+  const header = spec.join("\n");
+  const composed = header && body ? `${header}
+
+${body}` : header || body || compactJson(record);
+  return composed ? cap(composed) : void 0;
+}
+
+// src/commands/canvas/run-record.ts
+import path3 from "path";
+var MAX_RUN_NODES = 200;
+var MAX_OUTPUTS_PER_NODE = 10;
+var MAX_FINAL_OUTPUTS = 10;
 var MAX_CREATIVE_SLUG_LENGTH = 100;
 function creativeSlugFromCanvasPath(filePath) {
   const normalized = filePath.split(path3.sep).join("/");
@@ -14583,7 +14614,7 @@ var RunProgressTracker = class {
           outputs: [],
           deps: node.deps,
           status: "pending",
-          paramsPreview: paramsPreviewFromParams(node.params)
+          paramsPreview: nodeParamsPreview(node.params, node.deps)
         });
       }
       this.planned = true;
@@ -14658,6 +14689,7 @@ var RunRecordPoster = class {
   latest = null;
   inflight = null;
   warned = false;
+  keepaliveTimer = null;
   constructor(post) {
     this.post = post;
   }
@@ -14666,12 +14698,36 @@ var RunRecordPoster = class {
     this.latest = payload;
     if (!this.inflight) this.inflight = this.pump();
   }
+  /**
+   * Re-post the latest snapshot on an interval even with no new node events, so
+   * the backend's `canvasRuns.updatedAt` heartbeat stays fresh during a long
+   * single-clip poll (a video_generate clip can run minutes with no
+   * intervening node events). When this process dies the keepalive stops → the
+   * run's `updatedAt` goes stale → the backend reconciliation sweep force-fails
+   * it as interrupted and surfaces the clips that finished. `produce` returns
+   * null before the plan lands (nothing worth posting yet).
+   */
+  startKeepalive(produce, intervalMs = 6e4) {
+    if (this.keepaliveTimer) return;
+    this.keepaliveTimer = setInterval(() => {
+      const snapshot = produce();
+      if (snapshot) this.enqueue(snapshot);
+    }, intervalMs);
+    this.keepaliveTimer.unref?.();
+  }
+  stopKeepalive() {
+    if (this.keepaliveTimer) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+  }
   /**
    * Post the terminal record (awaited, errors surfaced to the caller). Any
    * queued progress snapshot is superseded — the terminal record is the full
    * state — but an in-flight POST is awaited first so it can't land after.
    */
   async flush(terminal) {
+    this.stopKeepalive();
     this.latest = null;
     if (this.inflight) await this.inflight;
     await this.post(terminal);
@@ -14774,6 +14830,10 @@ var runCommand = defineCommand88({
       description: "Ignore any interrupted-run marker and start a new run id instead of resuming"
     },
     "cache-policy": { type: "string", description: "read_write | bypass | read_only" },
+    regenerate: {
+      type: "string",
+      description: "Comma-separated node ids to force fresh THIS run (e.g. --regenerate gen_4x5,gen_9x16), bypassing the content cache for just those nodes + everything downstream. For a persistent re-render, bump a node's `regenerate` field in the canvas JSON instead."
+    },
     concurrency: {
       type: "string",
       description: "Max nodes per layer in flight at once (default 5; env BAKER_CANVAS_CONCURRENCY)"
@@ -14831,6 +14891,34 @@ var runCommand = defineCommand88({
       );
       process.exit(2);
     }
+    let regenerate;
+    if (args.regenerate !== void 0) {
+      const requested = String(args.regenerate).split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+      const known = new Set(canvasNodeIds(parsed));
+      const unknown = requested.filter((id) => !known.has(id));
+      if (unknown.length > 0) {
+        process.stderr.write(
+          `${JSON.stringify(
+            {
+              ok: false,
+              error: {
+                code: "unknown_regenerate_node",
+                message: `--regenerate names node id(s) not in this canvas: ${unknown.join(", ")}. Known ids: ${[...known].join(", ")}`
+              }
+            },
+            null,
+            2
+          )}
+`
+        );
+        process.exit(2);
+      }
+      if (requested.length > 0) {
+        regenerate = new Set(requested);
+        process.stdout.write(`[regenerate] forcing fresh this run: ${[...regenerate].join(", ")} (+ downstream)
+`);
+      }
+    }
     const remoteCache = args["remote-cache"] !== void 0 ? String(args["remote-cache"]) !== "off" : void 0;
     const engine = createEngineFromEnv({
       cacheDir: args["cache-dir"] ? String(args["cache-dir"]) : void 0,
@@ -14860,6 +14948,9 @@ var runCommand = defineCommand88({
     const record = args.record === false ? null : buildRecorder();
     const progress = record ? new RunProgressTracker(runId, recordMeta) : null;
     const poster = record ? new RunRecordPoster(record) : null;
+    if (progress && poster) {
+      poster.startKeepalive(() => progress.hasPlan() ? progress.snapshot() : null);
+    }
     try {
       const policy = args["cache-policy"] ?? "read_write";
       const result = await engine.run(parsed, {
@@ -14870,6 +14961,7 @@ var runCommand = defineCommand88({
           (args.concurrency ?? args.parallel) !== void 0 ? String(args.concurrency ?? args.parallel) : void 0,
           process.env.BAKER_CANVAS_CONCURRENCY
         ),
+        regenerate,
         onProgress: progress && poster ? (event) => {
           progress.apply(event);
           if (progress.hasPlan()) poster.enqueue(progress.snapshot());
@@ -14923,6 +15015,11 @@ var runCommand = defineCommand88({
     }
   }
 });
+function canvasNodeIds(parsed) {
+  const nodes = parsed?.nodes;
+  if (!Array.isArray(nodes)) return [];
+  return nodes.map((node) => node?.id).filter((id) => typeof id === "string");
+}
 function buildRecorder() {
   return async (payload) => {
     try {
@@ -14946,6 +15043,12 @@ import { defineCommand as defineCommand89 } from "citty";
 import { z as z11 } from "zod";
 var GEN_ASPECT_RATIOS = /* @__PURE__ */ new Set(["1:1", "4:5", "9:16", "16:9", "4:3", "3:4", "2:3", "3:2", "21:9"]);
 var DEFAULT_ASPECT_RATIO = "9:16";
+var SHEET_SUBJECT_TYPE = {
+  person: "person",
+  animal: "character"
+};
+var ACTOR_SHEET_MODEL = "google/gemini-3-pro-image-preview";
+var ACTOR_SHEET_IMAGE_SIZE = "4K";
 var Blueprint = z11.object({
   meta: z11.object({ estimated_aspect_ratio: z11.string().optional() }).loose().optional(),
   text_content: z11.array(z11.object({ text: z11.string().optional() }).loose()).optional()
@@ -15017,6 +15120,11 @@ function todoPath(el, label) {
   const lock = t === "person" || t === "animal" ? " \u2014 REQUIRED: this is the emotional hero; ground it in a real reference (image-library / video-library / Pinterest), do not delete this slot and free-generate" : "";
   return `[TODO: drop a real image for ${label} (${el.type})${desc}${expr}${lock}]`;
 }
+function sheetSubjectDescription(el) {
+  const desc = el.description ?? `the ${el.type}`;
+  const expr = el.expression ? `, ${el.expression} expression` : "";
+  return `${desc}${expr} \u2014 clean plate: no phone-camera UI chrome, no app interface, no watermarks, no captions or on-image text`;
+}
 function aspectRatio(blueprint, opts) {
   const requested = opts.aspectRatio ?? blueprint.meta?.estimated_aspect_ratio;
   return requested && GEN_ASPECT_RATIOS.has(requested) ? requested : DEFAULT_ASPECT_RATIO;
@@ -15040,6 +15148,7 @@ function scaffoldStaticAd(input, elementsInput, opts) {
     type: "ingest",
     params: opts.imageIsUrl ? { source: "url", url: opts.imagePath, expect: "image" } : { source: "path", path: opts.imagePath, expect: "image" }
   });
+  const includeActorSheets = opts.includeActorSheets !== false;
   const usedIds = /* @__PURE__ */ new Set(["prompt", "original", "gen", "brandfont", "type_ref"]);
   const elementSlots = [];
   assignElementLabels(elements).forEach(({ el, label }, i) => {
@@ -15051,7 +15160,25 @@ function scaffoldStaticAd(input, elementsInput, opts) {
       type: "ingest",
       params: { source: "path", path: todoPath(el, label), expect: "image" }
     });
-    elementSlots.push({ ref: `$ref:${id}.asset`, label, type: el.type });
+    let ref = `$ref:${id}.asset`;
+    const subjectType = includeActorSheets ? SHEET_SUBJECT_TYPE[el.type.toLowerCase()] : void 0;
+    if (subjectType) {
+      const sheetId = `${id}_sheet`;
+      usedIds.add(sheetId);
+      nodes.push({
+        id: sheetId,
+        type: "image_reference_sheet",
+        inputs: { references: [ref] },
+        params: {
+          model: ACTOR_SHEET_MODEL,
+          subject_description: sheetSubjectDescription(el),
+          subject_type: subjectType,
+          image_size: ACTOR_SHEET_IMAGE_SIZE
+        }
+      });
+      ref = `$ref:${sheetId}.sheet`;
+    }
+    elementSlots.push({ ref, label, type: el.type });
   });
   const hasFont = includeFont;
   if (hasFont) {
@@ -15112,6 +15239,7 @@ function scaffoldStaticAd(input, elementsInput, opts) {
 function staticAdReport(input, elementsInput, opts) {
   const blueprint = Blueprint.parse(input);
   const elements = MainElements.parse(elementsInput);
+  const includeActorSheets = opts.includeActorSheets !== false;
   return {
     element_count: elements.length,
     elements: assignElementLabels(elements).map(({ el, label }) => ({
@@ -15121,6 +15249,7 @@ function staticAdReport(input, elementsInput, opts) {
       asset_todo: todoPath(el, label)
     })),
     includes_font: opts.includeFont !== false,
+    actor_sheets: includeActorSheets ? assignElementLabels(elements).filter(({ el }) => SHEET_SUBJECT_TYPE[el.type.toLowerCase()]).map(({ label }) => label) : [],
     aspect_ratio: aspectRatio(blueprint, opts)
   };
 }
@@ -15190,6 +15319,84 @@ function isValidScaffoldSlug(slug) {
   return slug.length <= SCAFFOLD_SLUG_MAX_LENGTH && SCAFFOLD_SLUG_PATTERN.test(slug);
 }
 
+// src/commands/canvas/definition-graph.ts
+var MAX_NODES = 300;
+function walkStrings(value, cb) {
+  if (typeof value === "string") {
+    cb(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) walkStrings(v, cb);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const v of Object.values(value)) walkStrings(v, cb);
+  }
+}
+function canvasToDefinitionGraph(canvas) {
+  const rawNodes = canvas?.nodes;
+  if (!Array.isArray(rawNodes)) return null;
+  const parsed = [];
+  for (const raw of rawNodes) {
+    const id = raw?.id;
+    const type = raw?.type;
+    if (typeof id !== "string" || typeof type !== "string") continue;
+    parsed.push({ id, type, inputs: raw.inputs, params: raw.params });
+    if (parsed.length >= MAX_NODES) break;
+  }
+  if (parsed.length === 0) return null;
+  const ids = new Set(parsed.map((n) => n.id));
+  const nodes = parsed.map(({ id, type, inputs, params }) => {
+    const deps = /* @__PURE__ */ new Set();
+    const collect = (s) => {
+      if (!s.startsWith(REF_PREFIX)) return;
+      const expr = parseRefExpr(s);
+      if (expr && expr.nodeId !== id && ids.has(expr.nodeId)) deps.add(expr.nodeId);
+    };
+    walkStrings(inputs, collect);
+    walkStrings(params, collect);
+    const depList = [...deps];
+    const paramsPreview = nodeParamsPreview(params, depList);
+    const base = { id, type };
+    if (depList.length > 0) base.deps = depList;
+    if (paramsPreview) base.paramsPreview = paramsPreview;
+    return base;
+  });
+  const rawOutput = canvas?.output;
+  const outNode = rawOutput?.node;
+  const outSlot = rawOutput?.output;
+  const output = typeof outNode === "string" && typeof outSlot === "string" ? { node: outNode, output: outSlot } : void 0;
+  return { nodes, output };
+}
+
+// src/commands/canvas/sync-definition.ts
+async function syncCreativeDefinitionBestEffort(input) {
+  const chatId = process.env.BAKER_CHAT_ID;
+  if (!chatId) return;
+  const graph = canvasToDefinitionGraph(input.canvas);
+  if (!graph || graph.nodes.length === 0) return;
+  try {
+    const creds = requireCredentialsFromEnv();
+    const client = new BackendClient({ baseUrl: creds.url, apiKey: creds.apiKey });
+    await client.syncCreativeDefinition({
+      slug: input.slug,
+      title: input.title,
+      platform: input.platform,
+      formats: input.formats,
+      sourceReferenceUrl: input.sourceReferenceUrl,
+      graph,
+      chatId
+    });
+    process.stdout.write(`[definition] synced workflow graph (${graph.nodes.length} nodes) \u2014 view it in the dashboard
+`);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`[warn] workflow graph not synced (${msg})
+`);
+  }
+}
+
 // src/commands/canvas/scaffold-static-ad.ts
 async function fileExists(target) {
   try {
@@ -15225,7 +15432,7 @@ function resolveModel(kind, preferred) {
   const ids = Object.keys(MODEL_REGISTRY[kind]);
   return ids.includes(preferred) ? preferred : ids[0] ?? preferred;
 }
-var DESCRIBE_FOCUS = `the GLOBAL LAYOUT GEOMETRY above all \u2014 the column/row grid, each region's approximate bounds as a percentage of frame width and height, any panel SPLITS and their proportions (e.g. a left column split into a ~60% top photo and a ~20% bottom price box), what occupies every region, and for EVERY text block its string verbatim, relative size (x_large | large | medium | small), weight, case, color, and alignment \u2014 including small bottom-corner fine print. Also: the EXPRESSION and emotion of every person/animal (capture exaggerated or AI-edited faces), the ad_intent (what feeling it engineers and how), per-color brand_ownership (which colors are the advertiser's brand vs borrowed-functional like a red comparison column), logos by brand, and all visible text verbatim. CRITICAL \u2014 name the WINNING MECHANISM(S): the special sauce, the specific thing that makes THIS ad a candidate winner rather than a generic ad. A great ad is rarely great by accident, and the mechanism is invisible unless named, so a faithful rewrite quietly discards it. It may be VERBAL (a rhyme, pun, alliteration, rhythm/meter, repetition, antithesis, double meaning), VISUAL (an unexpected crop or scale, a visual gag or pun, a striking juxtaposition, a pattern interrupt, an exaggerated/AI-edited expression, a before/after or comparison, bold negative space, a surprising focal point), or STRUCTURAL (an unusual hook, order, or reveal). Record each as a \`winning_mechanisms\` array of { kind: verbal|visual|structural, device, why_it_works } (e.g. { kind: verbal, device: "rhyme \u2014 'today' / 'go away'", why_it_works: "memorable, playful, reframes cost as relief" }) so a rewrite can rebuild the SAUCE for our brand instead of adapting only the surface and losing what made it convert`;
+var DESCRIBE_FOCUS = "the GLOBAL LAYOUT GEOMETRY above all \u2014 the column/row grid, each region's approximate bounds as a percentage of frame width and height, any panel SPLITS and their proportions (e.g. a left column split into a ~60% top photo and a ~20% bottom price box), what occupies every region, and for EVERY text block its string verbatim, relative size (x_large | large | medium | small), weight, case, color, and alignment \u2014 including small bottom-corner fine print. Also: the EXPRESSION and emotion of every person/animal (capture exaggerated or AI-edited faces), the ad_intent (what feeling it engineers and how), per-color brand_ownership (which colors are the advertiser's brand vs borrowed-functional like a red comparison column), logos by brand, and all visible text verbatim. the TYPOGRAPHY as a first-class identity signal \u2014 for EVERY distinct typeface in the ad record a `fonts` entry: which text blocks use it, its classification (serif | slab-serif | sans | script | display | mono), a best-guess family or a close lookalike (e.g. 'a Tiempos-like high-contrast serif', 'Circular-like geometric sans'), and its weight/case/styling \u2014 because a faithful rewrite that keeps the words but loses the letterforms loses the brand; ALSO record whether the advertiser's LOGO appears in more than one lockup (a square/icon MARK and a horizontal WORDMARK are two different assets \u2014 capture BOTH). CRITICAL \u2014 name the WINNING MECHANISM(S): the special sauce, the specific thing that makes THIS ad a candidate winner rather than a generic ad. A great ad is rarely great by accident, and the mechanism is invisible unless named, so a faithful rewrite quietly discards it. It may be VERBAL (a rhyme, pun, alliteration, rhythm/meter, repetition, antithesis, double meaning), VISUAL (an unexpected crop or scale, a visual gag or pun, a striking juxtaposition, a pattern interrupt, an exaggerated/AI-edited expression, a before/after or comparison, bold negative space, a surprising focal point), or STRUCTURAL (an unusual hook, order, or reveal). Record each as a `winning_mechanisms` array of { kind: verbal|visual|structural, device, why_it_works } (e.g. { kind: verbal, device: \"rhyme \u2014 'today' / 'go away'\", why_it_works: \"memorable, playful, reframes cost as relief\" }) so a rewrite can rebuild the SAUCE for our brand instead of adapting only the surface and losing what made it convert";
 var LAYOUT_SYSTEM = "You convert an advertisement's JSON blueprint into a precise, structured LAYOUT MAP of the frame \u2014 the spatial grid a designer would rebuild it from. Be exhaustive and quantitative: every region, its bounds as a percentage of the frame, and every text block with its relative size. Output ONLY a JSON object, no prose.";
 var LAYOUT_PROMPT = `AD BLUEPRINT (from image_describe):
 {{blueprint}}
@@ -15251,7 +15458,7 @@ var SELECT_PROMPT = `AD BLUEPRINT (from image_describe):
 {{blueprint}}
 
 From this blueprint, list ONLY the elements that are prominent, important, and identity-bearing \u2014 the ones a reproduction must ground in a real asset:
-- the brand logo/wordmark (from brands_logos with function_in_image = advertiser_brand) -> type "logo"
+- the brand logo/wordmark (from brands_logos with function_in_image = advertiser_brand) -> type "logo". A brand often ships its logo in TWO lockups \u2014 a square/icon MARK and a horizontal WORDMARK \u2014 and an ad may use both (e.g. an icon in a product mock plus the wordmark in the sign-off). When more than one distinct lockup of the SAME advertiser appears, emit a SEPARATE logo element for each (label them by lockup, e.g. LOGO_MARK and LOGO_WORDMARK) so the reproduction can drop the right file in each slot instead of stretching one logo to cover both.
 - trust/rating/certification/app-store/review badges (brands_logos with function_in_image = trust_badge | review_platform | certification_or_seal | app_store_badge | payment_method) -> type "badge"
 - a showcased/hero product or package (a foreground entry in subjects that the ad is selling) -> type "product"
 - a foreground person (from people) \u2014 keep it when its identity matters OR it is the emotional/hero focal point of the ad, even a generic one with no brand identity -> type "person"
@@ -15395,7 +15602,11 @@ var scaffoldStaticAdCommand = defineCommand89({
     "layout-model": { type: "string", description: "Override the text_generate model id for the layout pass" },
     "gen-model": { type: "string", description: "Override the image_generate model id" },
     aspect: { type: "string", description: "Force the output aspect ratio (else inferred from the image)" },
-    "skip-font": { type: "boolean", description: "Skip the brand-font \u2192 type-specimen slot" }
+    "skip-font": { type: "boolean", description: "Skip the brand-font \u2192 type-specimen slot" },
+    "skip-actor-sheets": {
+      type: "boolean",
+      description: "Ground each person/animal on its lone dropped photo instead of a generated multi-view sheet"
+    }
   },
   async run({ args }) {
     const slug = args.slug ? String(args.slug) : void 0;
@@ -15445,7 +15656,8 @@ var scaffoldStaticAdCommand = defineCommand89({
       imageIsUrl: canvasImageIsUrl,
       blueprintPath: canvasBlueprintPath,
       aspectRatio: args.aspect ? String(args.aspect) : void 0,
-      includeFont: !args["skip-font"]
+      includeFont: !args["skip-font"],
+      includeActorSheets: !args["skip-actor-sheets"]
     };
     let canvas;
     let report;
@@ -15482,6 +15694,16 @@ var scaffoldStaticAdCommand = defineCommand89({
         "utf8"
       );
     }
+    if (slug) {
+      await syncCreativeDefinitionBestEffort({
+        slug,
+        title: args.title ? String(args.title) : titleFromSlug(slug),
+        platform: resolvePlatform(args.platform ? String(args.platform) : void 0),
+        formats: resolveFormats(args.aspect ? String(args.aspect) : report.aspect_ratio),
+        sourceReferenceUrl: imageIsUrl ? imageSource : void 0,
+        canvas
+      });
+    }
     process.stdout.write(
       `${JSON.stringify(
         {
@@ -15502,8 +15724,9 @@ var scaffoldStaticAdCommand = defineCommand89({
           checklist: {
             edit_prompt: `Edit ${path9.basename(blueprintPath)} \u2014 it is the blueprint generated from your image; rewrite it into the ad you want (palette, copy, claims, subjects). It feeds the generator directly.`,
             assets_to_supply: report.elements,
-            font_slot: report.includes_font ? "Drop a brand font at the [TODO] brandfont path, or delete the brandfont + type_ref nodes to skip it." : "skipped (--skip-font)",
-            note: "Replace every [TODO] ingest path with a real file, then `baker canvas validate` and `baker canvas run`. Running generates a billed image \u2014 it is not free."
+            font_slot: report.includes_font ? "Drop a brand font at the [TODO] brandfont path (the describe pass recorded the ad's typefaces under `fonts` in prompt.json \u2014 match those). The font is wired into the render as a TYPE SPECIMEN reference so generated text takes the brand letterforms. Delete the brandfont + type_ref nodes to skip it." : "skipped (--skip-font)",
+            actor_sheets: report.actor_sheets.length > 0 ? `Each living hero (${report.actor_sheets.join(", ")}) is fused into a generated multi-view reference sheet (image_reference_sheet) that the render grounds on \u2014 so drop ONE clean photo at that hero's ingest and the sheet builds the consistent turnaround. Pass --skip-actor-sheets to ground on the lone photo instead.` : "none (no person/animal heroes detected, or --skip-actor-sheets)",
+            note: "Populate as you go: for each [TODO] ingest slot, source its real asset and wire it into the slot right away \u2014 one at a time, not all sourced first then reconciled at the end. When every slot is filled, `baker canvas validate` then `baker canvas run`. Running generates a billed image \u2014 it is not free."
           }
         },
         null,
@@ -15515,7 +15738,8 @@ var scaffoldStaticAdCommand = defineCommand89({
 });
 
 // src/commands/canvas/scaffold-video.ts
-import { cp, mkdir as mkdir3, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
+import { access as access2, cp, mkdir as mkdir3, readFile as readFile7, writeFile as writeFile3 } from "fs/promises";
+import { tmpdir as tmpdir2 } from "os";
 import path12 from "path";
 import { defineCommand as defineCommand90 } from "citty";
 
@@ -16224,6 +16448,13 @@ function slimBlueprintForSelection(blueprintInput) {
   }
   return out;
 }
+function slimBlueprintForFrameStyle(blueprintInput) {
+  if (!blueprintInput || typeof blueprintInput !== "object" || Array.isArray(blueprintInput)) return blueprintInput;
+  const bp = blueprintInput;
+  const out = {};
+  for (const k of ["version", "source", "global", "reference_elements"]) if (k in bp) out[k] = bp[k];
+  return out;
+}
 function roleForType2(type) {
   switch (type.toLowerCase()) {
     case "logo":
@@ -16316,8 +16547,8 @@ function extendPresenceByPromptMentions(slots, blueprint) {
     }
   });
 }
-var ACTOR_SHEET_MODEL = "google/gemini-3-pro-image-preview";
-var SHEET_SUBJECT_TYPE = {
+var ACTOR_SHEET_MODEL2 = "google/gemini-3-pro-image-preview";
+var SHEET_SUBJECT_TYPE2 = {
   person: "person",
   animal: "character",
   product: "product",
@@ -16325,7 +16556,7 @@ var SHEET_SUBJECT_TYPE = {
 };
 function buildElementSheets(slots, nodes) {
   for (const slot of slots) {
-    const subjectType = SHEET_SUBJECT_TYPE[slot.type.toLowerCase()];
+    const subjectType = SHEET_SUBJECT_TYPE2[slot.type.toLowerCase()];
     if (!subjectType) continue;
     if (slot.sameAs) continue;
     if (slot.presence.size < 1) continue;
@@ -16338,7 +16569,7 @@ function buildElementSheets(slots, nodes) {
       // The lone dropped ingest is the source; the sheet fans it into a turnaround.
       inputs: { references: [slot.ref] },
       params: {
-        model: ACTOR_SHEET_MODEL,
+        model: ACTOR_SHEET_MODEL2,
         // The clean-plate clause mirrors the frame prompts' CLEAN PLATE block: a sheet
         // that comes back with a fake camera app baked in (P2-22) poisons EVERY frame
         // grounded on it, so the suppression must live on the sheet too.
@@ -16481,9 +16712,10 @@ function buildFrameRef(edge, url, framePrompt, present, ctx, nodes) {
     id: genId,
     type: "image_generate",
     // `params.prompt` is this frame's authoritative, edit-per-frame description.
-    // `target_blueprint` is the shared ad spec (cast identity, palette, brand, type)
-    // the frame must stay consistent with — editing one frame never touches another.
-    inputs: { target_blueprint: "$ref:prompt.asset", ...reference.length > 0 ? { reference } : {} },
+    // `target_blueprint` is the SLIM shared ad spec (global cast identity, palette, brand,
+    // type — no per-scene content) the frame must stay consistent with; editing one frame
+    // never touches another, and no image inlines the whole film to render one frame.
+    inputs: { target_blueprint: "$ref:prompt_style.asset", ...reference.length > 0 ? { reference } : {} },
     params: genParams
   });
   return `$ref:${genId}.images#0`;
@@ -17005,18 +17237,24 @@ function emitFlashHold(i, scene, slots, ctx, lengths, out, outAr, nodes, clips)
   });
   clips.push({ ref: `$ref:s${i}_clip.video`, scene_s: lengths.dur, out });
 }
-function emitScreenScene(i, scene, lengths, out, outAr, nodes, clips) {
-  const label = commentSafe((scene.summary || scene.start_frame_prompt || "the app screen").slice(0, 120));
-  const refId = `s${i}_screen_ref`;
-  nodes.push({
-    id: refId,
-    type: "ingest",
-    params: {
-      source: "path",
-      path: `[TODO: supply the REAL screen for "${label}" \u2014 NEVER AI-generate a UI. Capture a clean, text-free screenshot with \`baker images screenshot https://<brand-domain>/<path>\` (image-library skill); spoken/overlay text rides the overlay layer, not the screenshot]`,
-      expect: "image"
-    }
-  });
+function emitScreenScene(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 app screen").slice(0, 120));
+    refId = `s${i}_screen_ref`;
+    nodes.push({
+      id: refId,
+      type: "ingest",
+      params: {
+        source: "path",
+        path: `[TODO: supply the REAL screen for "${label}" \u2014 NEVER AI-generate a UI. Capture a clean, text-free screenshot with \`baker images screenshot https://<brand-domain>/<path>\` (image-library skill); spoken/overlay text rides the overlay layer, not the screenshot]`,
+        expect: "image"
+      }
+    });
+    if (surfaceId) surfaceIngests.set(surfaceId, refId);
+  }
   nodes.push({
     id: `s${i}_clip`,
     type: "ffmpeg",
@@ -17260,9 +17498,16 @@ function makePresenterPresent(slots, canonical, opts = {}) {
     return presence.has(sceneIndex);
   };
 }
-var PAUSE_GAP_S = 0.6;
 var SEEDANCE_SAFE_MAX_S = SEEDANCE_DURATIONS.find((d) => d >= 10) ?? 10;
 var PHRASE_MAX_S = SEEDANCE_SAFE_MAX_S;
+var PAUSE_GAP_S = 0.6;
+function isAdjacentShownCut(ln, lastShownScene, scenes) {
+  if (!ln.shown || lastShownScene === null) return false;
+  return ln.sceneIndex === lastShownScene + 1 && scenes[ln.sceneIndex]?.continues_previous !== true;
+}
+function breaksPhrase(cur, ln, lineCover, lineClipStart, scenes) {
+  return cur.speaker !== ln.speaker || ln.start - cur.end > PAUSE_GAP_S || isAdjacentShownCut(ln, cur.lastShownScene, scenes) || Math.max(cur.coverEnd, lineCover) - Math.min(cur.clipStart, lineClipStart) > PHRASE_MAX_S;
+}
 var JOIN_DEDUP_MAX_WORDS = 4;
 function joinKey(word) {
   return word.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
@@ -17305,10 +17550,7 @@ function collapseVoiceover(blueprint) {
   const presenter = [...presenters][0];
   return (speaker) => NARRATOR_SPEAKERS.has(speaker.toLowerCase()) ? presenter : speaker;
 }
-function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, presentStrict) {
-  const casts = castIdSet(blueprint);
-  const cameraOn = onCameraDialogue(blueprint);
-  const sceneEndS = (i) => blueprint.scenes[i]?.end_s ?? blueprint.scenes[i]?.start_s ?? 0;
+function multiSpeakerScenes(blueprint, casts, cameraOn, canonical, presentStrict) {
   const multiSpeaker = /* @__PURE__ */ new Set();
   blueprint.scenes.forEach((scene, i) => {
     const onCamAll = new Set(
@@ -17318,32 +17560,45 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
     const effective = onCamPresent.length > 0 ? new Set(onCamPresent) : onCamAll;
     if (effective.size >= 2) multiSpeaker.add(i);
   });
-  const lines = blueprint.scenes.flatMap(
-    (scene, sceneIndex) => compositeScenes.has(sceneIndex) ? [] : (scene.dialogue ?? []).filter((l) => Boolean(l.line?.trim())).map((l) => {
+  return multiSpeaker;
+}
+function lineClipWindow(ln, scenes) {
+  if (!ln.shown) return { cover: ln.end, clipStart: ln.start };
+  const sc = scenes[ln.sceneIndex];
+  const sceneEnd = sc?.end_s ?? sc?.start_s ?? 0;
+  return { cover: Math.max(ln.end, sceneEnd), clipStart: Math.min(ln.start, sc?.start_s ?? ln.start) };
+}
+function dialogueLines(blueprint, ctx) {
+  return blueprint.scenes.flatMap((scene, sceneIndex) => {
+    if (ctx.compositeScenes.has(sceneIndex)) return [];
+    return (scene.dialogue ?? []).filter((l) => Boolean(l.line?.trim())).map((l) => {
       const raw = l.speaker ?? "voiceover";
-      const sp = canonical(raw);
       const text = l.line.trim();
       const start = l.start_s ?? scene.start_s ?? 0;
+      const shown = l.on_camera !== false && !sceneIsAllGraphic(scene) && isOnCameraSpeaker(raw, ctx.casts, ctx.cameraOn) && !ctx.multiSpeaker.has(sceneIndex) && ctx.presenterPresent(ctx.canonical(raw), sceneIndex);
       return {
         sceneIndex,
-        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. 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),
+        speaker: ctx.canonical(raw),
+        shown,
         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
-        // a long silent b-roll gap and wrongly merge two separate phrases).
         end: l.end_s ?? start + estSpeechS(text),
         text
       };
-    })
-  ).sort((a, b) => a.start - b.start);
+    });
+  }).sort((a, b) => a.start - b.start);
+}
+function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, presentStrict) {
+  const casts = castIdSet(blueprint);
+  const cameraOn = onCameraDialogue(blueprint);
+  const multiSpeaker = multiSpeakerScenes(blueprint, casts, cameraOn, canonical, presentStrict);
+  const lines = dialogueLines(blueprint, {
+    compositeScenes,
+    multiSpeaker,
+    canonical,
+    casts,
+    cameraOn,
+    presenterPresent
+  });
   const phrases = [];
   let cur = null;
   const flush = () => {
@@ -17361,12 +17616,8 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
     cur = null;
   };
   for (const ln of lines) {
-    const lineCover = ln.shown ? Math.max(ln.end, sceneEndS(ln.sceneIndex)) : ln.end;
-    const lineClipStart = ln.shown ? Math.min(ln.start, blueprint.scenes[ln.sceneIndex]?.start_s ?? ln.start) : ln.start;
-    const breakRun = !cur || cur.speaker !== ln.speaker || ln.start - cur.end > PAUSE_GAP_S || // Cap by SCENE COVERAGE span, not line end — a presenter run whose sliced scenes span
-    // more than one Seedance clip splits into the next take here (at this scene's
-    // boundary, never mid-scene), so no segment ever reads past the generated clip.
-    Math.max(cur.coverEnd, lineCover) - Math.min(cur.clipStart, lineClipStart) > PHRASE_MAX_S;
+    const { cover: lineCover, clipStart: lineClipStart } = lineClipWindow(ln, blueprint.scenes);
+    const breakRun = !cur || breaksPhrase(cur, ln, lineCover, lineClipStart, blueprint.scenes);
     if (breakRun || !cur) {
       flush();
       cur = {
@@ -17377,6 +17628,7 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
         coverEnd: lineCover,
         clipStart: lineClipStart,
         texts: [ln.text],
+        lastShownScene: ln.shown ? ln.sceneIndex : null,
         shown: /* @__PURE__ */ new Set()
       };
     } else {
@@ -17384,6 +17636,7 @@ function buildPhrases(blueprint, canonical, compositeScenes, presenterPresent, p
       cur.end = Math.max(cur.end, ln.end);
       cur.coverEnd = Math.max(cur.coverEnd, lineCover);
       cur.clipStart = Math.min(cur.clipStart, lineClipStart);
+      if (ln.shown) cur.lastShownScene = ln.sceneIndex;
     }
     if (ln.shown) cur.shown.add(ln.sceneIndex);
   }
@@ -17491,19 +17744,12 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     inputs: { clip: clipRef },
     params: { args: audioExtractArgs(extractLen, speechOffset), outputs: { audio: { kind: "audio", ext: "mp3" } } }
   });
-  const convId = `s${anchor}_conv`;
-  nodes.push({
-    id: convId,
-    type: "audio_voice_convert",
-    inputs: { audio: `$ref:s${anchor}_voextract.audio`, voice_ref: `$ref:${voiceNode}.voice_id` },
-    params: { model: FIXED_VOICE_CONVERT_MODEL, voice: "{{voice_ref}}" }
-  });
-  out.voTracks.push({
-    slot: convId,
-    ref: `$ref:${convId}.audio`,
+  const convId = `${voiceNode}_conv`;
+  out.nativeSegments.push({
+    voiceNode,
+    ref: `$ref:s${anchor}_voextract.audio`,
     start_s: phrase.start_s,
-    end_s: phrase.end_s,
-    kind: "vo"
+    end_s: phrase.start_s + extractLen
   });
   out.voSegments.push({
     slot: convId,
@@ -17519,18 +17765,35 @@ function emitPhraseClip(phrase, voiceNode, env, nodes, out) {
     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];
-    if (!sc) continue;
-    const rawOffset = (sc.start_s ?? clipStart) - clipStart;
-    out.sceneSlice.set(s, {
+  registerMergedPhraseSlices(phrase, clipRef, clipStart, genDur, Boolean(chained), env, out);
+}
+function registerMergedPhraseSlices(phrase, clipRef, clipStart, genDur, chained, env, out) {
+  const shown = [...phrase.shownScenes].sort((a, b) => a - b);
+  let r = 0;
+  let firstRegistered = true;
+  while (r < shown.length) {
+    const first = shown[r];
+    let last = first;
+    while (r + 1 < shown.length && shown[r + 1] === last + 1) last = shown[++r];
+    r++;
+    const firstSc = env.blueprint.scenes[first];
+    if (!firstSc) continue;
+    const firstStart = firstSc.start_s ?? clipStart;
+    const rawOffset = firstStart - clipStart;
+    const runEnd = env.blueprint.scenes[last]?.end_s ?? firstStart + sceneDurationS(firstSc);
+    out.sceneSlice.set(first, {
       clipRef,
-      // Snap a sub-frame offset (line-start vs scene-start drift) to 0 so a single-scene
-      // phrase hits the whole-clip fast path instead of a needless re-encode + tiny shift.
+      // Snap a sub-frame offset (line-start vs scene-start drift) to 0 so a run that tiles
+      // the clip hits the whole-clip fast path instead of a needless re-encode + tiny shift.
       offset: rawOffset < 0.05 ? 0 : rawOffset,
-      len: sceneDurationS(sc),
-      clipDur: genDur
+      len: Math.max(0.5, runEnd - firstStart),
+      clipDur: genDur,
+      ...firstRegistered && chained ? { continuesFrame: true } : {}
     });
+    firstRegistered = false;
+    for (let s = first + 1; s <= last; s++) {
+      out.sceneSlice.set(s, { clipRef, offset: 0, len: 0, clipDur: genDur, skip: true });
+    }
   }
 }
 function emitPhraseTts(phrase, voiceNode, idx, used, nodes, out, languageCode) {
@@ -17673,7 +17936,7 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     return void 0;
   }
   if (!env.reuse && sceneIsFullScreenUi(scene, present)) {
-    emitScreenScene(i, scene, lengths, lengths.out, env.outAr, nodes, out.clips);
+    emitScreenScene(i, scene, lengths, lengths.out, env.outAr, env.surfaceIngests, nodes, out.clips);
     return void 0;
   }
   const isCta = scene.narrative_role?.trim() === "cta" || isLast;
@@ -17685,7 +17948,8 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
     emitFlashHold(i, scene, env.slots, ctx, lengths, lengths.out, env.outAr, nodes, out.clips);
     return void 0;
   }
-  const first = scene.continues_previous && prevEndFrame ? prevEndFrame : buildFrameRef(
+  const sharesPrevFrame = Boolean(scene.continues_previous && prevEndFrame);
+  const first = sharesPrevFrame && prevEndFrame ? prevEndFrame : buildFrameRef(
     "start",
     scene.start_frame_asset?.url,
     scene.start_frame_prompt,
@@ -17733,9 +17997,26 @@ function emitBrollScene(scene, i, isLast, env, nodes, out, prevEndFrame) {
       out.nativeSegments
     );
   }
-  out.clips.push(clip);
+  out.clips.push(sharesPrevFrame ? { ...clip, continuesFrame: true } : clip);
   return last;
 }
+function emitPresenterSliceClip(i, slice, env, nodes, out) {
+  if (slice.skip) return;
+  const cont = slice.continuesFrame ? { continuesFrame: true } : {};
+  const normDims = env.genAr !== env.outAr ? canvasDims(env.outAr) : void 0;
+  const whole = slice.offset === 0 && Math.abs(slice.len - slice.clipDur) <= 0.05 && !normDims;
+  if (whole) {
+    out.clips.push({ ref: slice.clipRef, scene_s: slice.len, out: null, ...cont });
+    return;
+  }
+  nodes.push({
+    id: `s${i}_seg`,
+    type: "ffmpeg",
+    inputs: { clip: slice.clipRef },
+    params: { args: trimArgs(slice.len, slice.offset, normDims), outputs: { video: { kind: "video", ext: "mp4" } } }
+  });
+  out.clips.push({ ref: `$ref:s${i}_seg.video`, scene_s: slice.len, out: null, ...cont });
+}
 function buildTimeline(blueprint, slots, opts, nodes) {
   const reuse = opts.frames === "reuse";
   const uiRouted = uiRoutedSceneSet(blueprint);
@@ -17808,22 +18089,7 @@ function buildTimeline(blueprint, slots, opts, nodes) {
     }
     const slice = out.sceneSlice.get(i);
     if (slice) {
-      const normDims = env.genAr !== env.outAr ? canvasDims(env.outAr) : void 0;
-      const whole = slice.offset === 0 && Math.abs(slice.len - slice.clipDur) <= 0.05 && !normDims;
-      if (whole) {
-        out.clips.push({ ref: slice.clipRef, scene_s: slice.len, out: null });
-      } else {
-        nodes.push({
-          id: `s${i}_seg`,
-          type: "ffmpeg",
-          inputs: { clip: slice.clipRef },
-          params: {
-            args: trimArgs(slice.len, slice.offset, normDims),
-            outputs: { video: { kind: "video", ext: "mp4" } }
-          }
-        });
-        out.clips.push({ ref: `$ref:s${i}_seg.video`, scene_s: slice.len, out: null });
-      }
+      emitPresenterSliceClip(i, slice, env, nodes, out);
       prevEndFrame = void 0;
       return;
     }
@@ -18109,25 +18375,40 @@ function lastSceneEnd(blueprint) {
   for (const s of blueprint.scenes) end = Math.max(end, s.end_s ?? 0);
   return end > 0 ? end : 8;
 }
-function concatArgs(count) {
+function seamDropOps(clips, i, seam) {
+  if (seam === "off") return null;
+  if (seam === "head" && i > 0 && clips[i]?.continuesFrame) return "trim=start_frame=1,setpts=PTS-STARTPTS";
+  if (seam === "tail" && clips[i + 1]?.continuesFrame) return "reverse,trim=start_frame=1,setpts=PTS-STARTPTS,reverse";
+  return null;
+}
+function concatArgs(clips, seam) {
   const inputs = [];
-  let labels = "";
-  for (let i = 0; i < count; i++) {
+  const pre = [];
+  const labels = [];
+  clips.forEach((_, i) => {
     inputs.push("-i", `{{in.c${i}}}`);
-    labels += `[${i}:v]`;
-  }
-  return [...inputs, "-filter_complex", `${labels}concat=n=${count}:v=1:a=0[v]`, "-map", "[v]", "{{out.video}}"];
+    const ops = seamDropOps(clips, i, seam);
+    if (ops) {
+      pre.push(`[${i}:v]${ops}[c${i}]`);
+      labels.push(`[c${i}]`);
+    } else {
+      labels.push(`[${i}:v]`);
+    }
+  });
+  const graph = [...pre, `${labels.join("")}concat=n=${clips.length}:v=1:a=0[v]`].join(";");
+  return [...inputs, "-filter_complex", graph, "-map", "[v]", "{{out.video}}"];
 }
 function clipInputLen(c) {
   return c.scene_s + (c.out?.dur ?? 0);
 }
-function xfadeSpineArgs(clips) {
+function xfadeSpineArgs(clips, seam) {
   const n = clips.length;
   const inputs = [];
   const filt = [];
   for (let i = 0; i < n; i++) {
     inputs.push("-i", `{{in.c${i}}}`);
-    filt.push(`[${i}:v]format=yuv420p,fps=30,setsar=1,settb=AVTB[c${i}]`);
+    const ops = seamDropOps(clips, i, seam);
+    filt.push(`[${i}:v]format=yuv420p,fps=30,setsar=1,settb=AVTB${ops ? `,${ops}` : ""}[c${i}]`);
   }
   let cur = "c0";
   let accLen = clipInputLen(clips[0]);
@@ -18149,13 +18430,13 @@ function xfadeSpineArgs(clips) {
   }
   return [...inputs, "-filter_complex", filt.join(";"), "-map", "[v]", "{{out.video}}"];
 }
-function buildSpine(clips, nodes) {
+function buildSpine(clips, seam, nodes) {
   const inputs = {};
   clips.forEach((c, i) => {
     inputs[`c${i}`] = c.ref;
   });
   const hasTransition = clips.length > 1 && clips.some((c) => c.out);
-  const args = hasTransition ? xfadeSpineArgs(clips) : concatArgs(clips.length);
+  const args = hasTransition ? xfadeSpineArgs(clips, seam) : concatArgs(clips, seam);
   nodes.push({
     id: "spine",
     type: "ffmpeg",
@@ -18164,16 +18445,24 @@ function buildSpine(clips, nodes) {
   });
   return "$ref:spine.video";
 }
-function scaffoldVideoCanvas(input, elementsInput, opts) {
-  const blueprint = VideoBlueprint.parse(input);
-  injectHookPhysicality(blueprint);
-  const elements = RecurringElements.parse(elementsInput);
-  const nodes = [];
+function emitBlueprintIngests(opts, nodes) {
   nodes.push({
     id: "prompt",
     type: "ingest",
     params: { source: "path", path: opts.blueprintPath ?? "./prompt.json", expect: "json" }
   });
+  nodes.push({
+    id: "prompt_style",
+    type: "ingest",
+    params: { source: "path", path: opts.blueprintStylePath ?? "./prompt.style.json", expect: "json" }
+  });
+}
+function scaffoldVideoCanvas(input, elementsInput, opts) {
+  const blueprint = VideoBlueprint.parse(input);
+  injectHookPhysicality(blueprint);
+  const elements = RecurringElements.parse(elementsInput);
+  const nodes = [];
+  emitBlueprintIngests(opts, nodes);
   const slots = buildElementSlots(elements);
   extendPresenceByPromptMentions(slots, blueprint);
   slots.forEach((slot, i) => {
@@ -18185,7 +18474,7 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
   });
   buildElementSheets(slots, nodes);
   const { clips, voTracks, vo_segments, talking_scenes } = buildTimeline(blueprint, slots, opts, nodes);
-  let videoRef = buildSpine(clips, nodes);
+  let videoRef = buildSpine(clips, opts.seamDedup ?? "head", nodes);
   let videoNode = "spine";
   const overlays = blueprint.scenes.flatMap((s) => s.overlays ?? []);
   const floating = blueprint.scenes.flatMap((s) => s.floating_elements ?? []);
@@ -18427,7 +18716,7 @@ function buildMotionBoard(blueprint) {
   });
 }
 var VIDEO_GUIDE = [
-  "Scaffolded by `baker canvas scaffold-video` \u2014 a runnable reproduction of your reference video, built like an editing timeline. The VOICE is cut at PAUSES, not at visual cuts: each continuous-speech PHRASE is ONE Seedance clip (native lip-sync + audio) re-voiced to one brand voice, so a sentence never breaks mid-word across a cut. Each scene's PICTURE is independent: a scene that SHOWS the speaker slices its window out of the phrase clip; a b-roll cutaway gets its own silent clip (or a still hold for a sub-2s flash) laid over the continuing voice; a pure-voiceover stretch is one ElevenLabs tts read. Every clip gets a CLEAN-PLATE start AND end keyframe (no baked text), RECAST to your dropped reference assets \u2014 Seedance interpolates real in-shot motion between them. Each frame grounds ONLY on its own extracted frame + el_* slots (never another generated frame), so all frames render in PARALLEL (no cross-frame cascade). A SPLIT-SCREEN / PICTURE-IN-PICTURE / KEYED-PRESENTER scene is reproduced as one clip PER REGION, stacked or overlaid (see `metadata.todo.composition`). On-screen text/graphics are a separate HTML overlay layer you paint; audio is the voice + SFX + a ducked music bed, normalized stereo. It is a STARTING POINT, not a locked render: add, delete, reorder, split, merge, or re-time scenes freely (a b-roll cutaway INSIDE a phrase lands at an approximate beat \u2014 nudge it) \u2014 see `metadata.todo.full_flexibility`.",
+  "Scaffolded by `baker canvas scaffold-video` \u2014 a runnable reproduction of your reference video, built like an editing timeline. It is a sequence of clear SHOTS separated at COMPLETE BREAKS (hard cuts): two adjacent presenter shots at a cut are TWO clips, never glued into one take. What stays continuous is the VOICE \u2014 a voiceover narration is ONE read across the b-roll it plays over, and a b-roll CUTAWAY between two on-camera moments leaves the presenter shot continuous with the insert sliced in \u2014 and each person keeps ONE brand voice (all their clips' native audio re-voiced in a single per-speaker pass), so timbre holds across the cuts. A presenter shot is ONE Seedance clip (native lip-sync + audio); a pure-voiceover stretch is one ElevenLabs tts read; a sub-2s flash is a still hold. A single shot too long for one clip splits into takes that share a boundary frame \u2014 the spine drops the duplicated frame (`--seam-dedup head|tail|off`). Every clip gets a CLEAN-PLATE start AND end keyframe (no baked text), RECAST to your dropped reference assets \u2014 Seedance interpolates real in-shot motion between them. Each frame grounds ONLY on its own extracted frame + el_* slots (never another generated frame), so all frames render in PARALLEL (no cross-frame cascade). A SPLIT-SCREEN / PICTURE-IN-PICTURE / KEYED-PRESENTER scene is reproduced as one clip PER REGION, stacked or overlaid (see `metadata.todo.composition`). On-screen text/graphics are a separate HTML overlay layer you paint; audio is the voice + SFX + a ducked music bed, normalized stereo. It is a STARTING POINT, not a locked render: add, delete, reorder, split, merge, or re-time scenes freely \u2014 see `metadata.todo.full_flexibility`.",
   "",
   "WHAT TO DO NEXT:",
   "0. RE-CRAFT THE SCRIPT FIRST (don't clone). This reference already won in-market, but copying a video is much harder than a static: the hook is targeting and may not transfer, and the message must become TRUE for our brand. Work the `metadata.todo.script_recraft` checklist \u2014 for each scene judge its role (hook/body/CTA), decide keep/cut/reorder/replace, and re-author every line for OUR customer's pain + OUR offer. See `references/script-craft.md` (hook/body/CTA framework) and the `meta-ads-playbook` skill. Most of the work lives here.",
@@ -18511,9 +18800,9 @@ function buildVideoTodo(report, overlayCount, floatingCount, opts, blueprint) {
       voice_description: d.voice_description,
       line: d.line
     })),
-    talking_head_note: "PHRASE-NATIVE: a continuous-speech phrase where the speaker is shown is ONE Seedance clip (the full phrase quoted in s<anchor>_clip's prompt + generate_audio) so lips+voice are generated together \u2014 no tts, no veed-lipsync. Scenes that show the speaker slice their window out of that clip (s<i>_seg); edit the phrase line in the s<anchor>_clip prompt to re-author it. A pure-voiceover phrase (speaker never shown) is one ElevenLabs tts read instead.",
-    voice_note: "ONE voice per person: a single voice_select is reused across all that person's phrases (on-camera AND off \u2014 the deconstruct's `voiceover` label folds into the sole presenter). Each presenter phrase's native audio is re-voiced to that brand voice via audio_voice_convert (eleven_multilingual_sts_v2, one convert per phrase, timing preserved so lips stay matched). Set voice_select.voice_id's gender/language to match the creator.",
-    native_timing: "The voice is cut at PAUSES, not at visual cuts, so a sentence spanning a cut stays one continuous read (no mid-word break). The clip is generated long enough for the estimated speech; if a line runs longer than its phrase window the voice continues a beat into the following pause (natural VO continuity). `metadata.video.talking_scenes` carries each phrase's scene_s vs est_speech_s. CAVEAT: a b-roll cutaway INSIDE a phrase lands at an approximate (proportional) time \u2014 Seedance exposes no word timing \u2014 so if a cutaway is off its beat, nudge the scene boundary (it's a starting point).",
+    talking_head_note: "SHOT-NATIVE: a presenter shot is ONE Seedance clip (its line quoted in s<anchor>_clip's prompt + generate_audio) so lips+voice are generated together \u2014 no tts, no veed-lipsync. Two adjacent presenter shots at a hard cut are SEPARATE clips; a cutaway phrase (the presenter on camera, cut to b-roll, back on camera) stays one clip and slices its on-camera windows (s<i>_seg). Edit the line in the s<anchor>_clip prompt to re-author it. A pure-voiceover phrase (speaker never shown) is one ElevenLabs tts read instead.",
+    voice_note: "ONE voice per person: a single voice_select is reused across all that person's shots (on-camera AND off \u2014 the deconstruct's `voiceover` label folds into the sole presenter). Every presenter clip's native audio is extracted and re-voiced to that brand voice through a SINGLE merged audio_voice_convert per speaker (<voice>_conv, eleven_multilingual_sts_v2, timing preserved so lips stay matched) \u2014 so timbre stays consistent across the separate shot clips. Set voice_select.voice_id's gender/language to match the creator.",
+    native_timing: "Clips separate at COMPLETE BREAKS between shots, but the VOICE stays continuous where it should: a voiceover narration is ONE read across the b-roll it plays over, and a cutaway leaves the presenter's read continuous under the insert. Each clip is generated long enough for its estimated speech. `metadata.video.talking_scenes` carries each shot's scene_s vs est_speech_s. CAVEAT: a b-roll cutaway INSIDE a phrase lands at an approximate (proportional) time \u2014 Seedance exposes no word timing \u2014 so if a cutaway is off its beat, nudge the scene boundary (it's a starting point).",
     craft: {
       note: "Production-craft principles that raise every clip's realism. Full rationale: references/video-craft.md (production craft); references/script-craft.md + meta-ads-playbook for the hook/message layer.",
       principles: [
@@ -18772,6 +19061,62 @@ function fail2(code, message) {
 `);
   process.exit(2);
 }
+var VIDEO_EXT_BY_MIME = {
+  "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/webm": ".webm",
+  "video/x-matroska": ".mkv"
+};
+function referenceVideoExt(url, contentType) {
+  const fromPath = path12.extname(new URL(url).pathname).toLowerCase();
+  if (fromPath && fromPath.length <= 5) return fromPath;
+  const mime = (contentType ?? "").split(";")[0]?.trim().toLowerCase();
+  return mime && VIDEO_EXT_BY_MIME[mime] || ".mp4";
+}
+async function fileExists2(target) {
+  return access2(target).then(
+    () => true,
+    () => false
+  );
+}
+function videoSourceReference(blueprint, fileArg2) {
+  const bp = blueprint ?? {};
+  const durable = typeof bp.source?.url === "string" ? bp.source.url : void 0;
+  const original = /^https?:\/\//i.test(fileArg2) ? fileArg2 : void 0;
+  const brand = bp.global?.branding?.brand_name;
+  return { url: durable ?? original, advertiser: typeof brand === "string" && brand.trim() ? brand.trim() : void 0 };
+}
+function videoDefinitionDescription(blueprint) {
+  const g = (blueprint ?? {}).global ?? {};
+  const notes = g.reproduction_notes;
+  if (typeof notes === "string" && notes.trim()) return notes.trim();
+  const product = g.branding?.product;
+  return typeof product === "string" && product.trim() ? product.trim() : void 0;
+}
+async function materializeReferenceVideo(fileArg2) {
+  if (!/^https?:\/\//i.test(fileArg2)) return path12.resolve(fileArg2);
+  let res;
+  try {
+    res = await fetch(fileArg2);
+  } catch (e) {
+    throw new Error(`failed to download reference video: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!res.ok) throw new Error(`failed to download reference video (${res.status} ${res.statusText})`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (bytes.length === 0) throw new Error("reference video download was empty");
+  const dest = path12.join(
+    tmpdir2(),
+    `baker-ref-${sha256Hex(bytes).slice(0, 16)}${referenceVideoExt(fileArg2, res.headers.get("content-type"))}`
+  );
+  await writeFile3(dest, bytes);
+  return dest;
+}
+function resolveSeamDedup(raw) {
+  if (raw === void 0) return "head";
+  const v = String(raw);
+  if (v === "head" || v === "tail" || v === "off") return v;
+  throw new Error(`--seam-dedup must be "head", "tail", or "off" (got "${v}")`);
+}
 function resolveModels2(args) {
   const pick = (flag, kind, fallback) => args[flag] ? String(args[flag]) : resolveModel2(kind, fallback);
   return {
@@ -18868,7 +19213,11 @@ var scaffoldVideoCommand = defineCommand90({
     description: "Turn a reference video into a runnable reproduction canvas in one command. Runs billed passes \u2014 video_deconstruct (the full scene-by-scene blueprint + transcript, baked to prompt.json as the editable 'prompt') and an AI selection of the video's RECURRING identity elements (person/animal/product/logo) \u2014 then scaffolds a pipeline where every scene boundary is a static-ad-grade frame (the blueprint as target_blueprint, a reference legend, the real frame as anchor) and each recurring element gets ONE shared [TODO] ingest slot wired into every frame it appears in. The clips feed Seedance an ultra-detailed motion brief (action, camera, dialogue, transcript). Edit prompt.json, drop the real source images, then `baker canvas run`."
   },
   args: {
-    file: { type: "positional", required: true, description: "Path to the reference video" },
+    file: {
+      type: "positional",
+      required: true,
+      description: "Reference video \u2014 a local path OR an http(s) URL (e.g. a winning-ads link). A URL is downloaded for you; pass --slug or --out with it."
+    },
     out: { type: "string", description: "Output canvas path (default <video-dir>/<name>.video.canvas.json)" },
     slug: {
       type: "string",
@@ -18879,6 +19228,10 @@ var scaffoldVideoCommand = defineCommand90({
       type: "boolean",
       description: "Give silent b-roll scenes native diegetic ambient mixed deep under the music bed (off by default)"
     },
+    "seam-dedup": {
+      type: "string",
+      description: `How to dedup the frame two clips SHARE when a long shot is split for length: "head" (default, drop the second clip's first frame), "tail" (drop the first clip's last frame), or "off" (keep both).`
+    },
     "max-scenes": { type: "string", description: "Cap the number of scenes the deconstruct emits" },
     "shot-threshold": {
       type: "string",
@@ -18886,6 +19239,14 @@ var scaffoldVideoCommand = defineCommand90({
     },
     language: { type: "string", description: "Transcript/dialogue language hint (e.g. fr, en)" },
     focus: { type: "string", description: "Known provenance/emphasis to ground the deconstruct" },
+    advertiser: {
+      type: "string",
+      description: "Source advertiser recorded in _definition.md (default: the brand the deconstruct identified)"
+    },
+    platform: {
+      type: "string",
+      description: "Ad platform for _definition.md (meta|google|linkedin|tiktok|youtube|x|other; default meta)"
+    },
     "deconstruct-model": { type: "string", description: "Override the video_deconstruct model id" },
     "select-model": { type: "string", description: "Override the text_generate model id for element selection" },
     "image-model": { type: "string", description: "Override the image_generate model id for frames" },
@@ -18900,8 +19261,7 @@ var scaffoldVideoCommand = defineCommand90({
     }
   },
   async run({ args }) {
-    const videoPath = path12.resolve(String(args.file));
-    const base = path12.basename(videoPath, path12.extname(videoPath));
+    const fileArg2 = String(args.file);
     const slug = args.slug ? String(args.slug) : void 0;
     if (slug && !isValidScaffoldSlug(slug)) {
       process.stderr.write(
@@ -18910,9 +19270,24 @@ var scaffoldVideoCommand = defineCommand90({
       );
       process.exit(2);
     }
+    const isUrl = /^https?:\/\//i.test(fileArg2);
+    if (isUrl && !slug && !args.out) {
+      return fail2(
+        "missing_output_target",
+        "When the reference is a URL, pass --slug (writes src/creatives/<slug>/) or --out <path> so the scaffolded canvas has a home in the repo."
+      );
+    }
+    let videoPath;
+    try {
+      videoPath = await materializeReferenceVideo(fileArg2);
+    } catch (e) {
+      return fail2("download", e instanceof Error ? e.message : String(e));
+    }
+    const base = path12.basename(videoPath, path12.extname(videoPath));
     const outPath = args.out ? path12.resolve(String(args.out)) : slug ? path12.join(process.cwd(), "src", "creatives", slug, `${slug}.canvas.json`) : path12.join(path12.dirname(videoPath), `${base}.video.canvas.json`);
     const outDir = path12.dirname(outPath);
     const blueprintPath = path12.join(outDir, "prompt.json");
+    const blueprintStylePath = path12.join(outDir, "prompt.style.json");
     const frames = args.frames === "reuse" ? "reuse" : "generate";
     const maxScenes = args["max-scenes"] ? Number(args["max-scenes"]) : void 0;
     if (Number.isFinite(maxScenes)) {
@@ -18935,6 +19310,12 @@ var scaffoldVideoCommand = defineCommand90({
     const annotated = annotateBlueprintWithElements(blueprint, elements);
     await writeFile3(blueprintPath, `${JSON.stringify(annotated, null, 2)}
 `, "utf8");
+    await writeFile3(
+      blueprintStylePath,
+      `${JSON.stringify(slimBlueprintForFrameStyle(annotated), null, 2)}
+`,
+      "utf8"
+    );
     let aspect;
     try {
       aspect = resolveAspect(
@@ -18974,8 +19355,10 @@ var scaffoldVideoCommand = defineCommand90({
       overlayCompositionPath: path12.relative(outDir, compositionDest),
       captionsCompositionPath: captions.compositionPath ? path12.relative(outDir, captions.compositionPath) : void 0,
       blueprintPath: path12.relative(outDir, blueprintPath),
+      blueprintStylePath: path12.relative(outDir, blueprintStylePath),
       frames,
       ambient: Boolean(args.ambient),
+      seamDedup: resolveSeamDedup(args["seam-dedup"]),
       ...args.aspect ? { aspect: String(args.aspect) } : {},
       ...args.resolution ? { resolution: String(args.resolution) } : {}
     };
@@ -19014,12 +19397,42 @@ var scaffoldVideoCommand = defineCommand90({
       process.exit(2);
     }
     await ensureGitignore(process.cwd(), ["canvas/", ".context/"]);
+    const sourceRef = videoSourceReference(blueprint, fileArg2);
+    if (slug) {
+      const definitionPath = path12.join(outDir, "_definition.md");
+      if (!await fileExists2(definitionPath)) {
+        await writeFile3(
+          definitionPath,
+          buildCreativeDefinition({
+            title: titleFromSlug(slug),
+            kind: "video",
+            platform: resolvePlatform(args.platform ? String(args.platform) : void 0),
+            formats: resolveFormats(aspect.outAr),
+            sourceReferenceUrl: sourceRef.url,
+            sourceAdvertiser: args.advertiser ? String(args.advertiser) : sourceRef.advertiser,
+            sourceKind: "video",
+            description: videoDefinitionDescription(blueprint)
+          }),
+          "utf8"
+        );
+      }
+    }
+    if (slug) {
+      await syncCreativeDefinitionBestEffort({
+        slug,
+        title: titleFromSlug(slug),
+        formats: [aspect.outAr],
+        canvas,
+        sourceReferenceUrl: sourceRef.url
+      });
+    }
     process.stdout.write(
       `${JSON.stringify(
         {
           ok: true,
           canvas_path: outPath,
           prompt_path: blueprintPath,
+          source_reference: sourceRef.url,
           composition_dir: compositionDest,
           output: canvas.output,
           frames_mode: frames,
@@ -19045,6 +19458,13 @@ var scaffoldVideoCommand = defineCommand90({
             scenes_clamped_to_15s: report.clamped_scenes,
             oversize_scenes: report.oversize_scenes,
             overstuffed_scenes: report.overstuffed_scenes,
+            // A photoreal on-camera person/animal on Seedance can trip ByteDance's
+            // real-person-likeness filter (422 content_policy_blocked, NON-retryable — no
+            // prompt reframe clears it). Surface the escape BEFORE the billed run so a
+            // face-heavy ad isn't discovered broken mid-render.
+            ...report.elements.some((e) => e.type === "person" || e.type === "animal") && /seedance/i.test(videoModel) ? {
+              content_policy_risk: "This ad has a photoreal on-camera cast generating on Seedance. ByteDance's real-person-likeness filter can reject a photoreal AI face with a NON-retryable 422 (content_policy_blocked) \u2014 no prompt change clears it. If clips fail that way, regenerate on Veo (re-run with `--video-model google/veo-3.1-fast`) or make the frame less photoreal."
+            } : {},
             note: "Drop ONE real source image at each el_* [TODO] (reused across every frame that element appears in), confirm each voice_select casting, then `baker canvas validate` and `baker canvas run`. Running generates many billed image/video/audio assets \u2014 it is not free."
           }
         },