@cliangdev/conductor 0.23.0 → 0.24.0

package/dist/creative/layouts/split/layout.css

@@ -12,6 +12,9 @@
   width: 100%; height: 100%;
   object-fit: cover;
   object-position: var(--cc-focal, 50% 30%);
+  /* motion.js's Ken Burns pan/zoom (a MOTION creative only); unset for STILL. */
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
 }
 .cc-board--split .cc-board__panel {
   flex: 1 1 auto; min-height: 0;

package/dist/creative/layouts/stacked/layout.css

@@ -12,6 +12,9 @@
   width: 100%; height: 100%;
   object-fit: cover;
   object-position: var(--cc-focal, 50% 30%);
+  /* motion.js's Ken Burns pan/zoom (a MOTION creative only); unset for STILL. */
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
 }
 .cc-board__scrim {
   position: absolute; left: 0; right: 0; bottom: 0; height: 220px;

package/dist/creative/motion.js

@@ -0,0 +1,347 @@
+/* motion.js — the MOTION creative's animation timeline: a pure function of
+ * time. Everything here computes, for a given `board` (a `.cc-board` element
+ * `render.js`'s `renderBoard` already built) and a time `tSec`, the exact
+ * inline styles/CSS vars that time's frame should show, and writes them.
+ * Nothing here uses `setTimeout`, a CSS `@keyframes`/`animation`, or `Date`.
+ *
+ * That purity is the whole point: the headless render job (`job/render.mjs`)
+ * captures a MOTION video by calling `applyMotion(board, motion, t)` for a
+ * sequence of `t` values and screenshotting after each call — a "frame-
+ * stepped" capture. If `applyMotion` depended on wall-clock time or a running
+ * CSS animation, two calls at the same `t` could render two different
+ * pixels, and the exported video would not match what the editor's live
+ * preview showed. `mount.js`'s `play()` (real-time, via
+ * `requestAnimationFrame`) and the render job's frame stepper both end up
+ * calling this exact same function — that is what keeps the live preview and
+ * the exported MP4 from ever drifting apart, the same guarantee `render.js`
+ * already gives the STILL frame vs. the editor's preview.
+ *
+ * A `motion` object (see README.md and the T-video contract):
+ *   {
+ *     preset: 'fade-up' | 'word-by-word' | 'accent-pop' | 'none',  // default 'fade-up'
+ *     durationSec: number,                                        // default 8
+ *     background: { motion: 'zoom-in'|'zoom-out'|'pan-left'|'pan-right'|'none' }, // default 'zoom-in'
+ *     endCard: boolean,                                            // default true
+ *   }
+ *
+ * Every element's intro is keyed to seconds-from-start, independent of
+ * `durationSec` (a 3s and a 60s creative both fade the lockup in over
+ * 0.2-0.6s) — except the end card, which is always the LAST 2 seconds,
+ * however long the creative is. When `endCard` is true (the default) and
+ * `tSec` falls in that final window, every text/lockup/CTA element is forced
+ * to its finished, fully-visible state regardless of where its own intro
+ * timeline would otherwise put it — a 3s creative's CTA (whose intro window
+ * is 1.8-2.3s) still needs to be showing throughout the 1-3s hold. Background
+ * photo/clip motion is on its own separate, continuous timeline (the whole
+ * `0..durationSec` span) and is never affected by the end-card hold or by
+ * `preset` — panning/zooming is what makes a still photo read as video for
+ * the full runtime, hold included.
+ */
+
+/* ── easing + small numeric helpers (exported: pure, used by mount.js/tests) */
+
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+const lerp = (a, b, t) => a + (b - a) * t;
+
+/** Standard easeOutCubic: fast start, gentle settle. Used for every fade/
+ * transform interpolation in this file, including the background pan/zoom. */
+export function easeOutCubic(x) {
+  const t = clamp01(x);
+  return 1 - Math.pow(1 - t, 3);
+}
+
+/** Eased 0-1 progress of `tSec` through the window `[start, end]`. `end <=
+ * start` is treated as an instant switch at `start` (never divides by zero). */
+function windowProgress(tSec, start, end) {
+  if (end <= start) return tSec >= start ? 1 : 0;
+  return easeOutCubic(clamp01((tSec - start) / (end - start)));
+}
+
+/* ── per-element timing windows (seconds from the creative's own start) ──── */
+
+const LOCKUP_WINDOW = [0.2, 0.6];
+const HEADLINE_FADEUP_WINDOW = [0.3, 0.9];
+const ACCENT_POP_FADE_WINDOW = [0.3, 0.8];
+const ACCENT_POP_POP_WINDOW = [0.8, 1.1];
+const WORD_WINDOW = [0.3, 1.5];
+const WORD_FADE_DURATION = 0.3; // each word's own fade length within WORD_WINDOW
+const BODY_WINDOW = [1.2, 1.7];
+const CTA_WINDOW = [1.8, 2.3];
+const FADE_UP_PX = 24; // headline/body/cta translateY start offset
+const WORD_UP_PX = 16; // a smaller offset per word reads better than 24px x N words
+const END_CARD_LEAD_SEC = 2; // the hold window is [durationSec - 2, durationSec]
+
+/* ── DOM helpers: always set BOTH opacity and transform on every call, never
+ * only one — mount.js's live preview scrubs `t` forward and backward, so a
+ * value this function does not explicitly set this call is a value left over
+ * from a previous call, not "unset". That is the one correctness rule this
+ * whole file exists to uphold. */
+
+function setFade(el, progress, translateY) {
+  if (!el) return;
+  el.style.opacity = String(progress);
+  if (translateY == null) return;
+  const y = lerp(translateY, 0, progress);
+  el.style.transform = y === 0 ? 'none' : `translateY(${round2(y)}px)`;
+}
+
+function finalState(el) {
+  if (!el) return;
+  el.style.opacity = '1';
+  el.style.transform = 'none';
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+/* ── word-by-word: wrap the headline's own text into <span class="cc-word">,
+ * once, idempotently (a rebuilt board from a fresh renderBoard() call always
+ * starts unwrapped; the same board is safe to wrap repeatedly across seeks). */
+
+function ensureWordSpans(headline) {
+  if (headline.querySelector('.cc-word')) return;
+  wrapWordsInPlace(headline);
+}
+
+function wrapWordsInPlace(container) {
+  const nodes = Array.from(container.childNodes);
+  const frag = container.ownerDocument.createDocumentFragment();
+  for (const node of nodes) {
+    if (node.nodeType === 3) {
+      // TEXT_NODE: split on whitespace, keeping the whitespace itself as plain text nodes so word
+      // spacing/wrapping behaves exactly as it did before splitting.
+      const parts = node.textContent.split(/(\s+)/);
+      for (const part of parts) {
+        if (!part) continue;
+        if (/^\s+$/.test(part)) {
+          frag.appendChild(container.ownerDocument.createTextNode(part));
+        } else {
+          const span = container.ownerDocument.createElement('span');
+          span.className = 'cc-word';
+          span.textContent = part;
+          frag.appendChild(span);
+        }
+      }
+    } else if (node.nodeType === 1) {
+      // ELEMENT_NODE: the accent <em> — wrap its own words too, keep the <em> wrapper (and its
+      // italic/accent-color styling) intact around them.
+      wrapWordsInPlace(node);
+      frag.appendChild(node);
+    } else {
+      frag.appendChild(node);
+    }
+  }
+  container.textContent = '';
+  container.appendChild(frag);
+}
+
+/* ── headline (preset-dependent) ──────────────────────────────────────────── */
+
+function applyHeadline(board, preset, tSec, inEndCard) {
+  const headline = board.querySelector('.cc-headline');
+  if (!headline) return;
+
+  if (preset === 'word-by-word') {
+    ensureWordSpans(headline);
+    headline.style.opacity = '1';
+    headline.style.transform = 'none';
+    const words = headline.querySelectorAll('.cc-word');
+    const n = words.length;
+    const [start, end] = WORD_WINDOW;
+    const span = n > 1 ? Math.max(0, (end - WORD_FADE_DURATION - start) / (n - 1)) : 0;
+    words.forEach((word, i) => {
+      if (inEndCard) {
+        finalState(word);
+        return;
+      }
+      const wordStart = start + i * span;
+      const progress = windowProgress(tSec, wordStart, wordStart + WORD_FADE_DURATION);
+      setFade(word, progress, WORD_UP_PX);
+    });
+    return;
+  }
+
+  if (preset === 'none') {
+    finalState(headline);
+    const em = headline.querySelector('em');
+    if (em) {
+      em.style.transform = 'none';
+      em.style.filter = 'none';
+    }
+    return;
+  }
+
+  if (preset === 'accent-pop') {
+    if (inEndCard) {
+      finalState(headline);
+      const em = headline.querySelector('em');
+      if (em) {
+        em.style.transform = 'scale(1)';
+        em.style.filter = 'brightness(1)';
+      }
+      return;
+    }
+    const fadeProgress = windowProgress(tSec, ACCENT_POP_FADE_WINDOW[0], ACCENT_POP_FADE_WINDOW[1]);
+    setFade(headline, fadeProgress, null);
+    const em = headline.querySelector('em');
+    if (em) {
+      const popProgress = windowProgress(tSec, ACCENT_POP_POP_WINDOW[0], ACCENT_POP_POP_WINDOW[1]);
+      em.style.transform = `scale(${round2(lerp(1.18, 1, popProgress))})`;
+      em.style.filter = `brightness(${round2(lerp(0.9, 1.3, popProgress))})`;
+    }
+    return;
+  }
+
+  // 'fade-up' (default)
+  if (inEndCard) {
+    finalState(headline);
+    return;
+  }
+  const progress = windowProgress(tSec, HEADLINE_FADEUP_WINDOW[0], HEADLINE_FADEUP_WINDOW[1]);
+  setFade(headline, progress, FADE_UP_PX);
+}
+
+/* ── lockup / body / cta: a shared fade(-up) treatment ────────────────────── */
+
+function applyFadeElement(board, selector, [start, end], tSec, preset, inEndCard, translateY) {
+  const el = board.querySelector(selector);
+  if (!el) return;
+  if (preset === 'none' || inEndCard) {
+    finalState(el);
+    return;
+  }
+  const progress = windowProgress(tSec, start, end);
+  setFade(el, progress, translateY);
+}
+
+/* ── background photo/clip motion ─────────────────────────────────────────── */
+
+const ZOOM_IN = [1, 1.12];
+const ZOOM_OUT = [1.12, 1];
+const PAN_SCALE = 1.08;
+const PAN_OFFSET_PCT = 4;
+
+/** Pure: the background's scale + horizontal pan (percent, ± PAN_OFFSET_PCT)
+ * at `tSec` of `durationSec`, given `motion.background.motion`. Runs the
+ * whole duration, eased, independent of preset/end-card. Exported for tests
+ * and for anything that wants the numbers without touching the DOM. */
+export function backgroundMotionState(motion, tSec, durationSec) {
+  const kind = (motion && motion.background && motion.background.motion) || 'zoom-in';
+  const progress = durationSec > 0 ? easeOutCubic(clamp01(tSec / durationSec)) : 0;
+  if (kind === 'zoom-in') return { scale: round2(lerp(ZOOM_IN[0], ZOOM_IN[1], progress)), panPct: 0 };
+  if (kind === 'zoom-out') return { scale: round2(lerp(ZOOM_OUT[0], ZOOM_OUT[1], progress)), panPct: 0 };
+  if (kind === 'pan-left') return { scale: PAN_SCALE, panPct: round2(lerp(PAN_OFFSET_PCT, -PAN_OFFSET_PCT, progress)) };
+  if (kind === 'pan-right') return { scale: PAN_SCALE, panPct: round2(lerp(-PAN_OFFSET_PCT, PAN_OFFSET_PCT, progress)) };
+  return { scale: 1, panPct: 0 }; // 'none'
+}
+
+/* "50% 30%" + a pan percent -> "54% 30%": keeps the focal point's own Y, only
+ * the X drifts (a Ken Burns pan is always horizontal here). */
+function panBackgroundPosition(focal, panPct) {
+  const parts = String(focal || '50% 50%').trim().split(/\s+/);
+  const y = parts[1] || '50%';
+  return `${round2(50 + panPct)}% ${y}`;
+}
+
+function applyBackgroundMotion(board, motion, tSec, durationSec) {
+  const { scale, panPct } = backgroundMotionState(motion, tSec, durationSec);
+  // Consumed two ways, both with a no-op fallback so a STILL board (which
+  // never calls applyMotion at all) is untouched:
+  //  - `.cc-board__band img` / `.cc-board__card img` / `.cc-bg-video`: a real
+  //    transform (band/card layouts, and any layout's clip background video).
+  //  - `.cc-board--bleed`'s own CSS `background-image`: background-size/
+  //    -position, since `transform` does not apply to a background image.
+  board.style.setProperty('--cc-bg-transform', `scale(${scale}) translateX(${panPct}%)`);
+  board.style.setProperty('--cc-bg-size', `${round2(scale * 100)}%`);
+  const focal = board.style.getPropertyValue('--cc-focal') || '50% 50%';
+  board.style.setProperty('--cc-bg-pos', panBackgroundPosition(focal, panPct));
+}
+
+/* ── the public entry point ───────────────────────────────────────────────── */
+
+/** Sets every inline style/CSS var a MOTION board needs to look right at
+ * `tSec`, on `board` (a live `.cc-board` from `renderBoard`, already
+ * `fitBoard`-ed). `motion` is `creative.motion` (see the header comment);
+ * `opts.durationSec` overrides `motion.durationSec` when the caller has
+ * already resolved it. Safe to call every frame, in any order of `tSec`
+ * (forward playback, scrubbing backward, or the render job's frame-stepped
+ * capture) — every call fully determines every value it touches. Returns a
+ * small summary (`{ preset, durationSec, inEndCard, background }`), mostly
+ * useful for tests. */
+export function applyMotion(board, motion, tSec, opts) {
+  if (!board) return null;
+  motion = motion || {};
+  const durationSec = (opts && opts.durationSec) || motion.durationSec || 8;
+  const preset = motion.preset || 'fade-up';
+  const endCardEnabled = motion.endCard !== false;
+  const inEndCard = endCardEnabled && tSec >= durationSec - END_CARD_LEAD_SEC;
+
+  applyHeadline(board, preset, tSec, inEndCard);
+  applyFadeElement(board, '.cc-lockup', LOCKUP_WINDOW, tSec, preset, inEndCard, null);
+  applyFadeElement(board, '.cc-body', BODY_WINDOW, tSec, preset, inEndCard, FADE_UP_PX);
+  applyFadeElement(board, '.cc-cta', CTA_WINDOW, tSec, preset, inEndCard, FADE_UP_PX);
+
+  const background = backgroundMotionState(motion, tSec, durationSec);
+  applyBackgroundMotion(board, motion, tSec, durationSec);
+
+  return { preset, durationSec, inEndCard, background };
+}
+
+/** Three representative moments for a `previewOnly` MOTION key-moments sheet:
+ * an early beat (past the lockup/headline intro), the midpoint, and a late
+ * beat inside the end-card hold. `motion.durationSec` defaults to 8 like
+ * everywhere else. */
+export function motionKeyTimes(motion) {
+  const durationSec = (motion && motion.durationSec) || 8;
+  const early = 0.6;
+  const mid = round2(durationSec / 2);
+  const late = round2(Math.max(early, durationSec - 0.5));
+  return [early, mid, late];
+}
+
+/* ── clip background video: shared by mount.js's live-preview seek() and the
+ * headless frame.js/job frame-stepped capture, so a clip background is
+ * frame-accurate in both. No-ops (resolves immediately) when `board` has no
+ * `.cc-bg-video` (a photo background, or a STILL board). */
+export function seekBackgroundVideo(board, tSec, clipStartSec) {
+  const video = board && board.querySelector && board.querySelector('.cc-bg-video');
+  if (!video) return Promise.resolve();
+  const target = Math.max(0, (clipStartSec || 0) + (tSec || 0));
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      video.removeEventListener('seeked', onSeeked);
+      resolve();
+    };
+    const onSeeked = () => done();
+    video.addEventListener('seeked', onSeeked);
+    // A video that never loads (a bad URL, an unreachable fixture in a test) must not hang the
+    // caller forever — a MOTION render with an unreachable clip should fail loudly downstream (a
+    // black/frozen frame trips the end-card assertions or an obviously wrong ffmpeg duration), not
+    // hang the job or the editor.
+    setTimeout(done, 4000);
+    try {
+      video.currentTime = target;
+    } catch {
+      done();
+    }
+  });
+}
+
+
+/* The API describes a clip background under `motion.background` ({source:'clip', clipUrl, clipStartSec});
+ * the engine reads `backgroundVideoUrl`/`clipStartSec` on the creative itself (the editor fills those
+ * directly). This bridges the two so a render spec from the API gets its clip background and clip sound. */
+export function normalizeMotionCreative(creative) {
+  if (!creative || !creative.motion || !creative.motion.background) return creative;
+  const bg = creative.motion.background;
+  if (bg.source !== 'clip' || !bg.clipUrl) return creative;
+  return {
+    ...creative,
+    backgroundVideoUrl: creative.backgroundVideoUrl || bg.clipUrl,
+    clipStartSec: creative.clipStartSec != null ? creative.clipStartSec : (bg.clipStartSec || 0),
+  };
+}

