@cliangdev/conductor 0.20.6 → 0.22.0

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

@@ -0,0 +1,144 @@
+---
+name: conductor-creative
+description: Creates on-brand ad creative through the Conductor MCP tools — a photo plus headline rendered at every enabled placement (e.g. TikTok/Reels 9:16, Instagram feed 4:5, Facebook 1:1, plus any opt-in placements) from a workspace's Brand Kit, rendered locally on this machine and checked by eye before it's called done. Use when asked to make, design, write or export a social ad, an ad creative, a promo image, a static ad, a story or carousel sequence, or a new lettered variant (headline test) of one.
+user-invocable: true
+allowed-tools: mcp__conductor__*, AskUserQuestion, Read, Glob, Grep
+---
+
+# Conductor Creative
+
+Turns one concept — a photo and a headline — into upload-ready artwork at every placement a
+workspace's Brand Kit enables. This is the front half of Conductor's marketing pillar: what this
+skill produces becomes a Post's media, and `conductor-publisher` takes it from there through review
+and out to each destination. You write the ad here; you do not post it.
+
+You are writing the ad, not just running a tool. The copy and the visual language both come from
+things that already exist for this workspace — a Brand Kit (data: tokens, copy rules, approved
+lines) and a Knowledge page (prose: positioning, voice, facts). Read them rather than inventing.
+
+Rendering happens locally, through this MCP server, with a browser on this machine — there is no
+separate render service to wait on. `render_creative` typically finishes in well under a minute.
+
+## How to make a Creative
+
+### 1. Read the brand
+
+Call `get_brand_kit` (a project may have more than one — pass `kitId` if the person named a
+specific brand, otherwise the default). It gives you the colour tokens, font, logo/wordmark/badge
+URLs, the CTA claim, the copy rules (each a regex, a message, and which fields it applies to), the
+approved lines, the enabled placements, and `knowledgePagePath` — the wiki page holding this
+brand's positioning, message hierarchy, approved verbatim lines and voice in prose. Read that page
+with `read_knowledge_pages` before writing anything. Quote its approved lines rather than
+paraphrasing them; they were worded and cleared on purpose.
+
+### 2. Pick the angle
+
+Lead with whatever the brand's own message hierarchy puts first — the job the product does end to
+end, not a secondary feature. A supporting capability is proof, not the headline.
+
+### 3. Write the headline
+
+Prefer an approved line from the Knowledge page verbatim. Otherwise write one that names something
+real and specific, not a generic claim.
+
+If the Brand Kit's `accentPhraseRequired` is true, mark exactly one phrase per headline with
+asterisks: `Every saved link, *finally usable*.` Never zero, never two — `create_creative` and
+`update_creative` refuse a headline that gets this wrong, naming the rule.
+
+Keep it short — checked at thumbnail size, not read up close.
+
+### 4. Obey the brand's copy rules
+
+Every rule in `copyRules` is data (a pattern, a message, and which fields it checks), not something
+to remember — the backend enforces it on every write and hands back the rule's own message on a
+violation, listing every rule the copy tripped. Fix the copy and retry rather than working around
+it. A kit with no rules configured is not a bug; it simply never fails a save on that account.
+
+### 5. Choose the photo and look at it
+
+Call `list_creatives`/an existing photo library read, or check what photos are already on hand
+before uploading a new one. A photo needs `checked: true` and not `blocked` before a Creative can
+go to `READY` — see the photo library's own listing for that state.
+
+A new photo goes through `upload_creative_photo` (local path or URL), which requires `source` (a
+URL or a short provenance note, e.g. "Generated with a named model on a given date") and `licence`
+(e.g. "Own work", "Unsplash Licence", "Generated, house use"). This closes a real legal exposure: an
+unattributed or unlicensed photo running as paid or organic media.
+
+**Open the photo and look at it before using it.** A picture can break every copy rule with text,
+a logo or a claim burned into its pixels, and no automated check can see that — this is the first
+of this skill's silent failure modes (the full list is below). A human or a prior pass marks a bad
+photo `blocked`; if you notice one that should be, say so rather than using it anyway.
+
+Match the crop to the subject: a layout that lays copy over the photo (e.g. `bleed`) puts a face in
+the top third in collision with the headline — prefer a layout that keeps the photo and copy on
+separate panels (e.g. `stacked`) for those.
+
+### 6. Create, then render
+
+`create_creative` with the Brand Kit (if not the default), layout, theme, photo, headline, body,
+caption and alt text. To test a headline variant of an existing concept, pass `variantOf` with that
+Creative's id instead of starting fresh — it inherits everything else and gets the next letter.
+Then call `get_creative` to verify what was actually stored.
+
+`render_creative` (previewOnly: true first, for a quick contact sheet) runs the render locally and
+returns the render id, state, frame URLs and any warnings. Then `preview_creative` to actually look
+at it — it returns the contact sheet as an image directly, not just a URL to trust.
+
+### 7. Look at the result honestly
+
+**A successful render proves the frame is structurally correct, not that the ad is good.** Its
+in-page checks catch text spilling out of a safe zone, a font that failed to load, a photo that
+never decoded, or contrast below the accessible minimum — not whether the headline reads at a
+glance, whether the accent phrase falls on the words that carry the meaning, or whether the copy is
+sitting on the subject's face. Judge those yourself from the image `preview_creative` hands back. If
+the copy collides with the photo, switch layout (see step 5) and re-render rather than shrinking
+text until it technically fits.
+
+### 8. Check readiness before calling it done
+
+`get_creative` includes a `readiness` block: caption, alt text, the photo's checked/blocked state
+and provenance, and the Creative's own state (not `DRAFT`) are blocking; an AI-generation disclosure
+is informational only. Do not call a Creative done while `ready` is false.
+
+### 9. Render for real, then hand off
+
+Once the preview looks right, `render_creative` again with `previewOnly: false` (or omitted) for the
+full-size placement frames, then `attach_creative_to_post` with the Post's Work Item id — it maps
+each placement to the right destinations (9:16 to TikTok/Reels, 4:5 to Instagram feed, 1:1 to
+Facebook, story to story targets) for every destination that has not set its own custom media, and
+never touches one that has. Verify with `get_post_status`. From here, use the `conductor-publisher`
+skill for scheduling, review and publishing — this skill's job ends at attaching the artwork.
+
+## Making a sequence instead of a single ad
+
+For a platform surface that's tapped or swiped through, set `sequenceKind` to `story` (2 to 7
+beats, aim for 3 to 5) or `carousel` (2 to 10 cards, 5 to 7 performs best) on `create_creative` or
+`update_creative`, with a `sequence` array. Each beat inherits the Creative and overrides only its
+own `headline`, and optionally `body`, `photoId` or `cta`. Structure a story hook, mechanism,
+payoff — the first beat has to earn the next tap on its own, since that's where the drop-off is
+worst. A logo lockup and CTA claim land on the last beat only by default; `cta: true` on an earlier
+beat overrides that. A carousel renders every card at one shared aspect ratio (`carouselRatio`),
+since the destination platforms require that.
+
+## Failures that are silent (carried over from this skill's predecessor)
+
+Automated checks are real but incomplete. These are the ones worth remembering to look for by eye:
+
+- **A photo with text, a logo or a claim burned into its pixels** passes every copy-rule and
+  render check, because none of them look at pixels for meaning — only step 5's "open and look at
+  it" catches this.
+- **A structurally valid render is not necessarily a good one.** The render's own assertions check
+  spill, safe zones, fonts and contrast — never whether the headline reads at a glance or the copy
+  sits on the subject's face. Step 7 exists because of this gap.
+- **A Brand Kit with no copy rules, or no accent-phrase requirement, never fails a save on that
+  account.** That is permissive by design, not a bug — but it means the model, not the platform, is
+  the only check on brand voice for that workspace until someone configures rules.
+- **A stale write is refused, not silently overwritten.** `update_creative` requires the Creative's
+  current `version`; a mismatch comes back as a 409 naming the conflict rather than clobbering a
+  concurrent edit — reread with `get_creative` and reapply, don't retry blind.
+
+## Related skills
+
+- `conductor-publisher`: schedules and tracks the Post this Creative's artwork attaches to, through
+  review and out to each destination. This skill hands off to it, never the reverse.

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

