@koda-sl/baker-cli 0.265.2-dev.1f1c09c80 → 0.267.0-dev.1f1c09c80

package/README.md

@@ -3641,9 +3641,11 @@ because a video model garbles a wordmark every time:
   becomes a flat brand colour plate (rendered by ffmpeg, not generated), with the mark and
   the call to action over it. `end_card: false` keeps the footage; `end_card: { cta }` sets
   the words on the button, which otherwise default to the last line of the script.
-- **`cast`** — one description of the person the ad is about. The engine builds a reference
-  sheet from it and grounds every beat they appear in on that one identity. A beat sets
-  `cast: false` to opt out (a fitter on a roof, a product close-up).
+- **`cast.avatar`** — the handle of a cast Avatar (`baker avatars list`). The ad grounds
+  every beat they appear in on that avatar's identity sheet and copies its subject
+  description verbatim, so the ad shows the same face as the rest of the company's work.
+  This is the whole journey: `baker avatars create` → `cast.avatar` in the spec → render.
+- **`cast.description`** — a person described in words, when there is no avatar.
 
 Each of these also removes a generation: the closing beat costs no image and no clip.
 

package/dist/cli.js

@@ -27314,6 +27314,12 @@ var RecurringElement = z27.object({
   // pink shirt and believer in a white shirt). Each look gets its own reference
   // slot, but the face/identity must stay identical across them.
   same_as: z27.string().nullable().optional(),
+  /**
+   * A picture of this element that already exists — a cast Avatar's identity sheet,
+   * a product photo, a real location shot. Given, the slot ingests it; absent, the
+   * slot emits a TODO for somebody to drop one by hand.
+   */
+  source_image: z27.string().optional(),
   // Scenes the element appears in. Either a bare list of scene indices (both
   // edges) or per-{scene,edge} entries. Both forms are accepted and merged.
   scenes: z27.array(z27.number()).optional(),
@@ -28683,7 +28689,7 @@ function buildPhrases(blueprint, canonical2, compositeScenes, presenterPresent,
   flush();
   return phrases;
 }
-function makeVoiceFactory(blueprint, canonical2, nodes) {
+function makeVoiceFactory(blueprint, canonical2, nodes, voiceLanguage) {
   const bySpeaker = /* @__PURE__ */ new Map();
   const describe = (speaker) => {
     for (const scene of blueprint.scenes)
@@ -28697,7 +28703,9 @@ function makeVoiceFactory(blueprint, canonical2, nodes) {
     if (existing) return existing;
     const id = sanitizeId(`voice_${speaker}`, `voice_${bySpeaker.size}`);
     const description = describe(speaker);
-    nodes.push({ id, type: "voice_select", params: { description, ...parseVoiceTraits(description) } });
+    const traits = parseVoiceTraits(description);
+    if (voiceLanguage) traits.language = voiceLanguage;
+    nodes.push({ id, type: "voice_select", params: { description, ...traits } });
     bySpeaker.set(speaker, id);
     return id;
   };
@@ -29098,7 +29106,7 @@ function buildTimeline(blueprint, slots, opts, nodes) {
     });
   }
   const canonical2 = collapseVoiceover(blueprint);
-  const ensureVoiceNode = makeVoiceFactory(blueprint, canonical2, nodes);
+  const ensureVoiceNode = makeVoiceFactory(blueprint, canonical2, nodes, opts.voiceLanguage);
   const aspect = resolveAspect(blueprint.source?.aspect_ratio, opts.aspect, genAspectsFor(opts.videoModel));
   const env = {
     blueprint,
@@ -29596,10 +29604,16 @@ function scaffoldVideoCanvas(input, elementsInput, opts) {
   const slots = buildElementSlots(elements);
   extendPresenceByPromptMentions(slots, blueprint);
   slots.forEach((slot, i) => {
+    const element = elements[i];
+    const supplied = typeof element?.source_image === "string" ? element.source_image.trim() : "";
     nodes.push({
       id: slot.id,
       type: "ingest",
-      params: { source: "path", path: todoPath(elements[i], slot.label), expect: "image" }
+      params: {
+        source: "path",
+        path: supplied || todoPath(element, slot.label),
+        expect: "image"
+      }
     });
   });
   buildElementSheets(slots, nodes);
@@ -30841,7 +30855,10 @@ var ReelReview = z28.object({
   brand_mark_visible: z28.boolean().default(false),
   /** Whether the last frames close the ad rather than trailing off. */
   ends_on_a_close: z28.boolean().default(false),
-  ending_note: z28.string().default("")
+  ending_note: z28.string().default(""),
+  /** Whether the ad ever cuts away from the presenter to show anything. */
+  shows_more_than_a_face: z28.boolean().default(true),
+  shows_note: z28.string().default("")
 });
 function buildFrameReviewPrompt(opts) {
   const subject = opts.subject ? ` The advertiser is ${opts.subject}.` : "";
@@ -30869,9 +30886,10 @@ Answer only about what is visible.
 1. CAST. Do the people stay the same people? If the script speaks about one customer and the frames show different faces in that role, say so and count them.
 2. BRAND. Is the advertiser's logo or wordmark visible in ANY frame? Answer yes only if you can actually see a mark \u2014 a colour is not a mark.
 3. ENDING. Do the final frames close the advertisement \u2014 a call to action, a mark, a card \u2014 or does the picture simply carry on and stop?
+4. WHAT IT SHOWS. Does the advertisement ever cut away from the person to show the thing it is selling, or its result? Answer false if every frame is the same person with only the framing changed, and nothing is ever shown.
 
 Reply with only this JSON:
-{"cast_is_consistent":true,"cast_note":"","brand_mark_visible":false,"ends_on_a_close":false,"ending_note":""}`;
+{"cast_is_consistent":true,"cast_note":"","brand_mark_visible":false,"ends_on_a_close":false,"ending_note":"","shows_more_than_a_face":true,"shows_note":""}`;
 }
 function parseReviewJson(raw) {
   const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
@@ -30937,6 +30955,12 @@ function classifyReelFindings(json) {
       what: "No brand mark is visible in any frame. `baker canvas scaffold-ad` draws one from `brand.logo` (the repo path in src/brand/BRAND.md) \u2014 top-left throughout and large on the closing card \u2014 so a mark missing here means the spec carried no logo, or the path did not resolve and the scaffold said so."
     });
   }
+  if (!r.shows_more_than_a_face) {
+    findings.push({
+      severity: "blocking",
+      what: `The ad never shows what it is selling${r.shows_note.trim() ? `: ${r.shows_note.trim()}` : ""} \u2014 every frame is the same person with only the framing changed. Give the middle beats their own picture (the bill, the roof, the install, the house) and set \`cast: false\` on them.`
+    });
+  }
   if (!r.ends_on_a_close) {
     findings.push({
       severity: "warning",
@@ -32483,8 +32507,20 @@ var AdSpec = z30.object({
    * collage rather than a story.
    */
   cast: z30.object({
+    /**
+     * A cast Avatar's handle — `baker avatars list` shows who there is.
+     *
+     * The right way to put a person in an ad. The avatar already has a settled
+     * identity and a rendered identity sheet, so the ad grounds on the same face the
+     * rest of the company's work uses, and its subject description is copied verbatim
+     * rather than re-written per spec — re-phrasing it per render is the other reason
+     * a face drifts across a set.
+     */
+    avatar: z30.string().min(1).optional(),
     /** Who they are, plainly: age, build, hair, wardrobe, the register of the ad. */
-    description: z30.string().min(1)
+    description: z30.string().min(1).optional()
+  }).refine((c) => Boolean(c.avatar || c.description), {
+    message: "give `avatar` (a cast avatar's handle) or `description` \u2014 a cast with neither grounds on nothing"
   }).optional(),
   /**
    * A bed, described in words. Omitted leaves the ad dry — the engine only wires
@@ -32516,6 +32552,11 @@ var AdSpec = z30.object({
   ]).optional(),
   beats: z30.array(Beat).min(2)
 });
+function presenterIsInEveryShot(spec) {
+  if (!spec.cast) return false;
+  const storyBeats = spec.beats.filter((_, i) => !(endCardWanted(spec) && i === spec.beats.length - 1));
+  return storyBeats.length >= 3 && storyBeats.every((b) => b.cast !== false);
+}
 function narrativeRole(index, total) {
   if (index === 0) return "hook";
   if (index === total - 1) return "cta";
@@ -32544,6 +32585,29 @@ var MARKET_BY_LANGUAGE = {
   en: "the United Kingdom",
   "en-us": "the United States"
 };
+var VOICE_LANGUAGE_NAME = {
+  es: "spanish",
+  "es-es": "spanish",
+  "es-mx": "spanish",
+  pt: "portuguese",
+  "pt-br": "portuguese",
+  fr: "french",
+  it: "italian",
+  de: "german",
+  nl: "dutch",
+  pl: "polish",
+  en: "english",
+  "en-us": "english",
+  "en-gb": "english"
+};
+function voiceLanguageFor(spec) {
+  const declared = spec.voice?.language?.trim().toLowerCase();
+  if (declared) return VOICE_LANGUAGE_NAME[declared];
+  const market = spec.market?.trim().toLowerCase();
+  if (!market) return void 0;
+  const byMarket = Object.entries(MARKET_BY_LANGUAGE).find(([, place]) => place.toLowerCase() === market);
+  return byMarket ? VOICE_LANGUAGE_NAME[byMarket[0]] : void 0;
+}
 function marketFor(spec) {
   if (spec.market) return spec.market;
   const lang = spec.voice?.language?.trim().toLowerCase();
@@ -32565,13 +32629,14 @@ function endCardCta(spec) {
   const declared = spec.end_card === false ? void 0 : spec.end_card?.cta;
   return declared?.trim() || (spec.beats[spec.beats.length - 1]?.say ?? "").trim() || null;
 }
-function adSpecCastElements(spec) {
-  const description = spec.cast?.description?.trim();
+function adSpecCastElements(spec, avatar) {
+  const description = (avatar?.subjectDescription ?? spec.cast?.description)?.trim();
   if (!description) return [];
   const lastIndex = spec.beats.length - 1;
   const scenes = spec.beats.map((beat, i) => ({ beat, i })).filter(({ beat, i }) => beat.cast !== false && !(endCardWanted(spec) && i === lastIndex)).map(({ i }) => i);
   if (scenes.length === 0) return [];
-  return [{ type: "person", label: "customer", description, scenes }];
+  const sheet = avatar?.sheetUrl?.trim();
+  return [{ type: "person", label: "customer", description, scenes, ...sheet ? { source_image: sheet } : {} }];
 }
 function adSpecToBlueprint(spec) {
   const total = spec.beats.length;
@@ -32602,7 +32667,10 @@ function adSpecToBlueprint(spec) {
           line: beat.say,
           start_s: Math.round(start * 100) / 100,
           end_s: Math.round(clock * 100) / 100,
-          on_camera: beat.on_camera === true,
+          // Never on the closing plate: it is a flat colour card with no one in it, and
+          // saying someone is on camera there told the engine to look for a mouth to
+          // lip-sync on a picture that has no person.
+          on_camera: beat.on_camera === true && !isClosingCard,
           ...spec.voice?.description ? { voice_description: spec.voice.description } : {}
         }
       ],
@@ -32711,12 +32779,18 @@ function adBrandOverlayCss() {
     "      /* Positioned by this block alone. The composition that actually renders an ad",
     "         is the caption track, which has no .pos-* helpers \u2014 relying on them put the",
     "         brand layer in a file nothing opens and shipped an empty green end plate. */",
-    "      .brand-mark { position: absolute; top: 90px; left: 56px; width: 220px; height: auto;",
+    "      /* Height-led, not width-led. Pinned to 220px WIDE, a wordmark whose SVG",
+    "         viewBox is wider than it is tall rendered clipped \u2014 the first real ad drew",
+    "         `greenlea`. Constraining the height and letting the width follow keeps any",
+    "         aspect ratio whole, and the max-width stops a very wide mark spanning the frame. */",
+    "      .brand-mark { position: absolute; top: 90px; left: 56px; height: 64px; width: auto;",
+    "        max-width: 420px; object-fit: contain;",
     "        opacity: 0.92; filter: drop-shadow(0 2px 8px rgba(0,0,0,0.45)); }",
     "      .endcard { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);",
     "        display: flex; flex-direction: column; align-items: center; gap: 56px;",
     "        width: 100%; max-width: 1080px; padding: 0 60px; text-align: center; }",
-    "      .endcard-logo { width: 620px; max-width: 78%; height: auto; }",
+    "      .endcard-logo { max-width: 78%; max-height: 420px; width: auto; height: auto;",
+    "        object-fit: contain; }",
     "      /* Capped and wrapping, not sized to its content: measured in a real browser,",
     "         `GET YOUR FREE QUOTE` renders 948px wide against a 1080px canvas, so the next",
     "         slightly longer call to action runs off the frame. Two lines beat an edge. */",
@@ -32766,7 +32840,7 @@ registerSchema({
     spec: {
       type: "string",
       required: true,
-      description: "Path to the ad spec JSON. Shape: { format?, market?, brand?, voice?, music?, beats: [{ say, show, on_camera? }] }. Fill `brand` from src/brand/BRAND.md \u2014 `palette` (its hex tokens, most important first) and `logo` (the repo path to the mark) are what make the ad look like the client rather than like stock. `market` is where the ad is SET; omitted, it is inferred from the voice language, and getting it wrong is what fills a Spanish ad with British houses. `say` is ONE clause ending in its own punctuation \u2014 it becomes a caption card verbatim, so two sentences in one beat produce a card holding both. `show` is the shot brief for that line. Set `on_camera` ONLY when that beat's subject talks to camera."
+      description: 'Path to the ad spec JSON. Shape: { format?, market?, brand?, cast?, end_card?, voice?, music?, beats: [{ say, show, on_camera?, cast? }] }. Fill `brand` from src/brand/BRAND.md \u2014 `palette` (its hex tokens, most important first) and `logo` (the repo path to the mark) are what make the ad look like the client rather than like stock. `market` is where the ad is SET; omitted, it is inferred from the voice language, and getting it wrong is what fills a Spanish ad with British houses. `say` is ONE clause ending in its own punctuation \u2014 it becomes a caption card verbatim, so two sentences in one beat produce a card holding both. `show` is the shot brief for that line. Set `on_camera` ONLY when that beat\'s subject talks to camera. `cast` is WHO the ad is about, and an ad with people in it needs one: `{ "avatar": "marta" }` names a cast avatar (`baker avatars list`) and every beat is grounded on that avatar\'s identity sheet with its subject description copied verbatim \u2014 the same face here as in the rest of the company\'s work. Without it each beat invents its own stranger, which is how one 28-second ad came back with five different men playing one customer. `{ "description": "..." }` is the fallback when there is no avatar, and it scaffolds a canvas that asks you to drop a photo before it can run \u2014 so prefer the avatar. A beat sets `cast: false` for a shot they are not in. `end_card` is on by default whenever `brand` is set: the last beat becomes a flat brand plate with the mark and a call to action drawn over it. `{ "cta": "..." }` sets the button copy, `false` keeps the footage.'
     },
     slug: {
       type: "string",
@@ -32783,7 +32857,7 @@ registerSchema({
 var scaffoldAdCommand = defineCommand104({
   meta: {
     name: "scaffold-ad",
-    description: 'Build a captioned vertical ad from a written spec, with no reference video to copy.\n\nA spec is a list of BEATS. One beat = one line the voice says + one shot on screen while it is said. That pairing is what keeps the ad honest: the caption card IS the line, so it can never end mid-sentence, and the picture can never drift from the read.\n\nTwo rules the spec enforces for you, both learned the expensive way:\n  \u2022 `say` is ONE clause with its own punctuation. Two sentences in a beat is rejected.\n  \u2022 Nobody in shot is speaking unless you set `on_camera` on that beat. A person visibly talking under a voice that is not theirs reads as bad dubbing.\n\nExample spec:\n  { "beats": [\n      { "say": "Mientras t\xFA sigues pagando la luz a precio de oro,", "show": "Aerial over Spanish rooftops at golden hour." },\n      { "say": "Haz clic en el enlace y reserva tu estudio gratuito.", "show": "A couple walking home at sunset." } ] }\n\nThen: baker canvas run <the canvas it writes>'
+    description: 'Build a captioned vertical ad from a written spec, with no reference video to copy.\n\nA spec is a list of BEATS. One beat = one line the voice says + one shot on screen while it is said. That pairing is what keeps the ad honest: the caption card IS the line, so it can never end mid-sentence, and the picture can never drift from the read.\n\nTwo rules the spec enforces for you, both learned the expensive way:\n  \u2022 `say` is ONE clause with its own punctuation. Two sentences in a beat is rejected.\n  \u2022 Nobody in shot is speaking unless you set `on_camera` on that beat. A person visibly talking under a voice that is not theirs reads as bad dubbing.\n\nExample spec:\n  { "beats": [\n      { "say": "Mientras t\xFA sigues pagando la luz a precio de oro,", "show": "Aerial over Spanish rooftops at golden hour." },\n      { "say": "Haz clic en el enlace y reserva tu estudio gratuito.", "show": "A couple walking home at sunset." } ] }\n\nWho is in it:\n  `cast: { avatar: "marta" }` grounds every beat on that avatar\'s face \u2014 cast one with `baker avatars`.\n  Without a cast, each beat invents its own person and the ad reads as a stock-footage collage.\n\nHow it ends: with a `brand`, the last beat closes on a flat brand plate carrying the mark and the CTA.\n\nThen: baker canvas run <the canvas it writes>'
   },
   args: {
     spec: { type: "string", required: true, description: "Path to the ad spec JSON" },
@@ -32824,6 +32898,26 @@ var scaffoldAdCommand = defineCommand104({
       process.exit(1);
       return;
     }
+    const handle = spec.data.cast?.avatar?.trim();
+    let avatar = null;
+    let avatarError = null;
+    if (handle) {
+      try {
+        avatar = await readAvatars(
+          "/api/avatars/get",
+          { handle }
+        );
+        if (avatar?.status && avatar.status !== "ready") {
+          avatarError = `Avatar \`${handle}\` is ${avatar.status}, not ready \u2014 only a ready avatar can be cast. Check \`baker avatars get ${handle}\`.`;
+          avatar = null;
+        } else if (!avatar?.sheetUrl) {
+          avatarError = `Avatar \`${handle}\` has no identity sheet yet, so the ad cannot ground on their face.`;
+          avatar = null;
+        }
+      } catch (e) {
+        avatarError = `Could not read avatar \`${handle}\`: ${e instanceof Error ? e.message : String(e)}. \`baker avatars list\` shows who there is.`;
+      }
+    }
     const blueprint = adSpecToBlueprint(spec.data);
     const slug = args.slug ?? path23.basename(specPath).replace(/\.[^.]+$/, "");
     const outPath = args.out ?? (args.slug ? path23.join("src/creatives", slug, `${slug}.canvas.json`) : path23.join(path23.dirname(specPath), `${slug}.canvas.json`));
@@ -32851,9 +32945,12 @@ var scaffoldAdCommand = defineCommand104({
       // The composition's default of 3 is TikTok karaoke styling; applied to an ad
       // it overrode the clause rule on every line and rendered "IS STANDARD. WE".
       // 8 is the composition's own maximum and clears every beat measured here.
-      captionWordsPerGroup: 8
+      captionWordsPerGroup: 8,
+      // Told, not guessed: the voice description is written in the ad's own language
+      // and the engine's trait parser reads English only.
+      voiceLanguage: voiceLanguageFor(spec.data)
     };
-    const canvas = scaffoldVideoCanvas(blueprint, adSpecCastElements(spec.data), opts);
+    const canvas = scaffoldVideoCanvas(blueprint, adSpecCastElements(spec.data, avatar), opts);
     const renderNode3 = canvas.nodes.find((n) => n.type === "hyperframe_render");
     const renderedDir = renderNode3 ? path23.join(outDir, String(renderNode3.params?.composition ?? "")) : null;
     let staged = null;
@@ -32890,6 +32987,19 @@ var scaffoldAdCommand = defineCommand104({
         ...logoPath && !staged ? [`Could not read the logo at \`${logoPath}\` \u2014 the ad has no mark on screen. Give the path as it appears in src/brand/BRAND.md, relative to the workspace root.`] : [],
         ...staged ? ["The brand mark is drawn by the composition \u2014 top-left throughout, and large on the closing card. It is never generated as a picture, so it cannot come back garbled."] : [],
         ...endCardWanted(spec.data) ? ["The last beat closes on a flat brand plate with the call to action over it, instead of one more photograph."] : [],
+        ...avatarError ? [avatarError] : [],
+        ...avatar ? [
+          `Every beat the customer appears in is grounded on \`${handle}\`'s identity sheet, and their subject description was copied into the frames verbatim \u2014 so it is the same face throughout and the same face as the rest of this company's work.`
+        ] : [],
+        ...presenterIsInEveryShot(spec.data) ? [
+          "The presenter is in every beat, so this ad has no cutaway \u2014 the viewer never sees the bill, the roof, the install or the house, only a face. A rendered ad built this way came back as three near-identical shots of one person smiling. Set `cast: false` on the beats that should show the thing itself."
+        ] : [],
+        ...!spec.data.cast ? [
+          'This ad declares no `cast`, so every beat renders whoever the model invents \u2014 a different face per shot. If a person appears more than once, run `baker avatars list`, cast one, and re-run with `cast: { avatar: "<handle>" }`.'
+        ] : [],
+        ...spec.data.cast && !avatar ? [
+          "This cast has a description but no avatar, so the canvas asks you to drop a real source photo before it can run. `baker avatars list` \u2014 casting one and passing `cast.avatar` fills that slot for you and keeps the face consistent across every piece of work."
+        ] : [],
         "The caption cards are your `say` lines verbatim \u2014 read them back before running; that is the copy the viewer sees.",
         "Every clip renders with nobody speaking unless a beat set `on_camera`. If a beat needs a presenter talking, set it there rather than describing it in `show`.",
         ...spec.data.brand?.palette?.length && spec.data.brand?.logo ? [] : [