package/dist/creative/render.js

@@ -123,6 +123,10 @@ export function resolveAd(raw, placements, layouts) {
     theme: raw.theme || 'dark',
     lockup: raw.lockup || 'plain',
     photoUrl: raw.photoUrl || null,
+    // A MOTION creative's clip background (see motion.js/README): renderBoard renders a muted
+    // <video class="cc-bg-video"> over the photo area when this is set, alongside (in front of, as a
+    // fallback while it loads) whatever photoUrl is also set.
+    backgroundVideoUrl: raw.backgroundVideoUrl || null,
     headline: raw.headline || '',
     body: raw.body || '',
     caption: raw.caption || '',
@@ -286,6 +290,26 @@ function buildCta(brand, parent, placement) {
   return row;
 }
 
+/* A MOTION creative's clip background: a muted, inline video layered over the photo area, honoring
+ * the same focal/object-fit every layout already gives its photo (`.cc-bg-video`'s CSS lives in
+ * frame.css — one generic rule for every layout — plus a small addition to each layout's own photo
+ * rule for the pan/zoom transform; see motion.js). Placed AFTER the photo element/background (which
+ * still renders as a same-frame fallback while the video loads) and BEFORE any scrim/panel, so it
+ * layers on top of the photo and under the copy without any explicit z-index. Muted: this element is
+ * never the audio source a viewer hears — the render job mixes audio into the exported MP4 itself
+ * (job/render.mjs); the browser preview never plays clip/track audio (see README). */
+function buildBgVideo(parent, videoUrl) {
+  const video = el('video', 'cc-bg-video', parent);
+  video.src = videoUrl;
+  video.muted = true;
+  video.setAttribute('muted', '');
+  video.playsInline = true;
+  video.setAttribute('playsinline', '');
+  video.preload = 'auto';
+  video.setAttribute('preload', 'auto');
+  return video;
+}
+
 /* Applies a headline size plus its derived leading and tracking. */
 function applyType(board, size, leading, tracking) {
   board.style.setProperty('--cc-h-size', size + 'px');
@@ -411,6 +435,9 @@ export function renderBoard(ad, placementKey, placements, layouts, brand, opts)
   let panel;
   if (photoType === 'background') {
     board.style.setProperty('--cc-photo', ad.photoUrl ? 'url("' + ad.photoUrl + '")' : 'none');
+    // The video (when present) must land BEFORE the panel, so the panel's own
+    // stacking (position:relative, later in the DOM) renders above it.
+    if (ad.backgroundVideoUrl) buildBgVideo(board, ad.backgroundVideoUrl);
     // The bottom panel variant hugs the bottom; the fill variant spreads its
     // copy over a full-artboard scrim.
     panel = el('div', 'cc-board__panel cc-board__panel--' + panelVariant, board);
@@ -422,6 +449,7 @@ export function renderBoard(ad, placementKey, placements, layouts, brand, opts)
       cimg.src = ad.photoUrl;
       cimg.alt = '';
     }
+    if (ad.backgroundVideoUrl) buildBgVideo(card, ad.backgroundVideoUrl);
     panel = el('div', 'cc-board__panel', board);
   } else {
     const band = el('div', 'cc-board__band', board);
@@ -430,6 +458,7 @@ export function renderBoard(ad, placementKey, placements, layouts, brand, opts)
       img.src = ad.photoUrl;
       img.alt = '';
     }
+    if (ad.backgroundVideoUrl) buildBgVideo(band, ad.backgroundVideoUrl);
     if (layouts[kind].bandScrim !== false) {
       el('div', 'cc-board__scrim', band);
       el('div', 'cc-board__glow', board);

package/dist/creative/sheet.html

@@ -7,6 +7,10 @@
 <style>
   html, body { margin: 0; background: #F2F2F7; font-family: system-ui, -apple-system, sans-serif; }
   #sheet { display: inline-flex; gap: 24px; align-items: flex-start; padding: 24px; }
+  /* A MOTION key-moments preview (sheet.js's `times` support): rows stack vertically, one per key
+     moment, each row itself a horizontal strip of that moment's enabled placements. */
+  #sheet.sheet--rows { flex-direction: column; align-items: flex-start; }
+  .row { display: flex; gap: 24px; align-items: flex-start; }
   .cell { display: flex; flex-direction: column; gap: 8px; align-items: center; }
   .shell { position: relative; overflow: hidden; border-radius: 6px; box-shadow: 0 3px 12px rgba(0,0,0,0.16); }
   .cap { font-size: 13px; font-weight: 700; color: #717171; }

package/dist/creative/sheet.js

@@ -11,6 +11,11 @@
  *                             // the backend); ignored when the creative has a
  *                             // sequence, which always renders every beat
  *     placements?, layouts?,  // registry overrides (default: the shipped ones)
+ *     times?: number[],       // a MOTION creative's key moments (motion.js's
+ *                             // motionKeyTimes()): one ROW per time, each row
+ *                             // holding every placement in placementKeys at
+ *                             // that time. Ignored for a sequence creative
+ *                             // (MOTION creatives never carry a sequence).
  *   }
  *
  * Result contract: window.__RENDER_RESULT = { ok: true, width, height } |
@@ -21,6 +26,7 @@ import { resolveAd, resolveSequence, renderBoard, fitAll } from './render.js';
 import { placements as DEFAULT_PLACEMENTS } from './placements.js';
 import { layouts as DEFAULT_LAYOUTS } from './layouts/index.js';
 import { ensureBrandFont } from './font.js';
+import { applyMotion } from './motion.js';
 
 const SHEET_SCALE = 0.34;
 
@@ -39,8 +45,9 @@ async function main() {
   const layoutsReg = spec.layouts || DEFAULT_LAYOUTS;
   const sheet = document.getElementById('sheet');
   const boards = [];
+  const motionCells = []; // { board, time }, applied after fitAll (see below)
 
-  function addCell(ad, placementKey, label) {
+  function addCell(ad, placementKey, label, container) {
     const placement = placementsReg[placementKey];
     if (!placement) throw new Error(`unknown placement "${placementKey}"`);
     const cell = document.createElement('div');
@@ -56,17 +63,40 @@ async function main() {
     cap.className = 'cap';
     cap.textContent = label;
     cell.appendChild(cap);
-    sheet.appendChild(cell);
+    (container || sheet).appendChild(cell);
     boards.push(board);
+    return board;
   }
 
   try {
     await ensureBrandFont(spec.brand);
     const isSequence = spec.creative.sequenceKind && Array.isArray(spec.creative.sequence) && spec.creative.sequence.length;
+    const motion = spec.creative.motion;
+    const hasKeyTimes = !isSequence && Array.isArray(spec.times) && spec.times.length && motion;
+
     if (isSequence) {
       const frames = resolveSequence(spec.creative, placementsReg, layoutsReg);
       const key = spec.creative.sequenceKind === 'carousel' ? spec.creative.carouselRatio || '4x5' : 'story';
       frames.forEach((frame, i) => addCell(frame, key, `${i + 1} of ${frames.length}`));
+    } else if (hasKeyTimes) {
+      // One row per key moment, each row holding every enabled placement at that time — lets a human
+      // see how the motion progresses without downloading the full MP4 (see job/render.mjs's
+      // previewOnly MOTION path).
+      sheet.classList.add('sheet--rows');
+      const ad = resolveAd(spec.creative, placementsReg, layoutsReg);
+      const keys = Array.isArray(spec.placementKeys) && spec.placementKeys.length
+        ? spec.placementKeys
+        : Object.keys(placementsReg).filter((k) => placementsReg[k].default);
+      spec.times.forEach((t) => {
+        const row = document.createElement('div');
+        row.className = 'row';
+        sheet.appendChild(row);
+        keys.forEach((key) => {
+          const label = `${(placementsReg[key] && placementsReg[key].label) || key} · ${t.toFixed(1)}s`;
+          const board = addCell(ad, key, label, row);
+          motionCells.push({ board, time: t });
+        });
+      });
     } else {
       const ad = resolveAd(spec.creative, placementsReg, layoutsReg);
       const keys = Array.isArray(spec.placementKeys) && spec.placementKeys.length
@@ -79,6 +109,13 @@ async function main() {
     // shrinks the measured rect and would throw fitBoard's line-count math
     // off), then apply the display scale — the same order mount.js uses.
     await fitAll(sheet, placementsReg);
+
+    // Only after fitting (motion's translateY offsets are fixed px, independent of the fitted
+    // headline size, but applying it before fitBoard risked the word-span wrapping interacting with
+    // the auto-fit measurement — see motion.js).
+    const durationSec = (motion && motion.durationSec) || 8;
+    motionCells.forEach(({ board, time }) => applyMotion(board, motion, time, { durationSec }));
+
     boards.forEach((board) => {
       board.style.transformOrigin = 'top left';
       board.style.transform = `scale(${SHEET_SCALE})`;

package/dist/creative/styles.css

@@ -162,6 +162,27 @@
 .cc-cta__note { font-weight: 600; font-size: var(--cc-note-size); color: var(--cc-note-color); }
 .cc-board--light .cc-cta__note { color: var(--cc-ink-2); }
 
+/* ── Background video (a MOTION clip background) ──────────────────────────── */
+/* One generic rule for every layout: a band/card layout's photo container is
+   already `position:relative; overflow:hidden`, sized to the band/card; a
+   bleed layout has no such container, but `.cc-board` itself is
+   `position:relative; overflow:hidden` (see above), so the video simply
+   covers the whole artboard there instead. render.js always appends this
+   AFTER the still photo (a same-frame fallback while the video loads) and
+   BEFORE the panel/scrim, so plain DOM order — no z-index anywhere in this
+   file — keeps it under the copy and over the photo. `--cc-bg-transform` is
+   motion.js's Ken Burns pan/zoom; unset (a STILL board, which never calls
+   applyMotion) falls back to no transform at all. */
+.cc-bg-video {
+  position: absolute; inset: 0;
+  width: 100%; height: 100%;
+  object-fit: cover;
+  object-position: var(--cc-focal, 50% 50%);
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
+  display: block;
+}
+
 /* ── Safe zones (review guide only, never exported) ───────────────────────── */
 .cc-safe { position: absolute; inset: 0; pointer-events: none; }
 .cc-safe__top    { position: absolute; top: 0; left: 0; right: 0; height: var(--cc-safe-top);
@@ -187,6 +208,9 @@
   width: 100%; height: 100%;
   object-fit: cover;
   object-position: var(--cc-focal, 50% 30%);
+  /* motion.js's Ken Burns pan/zoom (a MOTION creative only); unset for STILL. */
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
 }
 .cc-board__scrim {
   position: absolute; left: 0; right: 0; bottom: 0; height: 220px;
@@ -219,8 +243,12 @@
 
 .cc-board--bleed {
   background-image: var(--cc-photo);
-  background-size: cover;
-  background-position: var(--cc-focal, 50% 50%);
+  /* motion.js's Ken Burns pan/zoom (a MOTION creative only) sets --cc-bg-size/--cc-bg-pos on the
+     board; a background-image has no `transform`, so the zoom/pan is expressed as a growing
+     background-size and a shifting background-position instead. Unset for STILL: falls back to the
+     original fixed cover/focal. */
+  background-size: var(--cc-bg-size, cover);
+  background-position: var(--cc-bg-pos, var(--cc-focal, 50% 50%));
   justify-content: flex-end;
 }
 
@@ -282,6 +310,9 @@
   width: 100%; height: 100%;
   object-fit: cover;
   object-position: var(--cc-focal, 50% 40%);
+  /* motion.js's Ken Burns pan/zoom (a MOTION creative only); unset for STILL. */
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
 }
 .cc-board--card .cc-board__panel {
   flex: 1 1 auto; min-height: 0;
@@ -304,6 +335,9 @@
   width: 100%; height: 100%;
   object-fit: cover;
   object-position: var(--cc-focal, 50% 30%);
+  /* motion.js's Ken Burns pan/zoom (a MOTION creative only); unset for STILL. */
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
 }
 .cc-board--split .cc-board__panel {
   flex: 1 1 auto; min-height: 0;

package/dist/lib/creative-render.d.ts

@@ -29,10 +29,14 @@ export interface RenderCreativeResult {
     frames: RenderFrame[];
 }
 /**
- * Renders a Creative end to end. STILL creatives find a local browser and run the render core against
- * the external API, reading back the stored render (frames with signed URLs, final state) whether or
- * not the render itself succeeded — a FAILED render still has an id and an error message worth
- * returning. CLIP (and MOTION) creatives never launch a browser — see {@link renderViaApi}.
+ * Renders a Creative end to end. STILL and MOTION creatives both find a local browser and run the
+ * render core against the external API, reading back the stored render (frames with signed URLs,
+ * final state) whether or not the render itself succeeded — a FAILED render still has an id and an
+ * error message worth returning. A MOTION render (not previewOnly) additionally needs a local ffmpeg
+ * binary — resolved the same way `upload_creative_media`/`media-probe.ts` finds one (a system binary
+ * on PATH first, else the bundled `ffmpeg-static` fallback) — and runs at a fixed 30fps; a previewOnly
+ * MOTION render (the key-moments contact sheet) needs neither ffmpeg nor a video encode, so it skips
+ * this resolution entirely. CLIP creatives never launch a browser — see {@link renderViaApi}.
  */
 export declare function renderCreative(params: RenderCreativeParams, config: Config, log?: (...args: unknown[]) => void): Promise<RenderCreativeResult>;
 //# sourceMappingURL=creative-render.d.ts.map

package/dist/lib/creative-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"creative-render.d.ts","sourceRoot":"","sources":["../../src/lib/creative-render.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAI9C,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,0GAA0G;IAC1G,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AA+ED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAe,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAyC/B"}
+{"version":3,"file":"creative-render.d.ts","sourceRoot":"","sources":["../../src/lib/creative-render.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAS9C,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,0GAA0G;IAC1G,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,WAAW,EAAE,CAAA;CACtB;AAkFD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAe,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAoD/B"}