@@ -17,6 +17,10 @@ are. One instance of it is a MARKETING Post going to Instagram and TikTok; anoth
 own lifecycle that publishes somewhere else. Read the rules below as rules about the pipeline, and
 the platform names as examples.
 
+If the destination needs artwork that does not exist yet — a photo turned into on-brand ad
+creative, not just an attached file — make it first with the `conductor-creative` skill, then come
+back here with the rendered frames to attach and schedule.
+
 ## Step 1 — Gather three things, and ask rather than guess
 
 1. **The copy** — inline, or a file path you `Read`. Keep it exactly as given.

package/assets/cli-manifest.json

@@ -127,6 +127,26 @@
       "syntax": "conductor config set-url <url>",
       "description": "Update the API base URL. Use when running a self-hosted backend.",
       "category": "config"
+    },
+    {
+      "name": "creative render",
+      "syntax": "conductor creative render <creativeId>",
+      "description": "Render a Creative locally with a Playwright-driven browser to upload-ready JPEG frames, or a preview contact sheet. Prints the render id, state and frame URLs; exits non-zero on failure.",
+      "category": "marketing",
+      "options": [
+        {
+          "flag": "--preview",
+          "description": "Render a preview contact sheet instead of full-size frames"
+        },
+        {
+          "flag": "--renderer <name>",
+          "description": "Attribution tag stored on the render (default: cli)"
+        },
+        {
+          "flag": "--workflow-run-id <id>",
+          "description": "Attribute this render to a Workflow run"
+        }
+      ]
     }
   ],
   "claudeIntegration": {
@@ -168,6 +188,10 @@
       {
         "name": "conductor-publisher",
         "description": "Schedules and tracks a Post through the publishing pipeline: gathers copy, destinations and timing, checks content, creates it with create_post, reports the confirmation table, follows it through review and publishing."
+      },
+      {
+        "name": "conductor-creative",
+        "description": "Makes a Creative end to end: reads the Brand Kit and its Knowledge page, picks a photo and an angle, creates the Creative, renders and looks at the result, fixes what's wrong, then hands it to conductor-publisher."
       }
     ]
   },
