@cliangdev/conductor 0.26.0 → 0.27.1

package/assets/claude/skills/conductor-content-studio/references/publish-pack-template.md

@@ -0,0 +1,121 @@
+# Publish pack
+
+Two files in the run folder, written by the orchestrator in stage S5b from the scriptwriter's
+`## Publish copy` section in `script.md`, the art director's `## Publish assets` section in
+`direction.md`, and the compliance results (`compliance-checklist.md`). The pack is what the
+publisher uses later to pre-fill the Post, so it holds only what the Post needs. A run never
+creates a Post.
+
+Short-form craft this encodes: the search keyword sits in the caption's opening words, on-screen
+text and speech (TikTok search reads all three); a hook swap is the standard creative iteration;
+hook rate is 3-second plays over impressions and hold rate is completions over 3-second plays;
+posts work with the sound off.
+
+## Hook types
+
+Tag every hook, in ideas and in the pack, with one of: `question`, `bold-claim`,
+`pattern-interrupt`, `relatable-pain`, `how-to`, `number`, `curiosity-gap`, `story`,
+`social-proof`. Use another short kebab-case word only when none fits.
+
+## publish-pack.md (for people)
+
+One section per platform the brief asks for. Omit a platform it does not.
+
+```
+# Publish pack: <title>
+
+Run: <runId>   Creative: <display id, or "not yet committed">   Tags: hook <type>, angle <angle>, format <format>
+
+## <Platform> (<feed | reel | story>, as the destination's formats allow)
+- **Caption:** <final text; the search keyword is in the first line, within the first ~125
+  characters; within the platform's limit>
+- **Hashtags:** <3 to 5>
+- **First comment (post manually):** <text, or "none">. Conductor cannot post comments.
+- **Cover frame:** <video: timestamp in seconds and what is on it; carousel: card 1; still: n/a>
+- **Alt text:** <one line per image or card, in order>
+- **On-screen text placement:** <where each line sits, inside the safe zone>
+- **Sound:** <source and licence: original audio | Commercial Music Library track "<name>" |
+  library track id and its licence | clip's own sound | none>
+- **Posting window:** <best hour and weekday from get_marketing_insights byHour/byWeekday for this
+  platform, with the window it came from, or "no data yet">
+- **Options:** <the option keys and values this platform gets, from publish-pack.json>
+
+## Alternate hooks (for variantOf hook experiments)
+1. <hook line> (<hookType>)
+2. <hook line> (<hookType>)
+3. <optional>
+
+## Compliance
+<the table from compliance-checklist.md: check, answer, what was done, option set>
+
+## Third-party assets
+| Asset | Whose | Permission or licence |
+|---|---|---|
+| <music, footage, logo, meme, likeness, trademark, parody> | ... | ... |
+(Write "none" if the post uses only the brand's own and generated-by-Conductor material.)
+```
+
+## publish-pack.json (for the publisher)
+
+```json
+{
+  "creativeId": null,
+  "platforms": [
+    {
+      "platform": "tiktok",
+      "format": "feed",
+      "captionOverride": "<final caption>",
+      "options": { "brandOrganicToggle": true, "isAigc": false, "videoCoverTimestampMs": 1500 }
+    },
+    {
+      "platform": "instagram",
+      "format": "feed",
+      "captionOverride": "<final caption>",
+      "options": { "altText": "<alt text for a single feed image>" }
+    }
+  ],
+  "altText": ["<card 1 alt text>", "<card 2 alt text>"],
+  "alternateHooks": [{ "hook": "<line>", "hookType": "question" }],
+  "tags": { "hookType": "bold-claim", "angle": "utility-education", "format": "carousel" }
+}
+```
+
+Rules:
+
+- `creativeId` is null until the person approves the commit (S6, On Approve), then it is the
+  Creative's id. A `FILM` run leaves it null: the publisher is pointed at the pack by the person.
+- `platforms[]` items are shaped to drop straight into `create_post` targets or
+  `set_publish_targets` targets: `platform`, `format` (`feed`, `reel` or `story`, and only one the destination's `formats` offers: at the time
+  of writing TikTok and YouTube are feed only, Facebook and Instagram offer all three),
+  `captionOverride`, and `options`. Name `options` `publishOptions` for `set_publish_targets`. They
+  carry no account: the publisher resolves the account (`account` or `connectionId`) from
+  `list_publish_targets`. `captionOverride` is ignored on a story.
+- `captionOverride` is the **complete text that gets posted**: the caption, then a blank line, then that
+  platform's hashtags. The publisher posts it as-is, so hashtags listed only in `publish-pack.md` never
+  reach the platform. The first comment is the one thing that stays out: it is posted by hand.
+- `options` holds real option keys only, in the camelCase the destination reports under
+  `optionKeys`. Never add a key that is not in this table, and never `privacyLevel` (the person
+  picks it from the account's allowed levels at publish time):
+
+  | Platform | Keys the pack may set | Applies to |
+  |---|---|---|
+  | TikTok | `brandContentToggle`, `brandOrganicToggle` | video and photo posts |
+  | TikTok | `isAigc` | video posts only |
+  | TikTok | `videoCoverTimestampMs` (milliseconds, from the cover frame) | video posts only |
+  | TikTok | `disableComment` | video and photo posts |
+  | TikTok | `disableDuet`, `disableStitch` | video posts only |
+  | Instagram | `altText` (at most 1000 characters) | a single feed image only |
+  | Instagram | `audioName`, `shareToFeed`, `collaborators` (at most 3, not on a carousel) | reels only |
+  | YouTube | `containsSyntheticMedia` | video |
+
+  Set only what the compliance check or the plan decided: leave a key out rather than writing a
+  default. Keys that need a Post's own asset id (`coverAssetId`, `thumbnailAssetId`,
+  `photoCoverIndex`) are not known until media is attached to a Post, so the pack does not carry
+  them; the cover frame is in `publish-pack.md` for the publisher to act on.
+- `altText` is one string per image or card, in order. It is also the source for the Creative's
+  own `altText` field.
+- `alternateHooks` and `tags` are for learning and experiments, not for publishing. `tags` is also
+  copied into `run.json`.
+- `tags.angle` is the ideator's angle: `story-emotion`, `utility-education` or `trend-humor`.
+  `tags.format` is the idea's format (`still`, `carousel`, `story`, `motion`, `clip` or `film`).
+- Valid JSON, no comments.

