creator-editing-studio 1.3.5 → 1.3.7

package/template/src/components/Cursor.tsx

@@ -1,153 +1,153 @@
-import React from 'react';
-import {useCurrentFrame, useVideoConfig} from 'remotion';
-import {EASE} from '../design/motion';
-import {COLOR, FONT, RADIUS, WEIGHT} from '../design/tokens';
-import {durFrames, perFrame, progress, travelFrames} from '../lib/animate';
-import {Presence} from './Presence';
-import {VelocityBlur} from './VelocityBlur';
-
-/** A point the cursor ARRIVES at by frame `at` (the tip of the arrow). */
-export type CursorStop = {at: number; x: number; y: number; click?: boolean};
-
-const CLICK_FRAMES = 6;
-/** Pointer size and where its tip sits inside the 64px artwork. */
-const POINTER = 68;
-const TIP = 6 * (POINTER / 64);
-
-/**
- * An arrow cursor that guides the eye: travels between stops on gentle arcs,
- * arriving exactly on time, and clicks with a press + ripple.
- */
-export const Cursor: React.FC<{
-  stops: CursorStop[];
-  hideAt: number;
-  /**
-   * A name tag riding behind the arrow, the way a collaborator's cursor is labelled in Figma.
-   * Optional and additive: every existing use renders exactly as before without it.
-   *
-   * Pass a function of the frame to change the word mid-move — "copy" becoming "copied" the
-   * instant the click lands reads as the action succeeding, with no second element needed.
-   */
-  label?: string | ((frame: number) => string);
-  /**
-   * Arrow colour. Defaults to the brand accent, which is what every earlier use gets.
-   *
-   * The setup walkthrough passes ink instead, asked for directly ("the arrow should be black"):
-   * over a white email and a light desktop a accent arrow reads as a graphic sitting on the shot,
-   * where a black one reads as the viewer's own pointer.
-   */
-  fill?: string;
-  /** Tag colour, as a function of the frame where it changes state mid-move. */
-  tagColour?: string | ((frame: number) => string);
-  /** Tag text colour, for tags too dark for ink to read on. */
-  tagText?: string | ((frame: number) => string);
-}> = ({
-  stops,
-  hideAt,
-  label,
-  fill = COLOR.accent,
-  tagColour = COLOR.accent,
-  tagText = COLOR.fg,
-}) => {
-  const frame = useCurrentFrame();
-  const {fps} = useVideoConfig();
-
-  const positionAt = (f: number) => {
-    let x = stops[0].x;
-    let y = stops[0].y;
-    for (let i = 1; i < stops.length; i++) {
-      const from = stops[i - 1];
-      const to = stops[i];
-      const distance = Math.hypot(to.x - from.x, to.y - from.y);
-      const travel = Math.min(travelFrames(distance, fps), Math.max(1, to.at - from.at));
-      const depart = to.at - travel;
-      if (f <= depart) break;
-      const t = progress(f, depart, travel, EASE.inOut);
-      // Arc: bulge perpendicular to the path, peaking mid-way.
-      const bulge = Math.sin(Math.PI * t) * distance * 0.1;
-      const nx = distance ? -(to.y - from.y) / distance : 0;
-      const ny = distance ? (to.x - from.x) / distance : 0;
-      x = from.x + (to.x - from.x) * t + nx * bulge;
-      y = from.y + (to.y - from.y) * t + ny * bulge;
-    }
-    return {x, y};
-  };
-
-  const {x, y} = positionAt(frame);
-  const click = stops.find((s) => s.click && frame >= s.at && frame < s.at + durFrames('slow', fps));
-  const pressT = click ? progress(frame, click.at, CLICK_FRAMES, EASE.inOut) : 0;
-  const press = 1 - 0.14 * Math.sin(Math.PI * pressT);
-  const ripple = click ? progress(frame, click.at, durFrames('slow', fps)) : 0;
-
-  // Resolved first so a label that returns an empty string removes the tag outright, which is
-  // how "copied" disappears once the line has been pasted.
-  const labelText = typeof label === 'function' ? label(frame) : label;
-
-  return (
-    <Presence at={stops[0].at} until={hideAt} dur="fast" from="none" style={{position: 'absolute', inset: 0}}>
-      {click ? (
-        <div
-          style={{
-            position: 'absolute',
-            left: click.x - 70 * ripple,
-            top: click.y - 70 * ripple,
-            width: 140 * ripple,
-            height: 140 * ripple,
-            borderRadius: RADIUS.pill,
-            border: `4px solid ${fill}`,
-            opacity: 1 - ripple,
-          }}
-        />
-      ) : null}
-      <VelocityBlur
-        vx={perFrame((f) => positionAt(f).x, frame)}
-        vy={perFrame((f) => positionAt(f).y, frame)}
-        style={{
-          position: 'absolute',
-          left: x - TIP,
-          top: y - TIP,
-          transformOrigin: `${TIP}px ${TIP}px`,
-          transform: `scale(${press.toFixed(4)})`,
-          filter: `drop-shadow(0 8px 14px ${COLOR.fg}66)`,
-        }}
-      >
-        {/* Solid pointer (as in the reference): tip top-left, notched tail. */}
-        <svg width={POINTER} height={POINTER} viewBox="0 0 64 64">
-          <path
-            d="M6 6 L58 26 Q60 27 58 28 L35 35 L28 58 Q27 60 26 58 Z"
-            fill={fill}
-            stroke={COLOR.fg}
-            strokeWidth={3}
-            strokeLinejoin="round"
-          />
-        </svg>
-      </VelocityBlur>
-
-      {labelText ? (
-        <div
-          style={{
-            position: 'absolute',
-            // Sits behind and below the tip, where a Figma cursor label sits, so it never
-            // covers the thing being pointed at.
-            left: x + POINTER * 0.42,
-            top: y + POINTER * 0.52,
-            display: 'flex',
-            alignItems: 'center',
-            padding: '7px 16px',
-            borderRadius: RADIUS.pill,
-            backgroundColor: typeof tagColour === 'function' ? tagColour(frame) : tagColour,
-            fontFamily: FONT.sans,
-            fontSize: 26,
-            fontWeight: WEIGHT.semibold,
-            letterSpacing: '-0.015em',
-            color: typeof tagText === 'function' ? tagText(frame) : tagText,
-            whiteSpace: 'nowrap',
-            boxShadow: `0 6px 16px ${COLOR.fg}33`,
-          }}
-        >
-          {labelText}
-        </div>
-      ) : null}
-    </Presence>
-  );
-};
+import React from 'react';
+import {useCurrentFrame, useVideoConfig} from 'remotion';
+import {EASE} from '../design/motion';
+import {COLOR, FONT, RADIUS, WEIGHT} from '../design/tokens';
+import {durFrames, perFrame, progress, travelFrames} from '../lib/animate';
+import {Presence} from './Presence';
+import {VelocityBlur} from './VelocityBlur';
+
+/** A point the cursor ARRIVES at by frame `at` (the tip of the arrow). */
+export type CursorStop = {at: number; x: number; y: number; click?: boolean};
+
+const CLICK_FRAMES = 6;
+/** Pointer size and where its tip sits inside the 64px artwork. */
+const POINTER = 68;
+const TIP = 6 * (POINTER / 64);
+
+/**
+ * An arrow cursor that guides the eye: travels between stops on gentle arcs,
+ * arriving exactly on time, and clicks with a press + ripple.
+ */
+export const Cursor: React.FC<{
+  stops: CursorStop[];
+  hideAt: number;
+  /**
+   * A name tag riding behind the arrow, the way a collaborator's cursor is labelled in Figma.
+   * Optional and additive: every existing use renders exactly as before without it.
+   *
+   * Pass a function of the frame to change the word mid-move — "copy" becoming "copied" the
+   * instant the click lands reads as the action succeeding, with no second element needed.
+   */
+  label?: string | ((frame: number) => string);
+  /**
+   * Arrow colour. Defaults to the brand accent, which is what every earlier use gets.
+   *
+   * The setup walkthrough passes ink instead, asked for directly ("the arrow should be black"):
+   * over a white email and a light desktop a accent arrow reads as a graphic sitting on the shot,
+   * where a black one reads as the viewer's own pointer.
+   */
+  fill?: string;
+  /** Tag colour, as a function of the frame where it changes state mid-move. */
+  tagColour?: string | ((frame: number) => string);
+  /** Tag text colour, for tags too dark for ink to read on. */
+  tagText?: string | ((frame: number) => string);
+}> = ({
+  stops,
+  hideAt,
+  label,
+  fill = COLOR.accent,
+  tagColour = COLOR.accent,
+  tagText = COLOR.fg,
+}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  const positionAt = (f: number) => {
+    let x = stops[0].x;
+    let y = stops[0].y;
+    for (let i = 1; i < stops.length; i++) {
+      const from = stops[i - 1];
+      const to = stops[i];
+      const distance = Math.hypot(to.x - from.x, to.y - from.y);
+      const travel = Math.min(travelFrames(distance, fps), Math.max(1, to.at - from.at));
+      const depart = to.at - travel;
+      if (f <= depart) break;
+      const t = progress(f, depart, travel, EASE.inOut);
+      // Arc: bulge perpendicular to the path, peaking mid-way.
+      const bulge = Math.sin(Math.PI * t) * distance * 0.1;
+      const nx = distance ? -(to.y - from.y) / distance : 0;
+      const ny = distance ? (to.x - from.x) / distance : 0;
+      x = from.x + (to.x - from.x) * t + nx * bulge;
+      y = from.y + (to.y - from.y) * t + ny * bulge;
+    }
+    return {x, y};
+  };
+
+  const {x, y} = positionAt(frame);
+  const click = stops.find((s) => s.click && frame >= s.at && frame < s.at + durFrames('slow', fps));
+  const pressT = click ? progress(frame, click.at, CLICK_FRAMES, EASE.inOut) : 0;
+  const press = 1 - 0.14 * Math.sin(Math.PI * pressT);
+  const ripple = click ? progress(frame, click.at, durFrames('slow', fps)) : 0;
+
+  // Resolved first so a label that returns an empty string removes the tag outright, which is
+  // how "copied" disappears once the line has been pasted.
+  const labelText = typeof label === 'function' ? label(frame) : label;
+
+  return (
+    <Presence at={stops[0].at} until={hideAt} dur="fast" from="none" style={{position: 'absolute', inset: 0}}>
+      {click ? (
+        <div
+          style={{
+            position: 'absolute',
+            left: click.x - 70 * ripple,
+            top: click.y - 70 * ripple,
+            width: 140 * ripple,
+            height: 140 * ripple,
+            borderRadius: RADIUS.pill,
+            border: `4px solid ${fill}`,
+            opacity: 1 - ripple,
+          }}
+        />
+      ) : null}
+      <VelocityBlur
+        vx={perFrame((f) => positionAt(f).x, frame)}
+        vy={perFrame((f) => positionAt(f).y, frame)}
+        style={{
+          position: 'absolute',
+          left: x - TIP,
+          top: y - TIP,
+          transformOrigin: `${TIP}px ${TIP}px`,
+          transform: `scale(${press.toFixed(4)})`,
+          filter: `drop-shadow(0 8px 14px ${COLOR.fg}66)`,
+        }}
+      >
+        {/* Solid pointer (as in the reference): tip top-left, notched tail. */}
+        <svg width={POINTER} height={POINTER} viewBox="0 0 64 64">
+          <path
+            d="M6 6 L58 26 Q60 27 58 28 L35 35 L28 58 Q27 60 26 58 Z"
+            fill={fill}
+            stroke={COLOR.fg}
+            strokeWidth={3}
+            strokeLinejoin="round"
+          />
+        </svg>
+      </VelocityBlur>
+
+      {labelText ? (
+        <div
+          style={{
+            position: 'absolute',
+            // Sits behind and below the tip, where a Figma cursor label sits, so it never
+            // covers the thing being pointed at.
+            left: x + POINTER * 0.42,
+            top: y + POINTER * 0.52,
+            display: 'flex',
+            alignItems: 'center',
+            padding: '7px 16px',
+            borderRadius: RADIUS.pill,
+            backgroundColor: typeof tagColour === 'function' ? tagColour(frame) : tagColour,
+            fontFamily: FONT.sans,
+            fontSize: 26,
+            fontWeight: WEIGHT.semibold,
+            letterSpacing: '-0.015em',
+            color: typeof tagText === 'function' ? tagText(frame) : tagText,
+            whiteSpace: 'nowrap',
+            boxShadow: `0 6px 16px ${COLOR.fg}33`,
+          }}
+        >
+          {labelText}
+        </div>
+      ) : null}
+    </Presence>
+  );
+};

