{
  "$schema": "../../schema.json",
  "id": "explainer",
  "type": "recipe",
  "title": "Explainer",
  "summary": "How something works in three steps on one card that changes state, with a recap and a close, in 36 s.",
  "tags": [
    "recipe",
    "explainer",
    "steps",
    "16:9"
  ],
  "version": "1.0.0",
  "license": "MIT",
  "params": [
    {
      "name": "question",
      "type": "string",
      "default": "How does it work?",
      "description": "what this answers",
      "group": "main",
      "control": "text"
    },
    {
      "name": "action",
      "type": "string",
      "default": "your.site",
      "description": "the action at the end",
      "group": "main",
      "control": "text"
    },
    {
      "name": "background",
      "type": "string",
      "default": "",
      "description": "a background id from the registry; empty uses the brand's first",
      "group": "main",
      "control": "select"
    },
    {
      "name": "format",
      "type": "enum",
      "default": "1920x1080",
      "options": [
        "1920x1080",
        "1080x1920",
        "1080x1080"
      ],
      "description": "output size",
      "group": "main",
      "control": "segmented"
    },
    {
      "name": "step1Label",
      "type": "string",
      "default": "01",
      "description": "step 1 label",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step1Title",
      "type": "string",
      "default": "First",
      "description": "step 1 title",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step1Body",
      "type": "string",
      "default": "What happens first, in one line.",
      "description": "step 1 line",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step2Label",
      "type": "string",
      "default": "02",
      "description": "step 2 label",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step2Title",
      "type": "string",
      "default": "Then",
      "description": "step 2 title",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step2Body",
      "type": "string",
      "default": "The step that does the work.",
      "description": "step 2 line",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step3Label",
      "type": "string",
      "default": "03",
      "description": "step 3 label",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step3Title",
      "type": "string",
      "default": "Done",
      "description": "step 3 title",
      "group": "advanced",
      "control": "text"
    },
    {
      "name": "step3Body",
      "type": "string",
      "default": "What you get at the end.",
      "description": "step 3 line",
      "group": "advanced",
      "control": "text"
    }
  ],
  "install": {
    "kind": "scene"
  },
  "files": [
    {
      "path": "pieces/explainer/scene.html",
      "content": "<!doctype html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>explainer</title>\n<!--\n  Recipe · explainer (36 s). How something works, in steps.\n  One idea: the steps are STATIONS on a line in space, left to right. The camera dollies along the line, leaning into\n  the direction of travel (yaw) and settling in front of each station; the previous one slides off to the side,\n  soft. The recap is the camera pulling BACK until all three stations are in frame at once; the close is a slow\n  push onto the name.\n  Question 0–3 s · Steps 3–27 s · Recap 27–32 s · Close 32–36 s.\n  Look, fonts, pace and sound come from /brand (serve from the project root). Edit CONFIG first; show real material\n  inside each step when there is some.\n-->\n<style>\n  #stage { overflow: hidden; }\n  .abs { position: absolute; box-sizing: border-box; }\n  .place { display: flex; flex-direction: column; align-items: center; text-align: center; box-sizing: border-box; }\n  .card { box-sizing: border-box; display: flex; flex-direction: column; align-items: flex-start; text-align: left; overflow: hidden; }\n</style>\n</head>\n<body>\n<main id=\"stage\">\n  <div id=\"bg\" class=\"abs\" style=\"inset:0\"></div>\n  <div id=\"vig\" class=\"abs\" style=\"inset:0\"></div>\n  <div id=\"world\">\n    <div id=\"p-q\" class=\"place\"><div id=\"question\"></div></div>\n    <div id=\"rail\"></div>\n    <div id=\"p-close\" class=\"place\"><div id=\"mark\"></div><div id=\"action\"></div></div>\n  </div>\n</main>\n<script type=\"module\">\nimport { scene, progress, ease } from 'paper-motion';\nimport { wordRise, blurIn, popIn } from 'paper-motion/moves';\nimport { camera } from 'paper-motion/kit';\nimport { loadBrand } from 'paper-motion/brand';\n\nconst CONFIG = {\n  background: null,                         // a calm shader-set id, or null for the brand's first entry\n  backgroundOpacity: 0.55,                 // the shader behind the type; 1 for a field with no words over it\n  question: 'How does it work?',            // what this answers, naming what the brand is\n  steps: [\n    { label: '01', title: 'First', body: 'What happens first, in one line.' },\n    { label: '02', title: 'Then', body: 'The step that does the work.' },\n    { label: '03', title: 'Done', body: 'What you get at the end.' },\n  ],\n  action: 'your.site',\n  format: [1920, 1080],\n};\n\nconst B = await loadBrand();\nconst [W, H] = CONFIG.format, SHORT = Math.min(W, H), D = 36;\nconst s = scene({ width: W, height: H, fps: 30, duration: D, background: B.color('ground') });\nconst bgId = CONFIG.background ?? B.set.entries.find((e) => e.shader && !e.image)?.id;\nif (bgId) B.shader(s, '#bg', bgId);\nconst bg = document.querySelector('#bg'); bg.style.opacity = CONFIG.backgroundOpacity;\ndocument.querySelector('#vig').style.background = 'radial-gradient(ellipse at 50% 55%, rgba(0,0,0,0) 30%, rgba(0,0,0,0.6) 100%)';\nconst $ = (id) => document.getElementById(id);\n\n// the line: stations STEP apart along x; the camera reads each from DIST in front; the recap sees them all from FAR\nconst STEP = SHORT * 1.25, DIST = SHORT * 0.7, FAR = SHORT * 2.35, K = 1 + DIST / (SHORT * 1.7);\nconst cam = camera($('stage'), $('world'), { perspective: SHORT * 1.7 });\nconst question = B.style($('question'), 'display', { short: SHORT * K });\nconst mark = B.style($('mark'), 'display', { short: SHORT * K }), action = B.style($('action'), 'body', { short: SHORT * K, color: 'figure' });\nObject.assign(action.style, { fontFamily: B.font('mono'), fontSize: `${SHORT * K * 0.028}px`, letterSpacing: '0em', marginTop: `${SHORT * 0.03}px` });\nquestion.textContent = CONFIG.question; mark.textContent = B.name; action.textContent = CONFIG.action;\nquestion.style.maxWidth = '16ch';\nfor (const id of ['p-q', 'p-close']) $(id).style.width = `${W * 0.9}px`;\n// a thin rail the stations stand on: the line made visible\nconst rail = $('rail');\nObject.assign(rail.style, { width: `${STEP * (CONFIG.steps.length + 1)}px`, height: '2px', background: `${B.color('muted')}66` });\ncam.place(rail, { x: STEP * (CONFIG.steps.length - 1) / 2, y: SHORT * 0.36 * K, z: -SHORT * 0.1 });\ncam.place($('p-q'), { x: -STEP, z: SHORT * 0.15, yaw: -6 });\nconst R = (B.tokens?.shape?.radius ?? 12) * (SHORT / 1080) * K;\nconst cw = SHORT * 0.92 * K, ch = cw * 0.56;\nconst steps = CONFIG.steps.map((p, i) => {\n  const c = document.createElement('div');\n  c.className = 'card';\n  const light = i === 1;\n  Object.assign(c.style, { width: `${cw}px`, height: `${ch}px`, padding: `${cw * 0.07}px`, borderRadius: `${R}px`, background: light ? B.color('accent', '#E9E4D8') : B.surface(), border: `1.5px solid ${light ? 'transparent' : B.color('muted') + '55'}`, boxShadow: `0 ${SHORT * 0.03}px ${SHORT * 0.1}px rgba(0,0,0,0.45)` });\n  c.innerHTML = `<div data-part=\"label\"></div><div data-part=\"title\"></div><div data-part=\"body\"></div>`;\n  const set = (el, role, color) => { B.style(el, role, { short: SHORT * K, color: light ? 'ground' : color }); return el; };\n  set(c.children[0], 'caption', 'muted').textContent = p.label;\n  set(c.children[1], 'display', 'figure').textContent = p.title;\n  set(c.children[2], 'body', 'muted').textContent = p.body;\n  c.children[1].style.marginTop = `${SHORT * 0.02}px`; c.children[2].style.marginTop = 'auto';\n  Object.assign(c.children[2].style, { fontSize: `${SHORT * K * 0.03}px`, lineHeight: 1.35, maxWidth: '26ch' });\n  $('world').append(c);\n  // on the line, each turned a few degrees toward where the camera comes from\n  cam.place(c, { x: STEP * i, y: [0, -SHORT * 0.03, SHORT * 0.02][i], z: [0, -SHORT * 0.05, 0][i], yaw: [-8, 0, 8][i] });\n  return c;\n});\ncam.place($('p-close'), { x: STEP * CONFIG.steps.length, z: -SHORT * 0.2 });\nawait document.fonts.ready;\nfor (const el of [question, mark]) { const k = (W * 0.84) / el.scrollWidth; if (k < 1) el.style.fontSize = `${parseFloat(el.style.fontSize) * k}px`; }\n\n// the dolly: along the line, leaning forward on the way; the recap pulls back; the close pushes in\nconst T = { s1: 3, s2: 11, s3: 19, recap: 27, close: 32 };\nconst atX = (x, extra = {}) => ({ x, z: DIST, ...extra });\nconst mid = STEP * (CONFIG.steps.length - 1) / 2;\nconst path = [\n  [0, atX(-STEP, { y: 0, yaw: -4, pitch: 0 })],\n  [T.s1 - 0.6, atX(-STEP, { yaw: -5 })],\n  [T.s1 + 1.0, atX(0, { yaw: -6 }), ease.inOutCubic],\n  [T.s1 + 1.6, atX(0, { yaw: 0 }), ease.outCubic],\n  [T.s2 - 0.6, atX(0)],\n  [T.s2 + 1.0, atX(STEP, { y: -SHORT * 0.03, yaw: -7 }), ease.inOutCubic],\n  [T.s2 + 1.6, atX(STEP, { y: -SHORT * 0.03, yaw: 0 }), ease.outCubic],\n  [T.s3 - 0.6, atX(STEP, { y: -SHORT * 0.03 })],\n  [T.s3 + 1.0, atX(STEP * 2, { y: SHORT * 0.02, yaw: -7 }), ease.inOutCubic],\n  [T.s3 + 1.6, atX(STEP * 2, { y: SHORT * 0.02, yaw: 0 }), ease.outCubic],\n  [T.recap - 0.6, atX(STEP * 2, { y: SHORT * 0.02 })],\n  [T.recap + 1.4, { x: mid, y: 0, z: FAR, yaw: 0, pitch: 0 }, ease.inOutQuart],        // pull back: all three at once\n  [T.close - 0.4, { x: mid, y: 0, z: FAR, pitch: 0 }],\n  [T.close + 1.2, { x: STEP * CONFIG.steps.length, y: 0, z: DIST * 0.95 - SHORT * 0.2, pitch: 0 }, ease.inOutQuart],\n  [D, { x: STEP * CONFIG.steps.length, z: DIST * 0.88 - SHORT * 0.2 }, ease.inOutSine],\n];\ns.update((t) => {\n  cam.travel(t, path);\n  // depth of field follows the camera; wide open for the recap so all stations read\n  const wide = progress(t, T.recap, T.recap + 1.4) * (1 - progress(t, T.close, T.close + 1.2));\n  // wide for the recap: all three stations present and sharp, the question and the close out of frame\n  cam.focus(DIST + (FAR - DIST) * wide, SHORT * (0.9 + 1.3 * wide), 10, { fade: SHORT * (0.8 + 1.3 * wide) });\n  bg.style.transform = `scale(${1.1 + 0.06 * progress(t, 0, D)}) translateX(${-SHORT * 0.08 * progress(t, 0, D)}px)`;\n  wordRise(question, t, { start: 0.3, each: B.pace.stagger, duration: 0.9 });\n  const starts = [T.s1 + 0.3, T.s2 + 0.3, T.s3 + 0.3];\n  steps.forEach((c, i) => { popIn(c.children[1], t, { start: starts[i] }); blurIn(c.children[2], t, { start: starts[i] + 0.4, duration: 0.6 }); });\n  wordRise(mark, t, { start: T.close + 0.1, each: B.pace.stagger, duration: 0.9 });\n  blurIn(action, t, { start: T.close + 0.8, duration: 0.8 });\n});\nB.cue(s, 'land', 0.3); for (const k of ['s1', 's2', 's3']) { B.cue(s, 'transition', T[k]); B.cue(s, 'land', T[k] + 1.0); }\nB.cue(s, 'transition', T.recap); B.cue(s, 'land', T.recap + 1.4); B.cue(s, 'transition', T.close); B.cue(s, 'land', T.close + 1.2);\nB.sound(s);\nawait s.start();\n</script>\n</body>\n</html>\n"
    },
    {
      "path": "pieces/explainer/brief.md",
      "content": "# Explainer\n\nRecipe: explainer (36 s), from paper-motion.app. The look, fonts, pace and sound come from `brand/`.\n\n## Before building\n- Agree the brief with the user: what the brand is in plain words, the one action at the end, the format.\n- Edit `CONFIG` at the top of scene.html: the copy, the background id, the format.\n- Swap the moves for the ones the user picked (`npx paper-motion add <id>`) and put real material where there is some.\n\n## Check and render\n- `npx paper-motion still pieces/explainer/scene.html --count 8` and look at the contact sheet.\n- `npx paper-motion render pieces/explainer/scene.html --motion-blur 5`\n"
    }
  ],
  "requires": {
    "engine": ">=0.2.0"
  },
  "usage": "npx paper-motion add explainer --name my-piece\n# edit CONFIG in pieces/my-piece/scene.html, then:\nnpx paper-motion render pieces/my-piece/scene.html --motion-blur 5",
  "notes": [
    "Wired to the brand folder: needs brand/tokens.json (a palette and a font pair work: pamo add sage-night instrument) and, for the background, a shader-set entry (pamo add mesh-sage).",
    "Structure and timing only; the look always comes from the brand.",
    "Uses these moves from the engine: push, magic-move, unfold, crossfade, word-rise, blur-in."
  ],
  "related": [
    "push",
    "magic-move",
    "unfold"
  ],
  "preview": {
    "video": "previews/explainer.webm",
    "poster": "previews/explainer.jpg",
    "at": 6,
    "values": {
      "question": "How does paper-motion work?",
      "step1Label": "01",
      "step1Title": "Interview",
      "step1Body": "Your agent asks what the brand is and what the video is for.",
      "step2Label": "02",
      "step2Title": "Boards",
      "step2Body": "It proposes options you open and choose in the browser.",
      "step3Label": "03",
      "step3Title": "Render",
      "step3Body": "It installs your choices and renders every frame.",
      "action": "paper-motion.app"
    }
  },
  "mood": [
    "technical",
    "calm",
    "editorial"
  ],
  "duration": 36,
  "formats": [
    "16:9"
  ],
  "when": [
    "how something works in steps",
    "onboarding and docs"
  ],
  "beats": [
    {
      "name": "Question",
      "from": 0,
      "to": 2.8,
      "what": "what this answers, naming the brand"
    },
    {
      "name": "Steps",
      "from": 3.6,
      "to": 26.6,
      "what": "three steps on one card that changes state"
    },
    {
      "name": "Recap",
      "from": 27.4,
      "to": 31.6,
      "what": "all steps at once, small"
    },
    {
      "name": "Close",
      "from": 32.4,
      "to": 36,
      "what": "the ending and the action"
    }
  ]
}