package/assets/claude/skills/conductor-content-studio/references/rubric.md

@@ -0,0 +1,99 @@
+# Judging rubric
+
+Used by the `conductor-content-creative-director` agent in `text-round` and `visual-round`, and by
+the orchestrator when it needs to break a tie. Everything here exists to counter a known judge
+failure mode, so follow it as written.
+
+## Why it is shaped this way
+
+- LLM judges favour longer answers, the first-listed answer and the answer written in their own
+  style (Zheng et al. 2023, MT-Bench). So ideas arrive at the same length, under shuffled neutral
+  IDs, and finalists are compared in both orders.
+- A judge that scores before it reasons anchors on its first impression, and a judge asked to
+  confirm a leader mostly confirms it (Verga et al. 2024 on panels of different models). So:
+  reasoning is written first, the judge is a different model tier from the ideators, and a
+  devil's-advocate pass runs against the leader.
+- Ideas generated by one assisted process converge on the same few mechanics (Doshi & Hauser 2024),
+  and a model asked to debate itself repeats its first stance (Liang et al., degeneration of
+  thought). So novelty is scored explicitly, and the leader must be argued against.
+
+## Criteria and weights
+
+Score each 1 to 5. Weighted total = sum(score x weight) / 5, so the maximum is 100.
+
+| Criterion | Weight | 1 | 3 | 5 |
+|---|---|---|---|---|
+| Hook strength | 25 | Opens on a greeting, a logo or context; nothing makes a stranger stay | A clear promise or question, but generic; could open any account's post | A specific, surprising or tension-filled claim a stranger understands in 1s, spoken and on screen |
+| Audience relevance | 20 | Aimed at "everyone"; ignores the brief's tension | Names the audience's topic but not their actual friction | Opens on a friction the brief names and the audience would recognise as theirs |
+| Brand fit | 15 | Breaks a copy rule or approved-line, or reads off-voice | Within the rules but could be any brand | Uses an approved line or the knowledge page's voice naturally; no rule risk |
+| Feasibility with assets on hand | 15 | Needs assets that do not exist and cannot be made here (and is tagged `RENDER`) | Needs one new photo or clip the user can supply easily | Fully buildable from `media.json` or a render with no photo; or an honest `FILM` with a simple shoot |
+| Novelty | 15 | The mechanic is the most common one for this topic (listicle, "5 tips", before/after) | A familiar mechanic with a fresh angle | A mechanic not seen elsewhere in the pool or in the performance data, still easy to grasp |
+| Shareability | 10 | Nothing to send to a friend; purely informational | Useful or pleasant, but no reason to send | A person would send it to a named other person ("this is you") or save it for later |
+
+## Scoring protocol
+
+1. Read `brief.md`, then every idea in `ideas/pool.md`. Ideas are identified by ID only; ignore the
+   order they appear in and any difference in polish.
+2. For each idea, per criterion, write one or two sentences of reasoning FIRST, citing the idea's
+   own words. Then write the score. Never write a score before its reasoning.
+3. Penalise nothing for length (ideas are length-matched) and reward nothing for confident tone.
+4. Compute the weighted total. Shortlist the top 3. If ties, apply the tie-break rule below.
+5. Any idea that breaks a copy rule or contradicts an approved line is capped at 2 on brand fit
+   and cannot be a finalist unless the fix is a one-word edit you state.
+
+## Pairwise protocol (visual round)
+
+For each pair of finalists (A,B), (A,C), (B,C):
+
+1. Judge the pair twice, once with each order, as two independent comparisons. Write reasoning
+   first, then the verdict "first" or "second", then say which idea won.
+2. If the two orders name different winners (position flipped the result), the pair is a tie.
+3. Tally wins: win = 1, tie = 0.5 each. The leader has the most points.
+
+## Judging a rendered draft
+
+Look at the actual image file, not the text description. Check:
+
+- Readability at phone size: shrink it mentally to a thumbnail. Can the headline be read in a glance?
+- Hook legibility in 1 second: is the first thing seen the hook, in high contrast?
+- Safe zones: text out of the platform UI (see `platform-specs.md`), nothing sitting on a face.
+- Brand look: tokens, font, logo lockup, accent phrase on the words that carry the meaning.
+- Whether the picture and the words do different jobs (photo shows, words claim) rather than
+  repeating each other.
+
+A finalist that could not be rendered keeps its text-round score; say so, and do not treat the
+missing image as a defect of the idea, except when the failure came from copy the validator refused.
+A `FILM` finalist has no image: judge its script and shot description against the same criteria and
+note that the visual round could not test it.
+
+## Devil's-advocate pass
+
+After the tally, and before naming a winner, write the strongest case against the leader in at
+least five sentences: the likeliest way it fails with this audience, the platform risk, the
+brand risk, and what the runner-up does better. Then decide whether the case is strong enough to
+change the winner. State the answer plainly. Do not soften the case to protect the leader.
+
+### Veto questions
+
+The pass must also answer these four about the leader, each yes or no with one line of reasoning.
+They come from `compliance-checklist.md`.
+
+1. Does it rely on an **unsubstantiated claim** (nothing in the brief, knowledge or approved lines
+   confirms it)?
+2. Is there a **trademark or parody risk** (another company's product, brand, logo or likeness)?
+3. Is there a **representation or sensitivity problem**?
+4. Is **disclosure needed** (anyone paid, gifted, an employee or an affiliate) that the brief does
+   not already handle?
+
+A "yes" that a copy edit can fix is fixed or noted for the scriptwriter. A "yes" that cannot be
+fixed in copy disqualifies the idea: record it in `decision.md` under **Veto**, take the next
+leader on the tally and run the same questions on it. Disclosure that only needs a toggle and a
+caption line is not a disqualifier; note it.
+
+## Tie-break rule
+
+If two ideas are within 3 points of weighted total, or tied on the pairwise tally, prefer in order:
+1. the higher hook-strength score;
+2. the idea buildable entirely from assets on hand (`RENDER` over `FILM`);
+3. the higher novelty score;
+4. the lower ID number (an arbitrary but fixed choice, so no one can say the order was chosen).

package/assets/claude/skills/conductor-content-studio/references/script-template.md

@@ -0,0 +1,53 @@
+# Script template
+
+`script.md` for the winning idea. Short-form craft rules this encodes: the hook lands in 0 to 3
+seconds, spoken and on screen; something new happens every 3 to 5 seconds; there is a payoff, then
+a call to action; the piece works with the sound off.
+
+```
+# Script: <title>
+
+Platform: <platform(s)>   Length: <seconds>   Tag: RENDER | FILM
+Idea: <id>   Source decision: decision.md
+
+## Hook (0-3s)
+- Spoken: <line, max 12 words, or "none">
+- On screen: <text, max 12 words>
+- Visual: <what is shown>
+
+## Beats
+| # | Time | Visual | On-screen text | Spoken / audio | What changes |
+|---|------|--------|----------------|----------------|--------------|
+| 1 | 3-6s | ... | ... | ... | <the new beat or pattern interrupt> |
+| 2 | 6-10s | ... | ... | ... | ... |
+
+## Payoff
+<the line or moment that delivers the hook's promise, with time>
+
+## CTA
+<one action; use the kit's CTA claim or an approved line where there is one>
+
+## Publish copy
+Per platform the brief asks for. The keyword the audience would search for sits in the caption's
+opening words (and in the on-screen text and speech); the first line carries the hook.
+- TikTok: <caption; keep the visible part to about 150 characters>
+- Instagram: <caption; first line carries the hook, max 125 characters shown before "more">
+- YouTube Shorts: <title max 100 characters>
+- Facebook: <caption>
+- Hashtags: <3 to 5, no more>
+- First comment: <text, or "none"; posted by hand, because Conductor cannot post comments>
+- Alternate hooks (hook swaps for variantOf experiments):
+  1. <hook line> (<hookType>)
+  2. <hook line> (<hookType>)
+  3. <optional>
+
+Hook types: question, bold-claim, pattern-interrupt, relatable-pain, how-to, number,
+curiosity-gap, story, social-proof.
+
+## Copy-rule check
+<each must-say / must-avoid item from brief.md, and ok or the fix>
+```
+
+Rules: a beat every 3 to 5 seconds; no beat longer than 5 seconds without a visual or text change;
+caption limits are in `platform-specs.md`; alternates differ from the main hook in hook type, not just wording (check current platform guidance); approved lines run
+verbatim; leave out platforms the brief did not ask for.

package/assets/claude/skills/conductor-content-studio/references/shotlist-template.md

@@ -0,0 +1,44 @@
+# Shot list and direction template
+
+`direction.md` (RENDER) and `shoot/shoot-script.md` (FILM) both use this table. A RENDER direction
+has no camera, so "visual" is the layout or frame, and the final section maps the direction onto
+the Creative's own fields.
+
+```
+# Direction: <title>
+
+## Shot list
+| Time | Visual | On-screen text | VO / audio | Asset |
+|------|--------|----------------|------------|-------|
+| 0-3s | ... | ... | ... | <media id, "to film", or none> |
+
+## Safe zones
+- Keep text out of the top ~14%, the bottom ~35% and ~6% at each side (9:16; check current
+  platform guidance).
+- Headline and CTA sit in the middle band. Nothing on a face.
+
+## Sound
+<sound on or off by design; music track id if any; voice-over; captions are always on screen>
+
+## Publish assets
+Per platform the script names:
+- Cover frame: <video: timestamp in seconds and what is on it; carousel: card 1; still: n/a>
+- Alt text: <one line per image or card, in order>
+- On-screen text placement: <where each line sits, inside the safe zone for that platform>
+- Sound source and licence: <original audio | Commercial Music Library track | library track id
+  and licence | clip's own sound | none>. Never a trending track a business account cannot license.
+
+## Capture settings (FILM only)
+9:16 vertical, 1080x1920, 30 fps, sound on, lit from the front, phone steady, shoot extra B-roll.
+
+## Ready-to-paste text (FILM only)
+<on-screen text lines in order, and the captions per platform>
+
+## Mapping to the Creative (RENDER only)
+- kind: STILL | MOTION
+- layout / theme: <from the kit and registry>
+- sequenceKind: story | carousel | none   (carouselRatio for a carousel)
+- motion: preset (fade-up | word-by-word | accent-pop | none), durationSec, background (photo or
+  clip, with its motion)
+- audio: clip | track | none
+```

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

@@ -240,6 +240,10 @@ destination rewards video over an image.
    - `audio` — `source: "clip"` (the background clip's own recorded sound — the default when there
      is one), `"track"` (a separate library track: `trackId` from `upload_creative_media`, plus
      `volume` and `fadeOutSec`), or `"none"`.
+
+   A MOTION Creative is one animated frame per placement: it cannot also be a story or a carousel
+   (`sequenceKind`/`sequence`) — that is refused with a 422 (`motionNoSequence`). For several beats, make
+   one MOTION Creative per beat, or a STILL story/carousel.
 3. The preview renders three key moments across the timeline into one sheet image (not the finished
    video). Judge it the same honest way as step 7 above — does the copy's entrance finish before the
    next beat, does the end card actually hold long enough to read — and get approval before

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

@@ -172,12 +172,40 @@
       {
         "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 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": [
@@ -196,6 +224,10 @@
       {
         "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, 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."
       }
     ]
   },

package/dist/creative/assertions.js

@@ -22,6 +22,12 @@
  * 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.
+ *
+ * Presence checks (`missingPhoto`, `missingLockup`, `missingHeadline`): every check above judges what
+ * IS on the board, so a board that silently lost its photo or logo used to pass them all. The caller
+ * says what the spec requires (`expect`, see expectedElements) and a required element that is absent,
+ * collapsed or hidden fails. `bodyDropped` is the one warning in this family: a layout that has no room
+ * for the body line at a placement drops it by design, but the author supplied that copy.
  */
 
 /* ── pure math ─────────────────────────────────────────────────────────── */
@@ -86,6 +92,19 @@ export function safeZoneIntrusion(boardRect, nodes, safe) {
   return issues;
 }
 
+/** Pure: what a render requires on the board, from the resolved ad and the brand kit it renders with —
+ * `{ photo, lockup, headline }`. A photo is required when the ad has a photo URL (a clip-only background
+ * does not need one); a lockup when the kit has a mark or a wordmark (a kit without logos renders none,
+ * by design); a headline when the ad has one. Pass the result as `runAssertions`'s `expect`. */
+export function expectedElements(ad, brand) {
+  const logos = (brand && brand.logos) || {};
+  return {
+    photo: Boolean(ad && ad.photoUrl),
+    lockup: Boolean(logos.mark || logos.wordmarkLight || logos.wordmarkDark),
+    headline: Boolean(ad && ad.headline && String(ad.headline).trim()),
+  };
+}
+
 /* ── DOM-dependent (real browser only) ────────────────────────────────────── */
 
 const CHECKED_SELECTOR = '.cc-headline, .cc-body, .cc-cta, .cc-lockup';
@@ -116,9 +135,10 @@ function sameRgb(a, b) {
 /* 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, { outputScale = 2 } = {}) {
+ * to renderBoard; `expect` (optional, see expectedElements) names the elements the spec requires, so a
+ * missing one fails. An empty `errors` array means the frame is safe to ship; `warnings` are non-fatal
+ * (e.g. a soft, upscaled photo, or a body line the layout drops at this placement). */
+export async function runAssertions(board, placement, brand, { outputScale = 2, expect = null } = {}) {
   const errors = [];
   const warnings = [];
   // The same findings with a stable `rule` id each, for callers (the draft preview) that report them
@@ -128,9 +148,9 @@ export async function runAssertions(board, placement, brand, { outputScale = 2 }
     errors.push(message);
     checks.push({ rule, severity: 'error', message });
   };
-  const warn = (rule, message) => {
+  const warn = (rule, message, extra) => {
     warnings.push(message);
-    checks.push({ rule, severity: 'warning', message });
+    checks.push({ rule, severity: 'warning', message, ...extra });
   };
   const br = rectOf(board);
 
@@ -155,14 +175,44 @@ export async function runAssertions(board, placement, brand, { outputScale = 2 }
     }
   }
 
+  // ── required elements: present, sized and visible (a spec that names them must get them) ──
+  if (expect) {
+    const shown = (n) => {
+      if (!n) return false;
+      const r = n.getBoundingClientRect();
+      const cs = getComputedStyle(n);
+      return r.width > 0 && r.height > 0 && cs.display !== 'none' && cs.visibility !== 'hidden';
+    };
+    if (expect.headline) {
+      const h = board.querySelector('.cc-headline');
+      if (!h || !h.textContent.trim() || !shown(h)) fail('missingHeadline', 'the headline is missing from the rendered frame');
+    }
+    if (expect.lockup && !shown(board.querySelector('.cc-lockup:not(.cc-lockup--spacer)'))) {
+      fail('missingLockup', 'the brand logo lockup is missing from the rendered frame (the brand kit has a logo)');
+    }
+    if (expect.photo) {
+      const layer = board.querySelector('.cc-bg-photo') || board.querySelector('.cc-board__band img, .cc-board__card img');
+      const hasImage = layer && (layer.tagName === 'IMG'
+        ? Boolean(layer.getAttribute('src')) && layer.complete && layer.naturalWidth > 0
+        : /url\(/.test(getComputedStyle(layer).backgroundImage || ''));
+      if (!shown(layer) || !hasImage) fail('missingPhoto', 'the photo is missing from the rendered frame (the spec has a photo URL)');
+    }
+  }
+  if (board.dataset.bodyDropped === 'true') {
+    const layout = board.dataset.layout || 'this layout';
+    const key = board.dataset.ratio;
+    warn('bodyDropped', `the body line is not shown: the ${layout} layout drops the body at ${key}. Put the words in the headline, or pick another layout or placement.`, { placementKey: key });
+  }
+
   const imgs = [...board.querySelectorAll('img')];
   const broken = imgs.filter((i) => !i.complete || i.naturalWidth === 0).map((i) => i.getAttribute('src'));
   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
+  // A bleed layout paints its photo as a CSS background (the `.cc-bg-photo` layer), 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 photoLayer = board.querySelector('.cc-bg-photo');
+  const bgImage = getComputedStyle(photoLayer || board).backgroundImage;
   const bgUrlMatch = /url\("?(.+?)"?\)/.exec(bgImage || '');
   if (bgUrlMatch && bgUrlMatch[1]) {
     const probe = await new Promise((done) => {

package/dist/creative/font.js

@@ -37,3 +37,32 @@ export async function ensureBrandFont(brand) {
     await Promise.all([400, 700].map((w) => document.fonts.load(`${w} 32px "${family}"`).catch(() => [])));
   }
 }
+
+/* Waits until every picture under `root` has loaded: each <img> (the logo lockup, the badge, a band/card
+ * photo) AND each bleed photo layer, which is a CSS background and so is not in `document.images` — the
+ * page's `load` event does not wait for it either. Without this a screenshot (the contact sheet most of
+ * all, which never ran this wait) could be taken before the photo or logos had arrived: a board with no
+ * photo and no logo that nothing flagged. A picture that fails to load resolves anyway; it is
+ * assertions.js's job (frame.html) to report it. Browser-only; a no-op outside a document. */
+export async function settleImages(root) {
+  if (typeof document === 'undefined') return;
+  const scope = root || document;
+  const loads = [...scope.querySelectorAll('img')].map((img) => (
+    img.complete ? Promise.resolve() : new Promise((done) => {
+      img.addEventListener('load', done, { once: true });
+      img.addEventListener('error', done, { once: true });
+    })
+  ));
+  for (const layer of scope.querySelectorAll('.cc-bg-photo')) {
+    const m = /url\("?(.+?)"?\)/.exec(getComputedStyle(layer).backgroundImage || '');
+    if (!m) continue;
+    loads.push(new Promise((done) => {
+      const probe = new Image();
+      probe.onload = done;
+      probe.onerror = done;
+      probe.src = m[1];
+    }));
+  }
+  await Promise.all(loads);
+  await Promise.all([...scope.querySelectorAll('img')].map((img) => (img.decode ? img.decode().catch(() => {}) : null)));
+}

package/dist/creative/frame.css

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

package/dist/creative/frame.js

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