@cliangdev/conductor 0.20.6 → 0.22.0

package/dist/creative/frame.css

@@ -0,0 +1,126 @@
+/* frame.css — the shared creative artboard rules: everything a layout does
+ * not own. Ratios and layouts are both data, not hardcoded here.
+ *
+ *   Placements (artboard sizes and per-placement numbers: lockup, body, cta,
+ *   card padding) live in placements.json / placements.js. render.js reads
+ *   them and sets CSS custom properties on the board (--cc-board-w,
+ *   --cc-lockup-gap, --cc-body-size, ...).
+ *
+ *   Layouts (structural families: stacked, bleed, card, split, and any added
+ *   later) live in layouts/<name>/layout.json + layout.css. This file keeps
+ *   only what every layout shares: the artboard, the lockup, the headline,
+ *   the body, the cta row, sequence anchoring, and the safe-zone review
+ *   guide.
+ *
+ * NOTHING structural here may be position:absolute. A PNG exporter that
+ * screenshots this DOM (the future render job) can drop absolutely
+ * positioned layers, so every photo and scrim stays in normal flow: photos
+ * are painted as background-image on the artboard or a band, scrims are
+ * background-image on the text panel.
+ *
+ * This file has no @import and no font-face: fonts are brand data (a kit's
+ * `fontUrl`), loaded by mount.js's loadFont(), never bundled here.
+ */
+
+/* ── Artboard ─────────────────────────────────────────────────────────────── */
+.cc-board {
+  position: relative;
+  overflow: hidden;
+  box-sizing: border-box;
+  font-family: var(--cc-font);
+  background-color: var(--cc-d-bg);
+  -webkit-font-smoothing: antialiased;
+  flex: none;
+  display: flex;
+  flex-direction: column;
+  width: var(--cc-board-w);
+  height: var(--cc-board-h);
+}
+.cc-board--light { background-color: var(--cc-l-bg); }
+
+.cc-board__panel {
+  position: relative; /* keeps the panel above the glow */
+  box-sizing: border-box;
+  display: flex; flex-direction: column; align-items: flex-start;
+}
+
+/* ── Sequence frames (stories and carousels) ──────────────────────────────── */
+/* Anchored to the bottom on every frame so the eye does not have to re-find the
+   copy between taps or swipes. The CTA appears only on the last frame. */
+.cc-board--seq .cc-lockup { position: absolute; top: var(--cc-safe-top, 48px); left: 88px; }
+
+/* ── Lockup ───────────────────────────────────────────────────────────────── */
+/* Renders only when the brand kit has a mark and/or a wordmark image; a kit
+   with neither renders no lockup at all (see render.js's buildLockup). */
+.cc-lockup { display: inline-flex; align-items: center; flex: none; align-self: flex-start; gap: var(--cc-lockup-gap); }
+.cc-lockup__icon { display: block; width: var(--cc-icon-size); height: var(--cc-icon-size); border-radius: var(--cc-icon-radius); }
+.cc-lockup__mark { display: block; height: var(--cc-mark-height); }
+.cc-lockup--spacer { visibility: hidden; }
+
+/* Chip variant: a white pill behind the lockup, for busy photography (ported
+   from nexus's schema.json `lockup: "chip"` / render.js). `--cc-l-card` and
+   `--cc-elev-overlay` are tokens.css's neutral light-ground surface and
+   shadow — brand-agnostic, so a white pill works over any brand's photo. */
+.cc-lockup--chip {
+  border-radius: 999px;
+  background: var(--cc-l-card);
+  box-shadow: var(--cc-elev-overlay);
+  padding: var(--cc-chip-pad);
+  gap: var(--cc-chip-gap);
+}
+.cc-lockup--chip .cc-lockup__icon {
+  width: var(--cc-chip-icon, var(--cc-icon-size));
+  height: var(--cc-chip-icon, var(--cc-icon-size));
+  border-radius: var(--cc-chip-icon-radius, var(--cc-icon-radius));
+}
+.cc-lockup--chip .cc-lockup__mark { height: var(--cc-chip-mark, var(--cc-mark-height)); }
+
+/* ── Headline ─────────────────────────────────────────────────────────────── */
+.cc-headline {
+  margin: 0;
+  font-size: var(--cc-h-size);
+  line-height: var(--cc-h-leading, 1.04);
+  font-weight: 800;
+  letter-spacing: var(--cc-h-track, -2.3px);
+  color: var(--cc-d-ink);
+  text-wrap: balance;
+}
+.cc-board--light .cc-headline { color: var(--cc-ink); }
+.cc-headline em { font-style: italic; color: var(--cc-accent); }
+
+/* ── Body ─────────────────────────────────────────────────────────────────── */
+.cc-body {
+  margin: 0;
+  font-weight: 500;
+  text-wrap: pretty;
+  font-size: var(--cc-body-size);
+  line-height: var(--cc-body-lh);
+  max-width: var(--cc-body-max-w);
+  color: var(--cc-body-color);
+}
+.cc-board--light .cc-body { font-size: var(--cc-light-body-size, var(--cc-body-size)); color: var(--cc-ink-2); }
+
+/* ── CTA row ──────────────────────────────────────────────────────────────── */
+/* Renders only when the kit has a badge image and/or a ctaClaim string; a kit
+   with neither renders no cta row at all (see render.js's buildCta). */
+.cc-cta { display: flex; align-items: center; flex-wrap: wrap; flex: none; gap: var(--cc-cta-gap); margin-top: var(--cc-cta-margin-top, 0); }
+
+/* The badge is brand artwork (a kit's `logos.badge`): sized by height only in
+   render.js, its own intrinsic aspect ratio preserved. Nothing here may
+   restyle it — no border, no border-radius, no filter, no shadow, no overlay —
+   since a store badge (Apple's, Google's, or a kit's own) typically comes with
+   guidelines against exactly that. */
+.cc-badge { display: block; flex: none; width: auto; }
+
+.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); }
+
+/* ── 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);
+                   background: rgba(74,173,219,0.28); border-bottom: 2px dashed var(--cc-sky); }
+.cc-safe__bottom { position: absolute; bottom: 0; left: 0; right: 0; height: var(--cc-safe-bottom);
+                   background: rgba(74,173,219,0.28); border-top: 2px dashed var(--cc-sky); }
+.cc-safe__right  { position: absolute; bottom: var(--cc-safe-bottom); top: var(--cc-safe-top); right: 0;
+                   width: var(--cc-safe-right);
+                   background: rgba(74,173,219,0.20); border-left: 2px dashed var(--cc-sky); }

package/dist/creative/frame.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Creative frame</title>
+<link rel="stylesheet" href="styles.css">
+<style>
+  /* No page chrome at all: the render job screenshots .cc-board directly, and
+     anything else on the page would only risk bleeding into the capture. */
+  html, body { margin: 0; padding: 0; background: #6E6E73; }
+  body { display: flex; align-items: flex-start; justify-content: center; }
+</style>
+</head>
+<body>
+<!--
+  Single-artboard renderer for the T3 render job (job/render.mjs). Renders
+  exactly one placement (or one sequence beat) of one creative at its TRUE
+  pixel size, fits its type, runs the in-page assertions, and reports the
+  result on window.__RENDER_RESULT / window.__ready.
+
+  Reads its spec from window.__RENDER_SPEC__, which the job sets via
+  Playwright's addInitScript() before navigation (see frame.js) — never a
+  query string or a fetch, so an arbitrarily large creative/brand payload
+  never hits a URL length limit. Always served over http (job/server.mjs),
+  never opened as file://, because `type="module"` imports are blocked there.
+-->
+<script type="module" src="frame.js"></script>
+</body>
+</html>

package/dist/creative/frame.js

@@ -0,0 +1,76 @@
+/* frame.js — builds one `.cc-board` from window.__RENDER_SPEC__ at its true
+ * pixel size, waits for fonts and images to settle, fits the headline, runs
+ * the in-page assertions (assertions.js), and reports the outcome.
+ *
+ * Spec shape (set by job/render.mjs via page.addInitScript before this page
+ * loads):
+ *   {
+ *     creative, brand,             // see README.md's Creative/Brand shapes
+ *     placementKey: '9x16' | ...,  // required, a key from the placements registry
+ *     sequenceIndex?: number,      // required when creative.sequenceKind is set
+ *     placements?, layouts?,       // registry overrides (default: the shipped ones)
+ *   }
+ *
+ * Result contract:
+ *   window.__RENDER_RESULT = { ok, errors?, warnings?, width, height } | { ok: false, error }
+ *   window.__ready = true   // set exactly once, success or failure, when the
+ *                           // job's page.waitForFunction should stop waiting
+ */
+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';
+
+function finish(result) {
+  window.__RENDER_RESULT = result;
+  window.__ready = true;
+}
+
+async function main() {
+  const spec = window.__RENDER_SPEC__;
+  if (!spec || !spec.creative || !spec.placementKey) {
+    finish({ ok: false, error: 'no render spec provided (window.__RENDER_SPEC__)' });
+    return;
+  }
+
+  const placementsReg = spec.placements || DEFAULT_PLACEMENTS;
+  const layoutsReg = spec.layouts || DEFAULT_LAYOUTS;
+  const placement = placementsReg[spec.placementKey];
+  if (!placement) {
+    finish({ ok: false, error: `unknown placement "${spec.placementKey}"` });
+    return;
+  }
+
+  let ad;
+  const isSequence = spec.creative.sequenceKind && Array.isArray(spec.creative.sequence) && spec.creative.sequence.length;
+  if (isSequence) {
+    const frames = resolveSequence(spec.creative, placementsReg, layoutsReg);
+    const idx = spec.sequenceIndex || 0;
+    ad = frames[idx];
+    if (!ad) {
+      finish({ ok: false, error: `no sequence frame at index ${idx} (sequence has ${frames.length})` });
+      return;
+    }
+  } else {
+    ad = resolveAd(spec.creative, placementsReg, layoutsReg);
+  }
+
+  let board;
+  try {
+    await ensureBrandFont(spec.brand);
+    board = renderBoard(ad, spec.placementKey, placementsReg, layoutsReg, spec.brand || {});
+    document.body.appendChild(board);
+
+    await document.fonts.ready;
+    await Promise.all([...document.images].map((img) => (img.decode ? img.decode().catch(() => {}) : null)));
+    fitBoard(board, placementsReg);
+
+    const { errors, warnings, width, height } = await runAssertions(board, placement, spec.brand || {});
+    finish({ ok: errors.length === 0, errors, warnings, width, height });
+  } catch (err) {
+    finish({ ok: false, error: String((err && err.message) || err) });
+  }
+}
+
+main();

package/dist/creative/job/render.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/* render.mjs — the T3 render job's rendering core, plus a thin CLI entry
+ * point at the bottom.
+ *
+ * `run()` below knows nothing about HTTP, Cloud Run, or a Conductor
+ * Workflow — it takes a `transport` object (see transport.mjs) with four
+ * methods (getSpec, putFrame, complete, fail) and drives Playwright against
+ * this package's own frame.html/sheet.html. That split exists because how
+ * this job is *launched and reports back* is expected to change (a direct
+ * Cloud Run Job launch talking straight REST vs. sitting behind a Conductor
+ * Workflow) while the rendering behavior — what gets rendered, how it is
+ * checked, and what "done" or "failed" mean — should not have to change
+ * alongside it. Tests exercise `run()` directly with an in-memory fake
+ * transport (test/job.test.mjs); transport.mjs's HTTP behavior is tested on
+ * its own (test/transport.test.mjs).
+ *
+ * Exit code (CLI only): 0 on success, 1 on any failure (spec fetch, page
+ * load, an assertion, an upload, or a timeout on any of those).
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { startServer } from './server.mjs';
+import { createApiTransport } from './transport.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(HERE, '..'); // conductor-creative/, the static root
+
+const PAGE_TIMEOUT_MS = 20_000;
+
+/* Placement frames are JPEG — Instagram feed images and TikTok photo posts both refuse PNG (see
+ * MediaTargetValidator on the backend) — at quality 92, a level export tooling generally treats as
+ * visually lossless while still compressing meaningfully smaller than PNG. The `sheet` contact sheet
+ * (a preview-only render, never attached to a Post) is a 1x JPEG: it exists to be looked at inside a
+ * chat (preview_creative returns it as an image), which caps it near 1 MB, and a 2x PNG grid of every
+ * placement runs well past that. Every `.cc-board` paints an explicit
+ * `background-color` (frame.css) — dark or light theme — so there is no transparency for JPEG's opaque
+ * export to clip. */
+const PLACEMENT_FRAME_SCREENSHOT = { type: 'jpeg', quality: 92 };
+const PLACEMENT_FRAME_CONTENT_TYPE = 'image/jpeg';
+const SHEET_SCREENSHOT = { type: 'jpeg', quality: 85 };
+const SHEET_CONTENT_TYPE = 'image/jpeg';
+const FRAME_SCALE = 2;
+const SHEET_SCALE = 1;
+
+async function defaultBrowserFactory() {
+  const { chromium } = await import('playwright');
+  return chromium.launch();
+}
+
+/** True when a local Chromium can actually launch. `playwright` lives only
+ * in job/node_modules (see job/package.json's header comment on why it is
+ * not a conductor-creative/ dependency), so anything outside job/ — e.g.
+ * test/job.test.mjs, one directory up — cannot `import('playwright')`
+ * itself and resolve it; it calls this instead, which resolves relative to
+ * THIS file. Tests use it to skip cleanly on a machine that never ran
+ * `npx playwright install chromium`. */
+export async function isChromiumAvailable() {
+  try {
+    const browser = await defaultBrowserFactory();
+    await browser.close();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/* Which page + placementKey(s) this render needs, from the spec's own
+ * shape — see the internal API contract in transport.mjs's header comment.
+ * A story/carousel's beats are separate indexed frames at the sequence's one
+ * placement key; a plain creative renders each of its placements once;
+ * `previewOnly` always renders exactly one contact-sheet frame, regardless
+ * of a sequence, uploaded as placementKey "sheet". */
+export function framesFor(spec) {
+  const { creative, placements, previewOnly } = spec;
+  if (previewOnly) return [{ page: 'sheet.html', placementKey: 'sheet' }];
+  const isSequence = creative.sequenceKind && Array.isArray(creative.sequence) && creative.sequence.length;
+  if (!placements || !placements.length) {
+    throw new Error('the render spec names no placements to render (check the Brand Kit\'s enabled placements, or the carousel ratio)');
+  }
+  if (isSequence) {
+    const key = placements[0];
+    return creative.sequence.map((_, index) => ({ page: 'frame.html', placementKey: key, index }));
+  }
+  return (placements || []).map((placementKey) => ({ page: 'frame.html', placementKey }));
+}
+
+/** Renders every frame a spec calls for, uploads each PNG, and reports
+ * complete/fail. Options:
+ *   transport        required. See transport.mjs.
+ *   packageRoot       static root to serve (default: this package's own root).
+ *   browserFactory    () => Promise<Browser> (default: launches real Playwright chromium).
+ *   log               (...args) => void (default: console.log).
+ * Resolves `true` on success, `false` on a reported failure (never throws —
+ * a thrown error from a truly unexpected place still gets caught and turned
+ * into a `transport.fail()` call before resolving `false`, so a caller never
+ * has to guess whether `transport.fail` was already called). */
+export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactory = defaultBrowserFactory, log = console.log }) {
+  let spec;
+  try {
+    log('fetching spec');
+    spec = await transport.getSpec();
+  } catch (err) {
+    log(`FAIL ${err.message}`);
+    await reportFailure(transport, err.message, log);
+    return false;
+  }
+
+  const { server, origin } = await startServer(packageRoot);
+  let browser;
+  const warnings = [];
+  try {
+    browser = await browserFactory();
+    const frames = framesFor(spec);
+    log(`rendering ${frames.length} frame(s)`);
+
+    for (const frame of frames) {
+      const label = frame.index !== undefined ? `${frame.placementKey}[${frame.index}]` : frame.placementKey;
+      const isSheet = frame.page === 'sheet.html';
+      const scale = isSheet ? SHEET_SCALE : FRAME_SCALE;
+      const page = await browser.newPage({ deviceScaleFactor: scale });
+      try {
+        await page.addInitScript((s) => {
+          window.__RENDER_SPEC__ = s;
+        }, {
+          creative: spec.creative,
+          brand: spec.brand,
+          placementKey: frame.placementKey,
+          sequenceIndex: frame.index,
+          placementKeys: spec.placements,
+        });
+        await page.goto(`${origin}/${frame.page}`, { waitUntil: 'load', timeout: PAGE_TIMEOUT_MS });
+        await page.waitForFunction(() => window.__ready === true, null, { timeout: PAGE_TIMEOUT_MS });
+        const result = await page.evaluate(() => window.__RENDER_RESULT);
+
+        if (!result || !result.ok) {
+          const message = (result && (result.error || (result.errors || []).join('; '))) || 'render failed for an unknown reason';
+          throw new Error(`${label}: ${message}`);
+        }
+        for (const message of result.warnings || []) {
+          warnings.push({ placementKey: frame.placementKey, index: frame.index, message });
+        }
+
+        const locator = isSheet ? page.locator('#sheet') : page.locator('.cc-board').first();
+        const bytes = await locator.screenshot(isSheet ? SHEET_SCREENSHOT : PLACEMENT_FRAME_SCREENSHOT);
+        const contentType = isSheet ? SHEET_CONTENT_TYPE : PLACEMENT_FRAME_CONTENT_TYPE;
+        const box = await locator.boundingBox();
+        const width = Math.round((box && box.width) || 0) * scale;
+        const height = Math.round((box && box.height) || 0) * scale;
+
+        await transport.putFrame(frame.placementKey, { index: frame.index, width, height, bytes, contentType });
+        log(`ok   ${label}  ${width}x${height}  ${contentType}`);
+      } finally {
+        await page.close();
+      }
+    }
+
+    await transport.complete(warnings);
+    log(`complete (${warnings.length} warning(s))`);
+    return true;
+  } catch (err) {
+    log(`FAIL ${err.message}`);
+    await reportFailure(transport, err.message, log);
+    return false;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    server.close();
+  }
+}
+
+async function reportFailure(transport, message, log) {
+  // A spec fetch the API refused never created a render, so there is nothing to mark failed.
+  if (typeof transport.getRenderId === 'function' && !transport.getRenderId()) return;
+  try {
+    await transport.fail(message);
+  } catch (err) {
+    log(`also failed to report failure to the backend: ${err.message}`);
+  }
+}
+
+/* ── CLI entry point ───────────────────────────────────────────────────── */
+
+function isMain() {
+  return process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+}
+
+if (isMain()) {
+  const apiUrl = process.env.CONDUCTOR_API_URL;
+  const apiKey = process.env.CONDUCTOR_API_KEY;
+  const projectId = process.env.CONDUCTOR_PROJECT_ID;
+  const creativeId = process.env.CREATIVE_ID;
+  const previewOnly = /^(1|true)$/i.test(process.env.PREVIEW_ONLY || '');
+  const renderer = process.env.RENDERER || 'cli';
+  const workflowRunId = process.env.WORKFLOW_RUN_ID || undefined;
+  const missing = ['CONDUCTOR_API_URL', 'CONDUCTOR_API_KEY', 'CONDUCTOR_PROJECT_ID', 'CREATIVE_ID'].filter((k) => !process.env[k]);
+  if (missing.length) {
+    console.error(`missing required env var(s): ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  const transport = createApiTransport({ apiUrl, apiKey, projectId, creativeId, previewOnly, renderer, workflowRunId });
+  const log = (...args) => console.log(`[render ${creativeId}]`, ...args);
+  run({ transport, log }).then((ok) => process.exit(ok ? 0 : 1));
+}

package/dist/creative/job/server.mjs

@@ -0,0 +1,72 @@
+/* server.mjs — tiny static file server scoped to the conductor-creative
+ * package root, so frame.html/sheet.html and everything they import
+ * (render.js, placements.js, layouts/, styles.css, assertions.js, ...)
+ * resolve over http. Dependency-free node:http: the job's only npm
+ * dependency is playwright. `type="module"` imports and stylesheet <link>s
+ * are both blocked under file://, which is why this exists rather than just
+ * pointing Playwright at the files directly.
+ *
+ * Adapted from nexus-marketing/social/server.mjs; the only change is that
+ * the static root is a parameter (this package's root) rather than assumed
+ * to be the module's own directory, since this job lives one level down, in
+ * job/.
+ */
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { extname, join, normalize, sep } from 'node:path';
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.webp': 'image/webp',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+};
+
+function makeHandler(root) {
+  return async function handler(req, res) {
+    const url = new URL(req.url, 'http://localhost');
+    let rel = decodeURIComponent(url.pathname);
+    if (rel === '/') rel = '/frame.html';
+    // Contain every request inside `root`.
+    const path = join(root, normalize(rel).replace(/^(\.\.[/\\])+/, ''));
+    if (path !== root && !path.startsWith(root + sep)) {
+      res.writeHead(403).end('forbidden');
+      return;
+    }
+    try {
+      const info = await stat(path);
+      if (!info.isFile()) throw new Error('not a file');
+      const body = await readFile(path);
+      res.writeHead(200, {
+        'content-type': TYPES[extname(path).toLowerCase()] || 'application/octet-stream',
+        'content-length': body.length,
+        'cache-control': 'no-store',
+      });
+      res.end(body);
+    } catch {
+      res.writeHead(404).end('not found');
+    }
+  };
+}
+
+/** Starts a static server rooted at `root` on an ephemeral loopback port.
+ * Resolves `{ server, origin }`; call `server.close()` when done. */
+export function startServer(root, port = 0) {
+  const handle = makeHandler(root);
+  return new Promise((resolve) => {
+    const server = createServer((req, res) => {
+      handle(req, res).catch((err) => {
+        res.writeHead(500).end(String((err && err.message) || err));
+      });
+    });
+    server.listen(port, '127.0.0.1', () => {
+      resolve({ server, origin: `http://127.0.0.1:${server.address().port}` });
+    });
+  });
+}

