{
  "$schema": "../../schema.json",
  "version": "1.0.0",
  "license": "MIT",
  "id": "cursor-guide",
  "type": "shot",
  "title": "Cursor guide",
  "summary": "A cursor crosses a component on a curve, hovers the control that matters, clicks; the component answers and the camera leans in, in 5 s.",
  "tags": [
    "shot",
    "cursor",
    "click",
    "ui",
    "guide",
    "camera"
  ],
  "params": [
    {
      "name": "image",
      "type": "string",
      "default": "",
      "description": "the component (path); empty draws a placeholder UI",
      "group": "main",
      "control": "text"
    },
    {
      "name": "button",
      "type": "string",
      "default": "Render",
      "description": "the control it clicks (drawn when there is no image)",
      "group": "main",
      "control": "text"
    },
    {
      "name": "answer",
      "type": "string",
      "default": "Rendering 720 frames…",
      "description": "what the click reveals",
      "group": "main",
      "control": "text"
    },
    {
      "name": "background",
      "type": "string",
      "default": "",
      "description": "a background id from the registry; empty uses the brand's first",
      "group": "advanced",
      "control": "select"
    },
    {
      "name": "format",
      "type": "enum",
      "default": "1920x1080",
      "options": [
        "1920x1080",
        "1080x1920",
        "1080x1080"
      ],
      "description": "output size",
      "group": "main",
      "control": "segmented"
    }
  ],
  "install": {
    "kind": "scene"
  },
  "files": [
    {
      "path": "pieces/cursor-guide/scene.html",
      "content": "<!doctype html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>cursor-guide</title>\n<!--\n  Shot · cursor guide (5 s). A cursor crosses a component, hovers the thing that matters, clicks it; the component\n  answers (the button presses, a panel opens) and the camera leans in with the click.\n  Arrive 0–1.4 s · Hover 1.4–2.4 s · Click 2.4–2.8 s · Answer 2.8–5 s.\n  Look, fonts and sound come from /brand. Edit CONFIG: the component (a screenshot, or the drawn placeholder), where\n  the target sits (0–1 across, 0–1 down), the label the click reveals. Ask your agent to point it at your real UI.\n-->\n<style>\n  #stage { overflow: hidden; }\n  .abs { position: absolute; box-sizing: border-box; }\n  #comp { overflow: hidden; }\n  #comp img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; object-position: top left; }\n  .ui { position: absolute; inset: 0; display: grid; grid-template-columns: 24% 1fr; }\n  .ui .side { display: flex; flex-direction: column; gap: 6%; padding: 7% 14%; }\n  .ui i { display: block; height: 0.55em; border-radius: 999px; opacity: 0.45; }\n  .ui .main { display: flex; flex-direction: column; gap: 5%; padding: 6%; position: relative; }\n  .ui .box { border-radius: 0.6em; }\n  #target { position: absolute; display: flex; align-items: center; justify-content: center; border-radius: 0.6em; }\n  #answer { position: absolute; border-radius: 0.8em; display: flex; flex-direction: column; justify-content: center; }\n  #cursor { position: absolute; width: 0; height: 0; }\n  #cursor svg { position: absolute; left: 0; top: 0; }\n</style>\n</head>\n<body>\n<main id=\"stage\">\n  <div id=\"bg\" class=\"abs\" style=\"inset:0\"></div>\n  <div id=\"world\">\n    <div id=\"comp\"><div id=\"target\"></div><div id=\"answer\"></div><div id=\"cursor\"></div></div>\n  </div>\n</main>\n<script type=\"module\">\nimport { scene, progress, ease, spring } from 'paper-motion';\nimport { 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 shader-set id, or null for the brand's first entry\n  image: '',                             // the component (path); empty draws a placeholder UI in the brand's colors\n  target: [0.78, 0.2],                   // where the cursor goes, 0–1 across and down\n  button: 'Render',                      // the control it clicks (drawn when there is no image)\n  answer: 'Rendering 720 frames…',       // what the click reveals\n  format: [1920, 1080],\n};\n\nconst B = await loadBrand();\nconst [W, H] = CONFIG.format, SHORT = Math.min(W, H), D = 5;\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);\ndocument.querySelector('#bg').style.opacity = 0.35;\nconst $ = (id) => document.getElementById(id);\n\nconst DIST = SHORT * 0.6, K = 1 + DIST / (SHORT * 1.7);\nconst cam = camera($('stage'), $('world'), { perspective: SHORT * 1.7 });\nconst comp = $('comp'), cw = W * 0.7 * K, ch = cw * 0.6, R = (B.tokens?.shape?.radius ?? 12) * (SHORT / 1080) * K;\nObject.assign(comp.style, { width: `${cw}px`, height: `${ch}px`, borderRadius: `${R}px`, background: B.surface(0.2), border: `1.5px solid ${B.color('muted')}55`, boxShadow: `0 ${SHORT * 0.04}px ${SHORT * 0.12}px rgba(0,0,0,0.5)` });\nif (CONFIG.image) { const img = document.createElement('img'); img.src = CONFIG.image; comp.prepend(img); }\nelse {\n  const ui = document.createElement('div'); ui.className = 'ui'; ui.style.fontSize = `${cw * 0.012}px`;\n  const line = (w, c = B.color('muted')) => `<i style=\"width:${w}%;background:${c}\"></i>`;\n  const box = (h) => `<div class=\"box\" style=\"height:${h}px;background:${B.color('ground')};border:1px solid ${B.color('muted')}33\"></div>`;\n  ui.innerHTML = `<div class=\"side\" style=\"background:${B.color('ground')}\">${line(60, B.color('figure'))}${line(80)}${line(55)}${line(70)}</div><div class=\"main\">${line(30, B.color('figure'))}${box(ch * 0.3)}${box(ch * 0.22)}</div>`;\n  comp.prepend(ui);\n}\n// the target: a button where the cursor is headed\nconst [tx, ty] = CONFIG.target, target = $('target'), tw = cw * 0.14, th = ch * 0.09;\nObject.assign(target.style, { left: `${tx * cw - tw / 2}px`, top: `${ty * ch - th / 2}px`, width: `${tw}px`, height: `${th}px`, background: B.color('accent', '#E9E4D8'), color: B.color('ground'), fontFamily: B.font('text'), fontSize: `${th * 0.42}px`, fontWeight: 500 });\ntarget.textContent = CONFIG.button; if (CONFIG.image) target.style.opacity = 0;\nconst answer = $('answer'), aw = cw * 0.34, ah = ch * 0.18;\nObject.assign(answer.style, { left: `${Math.min(tx * cw - aw / 2, cw - aw - cw * 0.04)}px`, top: `${ty * ch + th / 2 + ch * 0.03}px`, width: `${aw}px`, height: `${ah}px`, padding: `${ah * 0.22}px ${aw * 0.07}px`, background: B.surface(0.16), border: `1.5px solid ${B.color('figure')}33`, boxShadow: `0 ${SHORT * 0.02}px ${SHORT * 0.06}px rgba(0,0,0,0.5)` });\nconst aText = document.createElement('div'); B.style(aText, 'body', { short: SHORT * K, color: 'figure' }); aText.textContent = CONFIG.answer; aText.style.fontSize = `${ah * 0.3}px`; answer.append(aText);\nconst bar = document.createElement('div'); Object.assign(bar.style, { marginTop: `${ah * 0.14}px`, height: `${ah * 0.08}px`, width: '100%', background: `${B.color('muted')}44`, borderRadius: '999px', overflow: 'hidden' });\nconst fill = document.createElement('div'); Object.assign(fill.style, { height: '100%', width: '0%', background: B.color('accent', '#E9E4D8') }); bar.append(fill); answer.append(bar);\n// the cursor: an arrow in the brand's figure color\nconst cursor = $('cursor'), cs = SHORT * 0.05 * K;\ncursor.innerHTML = `<svg width=\"${cs}\" height=\"${cs * 1.4}\" viewBox=\"0 0 20 28\"><path d=\"M2 2 L18 14 L10 15.5 L14.5 25 L11 26.5 L6.5 17 L2 22 Z\" fill=\"${B.color('figure')}\" stroke=\"${B.color('ground')}\" stroke-width=\"1.5\" stroke-linejoin=\"round\"/></svg>`;\ncam.place(comp, { x: 0, y: 0, z: 0, yaw: -4 });\nawait document.fonts.ready;\n\n// the path: from off the component to the button, with a human curve; the click; the answer\nconst T = { arrive: [0.2, 1.4], hover: 1.4, click: 2.4, answer: 2.8 };\nconst start = [cw * 0.1, ch * 0.95], end = [tx * cw, ty * ch];\ns.update((t) => {\n  const p = progress(t, ...T.arrive, ease.inOutCubic);\n  const bend = Math.sin(p * Math.PI) * ch * 0.12;                                      // a curved path, not a straight line\n  const settle = t >= T.hover ? Math.sin(Math.min(1, (t - T.hover) / 0.5) * Math.PI) * cw * 0.004 : 0;\n  const x = start[0] + (end[0] - start[0]) * p + settle, y = start[1] + (end[1] - start[1]) * p - bend;\n  cursor.style.transform = `translate(${x}px, ${y}px) scale(${t >= T.click && t < T.click + 0.25 ? 0.88 : 1})`;\n  cursor.style.opacity = String(progress(t, 0, 0.2));\n  // hover: the button lifts; click: it presses and the camera leans in\n  const hover = progress(t, T.hover, T.hover + 0.3, ease.outCubic), press = t >= T.click ? 1 - spring(t - T.click, { stiffness: 320, damping: 14 }) : 0;\n  target.style.transform = `translateY(${-hover * th * 0.08}px) scale(${1 + hover * 0.03 - press * 0.08})`;\n  target.style.filter = hover ? `brightness(${1 + hover * 0.08})` : 'none';\n  const lean = progress(t, T.click, T.click + 0.9, ease.outCubic);\n  cam.at({ x: (tx - 0.5) * cw * 0.5 * lean, y: (ty - 0.5) * ch * 0.5 * lean, z: DIST - SHORT * 0.24 * lean, yaw: -4 + 4 * lean, pitch: 0 });\n  // the answer opens under the button and fills\n  const open = progress(t, T.answer, T.answer + 0.5, ease.outBack);\n  answer.style.opacity = String(Math.min(1, open * 1.5)); answer.style.transform = `translateY(${(1 - open) * -ah * 0.3}px) scale(${0.9 + 0.1 * open})`;\n  fill.style.width = `${progress(t, T.answer + 0.3, D - 0.2, ease.inOutSine) * 100}%`;\n});\nB.cue(s, 'text', T.hover); B.cue(s, 'land', T.click); B.cue(s, 'transition', T.answer);\nB.sound(s);\nawait s.start();\n</script>\n</body>\n</html>\n"
    },
    {
      "path": "pieces/cursor-guide/brief.md",
      "content": "# Cursor guide\n\nShot: cursor-guide (5 s), from paper-motion.app. The look, fonts and sound come from `brand/`.\n\nA shot is one gesture. Put the real component in `CONFIG.image`, set `target` to where the control sits (0–1 across and down), name what the click reveals; check `npx paper-motion still` at 1.2, 2.5 and 4 s; render.\n"
    }
  ],
  "requires": {
    "engine": ">=0.2.6"
  },
  "usage": "npx paper-motion add cursor-guide --name my-shot\n# edit CONFIG in pieces/my-shot/scene.html, then:\nnpx paper-motion render pieces/my-shot/scene.html --motion-blur 6",
  "notes": [
    "Wired to the brand folder: needs brand/tokens.json (a palette and a font pair work) and, for the field, a shader-set entry.",
    "`target` in CONFIG places the control as 0–1 across and down the component; with a real screenshot the drawn button hides and the cursor goes there."
  ],
  "related": [
    "product-demo",
    "punch"
  ],
  "preview": {
    "video": "previews/cursor-guide.webm",
    "poster": "previews/cursor-guide.jpg",
    "at": 2.6,
    "values": {
      "button": "Render",
      "answer": "Rendering 720 frames…"
    }
  },
  "mood": [
    "technical",
    "playful",
    "minimal"
  ],
  "duration": 5,
  "formats": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "beats": [
    {
      "name": "Arrive",
      "from": 0,
      "to": 1.4,
      "what": "the cursor crosses the component on a curve"
    },
    {
      "name": "Hover",
      "from": 1.4,
      "to": 2.4,
      "what": "the control lifts under it"
    },
    {
      "name": "Click",
      "from": 2.4,
      "to": 2.8,
      "what": "it presses; the camera leans in"
    },
    {
      "name": "Answer",
      "from": 2.8,
      "to": 5,
      "what": "a panel opens and fills"
    }
  ],
  "when": [
    "showing where to click in a real UI",
    "a feature in one gesture"
  ],
  "needs": [
    {
      "kind": "action",
      "has": [
        "answer"
      ],
      "fill": {
        "image": "$image",
        "button": "$button",
        "answer": "$answer"
      }
    }
  ]
}