## Core Principles
The video narrative is independent from the input text's layout. An article / brief / set of notes is an information dump; a video is a guided act of understanding.
- Scene sequence comes from narrative design, not from the input text's paragraph order.
- A text may run `intro -> background -> detail -> detail -> caveat -> conclusion`; a video may run `hook -> question -> concept -> mechanism -> example -> takeaway`, or `setup -> tension -> turn -> resolution -> lesson`, or `promise -> step -> step -> step -> payoff`, depending on the structure.
- Reorder, merge, omit, or compress the source text as needed. Strip the asides; surface the spine. The single most common failure is paraphrasing the article in order — do not do that.
- The input text is the source of **information**, not a story template.
The planning standard: **write the emotional beat alongside the structural type**, **name the specific rhetorical / clarity technique** (do not merely write "explain the idea"), and **specify a transition for every seam**. What carries the viewer's eye from scene N to scene N+1 is part of the story itself, not something to defer to the visual phase.
## Pick the Style Preset (you choose it; it sets the whole look)
This workflow does **not** hardcode a preset. Read the input, **pick one of the 5 shipped presets**, emit it as the top-level `stylePreset` in `narrator_scripts.json`, and match the narration register to it. The deterministic design-system step runs right after you return and builds the entire visual system from your choice — so `stylePreset` is the single lever that sets the film's look. There is **no `inference.json` to read** at this phase (design-system has not run yet); your choice _is_ the register signal. Default to `pin-and-paper` when nothing clearly fits.
| `stylePreset` | Look | Pick it when the topic is… | Register |
| --------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------- |
| `pin-and-paper` | Yellow field-notebook paper, hard ink offset shadows, hairline ink — warm, handmade, considered (default) | reflective, educational, notes-like, humane — safe for almost any | warm, plain, considered; no hype |
| `block-frame` | 4px solid ink borders, hard black offset shadows, saturated pastel cycle — bold, poster-like, punchy | confident, energetic, declarative; bold claims, "loud" explainers | crisp, confident, declarative |
| `capsule` | Universal pill geometry, soft low shadows, Didone serif + grotesk — rounded, modern-editorial, friendly | approachable, lifestyle, product-adjacent, polished | friendly, polished |
| `scatterbrain` | Cork / paper with post-its, hand-placed tilt, soft paper-lift — playful, messy-desk, brainstorm | casual, fun, ideation, list-y, "my scattered notes" | light, conversational |
| `claude` | Warm cream editorial surface, hairline elevation, **ships a code-window** — literary, technical-but-human | technical / dev-ish / thoughtful longform; anything that shows code | warm, plain, considered |
The preset tunes the **voice**, not the structure: scene segmentation is driven by the input text + the structure decision below.
## Explainer Structures
Before segmenting scenes, choose **one** explainer structure (or explicitly name a compound; see "Compound structures" below). Read its `overview.md` for guidance and study its samples. Do not splice phases from different structures, because each one is a complete, coherent path through understanding.
**Concept Explainer** — "what is X, and why does it matter." Open a curiosity gap, name the core concept, build understanding one layer at a time (definition -> mechanism -> implication), land a takeaway. Best for: a single idea, term, technology, or phenomenon the audience has heard of but does not truly grasp. The concept is usually named early (after the hook) and revisited at the takeaway.
**How-To / Process** — "here is how to do X" or "here is how X works," as an ordered sequence of steps / stages. Best for: tutorials, workflows, recipes, pipelines, mechanisms with a clear start→finish. The core is a **3–6 step sequence on a consistent visual stage**, each step advancing one move. When a shared motif (the object being acted on, the position marker, the running tally) carries across several adjacent steps as one continuous shot, group those steps as a `continue` run (one worker, up to 3 scenes) and hint `morph`.
**Listicle** — "N things about X" — a hook, then N roughly co-equal items, then a wrap. Best for: tips, mistakes, features-of-a-field, reasons, comparisons where items are parallel rather than sequential. Items are usually `cut`/`slide` between (parallel, not continuous); use `morph` only when a genuine throughline element survives from one item to the next. Rule-of-three is the strongest item count when the source allows compression.
**Story Explainer** — teach through narrative: a setup, a tension or turn, a resolution, and the lesson it carries. Best for: case studies, histories, "how this came to be," cautionary tales, anything where a concrete arc makes an abstract point land. The emotional arc has real shape (calm -> tension -> turn -> relief/insight); the takeaway generalizes the story into a transferable idea.
### Choosing the structure
Read the input text once, then ask:
- **Is the payload one idea to be understood?** → concept-explainer.
- **Is the payload an ordered procedure or mechanism with steps?** → how-to-process.
- **Is the payload a set of parallel, co-equal items?** → listicle.
- **Is the payload best carried by a concrete narrative / case / history?** → story-explainer.
When the text genuinely mixes modes, name a compound (below) rather than splicing. Default tie-breakers: if the text is an argument about one concept that happens to list supporting reasons, prefer concept-explainer with a listicle inner rhythm over a bare listicle. If a process is wrapped in a story (someone learns the steps the hard way), prefer story-explainer with a how-to inner rhythm.
### Compound structures
Real explainers often _layer_ structures. Pattern:
- **Outer structure** = macro arc the viewer rides (concept / process / list / story).
- **Inner rhythm** = the tactical rhythm inside the body phase. Common inner rhythms: a **process** rhythm (ordered steps) nested inside a concept-explainer's mechanism phase; a **listicle** rhythm (parallel items) inside a concept-explainer's "why it matters" phase.
Write `narrativeArchetype` as `" with "`, e.g. `"concept-explainer with process"` or `"story-explainer with how-to"`. The downstream visual phase reads it for pacing; a process / step inner rhythm means tighter `morph` / `slide` seams on a consistent stage and shorter scenes.
> The field name is `narrativeArchetype` (schema-fixed). For FE it names the chosen explainer **structure**, not a sales archetype.
## Narrative Architecture
Define each scene's role in the explanation. Every scene has five narrative fields (type, narrativeRole, keyMessage, persuasion, emotionalBeat), plus a separate transition spec:
- **Type** — one of the enum values `hook` / `pain_point` / `product_intro` / `feature_showcase` / `benefit_highlight` / `social_proof` / `branding` / `cta`. The enum is schema-fixed (validate-narrator.mjs enforces it), so FE **repurposes** these labels for teaching rather than selling. Use the mapping table below; pick the value whose downstream pacing matches the scene's job.
- **Narrative Role** — what this scene does in the explanation (its _job_, e.g. "Concretizes compound interest as a snowball rolling downhill", not "Shows a chart").
- **Key Message** — the one thing the viewer should walk away understanding (one sentence).
- **Persuasion** — a _named_ rhetorical / clarity technique (see catalog below). "Explain the idea" / "show benefits" is a failure mode; the standard is "Analogy: tax brackets as a staircase, not a cliff" / "Progressive disclosure: reveal the formula one term at a time" / "Worked example with concrete round numbers."
- **Emotional Beat** — target feeling (see vocabulary below). One word or a short compound phrase (e.g. "Curiosity and clarity"). Avoid generic "positive" / "interested".
- **Transition** — `{ continuity, intent, description, sharedMotif? }`, defining how this scene arrives from the **previous** scene. Every scene must have one, including scene 1 (use `continuity: "break"` + `intent: "cut"`). This is a **narrative-layer judgment** (whether the seam is continuous and what kind of connection it is), not visual implementation detail (specific ease / blur / direction is translated downstream by visual-design according to preset/palette). See Transition taxonomy below.
### Type-enum repurposing (schema-fixed enum → explainer roles)
The enum values cannot change (validate-narrator.mjs enforces them; at least one scene must be `feature_showcase` or `product_intro`). Map your explainer roles onto them as follows:
| Explainer role you want | Use enum `type` | Why this value |
| -------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ |
| Hook / curiosity gap | `hook` | Same job: the high-leverage opening 3–5s. |
| Pain / problem / why-care | `pain_point` | The friction or gap the explanation resolves ("you've probably wondered…", "this keeps going wrong"). |
| Name the core concept | `product_intro` | The "introduce the protagonist" beat — here the protagonist is the **idea** being named/defined. |
| Mechanism / step / stage | `feature_showcase` | A unit of the explanation's body — one move of a process, one mechanism, one list item. |
| Implication / payoff / "so what" | `benefit_highlight` | The consequence or value of understanding — what it gets you, what now becomes possible. |
| Evidence / example / data point | `social_proof` | A concrete grounding: a real number, a worked example, a citation, a comparison that proves the point. |
| Thesis / takeaway / principle | `branding` | The _philosophical_ landing beat — the generalizable idea, the rule, the one line to remember. |
| Call to think / try / act | `cta` | The closing ask — try it, watch for it, question it, do the thing. |
Use this mapping consistently. The explainer body is usually a run of `feature_showcase` (steps/mechanisms/items) optionally interleaved with `benefit_highlight` (implications) and `social_proof` (examples/data). At least one `feature_showcase` or `product_intro` must exist (every explainer has a body and a named idea, so this is automatic).
### Hook Strategy Taxonomy
Choose one. The hook is the highest-leverage 3–5 seconds. For explainers it opens a cognitive gap or stakes:
| Strategy | When to use it | Example |
| ----------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Shocking statistic** | You have a credible data point that quantifies the stakes | "90% of plastic ever made has never been recycled." |
| **Rhetorical question** | Create an immediate cognitive gap | "Why does time seem to speed up as you get older?" |
| **Counterintuitive claim** | The truth contradicts common belief | "Adding more lanes to a highway makes traffic worse." |
| **Pain validation** | The audience already feels the confusion; say it back to them | "Everyone tells you to 'just diversify' — nobody says what that means." |
| **Visceral metaphor** | The idea is abstract and needs to become concrete / embodied | "Your attention is a spotlight, and apps are fighting over the switch." |
| **Concept announcement** | The term itself is the subject; make it memorable | "There's a word for this: the bystander effect." |
| **Direct address / character hail** | Audience is clearly defined | "If you've ever rage-quit a recipe halfway through — this is for you." |
| **Imagine / scenario** | A new perspective or thought experiment frames the whole piece | "Imagine money that loses value if you don't spend it." |
| **Stakes / consequence** | The "why care now" is a real cost or risk | "Get this one step wrong and the whole batch is ruined." |
### Rhetorical / Clarity Technique Catalog
Each scene's `persuasion` field is a _named technique_, not a vague intent. For explainers, the field carries **how this scene makes the idea land or clear** — a clarity / rhetoric mechanism, not a sales mechanism. Choose from this catalog (combine when several are active, e.g. "Analogy + progressive disclosure"):
| Family | Techniques |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Make-concrete** | Analogy / metaphor • Concretization (abstract → tangible object) • Worked example with real numbers • Anchoring on a familiar referent |
| **Reveal-in-order** | Progressive disclosure (one term/layer at a time) • Build-up (simple case → general case) • Signposting ("first… then… finally") |
| **Contrast** | Before/after contrast • Common-belief vs reality • Comparison of two options • Counterexample (here is when it breaks) |
| **Structure** | Rule of three (triplet) • Numbered enumeration • Question→answer pairing • Frame-then-fill (state the shape, then populate it) |
| **Evidence** | Statistical proof / hard metric • Citation / source attribution • Demonstration (show the mechanism running) • Causal chain (A → B → C) |
| **Memory & landing** | Callback (return to the hook's image) • Distillation (compress to one line) • Mnemonic / coined term • Generalization (specific → principle) |
When a scene's technique is not in the catalog, you may name a new one inline, but you must explain its _mechanism_ (e.g. "Subtractive framing: define the concept by what it is _not_ before saying what it is"). Do not write generic "explain the idea" / "show benefits."
### Emotional Beat Vocabulary
`emotionalBeat` should be one word or a short compound phrase (e.g. "Curiosity and clarity", "Tension and recognition"). Avoid generic "positive" / "happy" / "interested." Explainers ride a comprehension arc:
**Negative valley** — _open the gap_ (hook / pain_point scenes): curiosity • puzzlement • surprise • tension • concern • skepticism • recognition • intrigue
**Pivot** — _orient_ (product_intro / concept-naming scenes): clarity • orientation • anticipation • focus
**Build** — _build understanding_ (feature_showcase / benefit_highlight / social_proof scenes): comprehension • "aha" • confidence • fascination • foresight • momentum • conviction • delight • unease (for a caveat) • mastery
**Resolution** — _land_ (branding / cta / final beats): clarity • satisfaction • resolve • inspiration • inevitability • "now I get it"
> The structure pages (`structures/*/overview.md`) refer to these four groups by their register names — **Negative valley**, **Pivot**, **Build**, **Resolution** — so a beat-trajectory link from a structure page resolves to the matching group above.
Scenes with compound beats are often strongest, e.g. "Surprise _and_ recognition", "Comprehension _and_ delight". When two feelings are active, write both.
### Transition Taxonomy
Every scene's `transition` describes **how it arrives from the previous scene**, using two machine fields + prose + (for morph) a shared element name:
#### `continuity` — `"break"` | `"continue"` (**drives worker grouping**)
The only machine consequence of `continuity` is grouping: `prep.mjs` puts adjacent `continue` scenes into the **same scene worker** (cap=3 — a `continue` run is up to 3 scenes). The one worker that owns a run controls every DOM in it, so it authors the visual continuity across all its scenes itself and the seams read as one continuous shot.
- **`continue` = "same worker as the previous scene."** Use it for a run of 2-3 adjacent scenes that should flow as one continuous shot — a growing diagram, a persistent object, a camera that keeps moving, a counter that advances. The worker authors the flow (and any shared-element morph) directly inside one continuous visual stage.
- **`break` = a new worker** + an inter-scene Tier-B transition (`cut` / `slide` / `dissolve` / `zoom`) injected by the harness onto the clip wrappers after assembly.
- **Scene 1 is always `break`** (there is no previous scene to continue from).
> `continuity` is **decoupled from `intent`** (the old morph⟺continue biconditional was removed). `continue` no longer requires `morph`; it just means "keep these scenes on one worker for continuity." A `continue` **run is at most 3 scenes** (cap=3): `break → continue → continue` groups three scenes in one worker; a 4th consecutive scene must start a new run with a `break`. Use `continue` only where the scenes genuinely share a continuous stage — a seam that merely "feels continuous" should stay `break`. Many short runs are welcome: `run(1,2,3) → break → run(4,5) → break → 6 → 7`.
#### `intent` — 5 narrative seam intentions (**not** visual implementation)
Choose one of these 5. This is "narrative-level" vocabulary — it expresses what kind of connection the seam is, **not** blur amount / direction / duration (visual-design translates those according to preset/palette):
| Intent | Narrative meaning | Pairs with (soft hint) | Downstream translation direction (visual-design decides values) |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------- |
| `morph` | **One shared element transforms across scenes** (the shared element is open-ended: a diagram node that becomes a chart bar, a word that becomes an icon — only examples) | `continue` | worker carries a shared element across the continue run (it owns the shared visual stage) |
| `cut` | Clean switch; scenes are not continuous (topic/tone shift, new list item, high-energy beat) | **`break`** | hard cut / crossfade |
| `slide` | Directional slide / push (matches narrative flow: next step, next point) | **`break`** | push-slide (direction set by visual-design) |
| `dissolve` | Soft dissolve / focus shift (enter atmosphere, emotional transition, time passing) | **`break`** | crossfade / blur-crossfade (when colors clash) |
| `zoom` | Camera pushes / scales through to the next focal point (zoom into a detail, pull back to the big picture) | **`break`** | zoom-through |
`continuity` is **decoupled from `intent`** — `intent` is a soft hint. `morph` naturally pairs with `continue` (same worker carries the element); `cut` / `slide` / `dissolve` / `zoom` naturally pair with `break`. Nothing enforces this; choose `continuity` by whether the scenes share a continuous stage.
#### `sharedMotif` — optional hint (names the carried element)
Name the **element / motif that carries through this seam** (what morphs at the narrative layer), ≤8 words. Examples: `"the running tally"` / `"the central diagram node"` / `"the timeline marker"` / `"the key term"`. **Only name what it is; do not describe geometry/implementation** — the downstream worker uses this as the persistent subject inside the continue run. Omit this field when `intent` is not morph.
**What makes a good shared element (pass these three tests before choosing `morph`)**: do not invent a shared element just to have one; identify which element that already belongs in both scenes can connect them best.
- **Load-bearing in both scenes:** it is the visual protagonist or key information carrier in both outgoing and incoming scenes (the object the process acts on, the central diagram, the data series, the named concept's icon), **not** a decorative object inserted temporarily just to enable a morph.
- **Naturally co-present:** first ask "Is there an element that would naturally appear in both scenes?" If yes, use morph to connect it; if no, use Tier-B.
- **The transformation advances the explanation:** the element's morph must **carry** the conceptual jump (the same diagram gains a layer, the same number flows from formula into result, the same shape reorganizes from problem to solution), rather than making the explanation pause for a flashy animation.
Hint `morph` (with `continue`) when all three are true; otherwise the scenes don't share a continuous stage — use `break` + a Tier-B seam (`dissolve` / `slide`), which still reads clean.
#### `description` — 10–30 word visual direction (keep)
Concrete direction for downstream: what morphs/slides/dissolves, where the eye lands, and what color/shape guides it. For `morph`, be especially clear about the handoff point (what shape is handed to the next scene).
> **Why 5 intentions, not visual types:** the model lets scriptwriting express only **narrative intent + continuity**, leaving "which exact transition + blur/direction/duration" to visual-design, which has preset/palette context. `morph` covers shared-element continuity inside a continue run; the rest are Tier-B between-scene transitions per the table.
### Script Voice Quality Bar
Strong explainer scripts have these traits. The failure mode is reading the article aloud, or bullet-point prose.
**Strong:** _Concretization_: "Compound interest isn't addition, it's a snowball — every turn picks up the snow from the last turn, then more." — turns an abstract formula into a moving image.
**Weak:** _Article-paraphrase in order_: "The study, published in 2019, examined three cohorts and found that…" — that is reading, not explaining. Compress to the one fact that matters and lead with it.
### Empty / Silent Scripts Are Allowed
When the visual itself carries the information, set `script: ""` and keep the scene silent. This is common and good in explainers:
- A diagram assembling itself (each part appearing on beat) — the build _is_ the message; let it breathe.
- A worked-example animation (numbers flowing through a formula) — the motion teaches; narration would only narrate the obvious.
- A beat of held tension before the turn in a story-explainer — silence is the device.
If you set an empty script, `narrativeIntent` must be especially strong, because `narrativeRole` and `persuasion` must carry what the script does not say.
## The Explainer Body Is a Sequence, Not a Single Scene
An explainer's core is almost always **3–6 body scenes on a consistent visual stage**, each advancing one mechanism / step / item / layer, building understanding cumulatively (for connection rules, see the hard constraint below). The body runs `feature_showcase` / `benefit_highlight` / `product_intro` — these may interleave per the structure (a concept- or story-explainer typically goes `product_intro → feature_showcase → benefit_highlight` rather than 3 consecutive of one type); the only floor is the schema's `≥1 feature_showcase` or `product_intro`. Patterns by structure:
- **concept-explainer:** name the concept → reveal mechanism layer by layer → land implications. The body is `product_intro` then a run of `feature_showcase` (sometimes interleaved with `benefit_highlight` for "so what" beats and `social_proof` for a grounding example).
- **how-to-process:** `feature_showcase` per step, ordered, on one stage. The object being acted on is often a genuine shared motif → pair adjacent steps with `morph` where the throughline carries.
- **listicle:** `feature_showcase` per item; items are usually parallel, so default to `cut` / `slide` between them. Use `morph` only when a real element survives item→item.
- **story-explainer:** scenes follow the narrative beats (setup / tension / turn / resolution / lesson); types map per the table (`pain_point` for tension, `branding` for the lesson).
A single isolated body scene rarely teaches anything. Group adjacent scenes that share a continuous stage into a `continue` run (`continuity: "continue"`) — up to 3 scenes per run, all owned by one worker that authors the flow (and any shared-element morph) directly; **between runs, use a `break`** with a Tier-B transition (`cut` / `slide` / `dissolve` / `zoom`). A run is at most 3 scenes; a 4th consecutive scene starts a new run with a `break`. Shape: `run(s1,s2,s3) -> break -> run(s4,s5) -> break -> ...`. Use `continue` only where the scenes genuinely share a continuous stage; a parallel listicle may legitimately use `break` throughout.
Identify a body sequence by:
- Scene type is `feature_showcase`, `product_intro`, or `benefit_highlight`
- `narrativeRole` contains words such as "Defines", "Demonstrates", "Reveals", "Walks through", "Concretizes", "Builds on"
- `script` advances one mechanism / step / item / layer per scene, cumulatively
- Adjacent scenes that share a continuous stage are grouped as a `continue` run (up to 3); between runs (and across parallel items) is a `break` + Tier-B (`cut` / `slide` / `dissolve` / `zoom`)
## Faceless Visuals — assetCandidates is `[]` by Default
FE is a **faceless** explainer: there are no captured assets, no product screenshots, no asset inventory. Downstream (visual-design + scene workers) invents the visuals — typography, abstract graphics, diagrams, and data-viz — from each scene's `narrativeRole` / `keyMessage` / `script`. Both typographic/abstract treatments and diagram/data-viz treatments are first-class; downstream picks per scene by content. Your job here is the **narrative**, not the visual asset list.
Therefore:
- **`assetCandidates` is `[]` for every scene by default.** This is the normal, correct value — it tells downstream "this scene is invented from the brief."
- **The only exception:** the user explicitly provided a real image and placed it in `public/`. Then add one entry `{ "path": "public/", "description": "<≤25 words: what it is + visual notes>" }`. Do not invent paths, do not reference `capture/`, do not fabricate basenames — a path to a nonexistent file is a downstream fatal.
- Do **not** describe the intended diagram/typography here as if it were an asset. Visual intent belongs in `narrativeRole` + the transition `description`; the visual phase reads those.
## Validation Checklist
- Does every scene have complete Narrative Intent (all 5 fields)?
- Does every scene have `transition` — `continuity` (break/continue), `intent` (one of the 5, a soft hint), and `description` (10–30 words)? Is scene 1 `continuity: break`? Is every `continue` run at most 3 scenes?
- Is `assetCandidates` present on every scene as an array? Is it `[]` everywhere except where the user supplied a real `public/`?
- Does the emotional arc have meaningful variation (not monotone)? Does it match the structure (concept = gap → comprehension; story = calm → tension → insight)?
- Is the sequence driven by narrative, not by the input text's paragraph order?
- Is there a coherent body that builds cumulatively (a run of `feature_showcase` / `benefit_highlight` / `product_intro`, interleaving allowed per structure) — not a single isolated body scene? Are `continue` runs used only where scenes share a continuous stage, each run ≤3 scenes, separated by a `break`?
- Are Persuasion fields named rhetorical/clarity techniques from the catalog rather than vague "explain the idea"?
- Are Emotional beats specific (word or short compound phrase), not generic "positive"?
- Does the hook use a named strategy from the taxonomy?
- Is there only one outer structure (no splicing top-level frameworks)? Explicitly named inner-rhythm compounds are allowed.
- Is the type-enum used per the repurposing table (so the file stays schema-valid, with at least one `feature_showcase`/`product_intro`)?
- Is a top-level `stylePreset` set to one of the 5 shipped presets (`pin-and-paper` | `block-frame` | `capsule` | `scatterbrain` | `claude`)?
## `narrator_scripts.json`: Canonical Schema
Downstream agents expect these **exact** field names. Wrong names (e.g. `scene_id` instead of `sceneNumber`, `narration` instead of `script`, or flattened intent fields) are fatal in `validate-narrator.mjs`.
```json
{
"project": "Project name",
"narrativeArchetype": "Explainer structure (concept-explainer | how-to-process | listicle | story-explainer), or compound \" with \"",
"stylePreset": "One of: pin-and-paper | block-frame | capsule | scatterbrain | claude — drives the entire visual system (default pin-and-paper)",
"orientation": "Canvas aspect, echoed verbatim from the dispatch Orientation line: landscape (16:9, default) | portrait (9:16) | square (1:1). Dictated by the user's aspect, not chosen. prep maps it to group_spec.width/height. Omit → landscape.",
"emotionalArc": "Comprehension journey description (e.g. 'Puzzlement at why time speeds up shifting to clarity and a small delight as memory density explains it.')",
"scenes": [
{
"sceneNumber": 1,
"sceneName": "Scene name",
"transition": {
"continuity": "break|continue",
"intent": "morph|cut|slide|dissolve|zoom",
"sharedMotif": "Only when intent=morph: name of the element carried across scenes (<=8 words, e.g. 'the running tally'); omit this key for other intents",
"description": "10-30 word concrete visual direction explaining what morphs/slides/dissolves and where the eye should land"
},
"narrativeIntent": {
"type": "hook|pain_point|product_intro|feature_showcase|benefit_highlight|social_proof|branding|cta",
"narrativeRole": "The scene's job in the explanation (not what appears on screen)",
"keyMessage": "What the viewer should understand after this scene (one sentence)",
"persuasion": "Named rhetorical/clarity technique from the catalog (combine if multiple are active)",
"emotionalBeat": "Word or short compound phrase from the vocabulary"
},
"assetCandidates": [],
"script": "Plain-text narration. May include /// tags as authoring-time annotations (TTS strips them). Can be an empty string when visuals carry the information.",
"estimatedDuration": "5-6s"
}
]
}
```
Field rules (use exact field names above; wrong names are fatal in `validate-narrator.mjs`):
- Every scene must have a `transition` field (`continuity` + `intent` + `description`; add `sharedMotif` for morph), including scene 1 (`continuity: "break"` + `intent: "cut"`). **Scene 1 has no previous scene, so its `transition` does not generate any transition downstream (downstream ignores it) — `intent: "cut"` is just a placeholder.**
- `continuity` is **decoupled from `intent`** (a soft hint). `continue` = same worker (a run of up to 3 scenes); `break` = new worker. `validate-narrator.mjs` checks only enum membership + scene 1 = `break`.
- `assetCandidates` is a **required** field and must be an array. For FE it is `[]` on essentially every scene; only a user-provided `public/` image yields a `{path, description}` entry.
- `narrativeArchetype` names one of the four explainer structures (or a `" with "` compound). At least one scene must be `type: feature_showcase` or `product_intro`.
### Captions (not owned by scriptwriting)
Do not write a `captions: string[]` field. `///` tags inside `script` are stripped by TTS; whether you include them does not drive downstream visuals.