@cliangdev/conductor 0.24.1 → 0.26.0

package/dist/creative/assertions.js

@@ -121,12 +121,23 @@ function sameRgb(a, b) {
 export async function runAssertions(board, placement, brand, { outputScale = 2 } = {}) {
   const errors = [];
   const warnings = [];
+  // The same findings with a stable `rule` id each, for callers (the draft preview) that report them
+  // structured. `errors` / `warnings` stay plain message arrays, exactly as before.
+  const checks = [];
+  const fail = (rule, message) => {
+    errors.push(message);
+    checks.push({ rule, severity: 'error', message });
+  };
+  const warn = (rule, message) => {
+    warnings.push(message);
+    checks.push({ rule, severity: 'warning', message });
+  };
   const br = rectOf(board);
 
   const nodes = [...board.querySelectorAll(CHECKED_SELECTOR)].map((n) => ({ name: n.className, rect: rectOf(n) }));
 
   const spill = spillDetect(br, nodes);
-  if (spill.length) errors.push(`text spill: ${spill.join('; ')}`);
+  if (spill.length) fail('spill', `text spill: ${spill.join('; ')}`);
 
   const safe = {
     top: Number(board.dataset.safeTop) || 0,
@@ -134,19 +145,19 @@ export async function runAssertions(board, placement, brand, { outputScale = 2 }
     right: Number(board.dataset.safeRight) || 0,
   };
   const intrusion = safeZoneIntrusion(br, nodes, safe);
-  if (intrusion.length) errors.push(`safe-zone intrusion: ${intrusion.join('; ')}`);
+  if (intrusion.length) fail('safeZone', `safe-zone intrusion: ${intrusion.join('; ')}`);
 
   if (brand && brand.fontFamily) {
     const headlineEl = board.querySelector('.cc-headline');
     const size = Math.round(parseFloat(getComputedStyle(headlineEl).fontSize)) || 16;
     if (!document.fonts.check(`800 ${size}px "${brand.fontFamily}"`)) {
-      errors.push(`font "${brand.fontFamily}" did not load (would export in a fallback face)`);
+      fail('font', `font "${brand.fontFamily}" did not load (would export in a fallback face)`);
     }
   }
 
   const imgs = [...board.querySelectorAll('img')];
   const broken = imgs.filter((i) => !i.complete || i.naturalWidth === 0).map((i) => i.getAttribute('src'));
-  if (broken.length) errors.push(`image(s) failed to load: ${broken.join(', ')}`);
+  if (broken.length) fail('image', `image(s) failed to load: ${broken.join(', ')}`);
 
   // A bleed/card layout paints its photo as a CSS background, invisible to
   // the <img> check above — probe it directly, the same way a typo'd path
@@ -161,11 +172,11 @@ export async function runAssertions(board, placement, brand, { outputScale = 2 }
       img.src = bgUrlMatch[1];
     });
     if (!probe.ok) {
-      errors.push(`background photo failed to load: ${bgUrlMatch[1]}`);
+      fail('image', `background photo failed to load: ${bgUrlMatch[1]}`);
     } else if (placement && probe.w < placement.w * outputScale && probe.h < placement.h * outputScale) {
       // Soft photography check: a source smaller than the output frame (2x for images, 1x for video) is
       // upscaled, so the photo goes soft while the text stays crisp.
-      warnings.push(`photo is ${probe.w}x${probe.h}, upscaled to fit ${placement.w * outputScale}x${placement.h * outputScale}`);
+      warn('photoResolution', `photo is ${probe.w}x${probe.h}, upscaled to fit ${placement.w * outputScale}x${placement.h * outputScale}`);
     }
   }
 
@@ -176,9 +187,9 @@ export async function runAssertions(board, placement, brand, { outputScale = 2 }
     const expectedRaw = getComputedStyle(board).getPropertyValue('--cc-accent').trim();
     const expectedRgb = expectedRaw ? resolveCssColor(expectedRaw) : null;
     if (!emRgb) {
-      errors.push('accent colour did not resolve on the headline');
+      fail('accent', 'accent colour did not resolve on the headline');
     } else if (expectedRgb && !sameRgb(emRgb, expectedRgb)) {
-      errors.push(`accent colour unresolved: headline em is ${getComputedStyle(em).color}, brand accent resolves to ${expectedRaw}`);
+      fail('accent', `accent colour unresolved: headline em is ${getComputedStyle(em).color}, brand accent resolves to ${expectedRaw}`);
     }
   }
 
@@ -207,15 +218,15 @@ export async function runAssertions(board, placement, brand, { outputScale = 2 }
     if (fgRgb && bgRgb) contrast = contrastRatio(fgRgb, bgRgb);
   }
   if (contrast !== null && contrast < 3) {
-    errors.push(`headline contrast is ${contrast}:1 against its background, below the 3:1 floor for large text`);
+    fail('contrast', `headline contrast is ${contrast}:1 against its background, below the 3:1 floor for large text`);
   }
 
   const boxRect = board.getBoundingClientRect();
   const width = Math.round(boxRect.width);
   const height = Math.round(boxRect.height);
   if (placement && (width !== placement.w || height !== placement.h)) {
-    errors.push(`artboard is ${width}x${height}, expected ${placement.w}x${placement.h}`);
+    fail('size', `artboard is ${width}x${height}, expected ${placement.w}x${placement.h}`);
   }
 
-  return { errors, warnings, contrast, width, height };
+  return { errors, warnings, checks, contrast, width, height };
 }

