@cliangdev/conductor 0.25.0 → 0.27.0

package/assets/claude/skills/conductor-publisher/SKILL.md

@@ -34,6 +34,28 @@ back here with the rendered frames to attach and schedule.
 Also note any media the person handed you: local paths or public URLs, in the order they should
 appear. Media that must be measured (video) is measured by the tool; you do not need dimensions.
 
+### A publish pack, if one exists
+
+Some earlier steps hand over a publish pack with the content: per-destination copy and options, plus
+a first comment and notes. The content team (`conductor-content-studio`) writes one as
+`.conductor/content-runs/<run>/publish-pack.json` (and a readable `publish-pack.md`); any other
+producer can leave the same shape. When the content is a Creative, look for
+`.conductor/content-runs/*/publish-pack.json` whose `creativeId` matches it, or use the one the
+person points to. If you find one:
+
+- Pre-fill each target's `captionOverride` and `options` (`publishOptions` on `set_publish_targets`)
+  from the pack's matching `platforms[]` entry, by platform and format. The pack has no accounts;
+  resolve those from `list_publish_targets` as usual.
+- Check every option key against that destination's `optionKeys` and drop one it does not list,
+  saying so. Never invent a key the pack did not carry. A cover frame or alt text the pack names
+  that needs a Post's own asset (a cover image, per-card alt text) is a note for the person, not a
+  guess.
+- Show the pre-filled copy and options in the confirmation table (see Step 4) and let the person
+  change any of them before anything is submitted. Their edit wins over the pack.
+- Mention the pack's first comment as a **manual step**: Conductor cannot post comments, so give the
+  text to the person to paste once the post is live.
+- Pack or no pack, the normal review applies. The pack settles copy and options; it approves nothing.
+
 ### Formats
 
 Some platforms publish more than one surface. Ask which one the person means when it is not
@@ -84,7 +106,8 @@ connectors gain capabilities — so read `optionKeys` off that destination's row
 platform, and never invent one because it sounds plausible; an unrecognized key is silently
 dropped rather than acted on. TikTok needs a `privacyLevel` from that account's
 `privacyLevelOptions` before it will publish at all; nothing else needs an option to go out, so
-absent a stated preference, leave every other option unset rather than filling in a default.
+absent a stated preference (a publish pack, below, counts as one), leave every other option unset
+rather than filling in a default.
 
 Then run this checklist against the copy, per destination, and **halt on any failure** — report it
 and ask how to proceed. Do not fix content yourself.
@@ -117,7 +140,8 @@ Read the result before saying anything:
 
 ## Step 4 — The confirmation table is the last line of defense
 
-End every successful run with a table, one row per destination:
+End every successful run with a table, one row per destination (add a column for the options
+set, such as a disclosure toggle or an AI label, whenever any were pre-filled or chosen):
 
 | Post | Destination | Account | When | State |
 |---|---|---|---|---|

package/assets/cli-manifest.json

@@ -171,13 +171,41 @@
       },
       {
         "name": "conductor:creative",
-        "description": "One entry point for creative work \u2014 checks the workspace brand (offers to set it up if unconfigured), asks what to make (static ad, short video, an existing clip), then hands off to the conductor-creative skill through render, preview and attach."
+        "description": "One entry point for creative work \u2014 checks the workspace brand (offers to set it up if unconfigured), asks what to make (static ad, short video, an existing clip), then hands off to the conductor-creative skill through draft, preview, approval, commit and attach."
+      },
+      {
+        "name": "conductor:content",
+        "description": "Run a content team: agents brainstorm competing short-form post ideas, pick one with a bias-resistant judge, write the script and direction, and render a local draft. You approve at the preview; only then is the Creative uploaded. Never creates a Post."
       }
     ],
     "agents": [
       {
         "name": "conductor-researcher",
         "description": "Researches unfamiliar technologies, libraries, and APIs for PRD creation. Auto-triggered by conductor:prd when confidence is low."
+      },
+      {
+        "name": "conductor-coder",
+        "description": "Implements one task test-first. Spawned in parallel by conductor:implement with the conductor-coder skill preloaded."
+      },
+      {
+        "name": "conductor-content-strategist",
+        "description": "Writes the content brief (objective, audience tension, must-say/avoid, assets, what has worked) from a workspace context snapshot. Stage of conductor-content-studio."
+      },
+      {
+        "name": "conductor-content-ideator",
+        "description": "Brainstorms distinct short-form post ideas from one assigned angle, tagging each RENDER or FILM. Three run in parallel inside conductor-content-studio."
+      },
+      {
+        "name": "conductor-content-creative-director",
+        "description": "Judges ideas with a fixed rubric: scores anonymized ideas, compares finalists pairwise from rendered drafts, argues against its own leader. Stage of conductor-content-studio."
+      },
+      {
+        "name": "conductor-content-scriptwriter",
+        "description": "Writes the winning idea's script: hook, timed beats, payoff, CTA and captions per platform. Stage of conductor-content-studio."
+      },
+      {
+        "name": "conductor-content-art-director",
+        "description": "Writes visual direction and the creative-spec.json for the draft renderer (or a shoot script for a filming idea). Stage of conductor-content-studio."
       }
     ],
     "skills": [
@@ -195,7 +223,11 @@
       },
       {
         "name": "conductor-creative",
-        "description": "Makes a Creative end to end, static or short video: sets up the Brand Kit if unconfigured, reads it and its Knowledge page, picks media and an angle, creates the Creative, renders and looks at the result, fixes what's wrong, then hands it to conductor-publisher."
+        "description": "Makes a Creative end to end, static or short video: sets up the Brand Kit if unconfigured, reads it and its Knowledge page, picks media and an angle, previews a draft locally and shows it for approval before anything is saved, commits it, fixes what's wrong, then hands it to conductor-publisher."
+      },
+      {
+        "name": "conductor-content-studio",
+        "description": "Orchestrates the content team: context snapshot, parallel ideators, anonymized judging, finalist drafts, script and direction, then a local draft preview you approve before anything is uploaded. Ends at a committed Creative or a shoot script; never creates a Post."
       }
     ]
   },
@@ -781,7 +813,7 @@
     },
     {
       "name": "upload_creative_photo",
-      "description": "Deprecated alias for upload_creative_media — same behavior, including for video/audio.",
+      "description": "Deprecated alias for upload_creative_media \u2014 same behavior, including for video/audio.",
       "category": "marketing"
     },
     {
@@ -800,6 +832,19 @@
         "creativeId"
       ]
     },
+    {
+      "name": "preview_creative_draft",
+      "description": "Look at a Creative before anything is saved: renders a draft locally from the create_creative fields plus local files (photoPath, clipPath, audioPath) and returns the contact sheet as an image. Never writes to Conductor; commit only after the person approves.",
+      "category": "marketing"
+    },
+    {
+      "name": "commit_creative_draft",
+      "description": "Save an approved draft: uploads its local files, creates (or updates) the Creative, and renders the real frames. The first write to Conductor; a draft commits once. Call get_creative to verify.",
+      "category": "marketing",
+      "requiredParams": [
+        "draftDir"
+      ]
+    },
     {
       "name": "attach_creative_to_post",
       "description": "Attach a Creative's rendered frames to a Post as its media, placement to platform, for every destination without its own custom media. Call get_post_status (postId) to verify.",

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) {