package/template/src/components/HeadPin.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import {useCurrentFrame} from 'remotion';
+import {EASE} from '../design/motion';
+import {progress} from '../lib/animate';
+import {pinStyle, sampleTrack, type TrackFile} from '../lib/track';
+
+/**
+ * Text or a graphic that rides with the speaker's head (motion tracking). Never a default — use it when
+ * someone asks for it, on a stretch that has been tracked with scripts/track_head.py.
+ *
+ *   <HeadPin track={headTrack} toSource={(f) => f + 72} from={5} to={53} dy={-330}>
+ *     <div style={…}>Big title</div>
+ *   </HeadPin>
+ *
+ * dx/dy place it relative to the head (at the head's starting size; they grow as the head comes closer).
+ * It follows two frames behind and takes half the head's tilt — attached, not glued. Outside the tracked
+ * frames it simply does not draw, so it can never float in the wrong place.
+ */
+export const HeadPin: React.FC<{
+  track: TrackFile;
+  /** The source frame of the tracked clip shown at a composition frame (null when the clip is not on screen). */
+  toSource: (frame: number) => number | null;
+  from: number;
+  to: number;
+  dx?: number;
+  dy?: number;
+  tilt?: number;
+  children: React.ReactNode;
+}> = ({track, toSource, from, to, dx = 0, dy = 0, tilt = 0.5, children}) => {
+  const f = useCurrentFrame();
+  if (f < from - 2 || f > to) return null;
+  const src = toSource(f);
+  const head = src === null ? null : sampleTrack(track, src, 2);
+  if (!head) return null;
+  const p = progress(f, from, 8, EASE.overshoot);
+  const out = 1 - progress(f, to - 5, 5, EASE.in);
+  return (
+    <div style={{...pinStyle(head, {dx, dy, tilt}), opacity: Math.min(1, p * 1.6) * out}}>
+      <div style={{transform: `scale(${0.85 + Math.min(1.05, p) * 0.15}) translateY(${(1 - Math.min(1, p)) * 20}px)`, display: 'flex', flexDirection: 'column', alignItems: 'center'}}>{children}</div>
+    </div>
+  );
+};