package/dist/creative/frame.js

@@ -15,7 +15,7 @@
  *   }
  *
  * Result contract:
- *   window.__RENDER_RESULT = { ok, errors?, warnings?, width, height } | { ok: false, error }
+ *   window.__RENDER_RESULT = { ok, errors?, warnings?, checks?, width, height } | { ok: false, error }
  *   window.__ready = true   // set exactly once, success or failure, when the
  *                           // job's page.waitForFunction should stop waiting
  *
@@ -108,8 +108,8 @@ async function main() {
       return;
     }
 
-    const { errors, warnings, width, height } = await runAssertions(board, placement, spec.brand || {});
-    finish({ ok: errors.length === 0, errors, warnings, width, height });
+    const { errors, warnings, checks, width, height } = await runAssertions(board, placement, spec.brand || {});
+    finish({ ok: errors.length === 0, errors, warnings, checks, width, height });
   } catch (err) {
     finish({ ok: false, error: String((err && err.message) || err) });
   }

package/dist/creative/job/file-transport.mjs

@@ -0,0 +1,211 @@
+/* file-transport.mjs — a transport (see transport.mjs) that talks to NO backend at all: it renders a
+ * DRAFT spec (the backend's `draft-spec` response, which persists nothing) and leaves the frames in a
+ * local directory, so a person can look at the artwork before anything is uploaded or saved.
+ *
+ * It implements the same interface `run()` in render.mjs calls: getSpec / putFrame / putPoster /
+ * complete / fail, plus `getRenderId()` (run() asks for it before reporting a failure).
+ *
+ *   getSpec()   the draft spec, with every `local:<key>` string replaced by an http URL the headless
+ *               browser (and ffmpeg, for audio) can load. The local files are served by a small
+ *               loopback server (job/server.mjs, cors + Range) rooted at a temp dir that holds a
+ *               symlink (or copy) of each file — the server never exposes anything but those files.
+ *   putFrame    writes `sheet.jpg` (the contact sheet; named by the frame's content type),
+ *               `<placement>[-<index>].jpg|.mp4`
+ *   putPoster   writes `poster-<placement>[-<index>].jpg`
+ *   complete    writes `manifest.json` { ok: true, frames, warnings } — plus, when run() was asked to
+ *               check placements, `checks` (the full render's per-placement assertion results) and
+ *               `passed` (no check has severity "error")
+ *   fail        writes `manifest.json` { ok: false, error, frames, warnings }
+ *
+ * The asset server is started lazily by getSpec() and closed by complete()/fail()/close() (all
+ * idempotent), so a caller that never reaches either still has `close()`.
+ */
+import { copyFile, mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { extname, join, resolve } from 'node:path';
+import { startServer } from './server.mjs';
+
+const LOCAL_REF = /^local:([a-z0-9][a-z0-9-]{0,63})$/;
+
+const EXT_BY_TYPE = {
+  'image/jpeg': '.jpg',
+  'image/png': '.png',
+  'image/webp': '.webp',
+  'video/mp4': '.mp4',
+};
+
+/** A filesystem-safe fragment of a placement key / index. */
+function safe(part) {
+  return String(part).replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+/** Returns a copy of `value` with every string of the exact form `local:<key>` replaced by
+ * `urlFor(key)`. Walks objects and arrays; leaves every other value untouched. */
+function replaceLocalRefs(value, urlFor) {
+  if (typeof value === 'string') {
+    const m = LOCAL_REF.exec(value);
+    return m ? urlFor(m[1]) : value;
+  }
+  if (Array.isArray(value)) return value.map((v) => replaceLocalRefs(v, urlFor));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = replaceLocalRefs(v, urlFor);
+    return out;
+  }
+  return value;
+}
+
+/** Collects every `local:<key>` key a spec references. */
+export function localKeysIn(spec) {
+  const keys = new Set();
+  replaceLocalRefs(spec, (key) => {
+    keys.add(key);
+    return key;
+  });
+  return [...keys];
+}
+
+/**
+ * @param {object}  opts
+ * @param {object}  opts.spec        the draft spec (`{renderId, previewOnly, creative, brand, placements}`)
+ * @param {Record<string,string>} [opts.localFiles]  key -> absolute path of the local file behind `local:<key>`
+ * @param {string}  opts.outDir      directory the frames and manifest.json are written into (created if absent)
+ */
+export function createFileTransport({ spec, localFiles = {}, outDir }) {
+  if (!spec) throw new Error('createFileTransport: `spec` is required');
+  if (!outDir) throw new Error('createFileTransport: `outDir` is required');
+  const out = resolve(outDir);
+
+  let assetDir;
+  let assetServer;
+  let renderId;
+  let closed = false;
+  let error;
+  const frames = [];
+  let warnings = [];
+  let checks;
+
+  async function startAssetServer(keys) {
+    assetDir = await mkdtemp(join(tmpdir(), 'cc-draft-assets-'));
+    const files = {};
+    for (const key of keys) {
+      const source = localFiles[key];
+      if (!source) {
+        throw new Error(`the draft references local:${key} but no local file was given for "${key}"`);
+      }
+      const name = `${key}${extname(source).toLowerCase()}`;
+      const dest = join(assetDir, name);
+      try {
+        await symlink(resolve(source), dest);
+      } catch {
+        await copyFile(source, dest); // symlinks can be unavailable (Windows without privileges)
+      }
+      files[key] = name;
+    }
+    assetServer = await startServer(assetDir, 0, { cors: true });
+    return files;
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    if (assetServer) await new Promise((r) => assetServer.server.close(() => r()));
+    if (assetDir) await rm(assetDir, { recursive: true, force: true }).catch(() => {});
+  }
+
+  async function writeManifest(extra) {
+    await mkdir(out, { recursive: true });
+    const manifest = {
+      ok: !error,
+      ...(error ? { error } : {}),
+      renderId: renderId || 'draft',
+      previewOnly: !!spec.previewOnly,
+      frames,
+      warnings,
+      ...(checks ? { checks, passed: !checks.some((c) => c.severity === 'error') } : {}),
+      ...extra,
+    };
+    await writeFile(join(out, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    return manifest;
+  }
+
+  return {
+    async getSpec() {
+      let resolved = spec;
+      const keys = localKeysIn(spec);
+      if (keys.length) {
+        try {
+          const files = await startAssetServer(keys);
+          resolved = replaceLocalRefs(spec, (key) => `${assetServer.origin}/${files[key]}`);
+        } catch (err) {
+          error = err.message; // run() does not call fail() when the spec never resolved; keep the reason
+          await close();
+          throw err;
+        }
+      }
+      renderId = spec.renderId || 'draft';
+      return resolved;
+    },
+
+    async putFrame(placementKey, { index, width, height, bytes, contentType = 'image/jpeg', durationSeconds, hasAudio } = {}) {
+      const ext = EXT_BY_TYPE[contentType] || '.bin';
+      const hasIndex = index !== undefined && index !== null;
+      const file = `${safe(placementKey)}${hasIndex ? `-${safe(index)}` : ''}${ext}`;
+      await mkdir(out, { recursive: true });
+      await writeFile(join(out, file), bytes);
+      frames.push({
+        placementKey,
+        ...(hasIndex ? { index } : {}),
+        file,
+        contentType,
+        width,
+        height,
+        sizeBytes: bytes.length,
+        ...(durationSeconds !== undefined && durationSeconds !== null ? { durationSeconds } : {}),
+        ...(hasAudio !== undefined && hasAudio !== null ? { hasAudio } : {}),
+      });
+    },
+
+    async putPoster(placementKey, bytes, { index } = {}) {
+      const hasIndex = index !== undefined && index !== null;
+      const file = `poster-${safe(placementKey)}${hasIndex ? `-${safe(index)}` : ''}.jpg`;
+      await mkdir(out, { recursive: true });
+      await writeFile(join(out, file), bytes);
+      const frame = frames.find((f) => f.placementKey === placementKey && (f.index ?? null) === (hasIndex ? index : null));
+      if (frame) frame.poster = file;
+    },
+
+    async complete(w, c) {
+      warnings = Array.isArray(w) ? w : [];
+      checks = Array.isArray(c) ? c : undefined;
+      try {
+        return await writeManifest();
+      } finally {
+        await close();
+      }
+    },
+
+    async fail(message) {
+      error = message || 'render failed';
+      try {
+        return await writeManifest();
+      } finally {
+        await close();
+      }
+    },
+
+    /** 'draft' once getSpec() has succeeded, `undefined` before — run() uses this to decide whether
+     * there is a render to mark failed. */
+    getRenderId() {
+      return renderId;
+    },
+
+    /** The error `fail()` (or a failed getSpec()) recorded, if any. */
+    getError() {
+      return error;
+    },
+
+    /** Stops the asset server and removes the temp asset dir. Safe to call more than once. */
+    close,
+  };
+}

package/dist/creative/job/render.mjs

@@ -297,6 +297,73 @@ async function renderMotionPlacement({ browser, origin, spec, placementKey, ffmp
   }
 }
 
+/* ── Draft preview: the full render's per-placement checks, without the frames ───────────────── */
+
+/* A draft preview renders only the contact sheet (sheet.html), which never runs the assertions — a
+ * bad frame still shows up in a sheet so a human can see what broke. The full render DOES run them
+ * (spill, the bottom safe zone, contrast, fonts, images, the artboard size) on every placement's
+ * frame.html and fails the render, so a design the person approved from the sheet could still fail
+ * afterwards. This runs those very same checks (assertions.js's runAssertions, via frame.html) for
+ * each placement the full render would produce, in the one already-open browser against the
+ * already-served pages, and throws the screenshot away. A MOTION creative is checked the way its
+ * full render checks it: once, on the end-card (final) frame — no video is encoded.
+ *
+ * Resolves `[{ placementKey, index?, rule, message, severity: 'error' | 'warning' }]`; a board that
+ * would not even build (or a page error) is reported as rule "render". */
+async function checkFrame({ browser, origin, spec, frame, fps, log }) {
+  const label = frame.index !== undefined ? `${frame.placementKey}[${frame.index}]` : frame.placementKey;
+  const tag = (check) => ({
+    placementKey: frame.placementKey,
+    ...(frame.index !== undefined ? { index: frame.index } : {}),
+    rule: check.rule,
+    message: check.message,
+    severity: check.severity,
+  });
+  const isMotion = spec.creative && spec.creative.kind === 'MOTION' && spec.creative.motion;
+  const page = await browser.newPage({ deviceScaleFactor: 1 });
+  try {
+    const motion = isMotion ? spec.creative.motion : undefined;
+    const durationSec = (motion && motion.durationSec) || 8;
+    await page.addInitScript((s) => {
+      window.__RENDER_SPEC__ = s;
+    }, {
+      creative: spec.creative,
+      brand: spec.brand,
+      placementKey: frame.placementKey,
+      sequenceIndex: frame.index,
+      ...(isMotion ? { motion, time: 0, clipStartSec: spec.creative.clipStartSec } : {}),
+    });
+    await page.goto(`${origin}/frame.html`, { waitUntil: 'load', timeout: PAGE_TIMEOUT_MS });
+    await page.waitForFunction(() => window.__ready === true, null, { timeout: PAGE_TIMEOUT_MS });
+
+    if (isMotion) {
+      const boot = await page.evaluate(() => window.__RENDER_RESULT);
+      if (!boot || !boot.ok) {
+        return [tag({ rule: 'render', severity: 'error', message: (boot && boot.error) || 'failed to build the MOTION board' })];
+      }
+      const frameCount = Math.max(1, Math.round(durationSec * fps));
+      const endTime = (frameCount - 1) / fps;
+      const seeked = await page.evaluate((t) => window.__seekMotion(t), endTime);
+      if (!seeked) return [tag({ rule: 'render', severity: 'error', message: `motion seek failed at t=${endTime.toFixed(2)}s` })];
+      const assertion = await page.evaluate(() => window.__assertBoard());
+      return ((assertion && assertion.checks) || []).map(tag);
+    }
+
+    const result = await page.evaluate(() => window.__RENDER_RESULT);
+    if (!result) return [tag({ rule: 'render', severity: 'error', message: 'render failed for an unknown reason' })];
+    if (result.checks) return result.checks.map(tag);
+    if (!result.ok) {
+      return [tag({ rule: 'render', severity: 'error', message: result.error || (result.errors || []).join('; ') || 'render failed for an unknown reason' })];
+    }
+    return [];
+  } catch (err) {
+    log(`check ${label}: ${err.message}`);
+    return [tag({ rule: 'render', severity: 'error', message: err.message })];
+  } finally {
+    await page.close().catch(() => {});
+  }
+}
+
 /** Renders every frame a spec calls for, uploads each PNG (or, for a MOTION
  * creative that is not `previewOnly`, one MP4 + poster per placement — see
  * renderMotionPlacement above), and reports complete/fail. Options:
@@ -306,12 +373,15 @@ async function renderMotionPlacement({ browser, origin, spec, placementKey, ffmp
  *   ffmpegPath        a local ffmpeg binary's path. Required for a MOTION
  *                     render (not previewOnly) — ignored otherwise.
  *   fps               frames per second for a MOTION render (default 30).
+ *   checkPlacements   true: when the spec is `previewOnly`, also run the full render's per-placement
+ *                     assertions (see checkFrame above) and pass them to `transport.complete(warnings,
+ *                     checks)`. They never fail the run; the caller decides what a failing check means.
  *   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, ffmpegPath, fps = DEFAULT_FPS, log = console.log }) {
+export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactory = defaultBrowserFactory, ffmpegPath, fps = DEFAULT_FPS, checkPlacements = false, log = console.log }) {
   let spec;
   try {
     log('fetching spec');
@@ -408,7 +478,19 @@ export async function run({ transport, packageRoot = PACKAGE_ROOT, browserFactor
       }
     }
 
-    await transport.complete(warnings);
+    if (checkPlacements && spec.previewOnly) {
+      const checks = [];
+      if ((spec.placements || []).length) {
+        for (const frame of framesFor({ ...spec, previewOnly: false })) {
+          checks.push(...(await checkFrame({ browser, origin, spec, frame, fps, log })));
+        }
+      }
+      const failed = checks.filter((c) => c.severity === 'error').length;
+      log(`checked placements: ${failed} failing, ${checks.length - failed} warning(s)`);
+      await transport.complete(warnings, checks);
+    } else {
+      await transport.complete(warnings);
+    }
     log(`complete (${warnings.length} warning(s))`);
     return true;
   } catch (err) {

package/dist/creative/job/server.mjs

@@ -12,7 +12,8 @@
  * job/.
  */
 import { createServer } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { extname, join, normalize, sep } from 'node:path';
 
 const TYPES = {
@@ -26,9 +27,43 @@ const TYPES = {
   '.jpg': 'image/jpeg',
   '.jpeg': 'image/jpeg',
   '.svg': 'image/svg+xml',
+  '.gif': 'image/gif',
+  '.mp4': 'video/mp4',
+  '.m4v': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
 };
 
-function makeHandler(root) {
+/* Parses a single `Range: bytes=a-b` header against a file of `size` bytes. Returns `{start, end}`
+ * (inclusive), `'unsatisfiable'`, or `null` when there is no usable range (serve the whole file). */
+function parseRange(header, size) {
+  const m = /^bytes=(\d*)-(\d*)$/.exec(header || '');
+  if (!m || (m[1] === '' && m[2] === '')) return null;
+  let start;
+  let end;
+  if (m[1] === '') {
+    const suffix = Number(m[2]);
+    start = Math.max(0, size - suffix);
+    end = size - 1;
+  } else {
+    start = Number(m[1]);
+    end = m[2] === '' ? size - 1 : Math.min(Number(m[2]), size - 1);
+  }
+  if (start > end || start >= size) return 'unsatisfiable';
+  return { start, end };
+}
+
+/* `cors` adds a permissive Access-Control-Allow-Origin header. It is for a SECOND server that serves
+ * local media (job/file-transport.mjs) from a different loopback port than the page that embeds it:
+ * a cross-origin <img>/<video> needs no CORS to display, but a stricter load path (a fetch, a font)
+ * does, and the server only ever listens on 127.0.0.1. Range requests are always honoured — a video
+ * <video> element cannot seek without them. */
+function makeHandler(root, { cors = false } = {}) {
   return async function handler(req, res) {
     const url = new URL(req.url, 'http://localhost');
     let rel = decodeURIComponent(url.pathname);
@@ -39,26 +74,48 @@ function makeHandler(root) {
       res.writeHead(403).end('forbidden');
       return;
     }
+    let info;
     try {
-      const info = await stat(path);
+      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');
+      return;
+    }
+    const headers = {
+      'content-type': TYPES[extname(path).toLowerCase()] || 'application/octet-stream',
+      'accept-ranges': 'bytes',
+      'cache-control': 'no-store',
+      ...(cors ? { 'access-control-allow-origin': '*' } : {}),
+    };
+    const range = parseRange(req.headers.range, info.size);
+    if (range === 'unsatisfiable') {
+      res.writeHead(416, { ...headers, 'content-range': `bytes */${info.size}` }).end();
+      return;
+    }
+    const status = range ? 206 : 200;
+    const start = range ? range.start : 0;
+    const end = range ? range.end : info.size - 1;
+    res.writeHead(status, {
+      ...headers,
+      'content-length': info.size === 0 ? 0 : end - start + 1,
+      ...(range ? { 'content-range': `bytes ${start}-${end}/${info.size}` } : {}),
+    });
+    if (req.method === 'HEAD' || info.size === 0) {
+      res.end();
+      return;
     }
+    const stream = createReadStream(path, { start, end });
+    stream.on('error', () => res.destroy());
+    stream.pipe(res);
   };
 }
 
 /** 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);
+ * Resolves `{ server, origin }`; call `server.close()` when done. `options.cors` adds an
+ * `Access-Control-Allow-Origin: *` header (see makeHandler). */
+export function startServer(root, port = 0, options = {}) {
+  const handle = makeHandler(root, options);
   return new Promise((resolve) => {
     const server = createServer((req, res) => {
       handle(req, res).catch((err) => {

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

@@ -39,4 +39,66 @@ export interface RenderCreativeResult {
  * 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>;
+export interface DraftManifestFrame {
+    placementKey: string;
+    index?: number;
+    file: string;
+    contentType: string;
+    width?: number;
+    height?: number;
+    sizeBytes?: number;
+    durationSeconds?: number;
+    hasAudio?: boolean;
+    poster?: string;
+}
+/** One finding of the full render's per-placement assertions (spill, safe zone, contrast, fonts, images,
+ * artboard size), run on a placement's frame without keeping the frame. */
+export interface DraftCheck {
+    placementKey: string;
+    index?: number;
+    /** spill | safeZone | contrast | font | image | accent | size | photoResolution | render */
+    rule: string;
+    message: string;
+    /** An "error" would fail the full render of that placement; a "warning" would only be reported. */
+    severity: 'error' | 'warning';
+}
+export interface DraftManifest {
+    ok: boolean;
+    error?: string;
+    renderId?: string;
+    previewOnly?: boolean;
+    frames: DraftManifestFrame[];
+    warnings: Array<{
+        placementKey?: string;
+        index?: number;
+        message: string;
+    }>;
+    /** Present on a preview: the per-placement assertion results the full render would produce. */
+    checks?: DraftCheck[];
+    /** Present with `checks`: true when none of them has severity "error". */
+    passed?: boolean;
+}
+export interface RenderDraftResult {
+    ok: boolean;
+    error?: string;
+    manifest?: DraftManifest;
+}
+/**
+ * Renders a DRAFT spec (the backend's `draft-spec` response — nothing about it is saved) with the same
+ * render core a saved Creative uses, but through the file transport: the local files behind
+ * `local:<key>` are served to the headless browser from this machine, and the frames plus a
+ * `manifest.json` land in `outDir`. A `previewOnly` spec also gets `manifest.checks` / `manifest.passed`:
+ * the full render's per-placement assertions, run without keeping their frames. Never talks to the Conductor API. A MOTION spec that is not
+ * `previewOnly` needs ffmpeg, resolved the same way {@link renderCreative} resolves it.
+ */
+export declare function renderDraft(params: {
+    spec: {
+        creative?: {
+            kind?: string;
+        };
+        previewOnly?: boolean;
+    };
+    localFiles: Record<string, string>;
+    outDir: string;
+}, log?: (...args: unknown[]) => void): Promise<RenderDraftResult>;
 //# 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;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"}
+{"version":3,"file":"creative-render.d.ts","sourceRoot":"","sources":["../../src/lib/creative-render.ts"],"names":[],"mappings":"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"}