@cliangdev/conductor 0.27.0 → 0.28.0

package/dist/creative/frame.css

@@ -87,6 +87,8 @@
 }
 .cc-board--light .cc-headline { color: var(--cc-ink); }
 .cc-headline em { font-style: italic; color: var(--cc-accent); }
+.cc-headline em.cc-accent-after-space { margin-left: 0.07em; }
+.cc-headline em.cc-accent-before-space { margin-right: 0.04em; }
 /* Word spans the motion presets animate: inline-block so transforms apply; the spaces between them stay
  * plain text, so lines wrap exactly as they do without the spans. */
 .cc-word { display: inline-block; }

package/dist/creative/frame.js

@@ -37,8 +37,8 @@
 import { resolveAd, resolveSequence, renderBoard, fitBoard } 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 { runAssertions } from './assertions.js';
+import { ensureBrandFont, settleImages } from './font.js';
+import { runAssertions, expectedElements } from './assertions.js';
 import { applyMotion, seekBackgroundVideo } from './motion.js';
 
 function finish(result) {
@@ -83,10 +83,13 @@ async function main() {
 
     await document.fonts.ready;
     await Promise.all([...document.images].map((img) => (img.decode ? img.decode().catch(() => {}) : null)));
+    await settleImages(board); // also the bleed photo layer, a CSS background `document.images` does not list
     // Motion presets restructure the headline (word spans): build that structure, in its final state,
     // before fitting, so the type is sized for the layout every captured frame will have.
     if (spec.motion) applyMotion(board, spec.motion, spec.motion.durationSec || 8, { durationSec: spec.motion.durationSec || 8 });
     fitBoard(board, placementsReg);
+    // What this spec requires on the board: a required element that did not render fails the checks.
+    const expect = expectedElements(ad, spec.brand);
 
     if (spec.motion) {
       const durationSec = spec.motion.durationSec || 8;
@@ -102,13 +105,13 @@ async function main() {
         return true;
       };
       // A motion frame is captured at 1x (video), so the photo only needs to cover the placement itself.
-      window.__assertBoard = async () => runAssertions(board, placement, spec.brand || {}, { outputScale: 1 });
+      window.__assertBoard = async () => runAssertions(board, placement, spec.brand || {}, { outputScale: 1, expect });
 
       finish({ ok: true, width: placement.w, height: placement.h });
       return;
     }
 
-    const { errors, warnings, checks, width, height } = await runAssertions(board, placement, spec.brand || {});
+    const { errors, warnings, checks, width, height } = await runAssertions(board, placement, spec.brand || {}, { expect });
     finish({ ok: errors.length === 0, errors, warnings, checks, width, height });
   } catch (err) {
     finish({ ok: false, error: String((err && err.message) || err) });

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

@@ -1,16 +1,23 @@
 /* bleed — photo covers the whole artboard, text sits over a scrim. */
 
 .cc-board--bleed {
-  background-image: var(--cc-photo);
-  /* 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;
 }
 
+/* The photo: a real layer under the copy (render.js adds it first, so plain DOM order keeps the panel and
+   any clip video above it). `cover` + `no-repeat` mean it can never tile or leave a strip uncovered;
+   the focal point is its background-position. motion.js's Ken Burns pan/zoom (a MOTION creative only)
+   is a transform on this layer, kept inside the overhang a scale >= 1 gives it; unset for STILL. */
+.cc-bg-photo {
+  position: absolute; inset: 0;
+  background-image: var(--cc-photo);
+  background-repeat: no-repeat;
+  background-size: cover;
+  background-position: var(--cc-focal, 50% 50%);
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
+}
+
 /* Fill variant (9x16, 4x5, story): the scrim covers the artboard and the
    copy is distributed from top to bottom over it. */
 .cc-board__panel--fill {

package/dist/creative/motion.js

@@ -136,6 +136,45 @@ function wrapWordsInPlace(container) {
   container.appendChild(frag);
 }
 
+/* ── accent-pop: how far a word may grow without eating the spaces around it ─────────────────────
+ * A scaled inline-block keeps its layout box, so growing it moves its ink into the neighbouring spaces:
+ * at 1.18x a long accent word swallowed the space before it ("slightdelay") for the first half second.
+ * The pop is therefore limited so each side grows by at most POP_GAP_EM of the font size (two accent words share one space, so each takes only a sliver of it), and only on a
+ * side that HAS a space (a word glued to punctuation, like "delay" in "delay.", does not grow towards it);
+ * the origin is placed so the growth lands on the open sides. Layout-less environments (a DOM shim)
+ * report no width and get the plain, uncapped pop. */
+
+const POP_PEAK = 1.18;
+const POP_GAP_EM = 0.04;
+
+function hasGap(word, direction) {
+  const prop = direction < 0 ? 'previousSibling' : 'nextSibling';
+  let node = word[prop];
+  // The first/last word of the accent <em> neighbours whatever sits beside the <em> itself.
+  if (!node && word.parentNode && word.parentNode.tagName === 'EM') node = word.parentNode[prop];
+  if (!node) return true; // a line edge: nothing to run into
+  if (node.nodeType !== 3) return false;
+  return direction < 0 ? /\s$/.test(node.textContent) : /^\s/.test(node.textContent);
+}
+
+/** Pure-ish (reads the word's measured width and font size): `{ peak, originX }` — the largest pop scale
+ * that keeps the word clear of its neighbours, and the transform-origin x (percent) that puts the growth
+ * on the sides that have a space. */
+function popLimits(word) {
+  const width = word.offsetWidth;
+  const view = word.ownerDocument && word.ownerDocument.defaultView;
+  const size = view && view.getComputedStyle ? parseFloat(view.getComputedStyle(word).fontSize) : NaN;
+  if (!(width > 0) || !(size > 0)) return { peak: POP_PEAK, originX: 50 };
+  const budget = POP_GAP_EM * size;
+  const left = hasGap(word, -1) ? budget : 0;
+  const right = hasGap(word, 1) ? budget : 0;
+  if (left + right === 0) return { peak: 1, originX: 50 };
+  return {
+    peak: Math.min(POP_PEAK, 1 + (left + right) / width),
+    originX: round2((100 * left) / (left + right)),
+  };
+}
+
 /* ── headline (preset-dependent) ──────────────────────────────────────────── */
 
 function applyHeadline(board, preset, tSec, inEndCard) {
@@ -189,11 +228,12 @@ function applyHeadline(board, preset, tSec, inEndCard) {
     const fadeProgress = windowProgress(tSec, ACCENT_POP_FADE_WINDOW[0], ACCENT_POP_FADE_WINDOW[1]);
     setFade(headline, fadeProgress, null);
     const popProgress = windowProgress(tSec, ACCENT_POP_POP_WINDOW[0], ACCENT_POP_POP_WINDOW[1]);
-    // Scale settles 1.18 → 1; brightness pulses up and back to 1, so the end card starts with no jump.
-    const scale = round2(lerp(1.18, 1, popProgress));
+    // Scale settles peak → 1; brightness pulses up and back to 1, so the end card starts with no jump.
     const brightness = round2(1 + 0.3 * Math.sin(Math.PI * popProgress));
     accentWords.forEach((w) => {
-      w.style.transformOrigin = '50% 70%';
+      const { peak, originX } = popLimits(w);
+      const scale = round2(lerp(peak, 1, popProgress));
+      w.style.transformOrigin = `${originX}% 70%`;
       w.style.transform = scale === 1 ? 'none' : `scale(${scale})`;
       w.style.filter = brightness === 1 ? 'none' : `brightness(${brightness})`;
     });
@@ -243,26 +283,28 @@ export function backgroundMotionState(motion, tSec, durationSec) {
   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}`;
+/** Pure: the rect (relative to the board/band/card it fills) the background layer occupies once
+ * `backgroundMotionState`'s transform is applied to a layer that exactly fills a `w` x `h` box. The
+ * transform is `translateX(panPct%) scale(scale)` (translate first, so the pan is in the BOX's own
+ * pixels, not the scaled layer's): a scale >= 1 overhangs each side by (scale - 1) / 2, and the pan is
+ * kept inside that overhang, so the layer covers the box at every `t`. Exported for tests. */
+export function backgroundLayerRect(w, h, state) {
+  const { scale, panPct } = state;
+  const width = w * scale;
+  const height = h * scale;
+  const left = (w - width) / 2 + (panPct / 100) * w;
+  const top = (h - height) / 2;
+  return { left, top, right: left + width, bottom: top + height, width, height };
 }
 
 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));
+  // One CSS var, consumed by every layout's photo layer, with a no-op fallback so a STILL board (which
+  // never calls applyMotion at all) is untouched: `.cc-bg-photo` (bleed's photo layer),
+  // `.cc-board__band img` / `.cc-board__card img` and `.cc-bg-video`. The layer is `cover`-sized, never
+  // scaled below 1 and never panned past its overhang, so no edge or repeat can show (see
+  // backgroundLayerRect). The focal point stays the layer's own object-/background-position.
+  board.style.setProperty('--cc-bg-transform', `translateX(${panPct}%) scale(${scale})`);
 }
 
 /* ── the public entry point ───────────────────────────────────────────────── */

package/dist/creative/render.js

@@ -159,7 +159,11 @@ export function resolveSequence(raw, placements, layouts) {
   if (!raw.sequenceKind || !Array.isArray(seq) || !seq.length) return [];
   const last = seq.length - 1;
   return seq.map((frame, i) => {
-    const merged = resolveAd({ ...raw, ...frame, sequence: undefined, sequenceKind: undefined }, placements, layouts);
+    // A beat inherits the creative for anything it leaves out, and the API sends an unset beat field as
+    // null: a null must not overwrite the creative's own value (a beat with `photoUrl: null` rendered
+    // with no photo at all).
+    const own = Object.fromEntries(Object.entries(frame).filter(([, v]) => v != null));
+    const merged = resolveAd({ ...raw, ...own, sequence: undefined, sequenceKind: undefined }, placements, layouts);
     // null and undefined both mean "not set" (the API sends null): the CTA then lands on the last frame only.
     merged.showCta = frame.cta != null ? frame.cta : i === last;
     // Body is per-frame opt-in: a hook frame can be a headline and nothing else.
@@ -260,7 +264,13 @@ function buildHeadline(ad, parent) {
     return h;
   }
   if (m[1]) h.appendChild(document.createTextNode(m[1]));
-  el('em', null, h).textContent = m[2];
+  const em = el('em', null, h);
+  em.textContent = m[2];
+  // Italic correction: a slanted accent leans into the upright word before it (and its last letter
+  // overhangs the word after), so a plain word space reads as no space at all ("slightdelay").
+  // Widen only the gaps that are real spaces, never one against glued punctuation.
+  if (/\s$/.test(m[1])) em.classList.add('cc-accent-after-space');
+  if (/^\s/.test(m[3])) em.classList.add('cc-accent-before-space');
   if (m[3]) h.appendChild(document.createTextNode(m[3]));
   return h;
 }
@@ -405,6 +415,7 @@ export function renderBoard(ad, placementKey, placements, layouts, brand, opts)
     (ad.isSequence ? ' cc-board--seq' : '') +
     (ad.isStory ? ' cc-board--story' : ''));
   board.dataset.ratio = placementKey;
+  board.dataset.layout = kind;
 
   applyBrandTokens(board, brand);
   board.style.setProperty('--cc-board-w', placement.w + 'px');
@@ -435,6 +446,11 @@ 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 photo is its own layer, not the board's background: a MOTION creative's Ken Burns zoom/pan is a
+    // transform on this layer, which always covers the board (cover, no-repeat) whatever the zoom. A
+    // background-size percentage on the board did not: it was relative to the photo's WIDTH, so a
+    // landscape photo on a tall board ended up shorter than the board and tiled (see motion.js).
+    if (ad.photoUrl) el('div', 'cc-bg-photo', board).setAttribute('aria-hidden', 'true');
     // 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);
@@ -474,6 +490,9 @@ export function renderBoard(ad, placementKey, placements, layouts, brand, opts)
   if (ad.body && !dropBody) {
     el('p', 'cc-body', panel).textContent = ad.body;
   }
+  // A layout may not have room for a body line at some placements (stacked at 4x5): keep that behaviour,
+  // but record it on the board so runAssertions can warn that supplied copy is not on the artwork.
+  if (ad.body && dropBody) board.dataset.bodyDropped = 'true';
   if (ad.showCta !== false) buildCta(brand, panel, placement);
 
   if (opts.safe && placement.safe.bottom) {

package/dist/creative/sheet.js

@@ -15,7 +15,7 @@
  *                             // 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).
+ *                             // (the backend refuses a MOTION creative with a sequence).
  *   }
  *
  * Result contract: window.__RENDER_RESULT = { ok: true, width, height } |
@@ -25,7 +25,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 { ensureBrandFont, settleImages } from './font.js';
 import { applyMotion } from './motion.js';
 
 const SHEET_SCALE = 0.34;
@@ -105,6 +105,11 @@ async function main() {
       keys.forEach((key) => addCell(ad, key, (placementsReg[key] && placementsReg[key].label) || key));
     }
 
+    // Every photo and logo must have arrived before fitting (a logo's width shapes the layout) and
+    // before the job screenshots the sheet: a sheet captured mid-load showed boards with no photo and no
+    // logo, which read as a render that had dropped them.
+    await settleImages(sheet);
+
     // Fit every board at its TRUE, unscaled size first (a CSS transform
     // shrinks the measured rect and would throw fitBoard's line-count math
     // off), then apply the display scale — the same order mount.js uses.

package/dist/creative/styles.css

@@ -134,6 +134,8 @@
 }
 .cc-board--light .cc-headline { color: var(--cc-ink); }
 .cc-headline em { font-style: italic; color: var(--cc-accent); }
+.cc-headline em.cc-accent-after-space { margin-left: 0.07em; }
+.cc-headline em.cc-accent-before-space { margin-right: 0.04em; }
 /* Word spans the motion presets animate: inline-block so transforms apply; the spaces between them stay
  * plain text, so lines wrap exactly as they do without the spans. */
 .cc-word { display: inline-block; }
@@ -245,16 +247,23 @@
 /* bleed — photo covers the whole artboard, text sits over a scrim. */
 
 .cc-board--bleed {
-  background-image: var(--cc-photo);
-  /* 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;
 }
 
+/* The photo: a real layer under the copy (render.js adds it first, so plain DOM order keeps the panel and
+   any clip video above it). `cover` + `no-repeat` mean it can never tile or leave a strip uncovered;
+   the focal point is its background-position. motion.js's Ken Burns pan/zoom (a MOTION creative only)
+   is a transform on this layer, kept inside the overhang a scale >= 1 gives it; unset for STILL. */
+.cc-bg-photo {
+  position: absolute; inset: 0;
+  background-image: var(--cc-photo);
+  background-repeat: no-repeat;
+  background-size: cover;
+  background-position: var(--cc-focal, 50% 50%);
+  transform: var(--cc-bg-transform, none);
+  transform-origin: center center;
+}
+
 /* Fill variant (9x16, 4x5, story): the scrim covers the artboard and the
    copy is distributed from top to bottom over it. */
 .cc-board__panel--fill {

package/dist/lib/codex-image.d.ts

@@ -0,0 +1,51 @@
+export type ImageAspect = 'portrait' | 'square' | 'landscape';
+export declare const ASPECT_SIZES: Record<ImageAspect, string>;
+export declare const NO_CODEX_HINT = "Codex CLI not found \u2014 install it (npm i -g @openai/codex) and run `codex login`, or set CONDUCTOR_CODEX_PATH.";
+export declare const NOT_LOGGED_IN_HINT = "Codex CLI is not logged in \u2014 run `codex login` (see `conductor doctor`).";
+export interface GenerateImagesParams {
+    prompt: string;
+    aspect?: ImageAspect;
+    count?: number;
+    referenceImagePaths?: string[];
+    outDir: string;
+    onProgress?: (message: string) => void;
+    timeoutMs?: number;
+}
+export interface GeneratedImage {
+    path: string;
+    width: number;
+    height: number;
+}
+export interface GenerateImagesResult {
+    files: GeneratedImage[];
+    provenance: {
+        source: string;
+        licence: string;
+        aiGenerated: true;
+    };
+    revisedPrompt: string;
+    outDir: string;
+    /** JPEG (or small PNG) of the first image for inline display; absent when none fits ~1 MB. */
+    preview?: {
+        data: Buffer;
+        mimeType: string;
+    };
+}
+/** `CONDUCTOR_CODEX_PATH`, else `codex` on PATH. Cached for the process lifetime. */
+export declare function resolveCodexPath(): Promise<string>;
+/** Test-only: the resolved path is cached, so tests that vary availability reset it. */
+export declare function resetCodexPathCache(): void;
+export type CodexStatus = {
+    state: 'ready';
+    version: string;
+} | {
+    state: 'logged-out';
+    version: string;
+} | {
+    state: 'missing';
+};
+/** For `conductor doctor`: never throws. */
+export declare function checkCodexCli(): Promise<CodexStatus>;
+export declare function buildPrompt(scene: string, aspect: ImageAspect, count: number, hasReferences: boolean): string;
+export declare function generateImages(params: GenerateImagesParams): Promise<GenerateImagesResult>;
+//# sourceMappingURL=codex-image.d.ts.map

package/dist/lib/codex-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-image.d.ts","sourceRoot":"","sources":["../../src/lib/codex-image.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE7D,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAIpD,CAAA;AAED,eAAO,MAAM,aAAa,uHACuF,CAAA;AACjH,eAAO,MAAM,kBAAkB,kFAA6E,CAAA;AAe5G,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,IAAI,CAAA;KAAE,CAAA;IAClE,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,8FAA8F;IAC9F,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7C;AAID,qFAAqF;AACrF,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAQxD;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AA4BD,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,CAAA;AAExB,4CAA4C;AAC5C,wBAAsB,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,CAoB1D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,MAAM,CAa7G;AA0ID,wBAAsB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA+EhG"}