@@ -667,6 +691,12 @@
       "category": "marketing",
       "requiredParams": []
     },
+    {
+      "name": "get_marketing_insights",
+      "description": "What is working across the project's published Posts: totals, engagement rate by platform, format and time, best and worst posts, and movers vs the prior window.",
+      "category": "marketing",
+      "requiredParams": []
+    },
     {
       "name": "submit_review",
       "description": "Record an approve / request_changes verdict on a Post as this API key's user (an assigned REVIEWER). Approval schedules the Post.",
@@ -689,6 +719,76 @@
       "description": "The project's best-performing published destinations ranked by one metric.",
       "category": "marketing",
       "requiredParams": []
+    },
+    {
+      "name": "get_brand_kit",
+      "description": "Read a workspace Brand Kit: colour tokens, font, logo/wordmark/badge URLs, CTA claim, copy rules, approved lines, enabled placements, and the Knowledge page path holding its prose context.",
+      "category": "marketing"
+    },
+    {
+      "name": "list_creatives",
+      "description": "List the project's Creatives (photo + headline + layout), newest display number first. Filter by state or brandKitId.",
+      "category": "marketing"
+    },
+    {
+      "name": "get_creative",
+      "description": "One Creative in full: its fields, readiness checklist, and the other lettered variants in its family.",
+      "category": "marketing",
+      "requiredParams": [
+        "creativeId"
+      ]
+    },
+    {
+      "name": "create_creative",
+      "description": "Create a Creative, or with variantOf cut a lettered variant of an existing one. Refused with the failing rule's message on a validation or readiness error.",
+      "category": "marketing"
+    },
+    {
+      "name": "update_creative",
+      "description": "Patch a Creative's fields. version must match the current value or the write is refused with a 409 conflict.",
+      "category": "marketing",
+      "requiredParams": [
+        "creativeId",
+        "version"
+      ]
+    },
+    {
+      "name": "upload_creative_photo",
+      "description": "Upload a photo into the project's photo library from a local file or a public URL, recording its provenance for the readiness checklist. Width/height are read from the file.",
+      "category": "marketing"
+    },
+    {
+      "name": "render_creative",
+      "description": "Render a Creative locally (Playwright on this machine) to upload-ready JPEG frames, or a contact sheet with previewOnly. Runs synchronously and returns the render id, state and frame URLs.",
+      "category": "marketing",
+      "requiredParams": [
+        "creativeId"
+      ]
+    },
+    {
+      "name": "preview_creative",
+      "description": "Look at a Creative: returns its latest contact sheet as an image, rendering a fresh preview first if none exists yet.",
+      "category": "marketing",
+      "requiredParams": [
+        "creativeId"
+      ]
+    },
+    {
+      "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.",
+      "category": "marketing",
+      "requiredParams": [
+        "creativeId",
+        "postId"
+      ]
+    },
+    {
+      "name": "create_experiment",
+      "description": "Start a hook experiment comparing every lettered variant of a Creative's family; settles itself once every variant has published and reported.",
+      "category": "marketing",
+      "requiredParams": [
+        "creativeId"
+      ]
     }
   ]
 }