package/template/src/compositions/BeatTest.tsx

@@ -3,7 +3,8 @@ import {AbsoluteFill, Sequence} from 'remotion';
 import {DataLine} from '../components/DataLine';
 import {MorphState} from '../components/MorphState';
 import {TypeAhead} from '../components/TypeAhead';
-import {FONT, PALETTE, SHADOW, WEIGHT} from '../design/tokens';
+import {withAlpha} from '../design/color';
+import {COLOR, FONT, SHADOW, WEIGHT} from '../design/tokens';
 
 /**
  * The three beats added from the UI-motion reference, side by side so they can be judged before
@@ -13,10 +14,10 @@ import {FONT, PALETTE, SHADOW, WEIGHT} from '../design/tokens';
  * Render stills with:  node scripts/stills.mjs BeatTest --frames=14,30,46,70
  */
 
-const LIME = PALETTE.lime400;
+const ACCENT = COLOR.accent;
 
 const Label: React.FC<{children: React.ReactNode}> = ({children}) => (
-  <div style={{fontFamily: FONT.sans, fontSize: 24, fontWeight: WEIGHT.semibold, letterSpacing: '0.06em', color: '#8a8880', textTransform: 'uppercase'}}>
+  <div style={{fontFamily: FONT.sans, fontSize: 24, fontWeight: WEIGHT.semibold, letterSpacing: '0.06em', color: COLOR.fgSecondary, textTransform: 'uppercase'}}>
     {children}
   </div>
 );