package/dist/creative/job/transport.mjs

@@ -0,0 +1,167 @@
+/* transport.mjs — the render job's ONLY knowledge of how it talks to the
+ * backend. render.mjs's rendering core never touches `fetch` or a
+ * `/api/v2/...` path directly; it calls the four methods below. Kept
+ * separate because the delivery contract is expected to change (T3's
+ * decision log: renders run LOCALLY through the Conductor CLI/MCP server,
+ * not as a backend-launched Cloud Run Job) — when it changes again, only
+ * this file and its own test change, not the rendering core or its tests.
+ *
+ * Today's contract (see the T3 render contract doc): the external v2
+ * creatives API, `Authorization: Bearer <apiKey>` on every request (the CLI
+ * sends the project/user API key — there is no separate render token).
+ *
+ *   POST {apiUrl}/api/v2/projects/{projectId}/marketing/creatives/{creativeId}/renders
+ *     body: { previewOnly?, renderer?, workflowRunId? }
+ *     -> 201 CreativeRenderResponse { id, state: "RUNNING", ..., spec: { renderId, previewOnly, creative, brand, placements } }
+ *     `spec` is only ever returned by this call — getSpec() hands back `response.spec` and
+ *     remembers `renderId` for the three calls below.
+ *   PUT  {apiUrl}/api/v2/projects/{projectId}/marketing/creatives/{creativeId}/renders/{renderId}/frames/{placementKey}?index&width&height
+ *     body: raw image bytes, Content-Type: image/jpeg (a placement frame) or image/png (the `sheet`
+ *     contact sheet) -> 204
+ *   POST {apiUrl}/api/v2/projects/{projectId}/marketing/creatives/{creativeId}/renders/{renderId}/complete
+ *     body: { warnings: [{ placementKey, index?, message }] } -> 200 CreativeRenderResponse
+ *   POST {apiUrl}/api/v2/projects/{projectId}/marketing/creatives/{creativeId}/renders/{renderId}/fail
+ *     body: { message, log? } -> 200 CreativeRenderResponse
+ */
+
+const DEFAULT_TIMEOUT_MS = 20_000;
+// A frame is a few hundred KB to a few MB; through a scale-to-zero backend (a cold start, a slow uplink)
+// that can outlast the JSON calls' limit, so uploads get their own, and one retry — the PUT is an upsert.
+const DEFAULT_UPLOAD_TIMEOUT_MS = 90_000;
+const UPLOAD_ATTEMPTS = 2;
+
+async function withTimeout(fn, ms, label) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), ms);
+  try {
+    return await fn(ctrl.signal);
+  } catch (err) {
+    if (err && err.name === 'AbortError') throw new Error(`${label} timed out after ${ms}ms`);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return '';
+  }
+}
+
+/** Builds the transport the real job uses, talking to the Conductor backend over HTTP per today's
+ * external v2 `/marketing/creatives/{creativeId}/renders` contract. `timeoutMs` bounds every
+ * individual network call, so a hung backend fails the job instead of hanging the caller (a Claude
+ * Code/Desktop session, or a self-hosted Workflow daemon) forever.
+ *
+ * `renderId` is not known until `getSpec()` returns (the backend assigns it on the POST that starts
+ * the render), so `putFrame`/`complete`/`fail` all reach for it lazily via `renderBase()` rather than
+ * capturing it at construction time. `getRenderId()` is an addition beyond the four-method adapter
+ * interface `render.mjs`'s `run()` relies on — callers that need the id for their own reporting (the
+ * CLI, the MCP tool) can read it after `getSpec()` without `run()` having to hand it back itself. */
+export function createApiTransport({
+  apiUrl,
+  apiKey,
+  projectId,
+  creativeId,
+  previewOnly,
+  renderer,
+  workflowRunId,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  uploadTimeoutMs = DEFAULT_UPLOAD_TIMEOUT_MS,
+  fetchImpl = fetch,
+}) {
+  const creativeBase = `${apiUrl.replace(/\/+$/, '')}/api/v2/projects/${projectId}/marketing/creatives/${creativeId}`;
+  const authHeaders = { Authorization: `Bearer ${apiKey}` };
+  let renderId;
+
+  function renderBase() {
+    if (!renderId) throw new Error('renderId is not known yet — getSpec() must succeed first');
+    return `${creativeBase}/renders/${renderId}`;
+  }
+
+  async function postJson(url, body) {
+    return withTimeout(async (signal) => {
+      const res = await fetchImpl(url, {
+        method: 'POST',
+        headers: { ...authHeaders, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal,
+      });
+      if (!res.ok) throw new Error(`POST ${url} failed: ${res.status} ${await safeText(res)}`);
+      if (res.status === 204) return undefined;
+      try {
+        return await res.json();
+      } catch {
+        return undefined;
+      }
+    }, timeoutMs, `POST ${url}`);
+  }
+
+  return {
+    async getSpec() {
+      const body = { previewOnly: !!previewOnly };
+      if (renderer) body.renderer = renderer;
+      if (workflowRunId) body.workflowRunId = workflowRunId;
+      const response = await withTimeout(async (signal) => {
+        const res = await fetchImpl(`${creativeBase}/renders`, {
+          method: 'POST',
+          headers: { ...authHeaders, 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+          signal,
+        });
+        if (!res.ok) throw new Error(`POST renders failed: ${res.status} ${await safeText(res)}`);
+        return res.json();
+      }, timeoutMs, 'POST renders');
+
+      const spec = response && response.spec;
+      const id = (spec && spec.renderId) || (response && response.id);
+      if (!spec || !id) throw new Error('POST renders response is missing `spec`/a render id');
+      renderId = id;
+      return spec;
+    },
+
+    async putFrame(placementKey, { index, width, height, bytes, contentType = 'image/jpeg' }) {
+      const qs = new URLSearchParams({ width: String(width), height: String(height) });
+      if (index !== undefined && index !== null) qs.set('index', String(index));
+      const base = renderBase();
+      const put = () => withTimeout(async (signal) => {
+        const res = await fetchImpl(`${base}/frames/${encodeURIComponent(placementKey)}?${qs}`, {
+          method: 'PUT',
+          headers: { ...authHeaders, 'Content-Type': contentType },
+          body: bytes,
+          signal,
+        });
+        if (res.status !== 204) {
+          const err = new Error(`PUT frame ${placementKey} failed: ${res.status} ${await safeText(res)}`);
+          err.retryable = res.status >= 500;
+          throw err;
+        }
+      }, uploadTimeoutMs, `PUT frame ${placementKey}`);
+      for (let attempt = 1; ; attempt++) {
+        try {
+          return await put();
+        } catch (err) {
+          const retryable = err.retryable || /timed out/.test(err.message);
+          if (!retryable || attempt >= UPLOAD_ATTEMPTS) throw err;
+        }
+      }
+    },
+
+    async complete(warnings) {
+      return postJson(`${renderBase()}/complete`, { warnings: warnings || [] });
+    },
+
+    async fail(message, log) {
+      return postJson(`${renderBase()}/fail`, log ? { message, log } : { message });
+    },
+
+    /** The render id assigned by `getSpec()`'s POST, or `undefined` before it has run. Not part of the
+     * `run()` adapter interface — a convenience for callers that report the id themselves. */
+    getRenderId() {
+      return renderId;
+    },
+  };
+}