package/dist/commands/creative.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerCreative(program: Command): void;
+//# sourceMappingURL=creative.d.ts.map

package/dist/commands/creative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creative.d.ts","sourceRoot":"","sources":["../../src/commands/creative.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAKnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiEvD"}

package/dist/commands/creative.js

@@ -0,0 +1,60 @@
+import { getConfig, resolveProject } from '../mcp/config.js';
+import { resolveCreativeId } from '../lib/creative-id.js';
+import { renderCreative } from '../lib/creative-render.js';
+export function registerCreative(program) {
+    const creative = program.command('creative').description('Render Conductor Creatives locally with Playwright');
+    creative
+        .command('render <creativeId>')
+        .description('Render a Creative to upload-ready JPEG frames (or a preview contact sheet) using a local browser')
+        .option('--preview', 'Render a preview contact sheet instead of full-size frames')
+        .option('--renderer <name>', 'Attribution tag stored on the render (default: cli)')
+        .option('--workflow-run-id <id>', 'Attribute this render to a Workflow run')
+        .addHelpText('after', `
+Examples:
+  conductor creative render 12a
+  conductor creative render 12a --preview
+  conductor creative render 12a --renderer workflow --workflow-run-id run_123`)
+        .action(async (creativeId, options) => {
+        let config;
+        try {
+            config = getConfig();
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        const resolution = resolveProject(config);
+        if (resolution.mismatch) {
+            console.error(`Refusing to act: the current directory (${process.cwd()}) is a git repository not linked to any ` +
+                'configured Conductor project. Run `conductor init` here, or set CONDUCTOR_PROJECT_ID.');
+            process.exitCode = 1;
+            return;
+        }
+        config.projectId = resolution.projectId;
+        try {
+            const result = await renderCreative({
+                creativeId: await resolveCreativeId(creativeId, config),
+                previewOnly: !!options.preview,
+                renderer: options.renderer ?? 'cli',
+                workflowRunId: options.workflowRunId,
+            }, config, (...args) => console.log(...args));
+            console.log(`render ${result.renderId ?? '(none)'}: ${result.state ?? (result.ok ? 'SUCCEEDED' : 'FAILED')}`);
+            for (const frame of result.frames) {
+                const label = frame.sequenceIndex != null ? `${frame.placementKey}[${frame.sequenceIndex}]` : frame.placementKey;
+                const size = frame.width && frame.height ? `${frame.width}x${frame.height}` : '';
+                console.log(`  ${label}  ${size}  ${frame.url ?? ''}`.trimEnd());
+            }
+            if (result.error)
+                console.error(result.error);
+            if (!result.ok || result.state === 'FAILED') {
+                process.exitCode = 1;
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=creative.js.map

package/dist/commands/creative.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"creative.js","sourceRoot":"","sources":["../../src/commands/creative.ts"],"names":[],"mappings":"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"}

package/dist/creative/assertions.js

@@ -0,0 +1,221 @@
+/* assertions.js — the in-page checks that refuse a wrong render, ported from
+ * nexus-marketing/social/export-png.mjs and made brand-agnostic: the accent
+ * check reads brand.tokens.accent (via the board's own resolved --cc-accent
+ * custom property) instead of a hardcoded Rexipe coral, and the font check
+ * reads brand.fontFamily instead of a hardcoded "DM Sans". A brand kit with
+ * neither set still gets a meaningful check — the board's actually-applied
+ * value is what is verified, not a specific brand's value.
+ *
+ * Split in two for testability:
+ *   - pure math (relativeLuminance, parseRgb, contrastRatio, spillDetect,
+ *     safeZoneIntrusion): plain data in, plain data out, no DOM. Exercised
+ *     directly with fixture rects in test/assertions.test.mjs.
+ *   - runAssertions(board, placement, brand): reads the live DOM
+ *     (getBoundingClientRect, getComputedStyle, document.fonts, Image
+ *     loading) and calls the pure functions above. Only runs in a real
+ *     browser (Playwright); this is what frame.js calls after fitBoard.
+ *
+ * These are the same checks fitBoard()'s own `fits()` helper in render.js
+ * uses to decide whether type fits (spill + the bottom safe zone) — this
+ * module reports the same two conditions as errors with a human-readable
+ * message, plus checks fits() has no opinion on: fonts loaded, images
+ * loaded (including a bleed layout's CSS background photo, invisible to a
+ * plain <img> check), headline contrast, the accent colour, and the
+ * rendered box size.
+ */
+
+/* ── pure math ─────────────────────────────────────────────────────────── */
+
+/** WCAG relative luminance of an [r, g, b] (0-255) triplet. */
+export function relativeLuminance([r, g, b]) {
+  const [R, G, B] = [r, g, b].map((v) => {
+    v /= 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * R + 0.7152 * G + 0.0722 * B;
+}
+
+/** "rgb(1, 2, 3)" / "rgba(1, 2, 3, 0.5)" -> [1, 2, 3]; anything else -> null. */
+export function parseRgb(str) {
+  // Anchored, bounded and limited to digits, dots, commas and spaces, so no input can make it backtrack.
+  const s = String(str || '').trim();
+  if (s.length > 64) return null;
+  const m = /^rgba?\(([0-9., ]+)\)$/.exec(s);
+  if (!m) return null;
+  const parts = m[1].split(',').map((s) => parseFloat(s));
+  return parts.length >= 3 && parts.slice(0, 3).every((n) => !Number.isNaN(n)) ? parts.slice(0, 3) : null;
+}
+
+/** WCAG contrast ratio between two [r, g, b] triplets, rounded to 1dp. 3:1 is
+ * the floor for large text, and every headline this engine renders is large. */
+export function contrastRatio(fgRgb, bgRgb) {
+  const l1 = relativeLuminance(fgRgb);
+  const l2 = relativeLuminance(bgRgb);
+  const ratio = (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+  return Math.round(ratio * 10) / 10;
+}
+
+/** Nodes whose box crosses the artboard's own edges — a wrapped headline or a
+ * too-tall CTA row bleeding off the visible artboard. `nodes` is
+ * `[{ name, rect: {top,bottom,right} }]`; `boardRect` is the artboard's own
+ * `{top,bottom,right}`. Returns human-readable messages, empty when clean. */
+export function spillDetect(boardRect, nodes) {
+  const issues = [];
+  for (const { name, rect } of nodes) {
+    if (rect.top < boardRect.top - 1) issues.push(`${name} over top by ${Math.round(boardRect.top - rect.top)}px`);
+    if (rect.bottom > boardRect.bottom + 1) issues.push(`${name} past bottom by ${Math.round(rect.bottom - boardRect.bottom)}px`);
+    if (rect.right > boardRect.right + 1) issues.push(`${name} past right by ${Math.round(rect.right - boardRect.right)}px`);
+  }
+  return issues;
+}
+
+/** Copy intruding on the placement's reserved bottom safe zone (where a
+ * platform's own UI — Instagram's story CTA, TikTok's caption — sits).
+ * Mirrors render.js's own `fits()` bottom check exactly, so fitting and this
+ * safety net can never disagree. Only the bottom zone is enforced: the top
+ * reserve varies far more per platform and is documented, not asserted, the
+ * same call nexus-marketing's export-png.mjs made. */
+export function safeZoneIntrusion(boardRect, nodes, safe) {
+  const issues = [];
+  const bottom = (safe && safe.bottom) || 0;
+  if (!bottom) return issues;
+  for (const { name, rect } of nodes) {
+    const over = rect.bottom - (boardRect.bottom - bottom);
+    if (over > 1) issues.push(`${name} intrudes ${Math.round(over)}px into the bottom safe zone (reserves ${bottom}px)`);
+  }
+  return issues;
+}
+
+/* ── DOM-dependent (real browser only) ────────────────────────────────────── */
+
+const CHECKED_SELECTOR = '.cc-headline, .cc-body, .cc-cta, .cc-lockup';
+
+function rectOf(node) {
+  const r = node.getBoundingClientRect();
+  return { top: r.top, bottom: r.bottom, right: r.right };
+}
+
+/* Resolves any valid CSS color string (hex, rgb(), a named color, or a
+ * var() the browser has already inlined) to an [r,g,b] triplet by letting
+ * the browser's own parser do the work via a throwaway element — the only
+ * reliable way to normalize an arbitrary brand token value. */
+function resolveCssColor(value) {
+  const probe = document.createElement('span');
+  probe.style.display = 'none';
+  probe.style.color = value;
+  document.body.appendChild(probe);
+  const rgb = parseRgb(getComputedStyle(probe).color);
+  probe.remove();
+  return rgb;
+}
+
+function sameRgb(a, b) {
+  return Boolean(a && b && a[0] === b[0] && a[1] === b[1] && a[2] === b[2]);
+}
+
+/* Runs every check against a live, fitted `.cc-board` and returns
+ * `{ errors, warnings, width, height }`. `placement` is this placement's own
+ * registry entry (pixel size, safe zone); `brand` is the same object handed
+ * to renderBoard. An empty `errors` array means the frame is safe to ship;
+ * `warnings` are non-fatal (e.g. a soft, upscaled photo). */
+export async function runAssertions(board, placement, brand) {
+  const errors = [];
+  const warnings = [];
+  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('; ')}`);
+
+  const safe = {
+    top: Number(board.dataset.safeTop) || 0,
+    bottom: Number(board.dataset.safeBottom) || 0,
+    right: Number(board.dataset.safeRight) || 0,
+  };
+  const intrusion = safeZoneIntrusion(br, nodes, safe);
+  if (intrusion.length) errors.push(`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)`);
+    }
+  }
+
+  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(', ')}`);
+
+  // 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
+  // would otherwise export a flat, photo-less board and pass everything else.
+  const bgImage = getComputedStyle(board).backgroundImage;
+  const bgUrlMatch = /url\("?(.+?)"?\)/.exec(bgImage || '');
+  if (bgUrlMatch && bgUrlMatch[1]) {
+    const probe = await new Promise((done) => {
+      const img = new Image();
+      img.onload = () => done({ ok: true, w: img.naturalWidth, h: img.naturalHeight });
+      img.onerror = () => done({ ok: false });
+      img.src = bgUrlMatch[1];
+    });
+    if (!probe.ok) {
+      errors.push(`background photo failed to load: ${bgUrlMatch[1]}`);
+    } else if (placement && probe.w < placement.w * 2 && probe.h < placement.h * 2) {
+      // Soft photography check: a source smaller than the 2x frame 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 * 2}x${placement.h * 2}`);
+    }
+  }
+
+  const headlineEl = board.querySelector('.cc-headline');
+  const em = headlineEl && headlineEl.querySelector('em');
+  if (em) {
+    const emRgb = parseRgb(getComputedStyle(em).color);
+    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');
+    } else if (expectedRgb && !sameRgb(emRgb, expectedRgb)) {
+      errors.push(`accent colour unresolved: headline em is ${getComputedStyle(em).color}, brand accent resolves to ${expectedRaw}`);
+    }
+  }
+
+  let contrast = null;
+  if (headlineEl) {
+    const fgRgb = parseRgb(getComputedStyle(headlineEl).color);
+    let bgRgb = null;
+    if (fgRgb) {
+      for (let n = headlineEl; n && n !== document.body; n = n.parentElement) {
+        const cs = getComputedStyle(n);
+        if (cs.backgroundImage && cs.backgroundImage !== 'none') {
+          const stops = (cs.backgroundImage.match(/rgba?\([^)]+\)/g) || []).map(parseRgb).filter(Boolean);
+          if (stops.length) {
+            // A scrim gradient: its darkest declared stop is the worst case.
+            bgRgb = stops.reduce((worst, c) => (relativeLuminance(c) < relativeLuminance(worst) ? c : worst));
+            break;
+          }
+        }
+        const col = cs.backgroundColor;
+        if (col && !/rgba?\(0,\s*0,\s*0,\s*0\)|transparent/.test(col)) {
+          const rgb = parseRgb(col);
+          if (rgb) { bgRgb = rgb; break; }
+        }
+      }
+    }
+    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`);
+  }
+
+  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}`);
+  }
+
+  return { errors, warnings, contrast, width, height };
+}

package/dist/creative/font.js

@@ -0,0 +1,39 @@
+/* Brand font loading shared by the editor (mount.js) and the headless render
+ * pages (frame.js, sheet.js). Browser-only; a no-op outside a document. */
+
+/* Loads `brand.fontUrl` as a <link rel="stylesheet"> (a Google Fonts URL or a
+ * self-hosted @font-face sheet both work this way) and resolves once the
+ * browser has it, or immediately if there is no fontUrl. Idempotent: calling
+ * it twice with the same URL does not insert a second <link>. Does not touch
+ * `document.fonts.ready` itself — callers that need the font *painted*, not
+ * just requested, should await that separately (mountBoard does). */
+const loadedFontUrls = new Set();
+export function loadFont(brand) {
+  const href = brand && brand.fontUrl;
+  if (!href) return Promise.resolve();
+  if (loadedFontUrls.has(href)) return Promise.resolve();
+  if (typeof document === 'undefined') return Promise.resolve();
+  const existing = Array.from(document.querySelectorAll('link[rel="stylesheet"]')).find((l) => l.href === href);
+  if (existing) {
+    loadedFontUrls.add(href);
+    return Promise.resolve();
+  }
+  return new Promise((resolve, reject) => {
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = href;
+    link.onload = () => { loadedFontUrls.add(href); resolve(); };
+    link.onerror = () => reject(new Error('failed to load font stylesheet: ' + href));
+    document.head.appendChild(link);
+  });
+}
+
+/* Loads the brand font and waits until its face is actually available, so
+ * fitting measures the real glyphs. Safe when the brand has no font. */
+export async function ensureBrandFont(brand) {
+  await loadFont(brand);
+  const family = brand && brand.fontFamily;
+  if (family && typeof document !== 'undefined' && document.fonts && document.fonts.load) {
+    await Promise.all([400, 700].map((w) => document.fonts.load(`${w} 32px "${family}"`).catch(() => [])));
+  }
+}