@@ -24,7 +25,7 @@ const Label: React.FC<{children: React.ReactNode}> = ({children}) => (
 export const BEAT_TEST_FRAMES = 90;
 
 export const BeatTest: React.FC = () => (
-  <AbsoluteFill style={{backgroundColor: PALETTE.cream, fontFamily: FONT.sans, padding: 80, gap: 56, display: 'flex', flexDirection: 'column'}}>
+  <AbsoluteFill style={{backgroundColor: COLOR.surfaceAlt, fontFamily: FONT.sans, padding: 80, gap: 56, display: 'flex', flexDirection: 'column'}}>
     {/* 1. Morph into state — a payment row becoming its own confirmation. */}
     <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
       <Label>Morph into state</Label>
@@ -35,8 +36,8 @@ export const BeatTest: React.FC = () => (
           width: 620,
           height: 104,
           radius: 999,
-          background: PALETTE.white,
-          colour: PALETTE.ink900,
+          background: COLOR.surface,
+          colour: COLOR.fg,
           children: (
             <span style={{fontSize: 34, fontWeight: WEIGHT.medium, padding: '0 36px'}}>
               Send ₹2,000 to Wise account
@@ -47,8 +48,8 @@ export const BeatTest: React.FC = () => (
           width: 340,
           height: 104,
           radius: 999,
-          background: LIME,
-          colour: PALETTE.ink900,
+          background: ACCENT,
+          colour: COLOR.onAccent,
           children: <span style={{fontSize: 36, fontWeight: WEIGHT.bold}}>Received ✓</span>,
         }}
       />
@@ -57,7 +58,7 @@ export const BeatTest: React.FC = () => (
     {/* 2. Live data morph — the panel holds still, only the line changes. */}
     <div style={{display: 'flex', flexDirection: 'column', gap: 16}}>
       <Label>Live data morph</Label>
-      <div style={{width: 820, height: 260, borderRadius: 24, backgroundColor: PALETTE.white, border: '1px solid rgba(18,18,16,0.10)', padding: 32, boxShadow: SHADOW.pop}}>
+      <div style={{width: 820, height: 260, borderRadius: 24, backgroundColor: COLOR.surface, border: `1px solid ${COLOR.borderSubtle}`, padding: 32, boxShadow: SHADOW.pop}}>
         <DataLine
           width={756}
           height={196}
@@ -67,9 +68,9 @@ export const BeatTest: React.FC = () => (
           frames={20}
           from={[0.22, 0.44, 0.3, 0.58, 0.41, 0.69, 0.52, 0.78, 0.6, 0.72]}
           to={[0.3, 0.26, 0.52, 0.38, 0.72, 0.5, 0.86, 0.62, 0.9, 0.84]}
-          colour="#3b82f6"
-          toColour="#e5484d"
-          fill="rgba(229,72,77,0.07)"
+          colour={COLOR.fgSecondary}
+          toColour={ACCENT}
+          fill={withAlpha(ACCENT, 0.1)}
         />
       </div>
     </div>
@@ -82,9 +83,9 @@ export const BeatTest: React.FC = () => (
           text="cut the gaps and add captions"
           at={8}
           speed={1.3}
-          colour={PALETTE.ink900}
-          ghost="rgba(18,18,16,0.22)"
-          background={LIME}
+          colour={COLOR.onAccent}
+          ghost={withAlpha(COLOR.fg, 0.22)}
+          background={ACCENT}
           fontSize={42}
           fontFamily={FONT.sans}
           fontWeight={WEIGHT.semibold}

package/template/src/lib/track.ts

@@ -0,0 +1,67 @@
+/**
+ * Motion tracking: pin graphics to something moving in the footage — a head, from scripts/track_head.py.
+ *
+ *   const head = sampleTrack(track, sourceFrame, 2);          // null outside the tracked stretches
+ *   if (head) <div style={pinStyle(head, {dy: -330})}>…</div>
+ *
+ * A track holds SOURCE frames of one clip, in that clip's pixels; a composition showing the clip
+ * full-frame at the same size can use it directly. One file per video can hold several tracked stretches.
+ * `lag` follows a couple of frames behind, so a graphic feels attached by a soft spring, not glued on.
+ */
+import type {CSSProperties} from 'react';
+
+export type TrackPoint = {f: number; x: number; y: number; s: number; r: number};
+export type TrackFile = {fps: number; size: number[]; first: number; box: {w: number; h: number}; frames: TrackPoint[]};
+export type Pin = {x: number; y: number; s: number; r: number};
+
+/** The tracked point at a source frame, or null if that frame was not tracked. */
+function pointAt(t: TrackFile, f: number): TrackPoint | null {
+  const fr = Math.round(f);
+  let lo = 0;
+  let hi = t.frames.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const m = t.frames[mid];
+    if (m.f === fr) return m;
+    if (m.f < fr) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  return null;
+}
+
+/** Where the tracked thing is at a source frame, averaged over `lag` frames behind it; null if untracked. */
+export function sampleTrack(t: TrackFile, sourceFrame: number, lag = 0): Pin | null {
+  const pts = Array.from({length: lag + 1}, (_, k) => pointAt(t, sourceFrame - k)).filter((p): p is TrackPoint => !!p);
+  if (!pointAt(t, sourceFrame) || !pts.length) return null;
+  const avg = (k: 'x' | 'y' | 's' | 'r') => pts.reduce((sum, p) => sum + p[k], 0) / pts.length;
+  return {x: avg('x'), y: avg('y'), s: avg('s'), r: avg('r')};
+}
+
+/**
+ * Absolute position for a graphic pinned to the track. dx/dy are offsets at the starting size and grow with
+ * the head; `tilt` is how much of the head's tilt the graphic takes (a little reads as attached; all of it
+ * reads as stuck on).
+ */
+export function pinStyle(p: Pin, {dx = 0, dy = 0, tilt = 0.5}: {dx?: number; dy?: number; tilt?: number} = {}): CSSProperties {
+  return {
+    position: 'absolute',
+    left: p.x + dx * p.s,
+    top: p.y + dy * p.s,
+    transform: `translate(-50%, -50%) scale(${p.s}) rotate(${p.r * tilt}deg)`,
+    transformOrigin: '50% 50%',
+  };
+}
+
+/**
+ * How far the head has moved since a reference frame, as a CSS transform about the head — for "follow":
+ * a layout keeps its design but moves, scales and (partly) tilts with the head. Null if either is untracked.
+ */
+export function followTransform(t: TrackFile, sourceFrame: number, fromSourceFrame: number, tilt = 0.5): {transform: string; transformOrigin: string} | null {
+  const now = sampleTrack(t, sourceFrame, 2);
+  const at = sampleTrack(t, fromSourceFrame);
+  if (!now || !at) return null;
+  return {
+    transform: `translate(${now.x - at.x}px, ${now.y - at.y}px) scale(${now.s / at.s}) rotate(${(now.r - at.r) * tilt}deg)`,
+    transformOrigin: `${at.x}px ${at.y}px`,
+  };
+}

package/template/src/lib/tweaks.tsx

@@ -0,0 +1,98 @@
+/**
+ * Live-preview adjustments ("tweaks"): what the preview's instant controls change, applied to an edit
+ * without touching its code.
+ *
+ * An edit wraps itself in <TweaksProvider beatStarts={…} tweaks={…}> and wraps each layer that should
+ * respond in <Tweaked>. In the preview the tweaks arrive as props and change the video instantly; saved,
+ * they live in the video's tweaks.json and the final render reads them from there. No tweaks = the edit
+ * exactly as built.
+ *
+ * Rules that keep an edit correct whatever someone clicks:
+ *  - Anything that hides a join in the cut (a full-screen card) must NOT be inside a moving <Tweaked> — the
+ *    card's exact frames are what hide the join. Wrap only what sits ON it.
+ *  - Layers locked to the footage (a subject cutout) use <Tweaked move={false}> and read the tweak with
+ *    useHereTweak() to move only their graphics.
+ */
+import React, {createContext, useContext} from 'react';
+import {AbsoluteFill, Sequence, useCurrentFrame} from 'remotion';
+import {followTransform, type TrackFile} from './track';
+
+/**
+ * One beat's adjustments. All optional.
+ *   scale  size of text and graphics, 0.7–1.4          dy     up (−) / down (+), px, ±300
+ *   shift  frames later (+) / earlier (−), ±12          gain   that beat's sound effects, dB, −12…+6
+ *   mute   that beat's sound effects off                icon   swap a 3D icon: {cart: 'shop'}
+ *   follow the beat's graphics move, scale and partly tilt with the speaker's head (needs a head track)
+ */
+export type Tweak = {scale?: number; dy?: number; shift?: number; gain?: number; mute?: boolean; icon?: Record<string, string>; follow?: boolean};
+export type Tweaks = Record<string, Tweak>; // keyed by beat index
+
+export const TWEAK_LIMITS = {scale: [0.7, 1.4], dy: [-300, 300], shift: [-12, 12], gain: [-12, 6]} as const;
+
+/** track/toSource: optional head track for the "follow" tweak — the clip's source frame at a composition frame. */
+type Ctx = {tweaks: Tweaks; beatAt: (frame: number) => number; beatStarts: number[]; track?: TrackFile; toSource?: (frame: number) => number | null};
+const All = createContext<Ctx>({tweaks: {}, beatAt: () => 0, beatStarts: [0]});
+const Here = createContext<Tweak>({});
+
+/** beatStarts: the first frame of each beat, in order. */
+export const TweaksProvider: React.FC<{tweaks?: Tweaks; beatStarts: number[]; track?: TrackFile; toSource?: (frame: number) => number | null; children: React.ReactNode}> = ({
+  tweaks = {},
+  beatStarts,
+  track,
+  toSource,
+  children,
+}) => {
+  const beatAt = (frame: number) => {
+    for (let i = beatStarts.length - 1; i >= 0; i--) if (frame >= beatStarts[i]) return i;
+    return 0;
+  };
+  return <All.Provider value={{tweaks, beatAt, beatStarts, track, toSource}}>{children}</All.Provider>;
+};
+
+/** The tweak of the beat at any frame — for things placed by frame number, like sound cues. */
+export const useTweakAt = () => {
+  const {tweaks, beatAt} = useContext(All);
+  return (frame: number): Tweak => tweaks[String(beatAt(frame))] ?? {};
+};
+
+/** The tweak of the beat being drawn, inside a <Tweaked>. */
+export const useHereTweak = () => useContext(Here);
+
+/**
+ * Applies the current beat's size, position and timing to what is inside it. `move={false}` only hands the
+ * tweak down (see the rules above).
+ */
+export const Tweaked: React.FC<{move?: boolean; children: React.ReactNode}> = ({move = true, children}) => {
+  const f = useCurrentFrame();
+  const ctx = useContext(All);
+  const t = useTweakAt()(f);
+  // Follow: the beat keeps its layout but moves, scales and partly tilts with the head, measured from the
+  // first frame of the beat where the head is visible and tracked (a beat may open on a full-screen card).
+  // Untracked frames leave it exactly where it was designed.
+  let follow: React.CSSProperties | null = null;
+  if (move && t.follow && ctx.track && ctx.toSource) {
+    const track = ctx.track;
+    const src = ctx.toSource(f);
+    const beat = ctx.beatAt(f);
+    let src0: number | null = null;
+    for (let g = ctx.beatStarts[beat] ?? 0; g <= f && src0 === null; g++) {
+      const s = ctx.toSource(g);
+      if (s !== null && followTransform(track, s, s)) src0 = s;
+    }
+    follow = src !== null && src0 !== null ? followTransform(track, src, src0) : null;
+  }
+  const placed = (
+    <Here.Provider value={t}>
+      {move && (t.scale || t.dy) ? <AbsoluteFill style={{transform: `translateY(${t.dy ?? 0}px) scale(${t.scale ?? 1})`, transformOrigin: '50% 55%'}}>{children}</AbsoluteFill> : children}
+    </Here.Provider>
+  );
+  const inner = follow ? <AbsoluteFill style={follow}>{placed}</AbsoluteFill> : placed;
+  // Later (+) or earlier (−): everything inside runs on a clock offset by that many frames.
+  return move && t.shift ? (
+    <Sequence from={t.shift} layout="none">
+      {inner}
+    </Sequence>
+  ) : (
+    inner
+  );
+};