@koda-sl/baker-cli 0.481.0-dev.2d33e194f → 0.495.0-dev.c2b64ccca

package/dist/scaffold-ad-3BSA7BWT.js

@@ -0,0 +1,1553 @@
+import {
+  stampCompositionDims
+} from "./chunk-5MBPIONY.js";
+import {
+  SHIPPED_CAPTIONS_DIR,
+  SHIPPED_OVERLAY_COMPOSITION_DIR
+} from "./chunk-CCFZB42B.js";
+import {
+  syncCreativeDefinitionBestEffort
+} from "./chunk-G2AZCDX4.js";
+import "./chunk-IVRXPYQ7.js";
+import {
+  pinnedModelHint
+} from "./chunk-66ZIZ7QP.js";
+import {
+  enforceNewCreativeLimit
+} from "./chunk-WDAWTHQK.js";
+import {
+  buildCreativeDefinition,
+  parseDefinitionStrategyFields,
+  resolveFormats,
+  resolvePlatform,
+  titleFromSlug
+} from "./chunk-SQQ4VBNI.js";
+import {
+  BRAND_DIR,
+  REBUILD_FILE,
+  authoredRole,
+  brandHeadlineFont,
+  cachedJev,
+  canvasDims,
+  carriesOnFromAnswers,
+  carriesOnQuestions,
+  computeSourceSha,
+  escapeHtml,
+  findBrandRoot,
+  genAspectsFor,
+  languageFromAnswer,
+  languageQuestion,
+  markInkIsLight,
+  markIsReal,
+  plateIsDark,
+  readBrandFromWorkspace,
+  readNamedTypefaces,
+  readStaticBrandKit,
+  renderStyleProjectionFromValue,
+  resolveAspect,
+  scaffoldVideoCanvas,
+  spokenLanguage,
+  svgIsLiveText,
+  voiceGenderModel,
+  webFontUrl,
+  writeSceneFiles
+} from "./chunk-WZDKROPU.js";
+import "./chunk-B2SAOVMU.js";
+import "./chunk-BVMXTD4B.js";
+import {
+  readAvatars
+} from "./chunk-AN7CMLYY.js";
+import "./chunk-7XH4UQWS.js";
+import "./chunk-S4ROJTDY.js";
+import {
+  fetchJson,
+  lookupGoogleCss
+} from "./chunk-YTV5VW7S.js";
+import "./chunk-YJAQWTS6.js";
+import "./chunk-MNPBPU3G.js";
+import "./chunk-WJNLQEOZ.js";
+import "./chunk-MMU6XHCH.js";
+import {
+  holdUnbilledSpend
+} from "./chunk-6FHP2HIK.js";
+import {
+  findWorkspaceRoot,
+  resolveRelativeCanvasPaths
+} from "./chunk-DS2ZRTAL.js";
+import {
+  defaultRegistry,
+  validateCanvasDeep
+} from "./chunk-NEHQGYZS.js";
+import {
+  READ_WORDS_PER_SECOND,
+  wordCount
+} from "./chunk-XXU7XRMM.js";
+import {
+  videoSafeArea
+} from "./chunk-XQ4KKF5E.js";
+import "./chunk-DGCUPJZD.js";
+import "./chunk-SYED65QF.js";
+import {
+  ACTOR_SHEET_MODEL
+} from "./chunk-5IGQ6IQO.js";
+import {
+  AD_IMAGE_MODEL,
+  DEFAULT_VIDEO_GENERATE_MODEL,
+  SEEDANCE_DURATIONS,
+  SPOKEN_CLIP_DURATION_S,
+  VIDEO_GENERATE_MODELS,
+  clipDurationsFor,
+  frameRealismDirection,
+  withoutCastName
+} from "./chunk-QK5PEHFX.js";
+import "./chunk-QEW64BBR.js";
+import "./chunk-KPYDTIAI.js";
+import "./chunk-KIGGMKAE.js";
+import {
+  askJevQuestions
+} from "./chunk-4TBDEV7X.js";
+import "./chunk-EIJDXZW5.js";
+import "./chunk-2WRK44LZ.js";
+import {
+  fetchExternalBytes
+} from "./chunk-3FFJYMKM.js";
+import "./chunk-MV2J73HP.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-XQIOCIDO.js";
+import "./chunk-I2DNBEV6.js";
+import {
+  apiGet,
+  apiPost
+} from "./chunk-OSWCEDFE.js";
+import "./chunk-D53AAUG4.js";
+import "./chunk-FZKUUI3F.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-4WYEGE4N.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/canvas/clientLogo.ts
+function decideClientLogo(domain, lookup) {
+  if (!domain) return { use: false, reason: "no_domain" };
+  const verdict = lookup?.brandMatch?.verdict;
+  if (verdict === "mismatch") {
+    return { use: false, reason: "mismatch", ...lookup?.brandMatch?.name ? { wrongBrand: lookup.brandMatch.name } : {} };
+  }
+  if (verdict !== "confirmed") return { use: false, reason: "unverified" };
+  const url = lookup?.hits?.map((hit) => hit.imageUrl ?? hit.sourceUrl).find((candidate) => Boolean(candidate));
+  return url ? { use: true, url } : { use: false, reason: "no_hits" };
+}
+function clientLogoMissNote(decision, domain) {
+  switch (decision.reason) {
+    case "no_domain":
+      return "Baker has no website on record for this company, so their mark could not be looked up.";
+    case "mismatch":
+      return `The mark found for \`${domain}\` belongs to ${decision.wrongBrand ?? "a different company"}, not to this client, so it was not used.`;
+    default:
+      return `No brand mark could be confirmed for \`${domain}\`, so nothing was placed.`;
+  }
+}
+
+// src/commands/canvas/scaffold-ad.ts
+import { copyFile, cp, mkdir, readFile, stat, writeFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+
+// src/engine/scaffold/ad-spec.ts
+import { z } from "zod";
+var oneClause = (line) => (line.match(/[.!?](\s|$)/g) ?? []).length <= 1;
+var isSpeech = (line) => new RegExp("\\p{L}\\p{L}", "u").test(line);
+var Beat = z.object({
+  /**
+   * The line the voice says in this beat — ONE clause, ending in its own
+   * punctuation. It becomes the caption card verbatim.
+   */
+  say: z.string().min(1).refine(
+    isSpeech,
+    "a beat's line has to be words someone says \u2014 a dot or a dash is not a line, and an ad with no voiceover is not supported yet"
+  ).refine(oneClause, "a beat is one clause: split a second sentence into its own beat"),
+  /** What is on screen while it is said, as a shot brief for the video model. */
+  show: z.string().min(1),
+  /**
+   * What this shot SOUNDS like — one effect, in words. Usually absent.
+   *
+   * An effect earns its place when the picture shows a SPECIFIC PHYSICAL EVENT the
+   * viewer expects to hear: a drill tightening a bolt, a door closing, rain on glass, a
+   * card tapping a reader, a graphic snapping into place. It grounds the shot.
+   *
+   * It does NOT belong on a talking head, on a lifestyle shot with no event in it, or
+   * on a beat that is simply someone sitting and reacting. Sound laid over those reads
+   * as a stock-library sting, and a bed of them turns a calm ad into a noisy one. Most
+   * ads are a music bed and a voice; a couple of effects at the right moments, or none
+   * at all, is a normal and often better answer than one per beat.
+   *
+   * Describe the SOUND, not the picture: "a cordless drill tightening a bolt", not "the
+   * fitter works on the rail".
+   */
+  sound: z.string().min(1).max(200).optional(),
+  /**
+   * Whether this beat's subject is talking to camera.
+   *
+   * Left unset it follows the cast: an ad that cast a presenter, in a shot they are in,
+   * with a line, is that person speaking. Set it to FALSE for the exception — a cutaway,
+   * a product shot, a beat you want a narrator to carry over.
+   *
+   * It used to be opt-in, back when the only route was dubbing and OFF was the safe
+   * default. That inverted the moment on-camera started meaning the video model voices
+   * the clip itself: measured on a real run, a brief that said "talking to camera all the
+   * way through" produced an ad with her face on screen and a narrator cast from a prose
+   * description reading her lines, because nothing set this flag.
+   */
+  on_camera: z.boolean().optional(),
+  /**
+   * Whether the ad's recurring person is in this shot. Defaults to true whenever the
+   * spec declares a `cast`, because an ad is usually about one person and defaulting
+   * the other way is how continuity gets forgotten. Set false for a beat they are not
+   * in — a fitter on a roof, a product close-up.
+   */
+  cast: z.boolean().optional()
+});
+var AdSpec = z.object({
+  format: z.object({
+    aspect_ratio: z.string().default("9:16"),
+    resolution: z.string().default("720p")
+  }).default({ aspect_ratio: "9:16", resolution: "720p" }),
+  brand: z.object({
+    name: z.string().optional(),
+    /** Figures to lift typographically — the one gold number every ad has. */
+    highlight: z.array(z.string()).optional(),
+    /**
+     * Brand hex colours, most important first. They dress the brand plate and
+     * the type — never the scenes: pushing hex into a shot brief makes the
+     * model paint the whole frame that colour, which reads as a filter.
+     */
+    palette: z.array(z.string()).optional(),
+    /** Repo path to the brand mark, so the CTA carries it instead of a name in a font. */
+    logo: z.string().optional()
+  }).optional(),
+  voice: z.object({
+    description: z.string().min(1),
+    language: z.string().optional()
+  }).optional(),
+  /**
+   * Where the ad is set, as a place a model can picture: "Spain", "Mexico",
+   * "the UK". Omitted, it is the country a regional `voice.language` names ("es-MX" →
+   * Mexico), else nowhere: a language alone names no country.
+   *
+   * It exists because nothing else in a shot brief says where it is, and a model
+   * with no location picks its own. An ad for Spain came back full of British
+   * houses — sash windows, slate roofs, English suburbs — in every single frame,
+   * from briefs that were otherwise perfectly good.
+   */
+  market: z.string().min(1).optional(),
+  /**
+   * The one person the ad is about.
+   *
+   * Declared once and grounded on every beat they appear in, because the engine already
+   * builds a reference sheet from this and tells each frame to render THE SAME
+   * individual. Without it each beat invents its own face: a 28-second ad came back
+   * with five different men playing one customer, which reads as a stock-footage
+   * collage rather than a story.
+   */
+  cast: z.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: z.string().min(1).optional(),
+    /** Who they are, plainly: age, build, hair, wardrobe, the register of the ad. */
+    description: z.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(),
+  /**
+   * The bed, described in words — or `false` for an ad that is meant to be dry.
+   *
+   * Omitted lays a soft, neutral bed. It used to leave the ad silent, on the reasoning
+   * that silence is a legitimate choice; it is, but only as a choice. In practice nothing
+   * ever set this, and finished ads shipped with a voice over nothing — which reads as
+   * unfinished, not as restraint. A bed is the ordinary case, so it is the default, and
+   * an ad that wants silence says `false` and means it.
+   *
+   * The bed never plays over the first beat: the opening line is the scroll-stopper and
+   * has to read clean. That is the engine's rule, not this one, and it is why the prompt
+   * is all this needs to carry.
+   */
+  music: z.union([z.string().min(1), z.literal(false)]).optional(),
+  /**
+   * The place the ad keeps coming back to, held still across every shot.
+   *
+   * The person has an identity sheet; nothing held the SETTING. Each shot's start frame is
+   * generated on its own, so three beats in "her living room" came back as three different
+   * living rooms. The engine already builds `location` reference sheets — its own comment
+   * calls them the strongest cross-scene consistency lock it has — and the ad path simply
+   * never emitted one.
+   *
+   * `image` is a real picture of the place, and it is what makes this work at all: a sheet
+   * fuses source material into a turnaround. Fed nothing, it is not a reference sheet, it
+   * is `image_generate` with extra steps — the model registry says exactly that. Generate
+   * the plate once with gpt-image-2 and pass its URL here.
+   */
+  set: z.object({
+    description: z.string().min(1).max(400),
+    image: z.string().min(1).optional()
+  }).optional(),
+  /**
+   * How the ad closes.
+   *
+   * On by default whenever the spec carries a brand, because an ad that stops instead
+   * of closing is what shipped: the last caption fell four seconds before the last
+   * frame and the picture simply ran out on a man shuffling paper. The closing beat's
+   * PICTURE becomes a flat brand plate — the engine already refuses to generate one as
+   * a photograph, since a video model garbles a wordmark — and the mark and the call to
+   * action are drawn over it by the composition.
+   *
+   * `false` opts out, for an ad that genuinely ends on its footage.
+   */
+  end_card: z.union([
+    z.literal(false),
+    z.object({
+      /**
+       * The words on the button. No default — with none the card carries the mark
+       * alone, because falling back to the last beat's line printed that sentence
+       * twice on the closing frame. See `endCardCta`.
+       */
+      cta: z.string().min(1).optional()
+    })
+  ]).optional(),
+  /**
+   * Whether a voice reads the lines.
+   *
+   * On by default. Turned off, the ad carries its music and its pictures and the `say`
+   * lines become ON-SCREEN text instead of spoken ones — which is how most music-led
+   * social ads are actually built.
+   *
+   * It exists because an agent wanted exactly this and had no way to ask: it wrote "·"
+   * as every line with a voice description reading "No voiceover; music only". The dot
+   * was sent to the voice model, the near-silence that came back was transcribed, and
+   * the transcriber hallucinated "Thank you." — which became the ad's only caption card,
+   * held over all sixteen seconds, in English, in a Spanish ad.
+   *
+   * The captions are BETTER on this path, not worse: they come from the script itself
+   * rather than from transcribing a rendered read, so the text is exact and no speech
+   * model is between the copy and the screen.
+   */
+  voiceover: z.boolean().default(true),
+  beats: z.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);
+}
+var CURRENCY_BY_MARKET = {
+  spain: "\u20AC (euros)",
+  mexico: "$ (Mexican pesos)",
+  portugal: "\u20AC (euros)",
+  brazil: "R$ (reais)",
+  france: "\u20AC (euros)",
+  italy: "\u20AC (euros)",
+  germany: "\u20AC (euros)",
+  "united kingdom": "\xA3 (pounds sterling)",
+  "united states": "$ (US dollars)"
+};
+var currencyFor = (market) => CURRENCY_BY_MARKET[market.trim().toLowerCase().replace(/^the\s+/, "")];
+function spokenLanguageFor(spec, known = {}) {
+  const declared = spec.voice?.language ? spokenLanguage(spec.voice.language) : null;
+  if (declared) return declared.tag;
+  const defined = known.definitionLanguage ? spokenLanguage(known.definitionLanguage) : null;
+  if (defined) return defined.tag;
+  return known.reading?.scriptLanguage;
+}
+function marketFor(spec, definitionLanguage) {
+  if (spec.market) return spec.market;
+  for (const tag of [spec.voice?.language, definitionLanguage]) {
+    const region = tag ? spokenLanguage(tag)?.region : void 0;
+    if (region) return region.name;
+  }
+  return void 0;
+}
+function beatSeconds(line, videoModel) {
+  const spoken = wordCount(line) / READ_WORDS_PER_SECOND;
+  const allowed = (videoModel ? clipDurationsFor(videoModel) : void 0) ?? [...SEEDANCE_DURATIONS].sort((a, b) => a - b);
+  const wanted = Math.max(spoken, SPOKEN_CLIP_DURATION_S);
+  return allowed.find((d) => d >= wanted) ?? allowed[allowed.length - 1];
+}
+var BRAND_PLATE = "A solid flat brand colour plate \u2014 an end card. No people, no objects, no scenery, no text of any kind.";
+function endCardWanted(spec) {
+  if (spec.end_card === false) return false;
+  return Boolean(spec.brand?.name || spec.brand?.logo);
+}
+function endCardCta(spec) {
+  if (!endCardWanted(spec)) return null;
+  const declared = spec.end_card === false ? void 0 : spec.end_card?.cta?.trim();
+  if (!declared) return null;
+  const closing = (spec.beats[spec.beats.length - 1]?.say ?? "").trim().toLowerCase();
+  return declared.toLowerCase().replace(/[.!?]$/, "") === closing.replace(/[.!?]$/, "") ? null : declared;
+}
+var AD_CAST_ID = "customer";
+var AD_NARRATOR_ID = "ad_narrator";
+var AD_SET_ID = "set";
+function castedAvatarOnRoster(ad, roster) {
+  if (ad.cast?.avatar) return null;
+  const haystack = [ad.cast?.description ?? "", ...(ad.beats ?? []).map((b) => b.show ?? "")].join(" ");
+  if (!haystack.trim()) return null;
+  const written = new Set(haystack.split(/[^\p{L}\p{N}]+/u).filter(Boolean));
+  for (const person of roster) {
+    if (labelWrittenAsName(person.name, written) || labelWrittenAsName(person.handle, written)) return person.handle;
+  }
+  return null;
+}
+function labelWrittenAsName(label, written) {
+  const token = label.trim();
+  if (!token || token.includes("-") || token.length < 3) return false;
+  const folded = token.toLowerCase();
+  for (const word of written) {
+    if (word.toLowerCase() === folded && word[0] === word[0]?.toUpperCase()) return true;
+  }
+  return false;
+}
+function adSpecCastElements(spec, avatar) {
+  const lastIndex = spec.beats.length - 1;
+  const speakingScenes = spec.beats.map((_, i) => i).filter((i) => !(endCardWanted(spec) && i === lastIndex));
+  const place = spec.set?.description?.trim();
+  const elements = [];
+  if (place && speakingScenes.length > 0) {
+    elements.push({
+      type: "location",
+      label: AD_SET_ID,
+      cast_id: AD_SET_ID,
+      description: place,
+      scenes: speakingScenes,
+      ...spec.set?.image?.trim() ? { source_image: spec.set.image.trim() } : {}
+    });
+  }
+  const description = (avatar?.subjectDescription ?? spec.cast?.description)?.trim();
+  if (!description) return elements;
+  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 elements;
+  const sheet = avatar?.sheetUrl?.trim();
+  elements.push({
+    type: "person",
+    label: AD_CAST_ID,
+    // Same id the dialogue names as speaker: that pairing is what lets the engine see
+    // the presenter as present in a scene and route it to native audio.
+    cast_id: AD_CAST_ID,
+    description,
+    scenes,
+    // An avatar's identity sheet IS the turnaround the engine would otherwise render,
+    // so it is handed over as one. Left unmarked, the run paid to generate a sheet OF
+    // a sheet and every frame grounded on the copy instead of the avatar.
+    ...sheet ? { source_image: sheet, source_is_sheet: true } : {}
+  });
+  return elements;
+}
+function motionPrompt(beat, toCamera, isClosingCard, place) {
+  if (isClosingCard) return BRAND_PLATE;
+  const shot = `${beat.show}${place}`;
+  if (toCamera) return shot;
+  return `${shot} Nobody in frame is speaking: mouths CLOSED and STILL throughout, no talking, no lip movement. Whoever is in shot is looking, reacting or working \u2014 never addressing the camera.`;
+}
+function staticTranscript(spec, videoModel) {
+  const out = [];
+  let clock = 0;
+  for (const beat of spec.beats) {
+    const duration = beatSeconds(beat.say, videoModel);
+    const words = beat.say.trim().split(/\s+/).filter(Boolean);
+    const each = words.length > 0 ? duration / words.length : duration;
+    words.forEach((text, i) => {
+      const start = clock + i * each;
+      out.push({
+        text,
+        start: Math.round(start * 100) / 100,
+        end: Math.round((start + each) * 100) / 100
+      });
+    });
+    clock += duration;
+  }
+  return out;
+}
+function spokenVariety(avatarAccent, market) {
+  const accent = avatarAccent?.trim();
+  if (accent) return `${accent} \u2014 perform the pronunciation of that region, not a neutral one`;
+  if (!market) return null;
+  return `the local accent of ${market} \u2014 the way people there actually speak, not a neighbouring country's variety of the same language`;
+}
+function musicBed(spec) {
+  if (spec.music === false) return null;
+  if (typeof spec.music === "string") return spec.music;
+  return "A soft, warm instrumental bed that sits well under a spoken voiceover: gentle acoustic guitar or soft piano with light pads, steady and unobtrusive, no vocals, no lyrics, no drop, no build to a climax, nothing that pulls attention off the voice.";
+}
+function beatToCamera(spec, beat, isClosingCard) {
+  if (isClosingCard) return false;
+  if (spec.cast?.avatar && beat.cast !== false) return true;
+  if (beat.on_camera !== void 0) return beat.on_camera;
+  return Boolean(spec.cast) && beat.cast !== false;
+}
+function beatsIntroducingSpeakerOffCamera(spec, reading) {
+  const closesOnCard = endCardWanted(spec);
+  const last = spec.beats.length - 1;
+  return spec.beats.flatMap(
+    (beat, i) => reading.introducesSpeaker[i] === true && !beatToCamera(spec, beat, closesOnCard && i === last) ? [i] : []
+  );
+}
+function beatSpeaksNatively(spec, beat, isClosingCard) {
+  if (!spec.cast || spec.voiceover === false) return false;
+  return beatToCamera(spec, beat, isClosingCard) && beat.cast !== false;
+}
+function beatDialogue(spec, beat, window) {
+  if (spec.voiceover === false) return [];
+  const narrator = narratorVoice(spec, window.avatarVoice);
+  return [
+    {
+      line: beat.say,
+      start_s: window.start,
+      end_s: window.end,
+      // Always stated, never left to the engine: absent, it guesses from who is in frame,
+      // which is how a still photograph once got lip-synced.
+      on_camera: beatToCamera(spec, beat, window.isClosingCard),
+      // Naming the CAST as speaker is the other half of what sends this beat down the
+      // native path. Left unnamed, the speaker defaults to "voiceover" — a narrator, who is
+      // by definition never on camera — so every beat took the dubbed path: a clip generated
+      // with one mouth and a separate ElevenLabs track laid over it. That is the mismatch
+      // behind every "the mouth does not match" in this ad's history.
+      //
+      // A beat that is NOT hers names the ad's OWN narrator (`AD_NARRATOR_ID`), rather
+      // than leaving the label off. A different speaker is what breaks the phrase, and a
+      // phrase break is what keeps each beat its own clip: left unlabelled, the engine read
+      // the cutaway as her narrating over an insert in one continuous take and merged the
+      // beats around it into a single native read with the dubbed one laid on top.
+      speaker: window.nativeSpeech ? AD_CAST_ID : AD_NARRATOR_ID,
+      // The narrator is cast from the ad's voice, and failing that from the CAST's own
+      // description. Naming a speaker of our own cost this: the engine casts an unnamed
+      // narrator by folding it into the lone presenter and reusing her casting, so the
+      // closing line inherited her persona for free. Named, it is a speaker in nobody's
+      // `cast`, and the engine's last-resort description for one of those is the literal
+      // "<speaker> voice" — so an ad with an avatar, a closing card and no `voice`
+      // (a perfectly ordinary spec) had its closing tagline cast off the words
+      // "ad_narrator voice".
+      ...narrator ? { voice_description: narrator } : {}
+    }
+  ];
+}
+function narratorVoice(spec, avatarVoice) {
+  return spec.voice?.description?.trim() || avatarVoice?.trim() || spec.cast?.description?.trim() || void 0;
+}
+function nativeSpeechByBeat(spec, closesOnCard) {
+  const last = spec.beats.length - 1;
+  return spec.beats.map((beat, i) => beatSpeaksNatively(spec, beat, closesOnCard && i === last));
+}
+function voiceoverMode(spec, nativeByBeat, closesOnCard) {
+  if (spec.voiceover === false) return "none";
+  const spoken = closesOnCard ? nativeByBeat.slice(0, -1) : nativeByBeat;
+  const native = spoken.filter(Boolean).length;
+  if (native === 0) return "voiceover";
+  return native === spoken.length ? "on_camera" : "mixed";
+}
+function castRole(spec, reading) {
+  if (!spec.cast) return void 0;
+  const described = spec.cast.description?.trim();
+  if (!described) return "a customer telling their own story, not a worker";
+  if (reading?.castWorksThere === false) return `${described} \u2014 a customer telling their own story, not a worker`;
+  return described;
+}
+function adSpecToBlueprint(spec, opts = {}) {
+  const avatarAccent = opts.avatarAccent;
+  const total = spec.beats.length;
+  const market = marketFor(spec, opts.definitionLanguage);
+  const place = market ? ` Set in ${market}: the architecture, streets and styling are ${market}'s.` : "";
+  const currency = market ? currencyFor(market) : void 0;
+  const physics = frameRealismDirection({ currency, role: castRole(spec, opts.reading) });
+  const closesOnCard = endCardWanted(spec);
+  const nativeByBeat = nativeSpeechByBeat(spec, closesOnCard);
+  const spokenMode = voiceoverMode(spec, nativeByBeat, closesOnCard);
+  let clock = 0;
+  const scenes = spec.beats.map((beat, i) => {
+    const isClosingCard = closesOnCard && i === total - 1;
+    const duration = beatSeconds(beat.say, opts.videoModel);
+    const start = clock;
+    clock += duration;
+    return {
+      start_s: Math.round(start * 100) / 100,
+      end_s: Math.round(clock * 100) / 100,
+      duration_s: duration,
+      summary: isClosingCard ? `${BRAND_PLATE} ${beat.say}` : beat.say,
+      narrative_role: authoredRole(i, total),
+      ...isClosingCard ? { route_hint: "brand_card" } : {},
+      // The read is built from per-scene dialogue, not from the global
+      // transcript: emitting only the transcript scaffolds a SILENT ad. And
+      // `on_camera` is the engine's own switch for "this line is narration" —
+      // absent, it guesses from who is in frame, which is how a still photograph
+      // once got lip-synced.
+      // No dialogue at all when nobody speaks: an empty array is what stops the engine
+      // wiring a voice track, and no voice track is what makes this a music-led ad
+      // rather than one with a silent narrator.
+      // One effect per beat, placed on this beat's window. The engine clamps the
+      // length to what the provider accepts. An ad emitted none of these until now,
+      // so every one shipped with a music bed and no sound design at all.
+      ...beat.sound?.trim() ? { sfx: [{ sound_effect_prompt: beat.sound.trim(), duration_s: Math.min(duration, 30) }] } : {},
+      dialogue: beatDialogue(spec, beat, {
+        start: Math.round(start * 100) / 100,
+        end: Math.round(clock * 100) / 100,
+        isClosingCard,
+        nativeSpeech: nativeByBeat[i] === true,
+        avatarVoice: opts.avatarVoice
+      }),
+      motion_prompt: motionPrompt(beat, beatToCamera(spec, beat, isClosingCard), isClosingCard, place),
+      start_frame_prompt: isClosingCard ? BRAND_PLATE : `${beat.show}${place}${physics}`
+    };
+  });
+  const accent = spokenVariety(avatarAccent, market);
+  const narrator = narratorVoice(spec, opts.avatarVoice);
+  const music = musicBed(spec);
+  return {
+    estimated_duration_s: Math.round(clock * 100) / 100,
+    global: {
+      transcript: spec.beats.map((b) => b.say).join(" "),
+      // Resolved: `marketFor` also reads the country a declared regional language names.
+      ...market ? { market } : {},
+      voiceover: {
+        mode: spokenMode,
+        ...accent ? { accent } : {},
+        ...narrator ? { voice_description: narrator } : {}
+      },
+      ...spec.cast ? {
+        cast: [
+          {
+            id: AD_CAST_ID,
+            description: (spec.cast.description ?? "the ad's recurring person").trim()
+          }
+        ]
+      } : {},
+      ...spec.brand?.name || spec.brand?.logo ? {
+        branding: {
+          ...spec.brand?.name ? { name: spec.brand.name } : {},
+          ...spec.brand?.logo ? { logo_path: spec.brand.logo } : {}
+        }
+      } : {},
+      ...spec.brand?.palette?.length ? { style: { palette: spec.brand.palette.map((hex) => ({ hex })) } } : {},
+      ...music ? { music: { music_prompt: music } } : {}
+    },
+    scenes
+  };
+}
+var MIN_BEAT_WORDS = 4;
+function beatsTooShortToPlay(spec) {
+  return spec.beats.map((beat, i) => ({ i, words: beat.say.trim().split(/\s+/).filter(Boolean).length })).filter(({ words }) => words < MIN_BEAT_WORDS).map(({ i }) => i + 1);
+}
+
+// src/engine/scaffold/ad-spec-reading.ts
+var INTRODUCES_SPEAKER_HELD = 0.5;
+var WANTS_LEGIBLE_TEXT_HELD = 0.5;
+var WORKS_THERE_HELD = 0.5;
+var INTRODUCES_SPEAKER = 'Does the speaker of `line` introduce themselves, saying their own name or who they are ("Hi, I\'m Marta")? A line about somebody else, or a first-person line that names nobody, is not.';
+var WANTS_LEGIBLE_TEXT = "Does `brief` ask for words, a number, a price or a figure in the picture to be readable (in focus, legible, highlighted, the point of the shot)? A document, screen or sign that is only present, out of focus or not meant to be read is not.";
+var WORKS_THERE = "Does `person` describe someone who works for the business in the ad (an installer, a technician, an employee, a doctor, a chef, its founder or owner, its team) rather than a customer or an ordinary person?";
+function adSpecVoices(spec, avatarVoice) {
+  const all = [spec.voice?.description, avatarVoice, spec.cast?.description].map((d) => d?.trim() ?? "");
+  return [...new Set(all.filter(Boolean))];
+}
+function unreadAdSpec(spec) {
+  return {
+    introducesSpeaker: spec.beats.map(() => false),
+    wantsLegibleText: spec.beats.map(() => false),
+    voiceGenders: {},
+    captionCarriesOn: [],
+    read: false
+  };
+}
+var yes = (answer, held) => answer !== void 0 && "noul" in answer && answer.noul >= held;
+async function readAdSpec(spec, options, readers) {
+  const lines = spec.beats.map((b) => b.say);
+  const castDescription = spec.cast?.description?.trim();
+  const carries = carriesOnQuestions(lines);
+  const sections = [
+    { name: "language", questions: options.askLanguage ? [languageQuestion(lines)] : [] },
+    {
+      name: "intro",
+      questions: lines.map((line) => ({ type: "noul", instructions: { line, question: INTRODUCES_SPEAKER } }))
+    },
+    {
+      name: "legible",
+      questions: spec.beats.map((b) => ({
+        type: "noul",
+        instructions: { brief: b.show, question: WANTS_LEGIBLE_TEXT }
+      }))
+    },
+    {
+      name: "works",
+      questions: castDescription ? [{ type: "noul", instructions: { person: castDescription, question: WORKS_THERE } }] : []
+    },
+    { name: "carries", questions: carries.questions }
+  ];
+  const [answers, genders] = await Promise.all([
+    readers.ask(sections.flatMap((s) => s.questions)),
+    readers.genders(options.voices).catch(() => null)
+  ]);
+  const voiceGenders = genders ?? {};
+  if (!answers) return { ...unreadAdSpec(spec), voiceGenders };
+  const bySection = /* @__PURE__ */ new Map();
+  let at = 0;
+  for (const section of sections) {
+    bySection.set(section.name, answers.slice(at, at + section.questions.length));
+    at += section.questions.length;
+  }
+  const of = (name) => bySection.get(name) ?? [];
+  const scriptLanguage = languageFromAnswer(of("language")[0]);
+  const works = of("works")[0];
+  return {
+    ...scriptLanguage ? { scriptLanguage } : {},
+    introducesSpeaker: lines.map((_, i) => yes(of("intro")[i], INTRODUCES_SPEAKER_HELD)),
+    wantsLegibleText: spec.beats.map((_, i) => yes(of("legible")[i], WANTS_LEGIBLE_TEXT_HELD)),
+    ...works && "noul" in works ? { castWorksThere: works.noul >= WORKS_THERE_HELD } : {},
+    voiceGenders,
+    captionCarriesOn: carriesOnFromAnswers(carries.words, of("carries")),
+    read: true
+  };
+}
+
+// src/engine/scaffold/ad-display-face.ts
+var AD_DISPLAY_FAMILY = "AdDisplay";
+function displayFontStack(face) {
+  const fallback = "'Arial Black', 'Helvetica Neue', Arial, sans-serif";
+  return face ? `'${face}', ${fallback}` : fallback;
+}
+function adDisplayFaceCss(file) {
+  return [
+    "      /* --- the brand's face (baker canvas scaffold-ad) --- */",
+    `      @font-face { font-family: '${AD_DISPLAY_FAMILY}'; src: url('./${file}'); font-weight: 100 900; font-display: block; }`,
+    `      .caption-group { font-family: ${displayFontStack(AD_DISPLAY_FAMILY)}; }`
+  ].join("\n");
+}
+function injectAdDisplayFace(indexHtml, file) {
+  return indexHtml.replace("    </style>", `${adDisplayFaceCss(file)}
+    </style>`);
+}
+
+// src/engine/scaffold/ad-layer-placement.ts
+var CAPTION_MIN_LIFT = 0.1;
+function adLayerPlacement(aspect) {
+  const safe = videoSafeArea(aspect);
+  return {
+    caption: { bottom: Math.max(safe.bottom, CAPTION_MIN_LIFT), side: Math.max(safe.left, safe.right) },
+    mark: { top: safe.top, left: safe.left },
+    card: safe
+  };
+}
+var cssPct = (fraction) => `${Math.round(fraction * 1e3) / 10}%`;
+function adCaptionPlacementCss(aspect) {
+  const { caption } = adLayerPlacement(aspect);
+  return [
+    "      /* --- caption placement (baker canvas scaffold-ad) --- */",
+    "      /* Relative to the frame and inside what the platform leaves clear: Reels covers the",
+    "         bottom 35% of a 9:16 frame, and cards drawn at the old 320px sat under it. */",
+    `      .caption-container { bottom: ${cssPct(caption.bottom)}; padding: 0 ${cssPct(caption.side)}; }`,
+    `      .caption-group { bottom: 0; max-width: ${cssPct(1 - 2 * caption.side)}; }`
+  ].join("\n");
+}
+function injectAdCaptionPlacement(indexHtml, aspect) {
+  return indexHtml.replace("    </style>", `${adCaptionPlacementCss(aspect)}
+    </style>`);
+}
+
+// src/engine/scaffold/ad-brand-overlay.ts
+var markFallback = (name) => name.trim() ? ` onerror="this.replaceWith(Object.assign(document.createElement('span'),{className:this.className+' brand-wordmark',textContent:${escapeHtml(JSON.stringify(name.trim()))}}))"` : "";
+function buildAdBrandOverlay(opts) {
+  const { logo, cta, cardAtS, cardDurationS, totalS } = opts;
+  if (!logo && !cta?.trim()) return "";
+  const inkClass = opts.markIsLight ? " on-dark" : "";
+  const parts = [
+    "<!-- Brand layer, emitted by `baker canvas scaffold-ad`. The mark and the closing",
+    "     card are drawn HERE, by the composition \u2014 never generated as a picture, because",
+    "     a video model garbles a wordmark every time. Restyle freely, but keep the",
+    "     data-start/data-dur attributes and the script below: that script is what shows",
+    "     and hides these, and the host composition has nothing that would. -->"
+  ];
+  if (logo) {
+    parts.push(
+      `<img class="clip brand-mark${inkClass}" src="${escapeHtml(logo.file)}" alt="${escapeHtml(logo.alt)}" data-start="0" data-dur="${totalS}"${markFallback(logo.alt)} />`
+    );
+  }
+  const cardBits = [];
+  if (logo) {
+    cardBits.push(
+      `<img class="endcard-logo${inkClass}" src="${escapeHtml(logo.file)}" alt="${escapeHtml(logo.alt)}"${markFallback(logo.alt)} />`
+    );
+  }
+  if (cta?.trim()) {
+    cardBits.push(
+      `<div class="endcard-cta${opts.plateIsDark ? " on-dark-plate" : ""}">${escapeHtml(cta.trim())}</div>`
+    );
+  }
+  parts.push(
+    `<div class="clip endcard" data-start="${cardAtS}" data-dur="${cardDurationS}" data-role="cta">`,
+    ...cardBits.map((b) => `  ${b}`),
+    "</div>",
+    brandLayerDriver()
+  );
+  return parts.join("\n");
+}
+function brandLayerDriver() {
+  return [
+    "<script>",
+    "  (function () {",
+    "    var els = Array.prototype.slice.call(document.querySelectorAll('.brand-mark, .endcard'));",
+    "    if (!els.length) return;",
+    "    els.forEach(function (el) { gsap.set(el, { visibility: 'hidden' }); });",
+    "    var card = document.querySelector('.endcard');",
+    "    var captions = document.getElementById('captions');",
+    "    function attach(tl) {",
+    "      if (!tl) return;",
+    "      els.forEach(function (el) {",
+    "        var at = parseFloat(el.getAttribute('data-start') || '0') || 0;",
+    "        var dur = parseFloat(el.getAttribute('data-dur') || '0') || 0;",
+    "        tl.set(el, { visibility: 'visible' }, at);",
+    "        if (dur > 0) tl.set(el, { visibility: 'hidden' }, at + dur);",
+    "      });",
+    "      // The closing card owns the frame it lands on. The caption track otherwise",
+    "      // keeps running underneath it, and what it captions there is the line spoken",
+    "      // OVER the card \u2014 the call to action, printed a second time in smaller letters",
+    "      // directly below the button that already says it. Hidden on the CONTAINER and",
+    "      // with `display`, because each caption group sets its own `visibility: visible`",
+    "      // and would win against anything set on its parent.",
+    "      if (card && captions) {",
+    "        var cardAt = parseFloat(card.getAttribute('data-start') || '0') || 0;",
+    "        var cardDur = parseFloat(card.getAttribute('data-dur') || '0') || 0;",
+    "        tl.set(captions, { display: 'none' }, cardAt);",
+    "        if (cardDur > 0) tl.set(captions, { display: '' }, cardAt + cardDur);",
+    "      }",
+    "    }",
+    "    var store = window.__timelines || {};",
+    "    var main = store.main;",
+    "    if (main) { attach(main); return; }",
+    "    Object.defineProperty(store, 'main', {",
+    "      configurable: true,",
+    "      get: function () { return main; },",
+    "      set: function (tl) { main = tl; attach(tl); },",
+    "    });",
+    "    window.__timelines = store;",
+    "  })();",
+    "</script>"
+  ].join("\n");
+}
+function adBrandOverlayCss(opts = {}) {
+  const { mark, card } = adLayerPlacement(opts.aspect ?? "9:16");
+  return [
+    "      /* --- brand layer (baker canvas scaffold-ad) --- */",
+    "      /* 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. */",
+    "      /* 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. */",
+    "      /* A LIGHT panel behind the mark by DEFAULT. A brand mark is usually drawn to sit",
+    "         on white \u2014 the first one here was #1D5D47 on transparent \u2014 so a dark backing hid",
+    "         it on the corner and the brand-coloured closing plate erased it completely: the",
+    "         end card came out as an empty green frame with a single leaf floating in it. A",
+    "         near-white panel is the background most marks in a brand kit are designed",
+    "         against; the ones that are not get `.on-dark` below. */",
+    "      /* Placed in percentages inside the frame's safe area (`adLayerPlacement`): at a fixed",
+    "         90px from the top it sat under the Stories and Reels header on every 9:16 ad. */",
+    `      .brand-mark { position: absolute; top: ${cssPct(mark.top)}; left: ${cssPct(mark.left)}; height: 52px; width: auto;`,
+    "        max-width: 420px; object-fit: contain; padding: 14px 22px; border-radius: 18px;",
+    "        background: rgba(255,255,255,0.94);",
+    "        filter: drop-shadow(0 3px 10px rgba(0,0,0,0.35)); }",
+    "      /* Centred in the safe area, not the frame, so the mark and the call to action stay",
+    "         clear of the chrome on a 9:16 closing card. */",
+    `      .endcard { position: absolute; top: ${cssPct(card.top)}; bottom: ${cssPct(card.bottom)}; left: ${cssPct(card.left)}; right: ${cssPct(card.right)};`,
+    "        display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 56px;",
+    "        text-align: center; }",
+    "      /* Sized to FILL, not merely bounded. Given only max-* constraints an SVG",
+    "         renders at its own intrinsic size, and a small viewBox drew a closing mark",
+    "         a few dozen pixels tall in the middle of a 1080px frame. */",
+    "      .endcard-logo { width: 62%; height: auto; max-height: 300px; object-fit: contain;",
+    "        padding: 46px 56px; border-radius: 40px; background: rgba(255,255,255,0.96);",
+    "        box-shadow: 0 10px 40px rgba(0,0,0,0.28); }",
+    "      /* A mark whose own ink is LIGHT gets the opposite panel. The near-white panel",
+    "         above is right for the mark a brand kit usually ships \u2014 drawn to sit on white",
+    "         \u2014 and it erases the one it does not: a client's white `logo-dark.svg` rendered",
+    "         as an empty white box in the corner, and again 300px tall on the closing card.",
+    "         Which one a mark is gets MEASURED off the file (`markInkIsLight`), never read",
+    "         off its name: `logo-dark` names the background it is for in one brand kit and",
+    "         the ink itself in the next. */",
+    "      .brand-mark.on-dark, .endcard-logo.on-dark { background: rgba(16,20,18,0.92); }",
+    "      /* The name, when the mark itself could not be drawn. */",
+    `      .brand-wordmark { display: inline-block; font-family: ${displayFontStack(opts.face)};`,
+    "        font-weight: 900; color: #14231b; letter-spacing: -0.01em; }",
+    "      .brand-mark.brand-wordmark { font-size: 34px; line-height: 1; height: auto; }",
+    "      .endcard-logo.brand-wordmark { font-size: 96px; line-height: 1; width: auto; }",
+    "      /* 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. */",
+    "      /* The SAME family the caption track uses, and only names the compiler maps.",
+    "         Declaring one matters \u2014 rendered without it the call to action inherited the",
+    "         document default and came out in Times beside sans-serif captions. But the",
+    "         first attempt led with 'BrandFont', which the overlay composition defines and",
+    "         the caption composition does not: HyperFrames refuses an unmapped family and",
+    "         the whole render died with `No deterministic font mapping for: BrandFont`. */",
+    "      /* The button is the OPPOSITE of the plate it sits on. Filling it with the brand",
+    "         colour made it invisible \u2014 the plate is filled with that same colour, so the",
+    "         button was brand-on-brand and its white copy read as another caption line \u2014",
+    "         and a fixed near-black fill is that defect mirrored, on the black plate an ad",
+    "         with no palette gets. The plate carries the brand; the button carries the",
+    "         contrast. Light copy on the near-black default, dark copy on the light one. */",
+    `      .endcard-cta { font-family: ${displayFontStack(opts.face)};`,
+    "        font-size: 64px; font-weight: 900; text-transform: uppercase;",
+    "        letter-spacing: 0.01em; color: #fff; padding: 28px 58px; border-radius: 56px;",
+    "        max-width: 900px; line-height: 1.15; background: rgba(0,0,0,0.82); }",
+    "      .endcard-cta.on-dark-plate { background: rgba(255,255,255,0.96); color: #14231b; }"
+  ].join("\n");
+}
+function injectAdBrandOverlay(indexHtml, overlayHtml, style = {}) {
+  if (!overlayHtml.trim()) return indexHtml;
+  const withCss = indexHtml.replace("    </style>", `${adBrandOverlayCss(style)}
+    </style>`);
+  if (withCss.includes("<!--OVERLAYS-->")) return withCss.replace("<!--OVERLAYS-->", () => overlayHtml);
+  const rootClose = withCss.lastIndexOf("</div>");
+  if (rootClose === -1) return withCss;
+  return `${withCss.slice(0, rootClose)}${overlayHtml}
+    ${withCss.slice(rootClose)}`;
+}
+
+// src/commands/canvas/scaffold-ad.ts
+function pinnedOnAvatar(handle, model) {
+  const hint = pinnedModelHint({ avatar: handle ?? void 0, model, generateAudio: true });
+  return hint ? [hint] : [];
+}
+var AD_SPEC_FILE = "ad.spec.json";
+registerSchema({
+  command: "canvas.scaffold-ad",
+  description: "Build a captioned vertical ad from a WRITTEN SPEC \u2014 no reference video. Start here when someone asks for an ad, a promo or a UGC-style clip and there is nothing to copy: `scaffold-video` reproduces a video you already have, this one writes a new one. You supply a spec of BEATS, and a beat is one line the voice says plus one shot the viewer sees while it is said. Everything else \u2014 the read, the caption cards, the clips, the music, the render \u2014 is derived from that pair, so the ad cannot drift out of sync with itself.",
+  args: {
+    spec: {
+      type: "string",
+      required: true,
+      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 ("Mexico"); omitted, it is the country of a regional `voice.language` ("es-MX"), else nowhere \u2014 a language alone names no country, and an ad with no place is what fills a Spanish ad with British houses. `voice.language` is a BCP-47 tag; omitted, the language is read off the `say` lines. `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. A beat\'s `sound` is one sound effect for that shot, and most beats should not have one. Add it only where the picture shows a specific physical event the viewer expects to hear (a drill tightening a bolt, a door closing, rain on glass, a graphic snapping in). On a talking head or a calm lifestyle shot it reads as a stock sting, and one per beat turns a quiet ad into a noisy one. A music bed plus two well-placed effects beats eight. `voiceover: false` makes it a MUSIC-LED ad: nobody speaks, the `say` lines become on-screen text captioned straight from the script, and it needs `music`. `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": "..." }` invents a realistic person for this one ad: a candid portrait is generated from the description and every beat grounds on it. Use an avatar only when the same actor must recur across ads. 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 \u2014 there is no default, so with no `cta` the card carries the mark alone, and a `cta` repeating the closing line is dropped rather than printed twice. `false` keeps the footage.'
+    },
+    avatar: {
+      type: "string",
+      required: false,
+      description: "Cast this avatar as the ad's recurring person \u2014 the same flag, the same word and the same meaning as on `baker studio generate` and `baker studio animate`. Every beat they appear in is grounded on their identity sheet and their subject description is copied verbatim, so it is one face throughout and the same face as the rest of the company's work. Overrides `cast.avatar` in the spec. `baker avatars list` shows who there is."
+    },
+    "no-brand": {
+      type: "boolean",
+      description: "Build the ad with no brand layer at all: no logo and no closing card. For an ad they asked to keep plain. A missing logo does not need it: with no mark in src/brand/logos/ the ad is built without the corner mark and the hints say how to add one. Never draw a stand-in mark.",
+      required: false,
+      default: false
+    },
+    "video-model": {
+      type: "string",
+      required: false,
+      description: "Curated video model id for the shots. Only for comparing models on one brief.",
+      enum: [...VIDEO_GENERATE_MODELS]
+    },
+    slug: {
+      type: "string",
+      required: false,
+      description: "Creative slug \u2014 writes to src/creatives/<slug>/<slug>.canvas.json"
+    },
+    out: {
+      type: "string",
+      required: false,
+      description: "Output canvas path (default <spec-dir>/<name>.canvas.json)"
+    }
+  }
+});
+function avatarVoiceBrief(avatar) {
+  if (!avatar) return void 0;
+  const parts = [avatar.subjectDescription, avatar.profile?.persona, avatar.profile?.speech].map((p) => p?.trim()).filter((p) => Boolean(p));
+  return parts.length > 0 ? parts.join("; ") : void 0;
+}
+var scaffoldAdCommand = defineCommand({
+  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\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" },
+    avatar: { type: "string", required: false, description: "Cast this avatar as the ad's recurring person \u2014 the same flag, the same word and the same meaning as on `baker studio generate` and `baker studio animate`. Every beat they appear in is grounded on their identity sheet and their subject description is copied verbatim, so it is one face throughout and the same face as the rest of the company's work. Overrides `cast.avatar` in the spec. `baker avatars list` shows who there is." },
+    "video-model": {
+      type: "string",
+      required: false,
+      description: "Which curated video model renders the shots. Defaults to the one the lane picks; pass this only to compare models on the same brief, because mixing models across a campaign changes how the same face reads. `baker canvas catalog --node video_generate` lists what each one takes."
+    },
+    "no-brand": {
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Build the ad with no brand layer at all: no logo and no closing card. For an ad they asked to keep plain. A missing logo does not need it: the ad is then built without the corner mark."
+    },
+    slug: {
+      type: "string",
+      required: false,
+      description: "Creative slug \u2014 writes to src/creatives/<slug>/<slug>.canvas.json"
+    },
+    out: { type: "string", required: false, description: "Output canvas path" }
+  },
+  async run({ args }) {
+    const specPath = args.spec;
+    let parsed;
+    try {
+      parsed = JSON.parse(await readFile(specPath, "utf-8"));
+    } catch (e) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Could not read the ad spec at ${specPath}: ${e instanceof Error ? e.message : String(e)}`,
+          fix: "Write the spec first \u2014 a JSON file with a `beats` array, each beat holding `say` (one clause) and `show` (the shot)."
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const spec = AdSpec.safeParse(parsed);
+    if (!spec.success) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `That ad spec is not usable: ${spec.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`,
+          fix: "A beat is ONE line and ONE shot. If a beat holds two sentences, split it into two beats \u2014 the line becomes a caption card verbatim, and a card holding two sentences is the defect this refuses."
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const flagAvatar = args.avatar?.trim();
+    if (flagAvatar) {
+      spec.data.cast = { ...spec.data.cast, avatar: flagAvatar };
+    }
+    let autoCast = null;
+    if (!flagAvatar && !spec.data.cast?.avatar) {
+      const roster = await readAvatars(
+        "/api/avatars",
+        { status: "ready" }
+      ).catch(() => null);
+      const named = roster ? castedAvatarOnRoster(spec.data, roster.avatars) : null;
+      if (named) {
+        spec.data.cast = { ...spec.data.cast, avatar: named };
+        autoCast = named;
+      }
+    }
+    const specArtifact = structuredClone(spec.data);
+    if (spec.data.set?.description && !spec.data.set.image?.trim()) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: "This ad names a recurring place but gives no picture of it. A location sheet is fused from a real image; with nothing to fuse there is no sheet, and every shot invents the room again.",
+          // Names `studio generate`, which is the command that exists — `baker images`
+          // finds and ingests pictures, it does not make them, so the line this used to
+          // print could not be run. No `--model` either: the lane already defaults to the
+          // curated image model, and the one named here was the legacy id the picker now
+          // offers to nobody.
+          fix: `Make the plate once, then pass it: \`baker studio generate "${spec.data.set.description}"\`, then put its url in the spec as \`"set": { "description": "\u2026", "image": "<url>" }\`. Drop \`set\` entirely if the ad does not keep returning to one place.`
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const requestedModel = args["video-model"]?.trim();
+    if (requestedModel && !VIDEO_GENERATE_MODELS.includes(requestedModel)) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `\`${requestedModel}\` is not one of the curated video models.`,
+          fix: `Pick one of: ${VIDEO_GENERATE_MODELS.join(", ")}. Leave --video-model off to use the default.`
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const chosenVideoModel = requestedModel ?? DEFAULT_VIDEO_GENERATE_MODEL;
+    const handle = flagAvatar || spec.data.cast?.avatar?.trim();
+    let avatar = null;
+    let avatarError = null;
+    if (handle) {
+      try {
+        avatar = await readAvatars(
+          "/api/avatars/get",
+          { handle, full: "true" }
+        );
+        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.`;
+      }
+    }
+    if (avatarError && !spec.data.cast?.description?.trim()) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: avatarError,
+          fix: `This ad casts \`${handle}\` and describes nobody else, so without them every shot renders a person nobody chose. Wait for the avatar and re-run \u2014 \`baker avatars get ${handle} --wait\` returns the moment it is ready \u2014 or cast someone who is (\`baker avatars list\`). To build it with an invented person instead, put a written description in \`cast.description\`.`
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const fromWorkspace = await readBrandFromWorkspace();
+    const filledLogo = !spec.data.brand?.logo && fromWorkspace.logo ? fromWorkspace.logo : void 0;
+    const filledPalette = !spec.data.brand?.palette?.length && fromWorkspace.palette?.length ? fromWorkspace.palette : void 0;
+    if (filledLogo || filledPalette) {
+      spec.data.brand = {
+        ...spec.data.brand,
+        ...filledLogo ? { logo: filledLogo } : {},
+        ...filledPalette ? { palette: filledPalette } : {}
+      };
+    }
+    const resolvedLogo = spec.data.brand?.logo?.trim();
+    const logoExists = resolvedLogo ? await stat(resolvedLogo).then(() => true, () => false) : false;
+    const noBrand = Boolean(args["no-brand"]);
+    const fetched = !logoExists && !noBrand ? await fetchClientLogo() : null;
+    if (fetched?.ok) {
+      spec.data.brand = { ...spec.data.brand, logo: fetched.path };
+    }
+    const haveLogo = logoExists || fetched?.ok === true;
+    if (!haveLogo && spec.data.brand?.logo) {
+      const { logo: _missing, ...rest } = spec.data.brand;
+      spec.data.brand = rest;
+    }
+    const noLogoHint = !haveLogo && !noBrand ? [
+      `This ad has no logo on screen: ${resolvedLogo ? `the mark at \`${resolvedLogo}\` does not exist` : `there is no mark in \`${BRAND_DIR}/logos/\``}. ${fetched && !fetched.ok ? `${fetched.reason} ` : ""}Meta still shows the page name and picture above it, so it can run as it is; say in your reply that it has no logo. To add the client's logo, put the file their designer delivered in \`${BRAND_DIR}/logos/\` and re-run this command. Never draw one.`
+    ] : [];
+    const markPath = spec.data.brand?.logo?.trim();
+    if (!noBrand && markPath?.toLowerCase().endsWith(".svg")) {
+      const svg = await readFile(markPath, "utf-8").catch(() => null);
+      if (svg === null) {
+        writeJson({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `The brand mark at \`${markPath}\` could not be read, so there is no way to tell whether it is a real logo or a typed stand-in. An ad is not shipped on a mark nobody could open.`,
+            fix: `Check the file is there and readable, or put the client's logo in \`${BRAND_DIR}/logos/\` \u2014 the file their designer delivered \u2014 an outlined SVG, or the PNG they gave you.`
+          }
+        });
+        process.exit(1);
+        return;
+      }
+      if (svgIsLiveText(svg)) {
+        writeJson({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `The mark at \`${markPath}\` draws its wordmark with live \`<text>\`, not outlines. That is a typed stand-in, not a logo: it renders in whatever font the machine happens to have, and the one that shipped this way came out reading "greenle\xE1" in every frame.`,
+            fix: `Ask the client for their real logo file and put it in \`${BRAND_DIR}/logos/\` \u2014 the one their designer delivered, as an outlined SVG or a PNG they gave you. Do not redraw it, and do not export this file to PNG: rasterising it only bakes the invented letters into pixels, where nothing downstream can tell they are wrong.`
+          }
+        });
+        process.exit(1);
+        return;
+      }
+    }
+    if (!noBrand && markPath && !await markIsReal(markPath)) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `There is no real logo in \`${BRAND_DIR}/logos/\` \u2014 what is there is a typed stand-in, whose wordmark is drawn as live text in a font the renderer does not have. An ad built on it wears letters the machine invented, and converting it to a PNG only bakes them in.`,
+          fix: `Ask the client for their actual logo file and put it in \`${BRAND_DIR}/logos/\` \u2014 the one their designer delivered, as an outlined SVG or a PNG they gave you. Do not redraw it and do not export the stand-in to another format.`
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    if (handle) {
+      const names = [handle, avatar?.name].filter((value) => Boolean(value));
+      spec.data.beats = spec.data.beats.map((beat) => ({ ...beat, show: withoutCastName(beat.show, names) }));
+      if (spec.data.cast?.description) {
+        spec.data.cast = { ...spec.data.cast, description: withoutCastName(spec.data.cast.description, names) };
+      }
+    }
+    const avatarVoice = avatarVoiceBrief(avatar);
+    if (noBrand || !haveLogo && !endCardCta(spec.data)) spec.data.end_card = false;
+    const slug = args.slug ?? path.basename(specPath).replace(/\.[^.]+$/, "");
+    const outPath = args.out ?? (args.slug ? path.join("src/creatives", slug, `${slug}.canvas.json`) : path.join(path.dirname(specPath), `${slug}.canvas.json`));
+    const definitionLanguage = parseDefinitionStrategyFields(
+      await readFile(path.join(path.dirname(outPath), "_definition.md"), "utf8").catch(() => "")
+    ).language;
+    const cacheDir = path.join(findWorkspaceRoot(path.dirname(path.resolve(outPath))) ?? process.cwd(), "canvas", ".cache");
+    const spent = [];
+    const reading = await readAdSpec(
+      spec.data,
+      {
+        voices: adSpecVoices(spec.data, avatarVoice),
+        askLanguage: !spokenLanguageFor(spec.data, { definitionLanguage })
+      },
+      {
+        ask: cachedJev(cacheDir, (questions) => askJevQuestions(questions, (u) => spent.push(u))),
+        genders: voiceGenderModel(cacheDir, (u) => spent.push(u))
+      }
+    );
+    await holdUnbilledSpend(cacheDir, spent).catch(() => {
+    });
+    const contradicts = spec.data.beats.flatMap((beat, i) => reading.wantsLegibleText[i] ? [{ i, show: beat.show }] : []);
+    if (contradicts.length > 0) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Beat ${contradicts.map(({ i }) => i + 1).join(", ")} asks the picture for a readable figure (e.g. "${contradicts[0]?.show.trim().slice(0, 90)}"). Every frame also carries "no readable text or numbers", so the two fight and the picture wins \u2014 one such brief rendered a bill reading $58,085.00 over a total of $139.00.`,
+          fix: "Say what the shot LOOKS like, not what it reads: 'a bill in her hands, her face falling'. The ad's numbers belong in the `say` line, where the caption track renders them correctly."
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const introducesOffCamera = beatsIntroducingSpeakerOffCamera(spec.data, reading);
+    const firstIntro = introducesOffCamera[0];
+    if (firstIntro !== void 0) {
+      const line = (spec.data.beats[firstIntro]?.say ?? "").trim();
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Beat ${firstIntro + 1} says "${line}" \u2014 the speaker introducing themselves \u2014 but nobody is on camera saying it. A voice from off screen introducing the person standing in shot reads as a mistake, the same way a moving mouth under someone else's voice does.`,
+          fix: 'Either set `on_camera: true` on that beat so they say it themselves \u2014 which needs the avatar to have their own accent \u2014 or rewrite the line as narration about them rather than by them: "Marta instal\xF3 placas en nueve d\xEDas", not "Hola, soy Marta".'
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const spokenLanguage2 = spokenLanguageFor(spec.data, { definitionLanguage, reading });
+    const blueprint = adSpecToBlueprint(spec.data, {
+      avatarAccent: avatar?.profile?.accent,
+      videoModel: chosenVideoModel,
+      ...avatarVoice ? { avatarVoice } : {},
+      ...definitionLanguage ? { definitionLanguage } : {},
+      reading
+    });
+    if (args.slug) await enforceNewCreativeLimit(slug, outPath);
+    let outAr;
+    try {
+      outAr = resolveAspect(void 0, spec.data.format.aspect_ratio, genAspectsFor(chosenVideoModel)).outAr;
+    } catch (e) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: e instanceof Error ? e.message : String(e),
+          fix: 'Set `format.aspect_ratio` to one of the ratios the message lists, e.g. "9:16" for Reels and Stories or "4:5" for the feed.'
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const outDims = canvasDims(outAr);
+    const outDir = path.dirname(outPath);
+    await mkdir(outDir, { recursive: true });
+    const compositionDest = path.join(outDir, "video-overlay-composition");
+    const captionsDest = path.join(outDir, "tiktok-captions-composition");
+    await cp(SHIPPED_OVERLAY_COMPOSITION_DIR, compositionDest, { recursive: true });
+    await cp(SHIPPED_CAPTIONS_DIR, captionsDest, { recursive: true });
+    await stampCompositionDims(compositionDest, outDims);
+    await stampCompositionDims(captionsDest, outDims);
+    const captionsIndex = path.join(captionsDest, "index.html");
+    await writeFile(captionsIndex, injectAdCaptionPlacement(await readFile(captionsIndex, "utf-8"), outAr), "utf-8");
+    const face = await stageBrandDisplayFace(outDir, captionsDest);
+    if (face) {
+      await writeFile(captionsIndex, injectAdDisplayFace(await readFile(captionsIndex, "utf-8"), face.file), "utf-8");
+    }
+    const blueprintPath = path.join(outDir, "prompt.json");
+    const blueprintStylePath = path.join(outDir, "prompt.style.json");
+    await writeSceneFiles(outDir, blueprint);
+    await writeFile(blueprintStylePath, renderStyleProjectionFromValue(blueprint), "utf8");
+    await writeFile(path.join(outDir, AD_SPEC_FILE), `${JSON.stringify(specArtifact, null, 2)}
+`, "utf8");
+    const logoPath = noBrand ? void 0 : spec.data.brand?.logo?.trim();
+    const transcriptPath = path.join(outDir, "transcript.json");
+    if (spec.data.voiceover === false) {
+      await writeFile(transcriptPath, `${JSON.stringify(staticTranscript(spec.data, chosenVideoModel), null, 2)}
+`, "utf-8");
+    }
+    const opts = {
+      imageModel: AD_IMAGE_MODEL,
+      // The frames' model cannot make the sheet: `image_reference_sheet` registers only
+      // the Gemini image models, and a sheet asked of gpt-image is an `unknown_model` node
+      // that stops the whole canvas. The same sheet model every other scaffold uses.
+      sheetModel: ACTOR_SHEET_MODEL,
+      videoModel: chosenVideoModel,
+      overlayCompositionPath: path.relative(outDir, compositionDest),
+      captionsCompositionPath: path.relative(outDir, captionsDest),
+      blueprintPath: path.relative(outDir, blueprintPath),
+      blueprintStylePath: path.relative(outDir, blueprintStylePath),
+      aspect: spec.data.format.aspect_ratio,
+      resolution: spec.data.format.resolution,
+      // A beat is one clause and one card, so the cap has to clear a whole clause.
+      // 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,
+      // The `say` lines are the copy the viewer reads, so they are what the captions print;
+      // the transcription of the voice track only times them.
+      captionsFromScript: true,
+      // Declared, or read off the lines by Jev; never off the voice description.
+      ...spokenLanguage2 ? { spokenLanguage: spokenLanguage2 } : {},
+      voiceGenders: reading.voiceGenders,
+      ...reading.captionCarriesOn.length ? { captionCarriesOn: reading.captionCarriesOn } : {},
+      // The avatar's ACCENT reaches the clip through the blueprint (`avatarAccent` above,
+      // baked into `global.voiceover.accent`), not a pinned voice. A pinned voice was
+      // removed on purpose (ADR 0005): the re-voice is speech-to-speech, so it replaces
+      // timbre and keeps the pronunciation it is handed. The clip speaks in the voice the
+      // video model renders, and the region is directed in the prompt.
+      //
+      // Same decision, one step further: with an avatar on camera the clip's own voice is
+      // kept, not re-voiced. The re-voice is the speech-to-speech route ADR 0005 measured
+      // and rejected — it would swap the voice that matches the mouth and the directed
+      // region for one cast off an English stock list. Only the on-camera voice; a
+      // voiceover read has no rendered voice to keep and is still cast.
+      //
+      // The KNOWN RISK this carries, recorded here because it is decided here: keeping the
+      // rendered voice also means no pass unifies her beats, and each beat is its own
+      // generation, so nothing guarantees two of them sound like the same person. The
+      // reference image fixes the face; nothing fixes the voice. Measured on a finished
+      // three-beat ad (her, a cutaway, her): median speaking pitch 210.5 Hz and 216.2 Hz,
+      // near-identical spreads — the same voice as far as pitch can say — and the two
+      // extracts were then listened to side by side and judged to be the same person. Not
+      // proof for every ad: one listener, one ad, and pitch is one dimension of a voice.
+      //
+      // If it does show up, the fix is not to drop `keepRenderedVoice` — that brings back
+      // the stock voice this exists to avoid. It is to convert the LATER extracts onto the
+      // first beat of the same speaker, which keeps a voice the clip really produced.
+      ...avatar ? { keepRenderedVoice: true } : {},
+      ...spec.data.voiceover === false ? { staticTranscriptPath: path.relative(outDir, transcriptPath) } : {}
+    };
+    const canvas = scaffoldVideoCanvas(blueprint, adSpecCastElements(spec.data, avatar), opts);
+    const renderNode = canvas.nodes.find((n) => n.type === "hyperframe_render");
+    const renderedDir = renderNode ? path.join(outDir, String(renderNode.params?.composition ?? "")) : null;
+    let staged = null;
+    let markIsLight = false;
+    if (logoPath && renderedDir) {
+      const ext = path.extname(logoPath) || ".png";
+      try {
+        await copyFile(logoPath, path.join(renderedDir, `brand-mark${ext}`));
+        staged = { file: `brand-mark${ext}`, alt: spec.data.brand?.name ?? "brand" };
+        markIsLight = await markInkIsLight(logoPath);
+      } catch {
+      }
+    }
+    const closing = blueprint.scenes[blueprint.scenes.length - 1];
+    const overlayHtml = !noBrand && endCardWanted(spec.data) && closing && renderedDir ? buildAdBrandOverlay({
+      logo: staged,
+      cta: endCardCta(spec.data),
+      cardAtS: closing.start_s,
+      cardDurationS: closing.duration_s,
+      totalS: blueprint.estimated_duration_s,
+      markIsLight,
+      // The card's button is coloured against the plate the engine will fill from
+      // this same palette — including the black plate an ad with no palette gets.
+      plateIsDark: plateIsDark(spec.data.brand?.palette)
+    }) : "";
+    if (overlayHtml && renderedDir) {
+      const indexPath = path.join(renderedDir, "index.html");
+      const html = await readFile(indexPath, "utf-8");
+      await writeFile(indexPath, injectAdBrandOverlay(html, overlayHtml, { aspect: outAr, ...face ? { face: AD_DISPLAY_FAMILY } : {} }), "utf-8");
+    }
+    await writeFile(
+      path.join(outDir, REBUILD_FILE),
+      `${JSON.stringify({ elements: adSpecCastElements(spec.data, avatar), opts }, null, 2)}
+`,
+      "utf8"
+    );
+    const validation = await validateCanvasDeep(resolveRelativeCanvasPaths(canvas, outDir), defaultRegistry());
+    if (!validation.ok) {
+      const meta = canvas.metadata;
+      meta.todo = { ...meta.todo ?? {}, blocking_validation_issues: validation.issues };
+    }
+    await writeFile(outPath, `${JSON.stringify(canvas, null, 2)}
+`, "utf-8");
+    if (!validation.ok) {
+      process.stderr.write(
+        `${JSON.stringify(
+          {
+            ok: false,
+            error: { code: "validation", issues: validation.issues },
+            canvas_path: outPath,
+            note: "The canvas WAS written despite the blocking issue(s). Fix the spec and re-run this command, or fix them in place, then `baker canvas validate` before running."
+          },
+          null,
+          2
+        )}
+`
+      );
+      process.exit(2);
+      return;
+    }
+    if (args.slug) {
+      const definitionPath = path.join(outDir, "_definition.md");
+      const definitionExists = await stat(definitionPath).then(() => true, () => false);
+      if (!definitionExists) {
+        await writeFile(
+          definitionPath,
+          buildCreativeDefinition({
+            title: titleFromSlug(slug),
+            kind: "video",
+            platform: resolvePlatform(void 0),
+            formats: resolveFormats(spec.data.format.aspect_ratio),
+            description: spec.data.beats.map((beat) => beat.say.trim()).join(" ")
+          }),
+          "utf8"
+        );
+      }
+      await syncCreativeDefinitionBestEffort({
+        slug,
+        title: titleFromSlug(slug),
+        formats: [spec.data.format.aspect_ratio],
+        canvas,
+        sourceSha: await computeSourceSha(outPath)
+      });
+    }
+    writeJson({
+      ok: true,
+      data: { canvas: outPath, beats: spec.data.beats.length, slug },
+      hints: [
+        // Before anything else: a beat too short to play is a beat to merge, and it is
+        // free to fix here and expensive to discover in a finished ad.
+        ...shortBeatHint(beatsTooShortToPlay(spec.data), spec.data.beats.length),
+        ...noLogoHint,
+        ...face ? [`The captions and the closing button are set in the brand's face: ${face.label}.`] : [],
+        ...noBrand ? [
+          "Built with NO brand mark and no closing card, because you passed --no-brand. Say that in your reply: the user is getting an unbranded ad and should know it, not discover it. When they do have a logo, put it in `src/brand/logos/` and re-run without the flag."
+        ] : [],
+        // Same reasoning as `studio animate`: a cast avatar that speaks routes to the
+        // default model on purpose, and pinning one discards that silently. An ad's
+        // beats always speak, so there is no silent case to exclude here.
+        ...pinnedOnAvatar(handle, requestedModel),
+        // `--until frames` on anything carrying a face or a mark, because that is where
+        // getting it wrong is expensive: the pictures cost a fraction of the clips, and
+        // every defect anyone has caught in a finished ad was visible in them. The run
+        // stops, the agent reviews the frames, and continuing pays for none of them twice.
+        handle || staged ? `Wrote ${spec.data.beats.length} beats to ${outPath}. Run it with \`baker canvas run ${outPath} --until frames --brief "<what they asked for, their words>"\`, review the frames against the brief and Brand, fix any defects, then resume immediately with the \`--run-id\` it gives you. Wait for the user only when they explicitly requested storyboards only or a review before continuing. This ad carries ${handle ? "a person's face" : "the client's mark"}, and a wrong look costs a whole ad to discover after the clips.` : `Wrote ${spec.data.beats.length} beats to ${outPath}. Run it with \`baker canvas run ${outPath} --brief "<what they asked for, their words>"\`.`,
+        ...autoCast ? [
+          `Cast \`${autoCast}\` \u2014 the spec described this person in words, and they are one of this company's avatars. Every shot now grounds on their identity sheet and carries their accent and delivery. Write \`"cast": { "avatar": "` + autoCast + '" }` yourself next time; a written description is for someone the company does not have.'
+        ] : [],
+        `These beats run about ${blueprint.estimated_duration_s}s. If the ask was longer, add beats \u2014 the length is the sum of the lines, so a 25s ad needs roughly 25s of script and cannot be stretched by holding shots.`,
+        ...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."] : [],
+        ...spec.data.brand?.logo && !filledLogo && !spec.data.brand.logo.startsWith(`${BRAND_DIR}/`) ? [
+          `The mark at \`${spec.data.brand.logo}\` is not in \`${BRAND_DIR}/logos/\`. If you drew it for this ad, it is not the client's logo and the ad is going out wearing something you invented \u2014 put the real one in the brand folder (\`/brand-build\`) and re-run. A hand-drawn wordmark also tends to overflow its own viewBox, which renders as a clipped word.`
+        ] : [],
+        ...filledLogo || filledPalette ? [
+          `The spec left the brand empty, so it was read from the workspace: ${[filledLogo ? `logo \`${filledLogo}\`` : null, filledPalette ? `palette ${filledPalette.slice(0, 3).join(", ")}` : null].filter(Boolean).join(" and ")}. Pass them yourself when the ad needs a different mark or colour.`
+        ] : [],
+        ...avatarError ? [avatarError] : [],
+        ...avatar ? [
+          ...avatar?.profile?.accent?.trim() ? [] : [
+            `Avatar \`${handle}\` has no accent on their profile, so the video model picks a region on its own and usually picks the commonest one. An avatar has no pinned voice by design (ADR 0005) \u2014 the accent IS the lever: \`baker avatars update ${handle} --accent "Spanish from Spain, Madrid"\`.`
+          ],
+          `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, describe them in `cast: { description: "..." }` (one invented person throughout), or cast an avatar with `cast: { avatar: "<handle>" }` when they must recur across ads.'
+        ] : [],
+        ...spec.data.cast && !avatar ? [
+          "This cast has a description but no avatar, so a realistic person is invented from it for this ad (a candid portrait every beat grounds on). That is right for a one-off ad; if the same actor has to come back in other ads, cast an avatar (`baker avatars list`) and pass `cast.avatar`."
+        ] : [],
+        ...marketFor(spec.data, definitionLanguage) ? [] : [
+          'This ad names no `market`, so its frames say nowhere and the model picks the place. A language is not a country: set `market` ("Mexico", "Spain") or give `voice.language` with its country ("es-MX") and re-run.'
+        ],
+        ...reading.read ? [] : [
+          `The spec's lines could not be read this time, so ${spokenLanguage2 ? "" : "the voice is cast with no language, "}no voice is held to a gender, captions break on the word count alone, and no line or brief was checked for a self-introduction or readable text. Re-run to read them, or set \`voice.language\` to say the language.`
+        ],
+        ...spec.data.voiceover === false ? [
+          "Nobody speaks in this ad, so the `say` lines are ON-SCREEN text: they are captioned straight from the script, exactly as written, with no voice and no transcription in between. Give it `music` \u2014 a music-led ad with no bed is a silent one."
+        ] : [],
+        "The caption cards print your `say` lines as written, timed to the voice as it reads them; a word the voice slurs or the recogniser mishears still shows as you wrote it. Read the lines 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`.",
+        // Keyed on what is MISSING, not on whether `brand` exists at all: a spec holding
+        // `brand.name` and nothing else once rendered 28 seconds with no palette anywhere.
+        // A missing logo is said once, by `noLogoHint`.
+        ...spec.data.brand?.palette?.length ? [] : [
+          "This spec has no `brand.palette`. Read src/brand/BRAND.md and re-run with it: a name alone leaves the ad in someone else's clothes."
+        ],
+        "`brand.palette` colours the closing plate the card sits on; `brand.logo` is the repo path to the mark, and it is drawn by the composition \u2014 top-left throughout and large on the closing card \u2014 never generated as a picture, so it cannot come back garbled. Give it whenever the client has one."
+      ]
+    });
+  }
+});
+function shortBeatHint(short, total) {
+  if (short.length === 0) return [];
+  return [
+    `Beat${short.length === 1 ? "" : "s"} ${short.join(", ")} of ${total} ${short.length === 1 ? "is" : "are"} a fragment rather than a line \u2014 a few words with a whole shot to themselves. Every beat's picture holds for at least ${SPOKEN_CLIP_DURATION_S}s, so a two-word beat buys six seconds of somebody standing still, and a run of those plays as a slideshow rather than an ad. Don't pad them. Merge them into the beat before or after, so each one carries a whole thought. Edit the spec and re-run this command.`
+  ];
+}
+async function fetchClientLogo() {
+  let domain;
+  try {
+    const company = await apiGet("/api/company");
+    domain = company.data.domain?.trim() || void 0;
+  } catch {
+    domain = void 0;
+  }
+  let lookup = null;
+  if (domain) {
+    try {
+      lookup = await apiPost("/api/images/logo", { domain, variant: "logo", autoIngest: 1 });
+    } catch {
+      lookup = null;
+    }
+  }
+  const decision = decideClientLogo(domain, lookup);
+  if (!decision.use) return { ok: false, reason: clientLogoMissNote(decision, domain) };
+  try {
+    const response = await fetch(decision.url);
+    if (!response.ok) return { ok: false, reason: clientLogoMissNote({ use: false, reason: "no_hits" }, domain) };
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const extension = /\.(svg|png|jpg|jpeg|webp)(?:\?|$)/i.exec(decision.url)?.[1]?.toLowerCase() ?? "svg";
+    const dir = path.join(BRAND_DIR, "logos");
+    await mkdir(dir, { recursive: true });
+    const file = path.join(dir, `brand-mark.${extension}`);
+    await writeFile(file, bytes);
+    return { ok: true, path: file };
+  } catch {
+    return { ok: false, reason: clientLogoMissNote({ use: false, reason: "no_hits" }, domain) };
+  }
+}
+var MAX_FONT_BYTES = 5e6;
+async function stageBrandDisplayFace(outDir, compositionDir) {
+  const root = await findBrandRoot(outDir) ?? process.cwd();
+  const kit = await readStaticBrandKit(root);
+  const face = await brandHeadlineFont({
+    file: kit.headlineFont,
+    named: await readNamedTypefaces(root),
+    resolveUrl: (family, weight) => webFontUrl(family, weight, { lookupGoogleCss, fetchJson })
+  }).catch(() => null);
+  if (!face) return null;
+  try {
+    if ("path" in face.slot) {
+      const file2 = `brand-face${path.extname(face.slot.path).toLowerCase()}`;
+      await copyFile(face.slot.path, path.join(compositionDir, file2));
+      return { file: file2, label: `the font file \`${path.relative(root, face.slot.path)}\`` };
+    }
+    const { buffer } = await fetchExternalBytes(face.slot.url, { maxBytes: MAX_FONT_BYTES });
+    const extension = /\.(woff2|woff|ttf|otf)(?:\?|$)/i.exec(face.slot.url)?.[1]?.toLowerCase() ?? "woff2";
+    const file = `brand-face.${extension}`;
+    await writeFile(path.join(compositionDir, file), buffer);
+    return { file, label: `${face.family ?? "the brand's typeface"}, loaded as a web font` };
+  } catch {
+    return null;
+  }
+}
+export {
+  scaffoldAdCommand
+};
+//# sourceMappingURL=scaffold-ad-3BSA7BWT.js.map