givemotion 0.0.0-stage → 0.1.0

package/skills/givemotion/references/styles.md

@@ -0,0 +1,133 @@
+# Styles: eight named looks
+
+Purpose: ready-made looks (palette tokens, fonts, background, motion personality) so a video is consistent from the first scene to the last. Pick one, adapt it to the brand if the brief gives colors or a logo, and stay with it.
+
+Contents
+- How to use a look
+- Fonts that work everywhere
+- 1 Midnight Tech · 2 Paper Whiteboard · 3 Editorial · 4 Bold Pop · 5 Swiss Grid · 6 Neon Night · 7 Soft SaaS · 8 Terminal
+- Choosing a look
+
+## How to use a look
+
+1. Pick the look that fits the brief (table at the end). If the brief names brand colors, keep the look's structure (background, ink, muted, one or two accents) and swap the hex values.
+2. Put the tokens on `:root` and use only them:
+   ```css
+   :root { --bg: #0b0d12; --surface: #151a23; --ink: #f2f4f8; --muted: #9aa3b2; --accent: #5b8cff; --accent-2: #38e1c7; }
+   body { background: var(--bg); color: var(--ink); }
+   ```
+3. Use the look's motion personality for every scene: the same easing family, the same transition family, the same camera behaviour. Change layouts and camera framing between scenes, not the style.
+4. Contrast: the ink and muted colors below pass 4.5:1 on their background; accents pass 3:1 or better, so use accents for big type, shapes and strokes, and ink for small text.
+
+## Fonts that work everywhere
+
+Built into the engine (no file, no network, the same on every machine, and they win over fonts installed on the machine):
+`Inter` (sans, 100-900, italic), `JetBrains Mono` (mono, 100-800, italic; ligatures are off inside `code`/`pre`), `Playfair Display`
+(display serif, 400-900, italic), `Space Grotesk` (grotesk display, 300-700), `Bebas Neue` (condensed caps, 400), `Nunito`
+(rounded, friendly, 200-1000), `Caveat` (handwriting, 400-700). Use these names first in every stack. For a brand font, put the file next to the HTML and load it with
+`@font-face`. A Google Fonts `<link>` also works (the render waits for it) but needs the network on every render.
+
+- Sans: `Inter, system-ui, sans-serif`
+- Display serif: `"Playfair Display", Georgia, serif`
+- Mono: `"JetBrains Mono", Menlo, monospace`
+- Grotesk display: `"Space Grotesk", Inter, sans-serif`
+- Condensed/impact: `"Bebas Neue", Impact, sans-serif`
+
+Your own `@font-face` with a built-in name (say a local `Inter`): **yours wins for every weight and style it declares**
+(it comes after the engine's faces). Weights or styles it does not declare still come from the built-in face of that name:
+a file declared only for 400 gives you your 400, and `font-weight: 700` or italic text uses the built-in Inter 700 / italic.
+That is fine when your file is the same font. If it is a different font, give it its own name (`font-family: 'Brand'`)
+so nothing mixes, and declare every weight you use (or one variable file with `font-weight: 100 900`).
+
+Text weight: the preset draws text with grayscale antialiasing and `text-rendering: geometricPrecision` (exact glyph
+sizes, so text that scales or zooms does not jump between sizes). It looks a little lighter than a browser or app on
+a desktop. To match a brand's own screenshots or renders, set `body { -webkit-font-smoothing: auto; text-rendering: auto; }`
+(or use the next weight up); keep the default for text the camera zooms.
+
+Numbers that change (`data-count`, clocks, scores): in natural motion a `data-count` element gets
+`font-variant-numeric: tabular-nums` (all digits as wide) unless your CSS sets `font-variant-numeric`. That matters: Inter and
+Space Grotesk digits are proportional by default (a 1 is a third narrower than an 8) and have tabular forms; JetBrains Mono,
+Bebas Neue and Caveat digits are already all as wide; Playfair Display has none (use `data-count-fixed`; classic motion keeps
+the font's default digits). The number still grows wider as digits are added
+(9 → 10 → 1,000), which moves centred text. Add `data-count-fixed` to stop all sideways movement: each digit sits in a cell as
+wide as the font's widest digit (works with any font, also ones without tabular digits like Playfair's old-style figures), and
+the box keeps the width of the longest number from the first frame, with the digits right-aligned in it (the units digit
+never moves; prefix and suffix stay put). For your own counters in `gm.onFrame`, set `font-variant-numeric: tabular-nums`.
+
+## 1 Midnight Tech
+
+For: product launches, AI/dev tools, SaaS promos, tech explainers.
+- Palette: `--bg #0b0d12` `--surface #151a23` `--ink #f2f4f8` `--muted #9aa3b2` `--accent #5b8cff` `--accent-2 #38e1c7` `--alert #ff5c7a`.
+- Type: sans, titles weight 800, `letter-spacing: -0.03em`, 120–200 px; mono for code and numbers.
+- Background: 2–3 large blurred glow blobs in the accents at 20–35% opacity (still blobs are almost free to render), fine grain, or `grid-bg` with `glow` in the accent. Screenshots tilted in 3D with a soft shadow and a 1 px light border.
+- Motion: crisp. Entrances `out-expo` 0.5–0.7 s, `mask-up` word reveals, `push-*`/`whip-*`/`zoom-through` transitions, camera push 1.06 on every scene, one burst + shake hit on the reveal.
+
+## 2 Paper Whiteboard
+
+For: whiteboard explainers, "how it works", teaching, sketch-note stories.
+- Palette: `--bg #fbfaf6` `--ink #1e1e1e` `--muted #5c5f66` `--accent #1971c2` `--accent-2 #e8590c` `--good #2f9e44` `--highlight #ffd43b` (hatch fills: `#ffd43b`, `#74c0fc`, `#ffc9c9`).
+- Type: `Caveat` 600–700 for titles and labels (≥ 48 px in world units, ≥ 40 px on screen), sans only for tiny UI text inside drawn screens.
+- Background: plain paper; optional very faint dot grid. Everything on one big world.
+- Motion: drawn, not animated: `data-sketch` shapes with `data-enter="draw"`, `write` for text, `data-sketch-mark` highlights; strokes 5–7 px; one `gm.camera` moving close from step to step, a short pull-back at the end. Easing `in-out-sine`/`in-out-cubic` for the camera, no bouncing.
+
+## 3 Editorial
+
+For: data stories, documentaries, reports, premium brands, quotes.
+- Palette: `--bg #f3eee4` (warm paper) `--ink #1b1a17` `--muted #5f5a50` `--accent #c2410c` (burnt orange) `--accent-2 #1e40af` (ink blue).
+- Type: display serif for headlines (96–180 px, weight 600–700, tight leading 0.95), sans for labels and numbers; big numbers in the serif.
+- Background: flat paper with a subtle vignette; thin rules (2–3 px) and a strict margin grid; photos in duotone or with a thin frame.
+- Motion: calm and confident. `out-quart` 0.8–1.0 s, line-by-line `mask-up` (`data-split="lines"`), `wipe-*` and `push-*` transitions, slow camera push 1.03–1.05, charts that draw with holds on the key points. No elastic or bouncy eases.
+
+## 4 Bold Pop
+
+For: vertical social clips, year recaps, celebrations, youth brands, music-driven edits.
+- Palette: `--bg #fff7e8` `--ink #1a1a2e` `--pink #e11d74` `--blue #2a6df4` `--teal #0f8a7e` `--yellow #ffd23f`. Color-blocked scenes: whole backgrounds in pink, blue or yellow (ink on yellow, white on pink and blue).
+- Type: heavy condensed or sans weight 900, UPPERCASE for short words, 140–260 px, one word per beat.
+- Background: flat color blocks, big geometric shapes (circles, stars, blobs) drifting and rotating behind the type.
+- Motion: punchy. `pop`, `drop`, `elastic`, `back.out(1.8)`, fast `cover-*`/`push-*` transitions (0.35–0.5 s) on the beat, `data-pulse="beat 0.06"` on the hero, confetti on the payoff. A change every 0.4–0.8 s.
+
+## 5 Swiss Grid
+
+For: corporate explainers, finance, architecture, B2B, clean information design.
+- Palette: `--bg #f5f5f2` `--ink #111111` `--muted #5a5a5a` `--accent #d62828` (one red) `--navy #1d3557`.
+- Type: sans (Helvetica/Inter), flush left, strong size contrast (a 200 px number next to 36 px labels), lots of alignment to a 12-column grid.
+- Background: flat; thin black rules that `grow-x`; solid red blocks as the only decoration.
+- Motion: precise and mechanical. `in-out-cubic`/`out-quart`, `wipe-*`, `grow-x`/`grow-y`, `mask-left`; transitions `wipe-left` or `push-left`; camera moves in straight lines; no overshoot.
+
+## 6 Neon Night
+
+For: gaming, music, events, hype trailers, energetic promos.
+- Palette: `--bg #07060d` `--ink #f5f3ff` `--muted #a9a3c7` `--magenta #ff2bd6` `--cyan #00e5ff` `--lime #b6ff3b`.
+- Type: wide or condensed sans weight 800–900; glow with `text-shadow: 0 0 calc(var(--px)*24) var(--magenta)`; mono for HUD details.
+- Background: dark with neon lines, a perspective grid, light streaks; grain and a vignette.
+- Motion: aggressive. Beat-cut `whip-*` and `zoom-through`, `scramble` and `steps(4)` glitches, shake on hits, `sparks` bursts, `--motion-blur 8` for the final render.
+
+## 7 Soft SaaS
+
+For: friendly app and UI demos, onboarding, consumer products, feature tours.
+- Palette: `--bg #f5f3ff` `--surface #ffffff` `--ink #1e1b4b` `--muted #5b5891` `--accent #4f46e5` `--pink #db2777` `--success #15803d`.
+- Type: sans weight 700 for titles (96–140 px), 500 for UI; rounded corners 20–28 px everywhere.
+- Background: a soft gradient (`gradient-bg` with light `c1/c2/c3` and dark ink on top) or white with large pastel blobs; cards with soft long shadows.
+- Motion: friendly. `spring`/`gentle`, `pop` for chips and toasts, `gm.fly` and `morph` to move UI between states, `cursor` with `show="auto"`, the camera gliding over the UI and pushing in on the part that changes.
+
+## 8 Terminal
+
+For: code explainers, developer tools, CLI demos, security and infra topics.
+- Palette: `--bg #0d1117` `--surface #161b22` `--ink #e6edf3` `--muted #8b949e` `--green #3fb950` `--purple #d2a8ff` `--orange #ffa657` `--blue #58a6ff`.
+- Type: mono for code and labels (code ≥ 32 px on screen), sans or mono weight 800 for titles.
+- Background: near-black with a faint grid or scanline texture; the `code-window` block restyled to these tokens.
+- Motion: `data-type` typing, `scramble` reveals, `steps()` blinking carets; the camera pushes into the line that matters while the other lines dim (`focus` on `code-window`); hand-drawn arrows (`gm.connect` with `sketch: true`) or numbered callouts for annotations.
+
+## Choosing a look
+
+| Brief | Look |
+|---|---|
+| Launch, AI tool, SaaS promo | Midnight Tech (or Soft SaaS for a consumer app) |
+| Whiteboard, "how X works" | Paper Whiteboard |
+| Data story, report, documentary | Editorial (or Midnight Tech for a startup's metrics) |
+| Vertical short, year recap, celebration | Bold Pop |
+| Corporate, finance, B2B explainer | Swiss Grid |
+| Music, gaming, event hype | Neon Night |
+| App or UI walkthrough | Soft SaaS |
+| Code explainer, CLI, devtools | Terminal |
+| Logo sting | The brand's own colors on Midnight Tech or Swiss Grid structure |

package/skills/givemotion/references/techniques/backgrounds-and-ambient.md

@@ -0,0 +1,85 @@
+# Living backgrounds and ambient motion
+Use for: every video that should never look frozen: title cards, promos, captions, holds and end cards; dark or light brands.
+
+## What makes it look premium
+- **Three depths, three speeds.** Far: 2-3 huge soft color blobs (1300 px, 7-11 s loops). Middle: a faint grid drifting one cell per 8 s. Near: 20-30 dust dots rising 12-40 px/s. Different speeds read as depth.
+- **Periods that never line up.** Blob loops of 7, 9 and 11 s (`sine.inOut`, yoyo) and 160-280 px travel, so the pattern never visibly repeats. Constant drifts (grid, dust) are `linear`; nothing else is.
+- **Quiet by default.** Blobs at 50-60% opacity on dark, 70% on light; grid 6-7%; dust 15-45% with a slow twinkle (`gm.noise`). If you notice the background before the headline, halve it.
+- **It reacts to the story.** On a scene change, blobs swing to a new layout (1.4 s `power3.inOut`, the second one 50 ms later), a thin ring pulses out (scale 0.4 → 2.2, 1.1 s `expo.out`) and the grid flashes 6% → 14% → 6%. One reaction per cut; between cuts it only drifts.
+- **Persistent across cuts.** The background lives outside the `data-sequence`, so scenes push over it and it keeps flowing: one world, not a reset per scene.
+- **Edges fade.** Mask the grid with a radial gradient so it dissolves toward the frame edges; add 4-5% film grain (`overlay` on dark, `multiply` on light) to kill banding.
+- **Cheap to render.** Soft blobs are `radial-gradient(closest-side, color, transparent)`, not `filter: blur()`; dust uses `transform` only.
+
+## Recipe
+```html
+<html data-width="1920" data-height="1080" data-fps="30">
+<style>
+  :root { --bg:#0a0c14; --ink:#f2f4f8; --c1:#5b4bff; --c2:#00b3ff; --c3:#ff3d8b; --line:#ffffff; --glow:.55; --grid:.06; }
+  body { background: var(--bg); color: var(--ink); font-family: Inter, system-ui, sans-serif; }
+  #ambient { position:absolute; inset:0; overflow:hidden; }
+  .blob { position:absolute; width:1300px; height:1300px; opacity: var(--glow); background: radial-gradient(closest-side, var(--c), transparent); }
+  #b1 { --c: var(--c1); left:-450px; top:-500px; }  #b2 { --c: var(--c2); left:1050px; top:-150px; }
+  #b3 { --c: var(--c3); left:300px; top:450px; opacity: calc(var(--glow) * .7); }
+  #grid { position:absolute; inset:-80px; opacity: var(--grid);
+          background: linear-gradient(var(--line) 1px, transparent 1px) 0 0 / 80px 80px, linear-gradient(90deg, var(--line) 1px, transparent 1px) 0 0 / 80px 80px;
+          mask-image: radial-gradient(ellipse 60% 60% at 50% 50%, #000 30%, transparent 100%); }
+  .dot { position:absolute; width:6px; height:6px; border-radius:50%; background: var(--line); }
+  #ring { position:absolute; left:960px; top:540px; width:700px; height:700px; margin:-350px; border-radius:50%; border:2px solid var(--c2); opacity:0; }
+  #grain { position:absolute; inset:0; opacity:.05; mix-blend-mode: overlay;
+           background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='200' height='200'%3E%3Cfilter id='n'%3E%3CfeTurbulence baseFrequency='.9'/%3E%3C/filter%3E%3Crect width='200' height='200' filter='url(%23n)'/%3E%3C/svg%3E"); }
+  .scene { display:grid; place-items:center; }  h1 { font-size:150px; font-weight:800; letter-spacing:-.035em; margin:0; }
+</style>
+<div id="ambient">
+  <div class="blob" id="b1"></div><div class="blob" id="b2"></div><div class="blob" id="b3"></div>
+  <div id="grid"></div><div id="dots"></div><div id="ring"></div><div id="grain"></div>
+</div>
+<main data-sequence data-transition="push-left 0.7">
+  <section class="scene" id="s1" data-duration="4" data-camera="push 1.05"><h1 data-split="words" data-enter="mask-up" data-stagger="0.07">Always moving</h1></section>
+  <section class="scene" id="s2" data-duration="4" data-camera="push 1.06, rotate -1"><div style="text-align:center">
+    <h1 data-split="words" data-enter="mask-up" data-stagger="0.07">Never loud</h1>
+    <p style="font-size:44px;opacity:.75;margin:24px 0 0" data-enter="fade-up 0.6 1.4">The background supports, the subject leads.</p></div></section>
+</main>
+<script>
+// 1. Far layer: each blob on its own loop (7/9/11 s), the grid drifts one cell per 8 s (seamless).
+[['#b1', 240, 160, 9], ['#b2', -260, 180, 11], ['#b3', 280, -150, 7]].forEach(([el, x, y, d]) =>
+  gm.to(el, { x, y, scale: 1.15, duration: d / 2, ease: 'sine.inOut', repeat: -1, yoyo: true }));
+gm.to('#grid', { x: -80, y: -80, duration: 8, ease: 'none', repeat: -1 });
+// 2. Near layer: dust rises, sways and twinkles; everything computed from t (seekable).
+const dots = Array.from({ length: 28 }, (_, i) => {
+  const d = document.createElement('i'); d.className = 'dot'; document.getElementById('dots').append(d);
+  return { d, x: gm.random('x' + i) * 1920, y: gm.random('y' + i) * 1080, v: 12 + gm.random('v' + i) * 28, s: .5 + gm.random('s' + i) };
+});
+gm.onFrame(t => dots.forEach((p, i) => {
+  p.d.style.transform = `translate(${p.x + Math.sin(t * .4 + i) * 20}px, ${gm.wrap(p.y - t * p.v, -20, 1100)}px) scale(${p.s})`;
+  p.d.style.opacity = .15 + .3 * gm.noise(t * .5 + i * 7);
+}));
+// 3. React to the cut: blobs swing to a new layout, a ring pulses out, the grid flashes.
+const cut = gm.timing('#s2').start;                    // video time the push starts
+gm.timeline()
+  .to('#b1', { xPercent: 45, yPercent: 30, duration: 1.4, ease: 'power3.inOut' }, cut)
+  .to('#b2', { xPercent: -50, yPercent: 35, duration: 1.4, ease: 'power3.inOut' }, cut + .05)
+  .fromTo('#ring', { opacity: .5, scale: .4 }, { opacity: 0, scale: 2.2, duration: 1.1, ease: 'expo.out' }, cut + .2)
+  .to('#grid', { opacity: .14, duration: .2, ease: 'power2.out' }, cut + .15)
+  .to('#grid', { opacity: .06, duration: .9, ease: 'sine.inOut' }, cut + .35);
+</script>
+```
+
+## Make it yours
+- **Light brand:** `--bg:#f5f2ec; --ink:#16181d; --c1:#ffb38a; --c2:#8ec5ff; --c3:#c7a6ff; --line:#16181d; --glow:.7; --grid:.07`, grain `mix-blend-mode: multiply`. Pastel blobs on off-white; dark ink keeps contrast.
+- **Calm / corporate:** one or two blobs, 11-15 s loops, no dust, no ring; the cut reaction is only the blob swing.
+- **Energetic / tech:** 5-7 s loops, grid 10%, dust 40-60 dots at 30-60 px/s, ring + `gm.burst(..., { kind: 'sparks', global: true, at: cut })` on the cut, blobs pulse on the beat (`data-pulse="beat 0.04"` on `#ambient`).
+- **Luxury:** near-black or ivory, one warm blob at 30%, no grid, dust 10 dots at 8 px/s, 2% grain, slow 1.8 s swings.
+
+## Variations
+- Ready-made: `<gm-include src="blocks/gradient-bg.html" c1="…" c2="…" c3="…">` or `blocks/grid-bg.html` (drift on global time, behind every scene).
+- Living blob shape: `gm.onFrame(t => path.setAttribute('d', gm.shape.blob(420, { t: t * .3 })))` on an SVG path with a gradient fill.
+- Inside a camera world, put the ambient layer next to the world with `data-parallax="0.3"` so it drifts slower than the content.
+- Brand color shift per scene: tween `--c1` at each cut, e.g. `tl.to('#b1', { '--c': '#ff7a1a', duration: 1.2 }, cut)`.
+
+## Pitfalls
+- A living background does not hide a frozen foreground: `check` still reports `still` when only the ambient layer moves for 2.5 s (1.9 s at the end). Give each scene a second beat (a subline, a counter, a camera move).
+- `filter: blur(150px)` on big layers renders slowly at 1080p and 4K; use radial gradients or a small canvas scaled up (see `blocks/gradient-bg.html`).
+- Saturated blobs behind colored text fail contrast; keep blobs mid-dark under white text and pastel under dark text, or add a soft scrim behind the headline.
+- Particles crossing the headline read as dirt: keep dust small (≤ 6 px), low opacity, or mask it out of the text area.
+- One shared loop period for everything (all 8 s) makes the frame "breathe" in sync and look mechanical; use co-prime periods.
+- The grid flash ends at a fixed `.06`; if you change `--grid`, change that number too.

package/skills/givemotion/references/techniques/camera-moves.md

@@ -0,0 +1,88 @@
+# Camera moves
+Use for: any scene that should feel filmed, not laid out: slow pushes on a title, a whip to the next idea, a push into a detail, following something that travels, an impact.
+
+## What makes it look premium
+- **Every move has a reason.** The camera pushes because something matters, follows because something moves, shakes because something hits. Start a move when its reason appears, not before.
+- **Slow push/pull: 1.04–1.10 over 2–4 s, `in-out-sine`.** It should be felt more than seen. A push that is visible as a zoom (> 1.15 in 2 s) reads as a slideshow effect.
+- **Whip pan: 0.35–0.5 s, `in-out-expo`, plus directional blur** that peaks mid-move (40–50 px along the move, 0 across it). Without blur a fast pan strobes; uniform `blur()` looks out of focus instead of fast.
+- **Push in to a detail and back out: 0.8–1 s in, hold ≥ 0.5 s, 0.6–0.8 s out** (`in-out-cubic`). Pair it with a focus pull: the rest blurs 8–12 px and dims to 30–40% while you are close.
+- **Follow with lead room and lag.** `follow` + `offset` 300–450 px ahead of the direction of travel, `lag: 0.2–0.3` so the frame trails like an operator. The subject moves with `in-out-quad`, the camera with its own lag: two curves, not one.
+- **Impact shake: 10–16 px, 0.3–0.4 s**, on the frame of the hit, with a ring (scale 0.5→2.2, opacity 0.9→0, 0.7 s `out-cubic`) and a 1.15× pop on the target. Shake alone looks like a glitch.
+- **Ambient layer.** A background outside the world with `data-parallax="0.2–0.3"` drifts less than the world, so every move shows depth.
+
+## Recipe
+One camera world, five moves in 10 s: push, whip, push-in with focus pull, follow, impact.
+```html
+<html data-width="1920" data-height="1080" data-fps="30" data-duration="10"><head><style>
+  :root { --bg: #0d1017; --ink: #f2efe8; --muted: #8a90a0; --accent: #ff6a3d; }
+  body { background: var(--bg); color: var(--ink); font-family: 'Space Grotesk', sans-serif; }
+  .glow { position: absolute; inset: -20%; background: radial-gradient(40% 35% at 30% 40%, color-mix(in oklab, var(--accent) 22%, transparent), transparent 70%); }
+  #world { position: absolute; left: 0; top: 0; width: 3400px; height: 1800px; filter: url(#whipblur); }
+  #title { position: absolute; left: 140px; top: 430px; margin: 0; font-size: 170px; line-height: .95; letter-spacing: -.04em; }
+  #title em { color: var(--accent); font-style: normal; }
+  #card { position: absolute; left: 1750px; top: 260px; width: 1000px; height: 600px; border-radius: 28px;
+    background: color-mix(in oklab, var(--ink) 6%, var(--bg)); box-shadow: 0 40px 90px -30px #000; }
+  #card .rest { position: absolute; left: 70px; top: 70px; font-size: 48px; color: var(--muted); }
+  #card .bars { position: absolute; left: 70px; bottom: 70px; display: flex; gap: 18px; align-items: end; }
+  #card .bars i { width: 48px; border-radius: 8px; background: color-mix(in oklab, var(--ink) 25%, transparent); }
+  #detail { position: absolute; right: 80px; top: 150px; font-size: 200px; font-weight: 700; color: var(--accent); }
+  #lane, #fill { position: absolute; left: 1700px; top: 1418px; width: 1600px; height: 6px; background: color-mix(in oklab, var(--ink) 18%, transparent); }
+  #fill { background: var(--accent); transform-origin: left; }
+  #dot { position: absolute; left: 1650px; top: 1371px; width: 100px; height: 100px; border-radius: 50%; background: var(--accent); box-shadow: 0 0 70px var(--accent); }
+  #goal { position: absolute; left: 3300px; top: 1421px; }
+  #goal b, #ring { position: absolute; left: -60px; top: -60px; width: 120px; height: 120px; border-radius: 50%; border: 6px solid var(--ink); }
+  #ring { border-color: var(--accent); opacity: 0; }
+  #goal span { position: absolute; left: -200px; width: 400px; top: -230px; text-align: center; font-size: 110px; font-weight: 700; }
+</style></head><body>
+<svg width="0" height="0" style="position:absolute"><filter id="whipblur" x="-10%" width="120%"><feGaussianBlur id="whipk" stdDeviation="0 0"/></filter></svg>
+<section class="scene" data-duration="10">
+  <div class="glow" data-parallax="0.25"></div>
+  <div id="world">
+    <h1 id="title">Move with<br><em>intent.</em></h1>
+    <div id="card"><div class="rest">Weekly retention</div>
+      <div class="bars"><i style="height:120px"></i><i style="height:180px"></i><i style="height:150px"></i><i style="height:240px"></i><i style="height:300px"></i></div>
+      <div id="detail">92%</div></div>
+    <div id="lane"></div><div id="fill"></div>
+    <div id="goal"><b></b><div id="ring"></div><span>Launch</span></div><div id="dot"></div>
+  </div>
+</section>
+<script>
+gm.camera('#world')
+  .shot(0,    { fit: '#title', padding: 260 })                                       // a touch wide
+  .shot(0.05, { fit: '#title', padding: 150, duration: 2.3, ease: 'in-out-sine' })   // slow push, felt not seen
+  .shot(2.4,  { fit: '#card', padding: 120, duration: 0.45, ease: 'in-out-expo' })   // whip pan
+  .shot(3.6,  { fit: '#detail', padding: 90, duration: 0.9, ease: 'in-out-cubic' })  // push in to the detail
+  .shot(5.0,  { fit: '#card', padding: 120, duration: 0.8, ease: 'in-out-cubic' })   // and back out
+  .shot(6.0,  { follow: '#dot', zoom: 1.25, offset: [420, -120], duration: 0.9, lag: 0.25 }) // lead room
+  .shake(8.55, { amount: 16, duration: 0.4 });                                       // impact on arrival
+const k = document.getElementById('whipk');   // horizontal-only blur, peaks mid-whip (2.4 → 2.85)
+gm.onFrame(t => k.setAttribute('stdDeviation', gm.interpolate(t, [2.4, 2.6, 2.85], [0, 46, 0]) + ' 0'));
+gm.timeline('#world')
+  .to('#card .rest, #card .bars', { filter: 'blur(10px)', opacity: 0.35, duration: 0.7 }, 3.7)   // focus pull
+  .to('#card .rest, #card .bars', { filter: 'blur(0px)', opacity: 1, duration: 0.6 }, 5.0)
+  .to('#dot', { x: 1600, duration: 2.4, ease: 'in-out-quad' }, 6.15)                // the subject motivates the move
+  .fromTo('#fill', { scaleX: 0 }, { scaleX: 1, duration: 2.4, ease: 'in-out-quad' }, 6.15)
+  .fromTo('#ring', { opacity: 0.9, scale: 0.5 }, { opacity: 0, scale: 2.2, duration: 0.7, ease: 'out-cubic' }, 8.55)
+  .fromTo('#goal span', { scale: 1 }, { keyframes: [{ scale: 1.15, duration: 0.12 }, { scale: 1, duration: 0.4, ease: 'out-back' }] }, 8.55);
+</script></body></html>
+```
+
+## Make it yours
+- **Calm / corporate:** pushes 1.04 over 3–4 s, no whip (use a 1.2 s `in-out-cubic` move), no shake, `float 8` while holding.
+- **Energetic / punchy:** whips 0.3 s with 50–60 px blur, push-ins 0.5 s `expo.out`, shake 16–20 px on every hit, `handheld 6` between moves.
+- **Luxury:** very slow (push 1.03 over 5 s), long focus pulls (1–1.2 s, 14 px blur), no shake, slight `rotate: -2` on a shot.
+- **Playful:** overshooting arrivals (leave the shot's default overshoot on), bank 3–5° into whips.
+
+## Variations
+- Bank/rotate into a move: `.shot(4, { fit: '#b', rotate: -4, duration: 0.8 })`, then `rotate: 0` on the next shot.
+- No world needed: `data-camera="push 1.06, float"` on a scene; `"pull 1.08"` for a reveal; `"handheld 6"` for documentary.
+- Impact without a world: `data-camera="shake 14 2.1-2.5"` (window in seconds of the clip).
+- Vertical whip: blur `'0 46'` instead of `46 + ' 0'`, and arrange the world top to bottom.
+
+## Pitfalls
+- **Whip without blur** strobes (the text jumps 300+ px per frame). Add the SVG directional blur; a uniform `filter: blur()` reads as defocus.
+- **Moves with no reason** (a push on nothing, a pan across empty space) look like a screensaver. Keep subjects close in the world; check the mid-whip frame with `snapshot --every 0.1 --from A --to B`.
+- **Push-in that cuts its neighbour:** a label half in frame reads as a mistake. Fit the detail with its label, or blur/dim the rest.
+- **`camera-stop` note** after a push-in hold is fine when the hold is meant (≥ 0.5 s, as here); chain shots back-to-back when it is not.
+- **Shake on calm brands** or on every beat cheapens it; one or two hits per video.
+- `filter: url(#…)` on a very large world costs render time; turn the blur to `0 0` outside whips (the interpolate above does).

package/skills/givemotion/references/techniques/captions-vertical.md

@@ -0,0 +1,89 @@
+# Word-by-word captions and vertical clips
+Use for: TikTok/Reels/Shorts, voice-over clips, any brief with word-timed captions, a hook title, or "subtitles that pop".
+
+## What makes it look premium
+- **Phrases, not sentences.** 1-3 words per caption, broken at pauses > 0.3 s and after `. ! ? ,`. 92 px, weight 850, centered; never more than ~6 words on screen.
+- **Each word pops 60 ms before it is spoken** (y 36 → 0, scale 0.7 → 1, 0.28 s `back.out(2.2)`). Exactly on the timestamp reads late; 60 ms early reads in sync.
+- **One highlight pill per phrase that slides** to the spoken word (0.12 s `power3.out`, starting 0.1 s early), not a box per word fading on and off (two half-boxes at once look muddy). The spoken word turns dark on the pill and scales 1.06; it hands back over 0.06 s.
+- **Fast exits.** The phrase leaves 0.14 s `power2.in` upward, 0.16 s before the next one. Two phrases never share the screen.
+- **Hook on frame 0.** The title is visible at frame 0 (it is the thumbnail), lands by 0.5 s, then steps back (scale 0.86, 0.6 s `power3.inOut`) to hand focus to the captions.
+- **The background answers the voice.** On each phrase change the big glow jumps (0.9 s `power3.out`) and the hue turns 25°. The beat is felt without anything new to read.
+- **Layers:** a slow camera on the whole frame (`push 1.04, float 10`), a second glow breathing (2.4 s `sine.inOut` yoyo), soft text-shadow on idle words.
+- **Safe zones (1080×1920):** keep key text out of the top 220 px and bottom 380 px, and 60 px in from the sides. Hook at y ≈ 300, captions at y ≈ 1180; the middle band is for the subject.
+
+## Recipe
+```html
+<html data-width="1080" data-height="1920" data-fps="30" data-duration="5" data-safe-zone="shorts">
+<style>
+  :root { --bg:#0d0f1a; --ink:#f4f5fa; --accent:#ffd23f; --accent-2:#6d5dfc; --font: Inter, system-ui, sans-serif; }
+  body { background: var(--bg); color: var(--ink); font-family: var(--font); overflow: hidden; }
+  .glow { position:absolute; width:1300px; height:1300px; background: radial-gradient(closest-side, var(--c), transparent); }
+  #g1 { --c: var(--accent-2); left:-500px; top:0; opacity:.6; }  #g2 { --c: var(--accent); left:300px; top:900px; opacity:.22; }
+  #hook { position:absolute; left:90px; right:90px; top:300px; margin:0; font-size:128px; font-weight:900; line-height:.95;
+          letter-spacing:-.04em; text-transform:uppercase; transform-origin:0 0; }
+  #hook .w { display:inline-block; }  #hook em { font-style:normal; color: var(--accent); }
+  .cap { position:absolute; left:70px; right:70px; top:1180px; text-align:center; isolation:isolate;
+         font-size:92px; font-weight:850; line-height:1.1; letter-spacing:-.02em; }
+  .cap .w { display:inline-block; padding:0 .14em; --hl:0;               /* --hl: 0 idle, 1 spoken */
+            color: color-mix(in oklab, var(--bg) calc(var(--hl) * 100%), var(--ink));
+            text-shadow: 0 6px 24px rgb(0 0 0 / calc(.5 - var(--hl) * .5)); }
+  .pill { position:absolute; left:0; top:.02em; height:1.06em; border-radius:.2em; z-index:-1; background: var(--accent);
+          box-shadow: 0 10px 40px color-mix(in oklab, var(--accent) 45%, transparent); }
+</style>
+<main class="scene" data-camera="push 1.04, float 10">
+  <div id="bg"><div class="glow" id="g1"></div><div class="glow" id="g2"></div></div>
+  <h1 id="hook"><span class="w">Stop</span> <span class="w">editing</span> <span class="w"><em>by&nbsp;hand</em></span></h1>
+  <div id="caps"></div>
+</main>
+<script>
+const words = [['Your',.5,.7],['video',.7,1],['is',1,1.1],['just',1.1,1.35],['HTML.',1.35,1.9],['Write',2.3,2.55],
+  ['it',2.55,2.65],['once,',2.65,3.1],['render',3.25,3.6],['anywhere.',3.6,4.3]].map(([text, start, end]) => ({ text, start, end }));
+const phrases = [[]];                       // 1. break on a pause > 0.3 s, after . ! ? , or at 3 words
+words.forEach((w, i) => { const cur = phrases.at(-1), prev = words[i - 1];
+  if (cur.length && (cur.length === 3 || w.start - prev.end > .3 || /[.!?,]$/.test(prev.text))) phrases.push([]);
+  phrases.at(-1).push(w); });
+const tl = gm.timeline();
+// 2. Hook: visible at frame 0 and already moving, then it steps back.
+tl.from('#hook .w', { y: 70, scale: 1.25, opacity: .35, filter: 'blur(10px)', duration: .5, ease: 'expo.out', stagger: .06 }, 0)
+  .to('#hook', { scale: .86, y: -40, duration: .6, ease: 'power3.inOut' }, .45);
+const caps = phrases.map(ph => { const el = document.createElement('div'); el.className = 'cap';
+  el.innerHTML = '<i class="pill"></i>' + ph.map(w => `<span class="w">${w.text}</span>`).join(' ');
+  document.getElementById('caps').append(el); return el; });
+gm.wait(document.fonts.ready.then(() => phrases.forEach((ph, p) => {   // measure words once fonts are in
+  const el = caps[p], spans = el.querySelectorAll('.w'), pill = el.querySelector('.pill'), next = phrases[p + 1];
+  const box = i => ({ x: spans[i].offsetLeft, width: spans[i].offsetWidth });
+  tl.fromTo(pill, { ...box(0), scale: .5, opacity: 0 }, { scale: 1, opacity: 1, duration: .22, ease: 'back.out(2)' }, ph[0].start - .04);
+  ph.forEach((w, i) => {
+    tl.fromTo(spans[i], { opacity: 0, y: 36, scale: .7 }, { opacity: 1, y: 0, scale: 1, duration: .28, ease: 'back.out(2.2)' }, w.start - .06);
+    if (i) tl.to(pill, { ...box(i), duration: .12, ease: 'power3.out' }, w.start - .1);      // 3. pill slides
+    tl.to(spans[i], { '--hl': 1, scale: 1.06, duration: .06 }, w.start - .03)                 // 4. spoken word
+      .to(spans[i], { '--hl': 0, scale: 1, duration: .06 }, ph[i + 1] ? ph[i + 1].start - .1 : w.end + .3);
+  });
+  if (!next) tl.to(pill, { opacity: 0, scale: .9, duration: .2, ease: 'power2.in' }, ph.at(-1).end + .3);
+  else tl.to(el, { y: -50, opacity: 0, duration: .14, ease: 'power2.in' }, next[0].start - .16);   // 5. fast exit
+  tl.to('#g1', { x: gm.random('x' + p) * 500 - 150, y: gm.random('y' + p) * 600 - 300, duration: .9, ease: 'power3.out' }, ph[0].start - .1)
+    .to('#bg', { filter: `hue-rotate(${p * 25}deg)`, duration: .6, ease: 'sine.inOut' }, ph[0].start - .1);  // 6. bg reacts
+})));
+gm.to('#g2', { scale: 1.25, duration: 2.4, ease: 'sine.inOut', repeat: -1, yoyo: true });            // 7. ambient
+</script>
+```
+Real timestamps: load a whisper-style JSON with `gm.wait(fetch('words.json').then(r => r.json()).then(build))` and build the same timeline inside.
+
+## Make it yours
+- **Calm / corporate:** no overshoot (`power3.out`), 0.35 s pops, pill as an underline (`height: .12em; top: 1em`), hue turn 0, Inter 700 mixed case.
+- **Energetic / punchy:** `back.out(3)`, pop from scale 0.4 with rotate ±6°, 1-2 words per phrase, `text-transform: uppercase`, hue turn 40°, add a `shake 8 2.1-2.4` (window around the key word) to the `data-camera` list.
+- **Playful:** a pill color per phrase (`gm.pick(['#ffd23f','#5ef2c2','#ff7ab6'], 'c' + p)`), `bouncy` ease, rotate the pill ±3°.
+- **Luxury:** no pill; the spoken word goes from 40% to 100% opacity, `"Playfair Display"` 80 px, slower 0.45 s rises, `sine.out`.
+
+## Variations
+- **Captions only, no code:** `<gm-include src="blocks/captions.html" file="captions.json" words="3">` (pages and highlights for you; less control).
+- **Phrase lands as one unit** (fast talkers, > 3.5 words/s): pop the whole `.cap` and only slide the pill per word.
+- **Keyword emphasis:** for words in a set, `tl.to(span, { scale: 1.3, rotate: -4, duration: .2, ease: 'back.out(3)' }, w.start)` and fire `gm.burst(..., { kind: 'sparks', global: true, at: w.start })`.
+- **Line that re-centres as it grows:** the word-grow pattern in `references/motion-design.md` §6.
+
+## Pitfalls
+- `phrases[p + 1]` is an array: use `next[0].start`. A wrong time silently leaves old phrases on screen (`text-overlap` everywhere).
+- Measuring `offsetLeft` before fonts load puts the pill in the wrong place: measure inside `gm.wait(document.fonts.ready…)`.
+- Captions over the subject or in the bottom 380 px: `check` warns `unsafe-zone` with `data-safe-zone="shorts"`; keep the caption band at y 1100-1400.
+- A `filter: blur(140px)` glow on a 1080×1920 frame is slow to render; a `radial-gradient(closest-side, …)` looks the same and costs almost nothing.
+- Words that pop in place leave a one-word phrase off-centre for a moment; that is fine for 1-3 words. For longer phrases use the re-centring variation.

package/skills/givemotion/references/techniques/code-on-screen.md

@@ -0,0 +1,125 @@
+# Code on screen
+Use for: code explainers and dev-tool videos: code types into an editor, the key line is singled out, a diagram shows what it does.
+
+## What makes it look premium
+- **Big, readable code.** 34 px JetBrains Mono, line-height 1.62, 8–12 lines, in an editor window with a tab bar and dim line numbers (60% of `--mute`). Never shrink the window to fit; let the camera frame it.
+- **Typing with a human rhythm, not a constant ticker:** ~90 chars/s with ±45% seeded jitter per char, +50 ms after `( { ;`, +100 ms at each line end, auto-indent appears at once. A 3 px accent caret blinks and rides the last char; it leaves when explaining starts. 10 lines take ~3.5 s.
+- **The camera pushes while it types** (`zoom: 1.1` over 3.4 s, `in-out-sine`), so the frame is never still.
+- **Single out one line in three layers (0.5 s):** a highlight bar sweeps in from the left (`scaleX` 0→1, `power3.out`, 16% accent + 5 px accent edge), the other lines dim to 28% rippling outward from it (20 ms stagger `from` that line), then the key token turns accent 0.5 s later.
+- **Zoom on the characters, not the line box.** `fit: '.ln[data-n="6"] i'` frames the text itself (a block line is full width, so fitting it barely zooms). ~2.5× here: code reads at ~85 px.
+- **The diagram is in the same world**, to the right; the camera slides there (1.3 s `in-out-quart`). The timeline axis draws at constant speed (`ease: 'none'`: it is time passing) and each marker pops (`back.out(2.2)`) exactly when the line reaches it.
+- **End back on the code line**, with the highlight breathing (opacity 1↔0.5 yoyo): cause and effect, and no frozen end.
+
+## Recipe
+```html
+<!doctype html>
+<html data-width="1920" data-height="1080" data-duration="11">
+<head><style>
+:root { --bg:#0d1017; --panel:#141923; --line:#232a37; --ink:#e6e9f0; --mute:#6c7689; --accent:#ffb454;
+        --kw:#c792ea; --fn:#82aaff; --str:#c3e88d; --num:#f78c6c; --mono:"JetBrains Mono", monospace; }
+body { background:radial-gradient(120% 90% at 30% 20%, #18202e, var(--bg)); color:var(--ink); font-family:Inter, sans-serif; }
+#world { position:absolute; inset:0; width:2900px; }
+#editor { position:absolute; left:160px; top:170px; width:1180px; border-radius:24px; background:var(--panel); border:1px solid var(--line); box-shadow:0 50px 110px #0008; overflow:hidden; }
+.tab { height:72px; display:flex; align-items:center; gap:14px; padding:0 30px; border-bottom:1px solid var(--line); font:500 28px var(--mono); color:var(--mute); }
+.tab i { width:14px; height:14px; border-radius:50%; background:var(--line); }
+pre { position:relative; margin:0; padding:34px 40px 40px 0; font:400 34px/1.62 var(--mono); }
+.ln { display:block; position:relative; padding-left:110px; white-space:pre; }
+.ln::before { content:attr(data-n); position:absolute; left:0; width:76px; text-align:right; color:var(--mute); opacity:.6; }
+.k { color:var(--kw); } .f { color:var(--fn); } .s { color:var(--str); } .n { color:var(--num); }
+#hl { position:absolute; top:0; left:0; right:0; height:55px; background:color-mix(in srgb, var(--accent) 16%, transparent); border-left:5px solid var(--accent); transform-origin:left; opacity:0; }
+#caret { position:absolute; left:0; top:0; width:3px; height:42px; background:var(--accent); animation:blink 1s steps(1) infinite; }
+.code i { font-style:normal; visibility:hidden; } .code i.on { visibility:visible; }
+#diagram { position:absolute; left:1560px; top:260px; width:1180px; height:560px; }
+#diagram h3 { font:600 44px Inter; margin:0 0 30px; }
+#axis { position:absolute; left:0; top:300px; }
+.hit { position:absolute; top:268px; width:64px; height:64px; margin-left:-32px; border-radius:50%; background:var(--panel); border:5px solid var(--mute); }
+.hit.ok { border-color:var(--str); background:var(--str); }
+.gap { position:absolute; top:150px; text-align:center; font:600 34px var(--mono); color:var(--accent); }
+.gap::after { content:""; display:block; height:18px; margin-top:10px; border:3px solid var(--accent); border-bottom:0; border-radius:8px 8px 0 0; }
+</style></head>
+<body>
+<section class="scene" data-duration="11">
+  <div id="world">
+    <div id="editor">
+      <div class="tab"><i></i><i></i><i></i>&nbsp;retry.ts</div>
+      <pre class="code"><div id="hl"></div><span id="caret"></span><span class="ln" data-n="1"><span class="k">async function</span> <span class="f">retry</span>(fn, tries = <span class="n">4</span>) {</span><span class="ln" data-n="2">  <span class="k">for</span> (<span class="k">let</span> i = <span class="n">0</span>; i &lt; tries; i++) {</span><span class="ln" data-n="3">    <span class="k">try</span> {</span><span class="ln" data-n="4">      <span class="k">return await</span> <span class="f">fn</span>();</span><span class="ln" data-n="5">    } <span class="k">catch</span> {</span><span class="ln" data-n="6">      <span class="k">await</span> <span class="f">sleep</span>(<span class="n">2</span> ** i * <span class="n">250</span>);</span><span class="ln" data-n="7">    }</span><span class="ln" data-n="8">  }</span><span class="ln" data-n="9">  <span class="k">throw new</span> <span class="f">Error</span>(<span class="s">"gave up"</span>);</span><span class="ln" data-n="10">}</span></pre>
+    </div>
+    <div id="diagram">
+      <h3>Each retry waits twice as long</h3>
+      <svg id="axis" width="1180" height="20"><path id="axisPath" d="M0 10H1160" stroke="#6c7689" stroke-width="4" stroke-linecap="round"/></svg>
+      <div class="gap" style="left:60px;width:150px">250</div><div class="gap" style="left:210px;width:300px">500</div><div class="gap" style="left:510px;width:600px">1000 ms</div>
+      <div class="hit" style="left:60px"></div><div class="hit" style="left:210px"></div><div class="hit" style="left:510px"></div><div class="hit ok" style="left:1110px"></div>
+    </div>
+  </div>
+</section>
+<script>
+// 1. split the code into chars; give each a reveal time with a human rhythm
+const chars = [];
+for (const ln of document.querySelectorAll('.code .ln')) {
+  const walk = (node) => [...node.childNodes].forEach((c) => {
+    if (c.nodeType === 3) { const f = document.createDocumentFragment(); for (const ch of c.data) { const i = document.createElement('i'); i.textContent = ch; f.append(i); chars.push(i); } c.replaceWith(f); }
+    else walk(c);
+  });
+  walk(ln); chars.push(null);                                   // null = end of line
+}
+let t = 0.6; const times = [];                                  // typing starts at 0.6 s
+chars.forEach((c, k) => {
+  if (!c) { t += 0.1; return; }                                 // breath at each line end
+  const indent = c.textContent === ' ' && (!chars[k - 1] || chars[k - 1].dataset.indent);
+  if (indent) { c.dataset.indent = 1; times.push(t); return; }  // auto-indent appears at once
+  t += (1 / 90) * (0.55 + gm.random('c' + k) * 0.9);           // ~90 chars/s, ±45% jitter
+  if ('({;'.includes(c.textContent)) t += 0.05;
+  times.push(t);
+});
+const typed = chars.filter(Boolean);
+const caret = document.querySelector('#caret');
+gm.onFrame('.scene', (now) => {
+  let n = 0; while (n < typed.length && times[n] <= now) n++;
+  typed.forEach((c, k) => c.classList.toggle('on', k < n));
+  const last = typed[Math.max(0, n - 1)];
+  const ln = last.closest('.ln');                               // char offsets are relative to their line
+  caret.style.translate = `${ln.offsetLeft + last.offsetLeft + (n ? last.offsetWidth : 0)}px ${ln.offsetTop + 6}px`;
+  caret.style.opacity = now > 4.4 ? 0 : 1;                     // caret leaves when the explaining starts
+});
+// 2. choreography
+const L = (n) => `.ln[data-n="${n}"]`, line6 = document.querySelector(L(6));
+gm.set('#hl', { y: line6.offsetTop });
+gm.timeline('.scene')
+  .from('#editor', { y: 120, rotateY: 14, rotateX: 8, transformPerspective: 2000, duration: 1.1, ease: 'expo.out' }, 0)
+  .from('#editor', { opacity: 0.3, duration: 0.4 }, 0)
+  .fromTo('#hl', { opacity: 1, scaleX: 0 }, { scaleX: 1, duration: 0.5, ease: 'power3.out' }, 4.5)
+  .to('.ln:not([data-n="6"])', { opacity: 0.28, duration: 0.5, stagger: { each: 0.02, from: 5 } }, 4.5)
+  .to(L(6) + ' .n', { color: '#ffb454', duration: 0.3 }, 5.0)
+  .from('#diagram h3', { y: 40, opacity: 0, duration: 0.6 }, 6.5)
+  .fromTo('#axisPath', { draw: 0 }, { draw: 1, duration: 1.8, ease: 'none' }, 6.7)        // constant speed: it is time passing
+  .from('.hit', { scale: 0, duration: 0.45, ease: 'back.out(2.2)', stagger: (i, el) => 1.8 * el.offsetLeft / 1160 }, 6.7)  // each dot pops as the line reaches it
+  .from('.gap', { opacity: 0, y: 20, scaleX: 0.4, duration: 0.5, stagger: (i, el) => 1.8 * (el.offsetLeft + el.offsetWidth) / 1160 }, 6.6)
+  .fromTo('#hl', { opacity: 1 }, { opacity: 0.5, duration: 0.3, repeat: 3, yoyo: true, ease: 'sine.inOut' }, 9.8);
+gm.camera('#world')
+  .shot(0,   { fit: '#editor', padding: 110 })
+  .shot(0.8, { fit: '#editor', padding: 110, zoom: 1.1, duration: 3.4, ease: 'in-out-sine' })        // slow push while it types
+  .shot(4.4, { fit: L(6) + ' i', padding: [240, 200, 240, 260], duration: 1.1 })   // fit the line's characters, not the full-width line box
+  .shot(6.1, { fit: '#diagram', padding: 110, duration: 1.3, ease: 'in-out-quart' })
+  .shot(9.2, { fit: L(6) + ' i', padding: [240, 200, 240, 260], duration: 1.2 });  // back to the line it explains
+</script>
+</body></html>
+```
+Color the code by hand with spans (`.k` keyword, `.f` function, `.s` string, `.n` number); the splitter keeps them.
+
+## Make it yours
+- Theme: swap the `:root` tokens. Light editor: `--panel:#fbfbfd; --ink:#1d2330; --kw:#7c3aed; --fn:#2563eb; --str:#15803d; --num:#c2410c`, highlight 12%.
+- Calm/tutorial: 45–60 chars/s, line-end pause 0.25 s, camera moves 1.5 s. Energetic/social: 140 chars/s or paste lines in whole (`.from('.ln', { opacity: 0, x: -30, stagger: 0.06 })`), camera 0.6 s, a `whip-left` cut to the diagram.
+- Luxury/keynote: no caret, lines fade up one by one, very slow push (`zoom: 1.05` over 5 s).
+
+## Variations
+- Code that changes: type a new value into a token with `.to('#val', { text: '500', duration: 0.3, ease: 'none' }, t)` after a 0.15 s red flash on the old one.
+- Several lines in turn: move the bar `.to('#hl', { y: line9.offsetTop, duration: 0.5, ease: 'power3.inOut' }, t)` and re-dim; camera `fit` the next line's `i`.
+- Arrow from a note to a token: `gm.connect` with `sketch: true` (`references/diagrams.md`).
+- Quick version without the splitter: `npx givemotion add code-window` (`typing`, `highlight`, `focus`, `.gm-line[data-line]`); less control over rhythm.
+
+## Pitfalls
+- Char offsets are relative to their line (`.ln` is `position: relative`): add `ln.offsetLeft/offsetTop` when placing the caret.
+- An absolute bar inside `pre` without `top: 0` starts below the padding, so `y: line.offsetTop` lands half a line low.
+- Typing that runs into the explaining: count chars ÷ rate + line pauses and finish ≥ 0.3 s before the highlight.
+- A final wide shot of code + diagram makes the code ~19 px (`tiny-text`). End close on the code instead.
+- Hide not-yet-typed chars with `visibility`, not `display`, so lines keep their width and the camera fit does not change.