creator-editing-studio 1.0.20260930

package/template/src/components/Transition.tsx

@@ -0,0 +1,100 @@
+import React from 'react';
+import {AbsoluteFill, useCurrentFrame, useVideoConfig} from 'remotion';
+import {EASE} from '../design/motion';
+import {TRANSITION_PRESETS, type TransitionDirection, type TransitionKind} from '../design/presets';
+import {durFrames, perFrame, progress} from '../lib/animate';
+import {VelocityBlur} from './VelocityBlur';
+
+/**
+ * A named transition between two scenes, built from the motion tokens.
+ *
+ *   <Transition kind="whipPan" at={cut} direction="left" from={<SceneA />} to={<SceneB />} />
+ *
+ * The outgoing scene is shown before `at`, the incoming after, and the named preset decides
+ * how they hand over. Anything that moves fast carries motion blur, so no hard edge ever
+ * jumps across the frame unblurred (law 10).
+ */
+export const Transition: React.FC<{
+  kind: TransitionKind;
+  /** Frame the cut lands on. */
+  at: number;
+  direction?: TransitionDirection;
+  from: React.ReactNode;
+  to: React.ReactNode;
+}> = ({kind, at, direction = 'left', from, to}) => {
+  const frame = useCurrentFrame();
+  const {fps, width, height} = useVideoConfig();
+  const preset = TRANSITION_PRESETS[kind];
+  const dur = durFrames(preset.dur, fps);
+
+  // The move is centred on the cut: half before, half after.
+  const start = at - Math.round(dur / 2);
+  const p = progress(frame, start, dur, EASE.inOut);
+  const velocity = perFrame((f) => progress(f, start, dur, EASE.inOut), frame);
+
+  const axis = direction === 'left' || direction === 'right' ? 'x' : 'y';
+  const sign = direction === 'left' || direction === 'up' ? -1 : 1;
+  const span = (axis === 'x' ? width : height) * preset.travel;
+
+  const shift = (amount: number) =>
+    axis === 'x' ? `translateX(${amount.toFixed(2)}px)` : `translateY(${amount.toFixed(2)}px)`;
+
+  const before = p < 1;
+  const after = p > 0;
+
+  /* ---------------------------------------------------------------- flash-based presets */
+
+  if (preset.flash) {
+    // colourFlip / dip: a hard cut through a solid frame, no sliding.
+    const half = dur / 2;
+    const showFlash = frame >= start && frame < start + dur;
+    const showTo = frame >= start + half;
+    return (
+      <AbsoluteFill>
+        {showTo ? to : from}
+        {showFlash ? <AbsoluteFill style={{backgroundColor: preset.flash}} /> : null}
+      </AbsoluteFill>
+    );
+  }
+
+  /* ---------------------------------------------------------------- moving presets */
+
+  // motion-ok: #000 is mask opacity here, not a design colour.
+  const maskEdge = `linear-gradient(${axis === 'x' ? (sign < 0 ? 'to left' : 'to right') : sign < 0 ? 'to top' : 'to bottom'}, #000 ${(p * 100).toFixed(1)}%, transparent ${(p * 100 + 12).toFixed(1)}%)`;
+
+  const outStyle: React.CSSProperties =
+    kind === 'maskWipe'
+      ? {opacity: 1}
+      : kind === 'matchCut'
+        ? {transform: `scale(${(1 + (preset.scale! - 1) * p).toFixed(4)})`, opacity: 1 - p}
+        : {transform: shift(sign * span * p)};
+
+  const inStyle: React.CSSProperties =
+    kind === 'maskWipe'
+      ? {
+          // A soft-edged wipe: the leading edge softens instead of cutting hard.
+          // motion-ok: #000 here is mask opacity, not a design colour.
+          WebkitMaskImage: maskEdge,
+          maskImage: maskEdge,
+        }
+      : kind === 'matchCut'
+        ? {transform: `scale(${(1 + (preset.scale! - 1) * (1 - p)).toFixed(4)})`, opacity: p}
+        : {transform: shift(-sign * span * (1 - p))};
+
+  const speed = velocity * span;
+  const wrap = (node: React.ReactNode, style: React.CSSProperties) =>
+    preset.blur ? (
+      <VelocityBlur vx={axis === 'x' ? speed : 0} vy={axis === 'y' ? speed : 0}>
+        <AbsoluteFill style={style}>{node}</AbsoluteFill>
+      </VelocityBlur>
+    ) : (
+      <AbsoluteFill style={style}>{node}</AbsoluteFill>
+    );
+
+  return (
+    <AbsoluteFill>
+      {before ? wrap(from, outStyle) : null}
+      {after ? wrap(to, inStyle) : null}
+    </AbsoluteFill>
+  );
+};

package/template/src/components/VelocityBlur.tsx

@@ -0,0 +1,53 @@
+import React, {useId, type CSSProperties} from 'react';
+import {BLUR} from '../design/motion';
+
+/** Below this Gaussian sigma (px) the blur is invisible, so it is skipped. */
+const MIN_SIGMA = 0.25;
+
+/**
+ * Directional motion blur sized to how far the element moves this frame, using the
+ * same 180-degree shutter as film / After Effects — but analytic, so it costs almost
+ * nothing to render. It fades to zero as the element settles.
+ *
+ * vx / vy: the element's movement in px per frame (use perFrame()).
+ * bleed:   how far the blur may spread beyond the element, as a fraction of its size.
+ *          Use 0 on full-frame wrappers that clip their content.
+ */
+export const VelocityBlur: React.FC<{
+  vx?: number;
+  vy?: number;
+  bleed?: number;
+  as?: 'div' | 'span';
+  style?: CSSProperties;
+  children: React.ReactNode;
+}> = ({vx = 0, vy = 0, bleed = 0.5, as: Tag = 'div', style, children}) => {
+  const id = `vblur${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`;
+  const shutter = BLUR.shutterAngle / 360;
+  // A box blur of length L spreads like a Gaussian with sigma ~ 0.29 L.
+  const sx = Math.abs(vx) * shutter * 0.29;
+  const sy = Math.abs(vy) * shutter * 0.29;
+  const active = sx >= MIN_SIGMA || sy >= MIN_SIGMA;
+  const filter = [active ? `url(#${id})` : undefined, style?.filter].filter(Boolean).join(' ') || undefined;
+
+  return (
+    <Tag style={{...style, filter}}>
+      {active ? (
+        <svg width={0} height={0} style={{position: 'absolute'}} aria-hidden>
+          <defs>
+            <filter
+              id={id}
+              x={`${-bleed * 100}%`}
+              y={`${-bleed * 100}%`}
+              width={`${100 + bleed * 200}%`}
+              height={`${100 + bleed * 200}%`}
+              colorInterpolationFilters="sRGB"
+            >
+              <feGaussianBlur stdDeviation={`${sx.toFixed(3)} ${sy.toFixed(3)}`} />
+            </filter>
+          </defs>
+        </svg>
+      ) : null}
+      {children}
+    </Tag>
+  );
+};

package/template/src/compositions/FilmTest.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import {AbsoluteFill, Sequence, useVideoConfig} from 'remotion';
+import {FilmOverlay} from '../components/FilmOverlay';
+import {FILM_PRESETS, type FilmLook} from '../design/overlays';
+import {BACKGROUND, COLOR, FONT, TYPE} from '../design/tokens';
+
+/**
+ * Every film look, back to back, over the same plate — so they can be judged against
+ * each other and against no overlay at all. Reference composition, not a video.
+ *
+ * The plate deliberately has a bright area (for halation), a flat mid tone (where grain
+ * shows worst) and a hard edge (where gate weave would be visible if it were too strong).
+ */
+
+const Plate: React.FC<{label: string; note: string}> = ({label, note}) => (
+  <AbsoluteFill style={{background: BACKGROUND.creamGlow}}>
+    <AbsoluteFill style={{backgroundColor: COLOR.surfaceDark, top: '55%'}} />
+    <AbsoluteFill style={{justifyContent: 'center', alignItems: 'center', padding: 96, textAlign: 'center'}}>
+      <span
+        style={{
+          fontFamily: FONT.sans,
+          fontSize: TYPE.h1.size,
+          fontWeight: TYPE.h1.weight,
+          letterSpacing: TYPE.h1.tracking,
+          color: COLOR.fg,
+        }}
+      >
+        {label}
+      </span>
+      <span
+        style={{
+          fontFamily: FONT.sans,
+          fontSize: TYPE.caption.size,
+          fontWeight: TYPE.caption.weight,
+          color: COLOR.fgSecondary,
+          marginTop: 24,
+          maxWidth: 820,
+          lineHeight: TYPE.caption.lineHeight,
+        }}
+      >
+        {note}
+      </span>
+    </AbsoluteFill>
+  </AbsoluteFill>
+);
+
+const LOOKS = Object.keys(FILM_PRESETS) as FilmLook[];
+const HOLD_SECONDS = 2;
+
+export const FilmTest: React.FC = () => {
+  const {fps} = useVideoConfig();
+  const hold = Math.round(HOLD_SECONDS * fps);
+
+  return (
+    <AbsoluteFill style={{backgroundColor: COLOR.surfaceAlt}}>
+      {LOOKS.map((look, i) => (
+        <Sequence key={look} from={i * hold} durationInFrames={hold} layout="none">
+          <FilmOverlay look={look} seed={i}>
+            <Plate label={look} note={FILM_PRESETS[look].note} />
+          </FilmOverlay>
+        </Sequence>
+      ))}
+    </AbsoluteFill>
+  );
+};
+
+export const FILM_TEST_FRAMES = LOOKS.length * Math.round(HOLD_SECONDS * 30);

package/template/src/compositions/PresetTest.tsx

@@ -0,0 +1,52 @@
+import React from 'react';
+import {AbsoluteFill, Sequence, useVideoConfig} from 'remotion';
+import {Transition} from '../components/Transition';
+import {COLOR, FONT, TYPE} from '../design/tokens';
+import {TRANSITION_PRESETS, type TransitionKind} from '../design/presets';
+
+/**
+ * Every transition preset, back to back, so they can be judged side by side
+ * (and so motion-check sees them). Reference composition — not a video.
+ */
+
+const Panel: React.FC<{label: string; bg: string; fg: string}> = ({label, bg, fg}) => (
+  <AbsoluteFill style={{backgroundColor: bg, justifyContent: 'center', alignItems: 'center'}}>
+    <span
+      style={{
+        fontFamily: FONT.sans,
+        fontSize: TYPE.display.size,
+        fontWeight: TYPE.display.weight,
+        letterSpacing: TYPE.display.tracking,
+        color: fg,
+      }}
+    >
+      {label}
+    </span>
+  </AbsoluteFill>
+);
+
+const KINDS = Object.keys(TRANSITION_PRESETS) as TransitionKind[];
+const HOLD_SECONDS = 1.6;
+
+export const PresetTest: React.FC = () => {
+  const {fps} = useVideoConfig();
+  const hold = Math.round(HOLD_SECONDS * fps);
+
+  return (
+    <AbsoluteFill style={{backgroundColor: COLOR.surfaceAlt}}>
+      {KINDS.map((kind, i) => (
+        <Sequence key={kind} from={i * hold} durationInFrames={hold} layout="none">
+          <Transition
+            kind={kind}
+            at={Math.round(hold / 2)}
+            direction={i % 2 ? 'right' : 'left'}
+            from={<Panel label={kind} bg={COLOR.surfaceDark} fg={COLOR.accent} />}
+            to={<Panel label="→" bg={COLOR.accent} fg={COLOR.onAccent} />}
+          />
+        </Sequence>
+      ))}
+    </AbsoluteFill>
+  );
+};
+
+export const PRESET_TEST_FRAMES = KINDS.length * Math.round(HOLD_SECONDS * 30);

package/template/src/design/color.ts

@@ -0,0 +1,6 @@
+/** `#rrggbb` + alpha (0-1) -> `rgba()` string, for fading token colours. */
+export const withAlpha = (hex: string, alpha: number): string => {
+  const n = parseInt(hex.replace('#', ''), 16);
+  const a = Math.min(1, Math.max(0, alpha));
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${a.toFixed(4)})`;
+};

package/template/src/design/glow.ts

@@ -0,0 +1,11 @@
+import {HERO} from './tokens';
+
+/** Accent glow for hero text; `strength` 0-1 fades it (e.g. when the text shrinks into a pill). */
+export const heroGlow = (strength = 1): string => {
+  const s = Math.max(0, Math.min(1, strength));
+  return [
+    `0 0 26px rgba(${HERO.glowRgb},${(0.55 * s).toFixed(3)})`,
+    `0 0 90px rgba(${HERO.glowRgb},${(0.35 * s).toFixed(3)})`,
+    `0 8px 30px rgba(${HERO.liftRgb},${(0.3 * s).toFixed(3)})`,
+  ].join(', ');
+};

package/template/src/design/logos.json

@@ -0,0 +1,18 @@
+{
+ "width": 256,
+ "height": 256,
+ "icons": {
+  "google-icon": {
+   "body": "<path fill=\"#4285f4\" d=\"M255.878 133.451c0-10.734-.871-18.567-2.756-26.69H130.55v48.448h71.947c-1.45 12.04-9.283 30.172-26.69 42.356l-.244 1.622l38.755 30.023l2.685.268c24.659-22.774 38.875-56.282 38.875-96.027\"/><path fill=\"#34a853\" d=\"M130.55 261.1c35.248 0 64.839-11.605 86.453-31.622l-41.196-31.913c-11.024 7.688-25.82 13.055-45.257 13.055c-34.523 0-63.824-22.773-74.269-54.25l-1.531.13l-40.298 31.187l-.527 1.465C35.393 231.798 79.49 261.1 130.55 261.1\"/><path fill=\"#fbbc05\" d=\"M56.281 156.37c-2.756-8.123-4.351-16.827-4.351-25.82c0-8.994 1.595-17.697 4.206-25.82l-.073-1.73L15.26 71.312l-1.335.635C5.077 89.644 0 109.517 0 130.55s5.077 40.905 13.925 58.602z\"/><path fill=\"#eb4335\" d=\"M130.55 50.479c24.514 0 41.05 10.589 50.479 19.438l36.844-35.974C195.245 12.91 165.798 0 130.55 0C79.49 0 35.393 29.301 13.925 71.947l42.211 32.783c10.59-31.477 39.891-54.251 74.414-54.251\"/>",
+   "height": 262
+  },
+  "meta-icon": {
+   "body": "<defs><linearGradient id=\"SVGYeLhubCc\" x1=\"13.878%\" x2=\"89.144%\" y1=\"55.934%\" y2=\"58.694%\"><stop offset=\"0%\" stop-color=\"#0064e1\"/><stop offset=\"40%\" stop-color=\"#0064e1\"/><stop offset=\"83%\" stop-color=\"#0073ee\"/><stop offset=\"100%\" stop-color=\"#0082fb\"/></linearGradient><linearGradient id=\"SVGll66Sdsg\" x1=\"54.315%\" x2=\"54.315%\" y1=\"82.782%\" y2=\"39.307%\"><stop offset=\"0%\" stop-color=\"#0082fb\"/><stop offset=\"100%\" stop-color=\"#0064e0\"/></linearGradient></defs><path fill=\"#0081fb\" d=\"M27.651 112.136c0 9.775 2.146 17.28 4.95 21.82c3.677 5.947 9.16 8.466 14.751 8.466c7.211 0 13.808-1.79 26.52-19.372c10.185-14.092 22.186-33.874 30.26-46.275l13.675-21.01c9.499-14.591 20.493-30.811 33.1-41.806C161.196 4.985 172.298 0 183.47 0c18.758 0 36.625 10.87 50.3 31.257C248.735 53.584 256 81.707 256 110.729c0 17.253-3.4 29.93-9.187 39.946c-5.591 9.686-16.488 19.363-34.818 19.363v-27.616c15.695 0 19.612-14.422 19.612-30.927c0-23.52-5.484-49.623-17.564-68.273c-8.574-13.23-19.684-21.313-31.907-21.313c-13.22 0-23.859 9.97-35.815 27.75c-6.356 9.445-12.882 20.956-20.208 33.944l-8.066 14.289c-16.203 28.728-20.307 35.271-28.408 46.07c-14.2 18.91-26.324 26.076-42.287 26.076c-18.935 0-30.91-8.2-38.325-20.556C2.973 139.413 0 126.202 0 111.148z\"/><path fill=\"url(#SVGYeLhubCc)\" d=\"M21.802 33.206C34.48 13.666 52.774 0 73.757 0C85.91 0 97.99 3.597 110.605 13.897c13.798 11.261 28.505 29.805 46.853 60.368l6.58 10.967c15.881 26.459 24.917 40.07 30.205 46.49c6.802 8.243 11.565 10.7 17.752 10.7c15.695 0 19.612-14.422 19.612-30.927l24.393-.766c0 17.253-3.4 29.93-9.187 39.946c-5.591 9.686-16.488 19.363-34.818 19.363c-11.395 0-21.49-2.475-32.654-13.007c-8.582-8.083-18.615-22.443-26.334-35.352l-22.96-38.352C118.528 64.08 107.96 49.73 101.845 43.23c-6.578-6.988-15.036-15.428-28.532-15.428c-10.923 0-20.2 7.666-27.963 19.39z\"/><path fill=\"url(#SVGll66Sdsg)\" d=\"M73.312 27.802c-10.923 0-20.2 7.666-27.963 19.39c-10.976 16.568-17.698 41.245-17.698 64.944c0 9.775 2.146 17.28 4.95 21.82L9.027 149.482C2.973 139.413 0 126.202 0 111.148C0 83.772 7.514 55.24 21.802 33.206C34.48 13.666 52.774 0 73.757 0z\"/>",
+   "height": 171
+  },
+  "shopify": {
+   "body": "<path fill=\"#95bf46\" d=\"M223.774 57.34c-.201-1.46-1.48-2.268-2.537-2.357a19614 19614 0 0 0-23.383-1.743s-15.507-15.395-17.209-17.099c-1.703-1.703-5.029-1.185-6.32-.805c-.19.056-3.388 1.043-8.678 2.68c-5.18-14.906-14.322-28.604-30.405-28.604c-.444 0-.901.018-1.358.044C129.31 3.407 123.644.779 118.75.779c-37.465 0-55.364 46.835-60.976 70.635c-14.558 4.511-24.9 7.718-26.221 8.133c-8.126 2.549-8.383 2.805-9.45 10.462C21.3 95.806.038 260.235.038 260.235l165.678 31.042l89.77-19.42S223.973 58.8 223.775 57.34M156.49 40.848l-14.019 4.339c.005-.988.01-1.96.01-3.023c0-9.264-1.286-16.723-3.349-22.636c8.287 1.04 13.806 10.469 17.358 21.32m-27.638-19.483c2.304 5.773 3.802 14.058 3.802 25.238c0 .572-.005 1.095-.01 1.624c-9.117 2.824-19.024 5.89-28.953 8.966c5.575-21.516 16.025-31.908 25.161-35.828m-11.131-10.537c1.617 0 3.246.549 4.805 1.622c-12.007 5.65-24.877 19.88-30.312 48.297l-22.886 7.088C75.694 46.16 90.81 10.828 117.72 10.828\"/><path fill=\"#5e8e3e\" d=\"M221.237 54.983a19614 19614 0 0 0-23.383-1.743s-15.507-15.395-17.209-17.099c-.637-.634-1.496-.959-2.394-1.099l-12.527 256.233l89.762-19.418S223.972 58.8 223.774 57.34c-.201-1.46-1.48-2.268-2.537-2.357\"/><path fill=\"#fff\" d=\"m135.242 104.585l-11.069 32.926s-9.698-5.176-21.586-5.176c-17.428 0-18.305 10.937-18.305 13.693c0 15.038 39.2 20.8 39.2 56.024c0 27.713-17.577 45.558-41.277 45.558c-28.44 0-42.984-17.7-42.984-17.7l7.615-25.16s14.95 12.835 27.565 12.835c8.243 0 11.596-6.49 11.596-11.232c0-19.616-32.16-20.491-32.16-52.724c0-27.129 19.472-53.382 58.778-53.382c15.145 0 22.627 4.338 22.627 4.338\"/>",
+   "height": 292
+  }
+ }
+}

package/template/src/design/motion.ts

@@ -0,0 +1,90 @@
+import {Easing} from 'remotion';
+
+/**
+ * MOTION TOKENS
+ * The ONLY file where timing, curves and springs are defined.
+ * Durations are milliseconds so the system works at 30 or 60 fps —
+ * convert with msToFrames()/durFrames() from src/lib/animate.ts.
+ */
+
+export const DUR = {
+  instant: 133, // micro state changes
+  fast: 267, // small elements
+  base: 400, // standard element entrance
+  slow: 600, // hero elements, long travel, line draws
+  scene: 800, // camera moves, scene handoffs
+  drift: 2400, // slow push-ins on the footage
+} as const;
+export type Dur = keyof typeof DUR;
+
+/** Raw cubic-bezier control points (also usable for After Effects handoff). */
+export const CURVE = {
+  out: [0.16, 1, 0.3, 1], // entrances — brand --ease-out-expo
+  outDecisive: [0.22, 1, 0.36, 1], // slightly softer landing than expo
+  outSoft: [0.33, 1, 0.68, 1], // gentle entrances, opacity
+  in: [0.64, 0, 0.78, 0], // exits
+  inOut: [0.65, 0, 0.35, 1], // A-to-B moves while on screen
+  emphasis: [0.2, 0, 0, 1], // hero moments
+  overshoot: [0.34, 1.56, 0.64, 1], // brand --ease-spring; scale only, sparingly
+} as const;
+export type Curve = keyof typeof CURVE;
+
+export const EASE: Record<Curve, (t: number) => number> = {
+  out: Easing.bezier(...CURVE.out),
+  outDecisive: Easing.bezier(...CURVE.outDecisive),
+  outSoft: Easing.bezier(...CURVE.outSoft),
+  in: Easing.bezier(...CURVE.in),
+  inOut: Easing.bezier(...CURVE.inOut),
+  emphasis: Easing.bezier(...CURVE.emphasis),
+  overshoot: Easing.bezier(...CURVE.overshoot),
+};
+
+export const SPRING = {
+  snap: {damping: 200, mass: 0.5, stiffness: 200}, // settles, no bounce
+  soft: {damping: 26, mass: 1, stiffness: 120}, // slight overshoot
+} as const;
+export type SpringKind = keyof typeof SPRING;
+
+/** Delay between items in a group. */
+export const STAGGER = {
+  tight: 67, // ~2 frames @30fps
+  normal: 100, // ~3 frames @30fps
+  dramatic: 167, // ~5 frames @30fps
+} as const;
+export type StaggerKind = keyof typeof STAGGER;
+
+/** Exits run at this fraction of the matching entrance duration (law 3). */
+export const EXIT_RATIO = 0.65;
+
+/** Opacity completes at this fraction of the transform duration (law 5). */
+export const OPACITY_LEAD = 0.6;
+
+export const LIMITS = {
+  minScaleFrom: 0.9, // never scale from below this (law 6)
+  maxBlurPx: 12, // blur-in cap (law 7)
+  defaultTravelPx: 16, // default entrance offset
+  maxTravelPx: 48, // element entrances, not camera moves
+  referenceTravelPx: 200, // distance that maps to DUR.base (law 9)
+  motionBlurFrameWidthShare: 0.15, // needs motion blur above this travel within DUR.fast (law 10)
+} as const;
+
+/** Minimum on-screen time for readable text (law 11). */
+export const READ = {
+  minHoldMs: 900,
+  baseMs: 250,
+  perWordMs: 55,
+} as const;
+
+/** Film-style motion blur for camera moves and fast elements (law 10). */
+export const BLUR = {
+  shutterAngle: 180, // classic film look: blur spans half the frame interval
+  samples: 10, // render cost multiplier while active
+} as const;
+
+/** Scene handoffs overlap, never gap (continuity rules). */
+export const TRANSITION = {
+  minOverlapMs: 133,
+  idealOverlapMs: 200,
+  sfxLeadMs: 133, // whoosh starts this early
+  sfxTailMs: 267, // and tails this long after the change
+} as const;

package/template/src/design/overlays.ts

@@ -0,0 +1,121 @@
+import {PALETTE} from './tokens';
+
+/**
+ * FILM OVERLAYS — grain, halation, light leaks, gate weave, letterbox.
+ *
+ * These exist to add the texture a camera and a lens would have added, not to put a
+ * filter on top of a video. Every strength is a token, and the defaults are deliberately
+ * low: the test is that someone notices the footage looks richer, never that it looks
+ * "filtered". If a viewer can name the effect, it is too strong.
+ *
+ * Add a look here, add its name to templates/BRIEF.md, and the user can ask for it by name.
+ */
+
+export type OverlayStrength = 'off' | 'subtle' | 'medium' | 'strong';
+
+const SCALE: Record<OverlayStrength, number> = {off: 0, subtle: 0.5, medium: 1, strong: 1.6};
+export const strengthScale = (s: OverlayStrength): number => SCALE[s];
+
+/**
+ * Grain lives at low opacity and a coarse-ish cell, so it survives platform compression.
+ *
+ * It composites normally rather than with `overlay`/`soft-light`. Those blend modes fade
+ * to nothing at both ends of the range, and this palette is cream and ink with almost no
+ * midtones — measured on a flat cream area, overlay grain came out at a standard deviation
+ * of 0.000, i.e. the layer did nothing at all. Normal blending costs a barely-perceptible
+ * pull toward grey and works the same on any footage.
+ */
+export const GRAIN = {
+  /**
+   * Opacity at 'medium'. Multiplied by the strength scale.
+   *
+   * Measured at this value: ~0.7 Y stddev on a flat area at 'medium', ~1.0 at 'strong' —
+   * enough to stop flat areas banding, which is the job. It is deliberately not louder:
+   * normal blending pulls the frame toward mid grey, so grain is paid for in black level
+   * (blacks measured 18 → 25 at 'medium'). Turn it up per shot with the `grain` prop if a
+   * nostalgia moment is worth the milkier blacks; do not raise this default to get there.
+   */
+  opacity: 0.045,
+  /** feTurbulence base frequency — higher is finer. Fine grain is eaten by the encoder. */
+  frequency: 0.72,
+  /** The noise plate renders at this fraction of the frame, then scales up. Keeps it cheap. */
+  renderScale: 0.28,
+  /**
+   * New seed every N frames. Real film holds its grain for an exposure, but anything above
+   * 1 means the frame is byte-identical to the one before it, which motion-check reports as
+   * a STUTTER on every other frame — so every video using a grainy look would fail its own
+   * verification gate. At this opacity a fresh seed each frame is invisible anyway.
+   */
+  framesPerSeed: 1,
+} as const;
+
+/**
+ * Halation: highlights bleeding into what is next to them, warm, never the whole frame.
+ *
+ * The bloom plate is a copy of the scene, crushed so that everything but the brightest
+ * areas goes to black, then blurred and screened back on. The crush is the whole trick —
+ * screen blending with black is a no-op, so the darks stay exactly where they were. Skip
+ * it and a cream-heavy frame blooms end to end and the blacks lift to brown, which reads
+ * as a filter rather than as a lens.
+ */
+export const HALATION = {
+  /** Blur radius of the bloom plate, in px at 1080 wide. */
+  blurPx: 12,
+  /** Crush: contrast pushes the mids down, brightness sets how much highlight survives. */
+  contrast: 2.6,
+  brightness: 0.72,
+  /** Warmth of the bleed — film halation is red/orange, never blue. */
+  sepia: 0.45,
+  saturate: 1.8,
+  /** Opacity at 'medium'. */
+  opacity: 0.28,
+} as const;
+
+/**
+ * A slow wash of light across the frame, as if it crept past the gate. A real leak enters
+ * from an edge, so this one is biased to the top and kept small — a glow in the middle of
+ * the frame is not a leak, it is a smudge.
+ */
+export const LEAK = {
+  opacity: 0.1,
+  /** How long one drift cycle takes, in seconds. Slow enough that it is never a "move". */
+  cycleSeconds: 9,
+  warm: 'rgba(255, 186, 120, 1)',
+  cool: 'rgba(255, 238, 198, 1)',
+} as const;
+
+/** Gate weave: the sub-pixel drift of film through a projector. Continuous, never random. */
+export const WEAVE = {
+  /** Maximum translation in px at 'medium'. Anything above ~3px reads as a shake. */
+  translatePx: 1.6,
+  /** Maximum rotation in degrees. */
+  rotateDeg: 0.06,
+  /** Two slow frequencies, so the drift never repeats on an obvious loop. */
+  hz: [0.19, 0.31] as const,
+} as const;
+
+export const LETTERBOX = {
+  /** Bar height as a fraction of frame height, per named ratio on a 9:16 frame. */
+  ratio: {cinema: 0.11, wide: 0.07},
+  color: PALETTE.ink900,
+} as const;
+
+export type FilmLook = 'none' | 'clean' | 'film' | 'super8' | 'cinema';
+
+export const FILM_PRESETS: Record<
+  FilmLook,
+  {
+    grain: OverlayStrength;
+    halation: OverlayStrength;
+    leak: OverlayStrength;
+    weave: OverlayStrength;
+    letterbox: keyof typeof LETTERBOX.ratio | 'off';
+    note: string;
+  }
+> = {
+  none: {grain: 'off', halation: 'off', leak: 'off', weave: 'off', letterbox: 'off', note: 'Graphics, screen recordings, anything with text as the subject.'},
+  clean: {grain: 'subtle', halation: 'off', leak: 'off', weave: 'off', letterbox: 'off', note: 'Default for talking head. Just enough grain to stop flat areas banding.'},
+  film: {grain: 'medium', halation: 'subtle', leak: 'off', weave: 'subtle', letterbox: 'off', note: 'B-roll and travel. The one to reach for first.'},
+  super8: {grain: 'strong', halation: 'medium', leak: 'medium', weave: 'medium', letterbox: 'off', note: 'Memory / nostalgia moments only. Never a whole video.'},
+  cinema: {grain: 'subtle', halation: 'medium', leak: 'off', weave: 'off', letterbox: 'cinema', note: 'A held, wide, quiet shot. Bars plus bloom, nothing that moves.'},
+};

package/template/src/design/presets.ts

@@ -0,0 +1,65 @@
+import type {Dur} from './motion';
+import {COLOR, RADIUS} from './tokens';
+
+/**
+ * PRESETS — named looks and transitions, so a brief can say "whip pan here" or
+ * "block captions" instead of describing it every time.
+ *
+ * Every preset is built from the motion tokens, so they all obey the same laws.
+ * Add one here, add its name to templates/BRIEF.md, and it becomes something the
+ * user can ask for by name.
+ */
+
+export type TransitionKind =
+  /** Fast pan with motion blur — energy, no meaning. Good between unrelated shots. */
+  | 'whipPan'
+  /** The new scene pushes the old one out. Direction carries the story forward. */
+  | 'push'
+  /** A soft-edged wipe reveals the next scene. Calm, premium. */
+  | 'maskWipe'
+  /** A hard cut to a solid accent screen, then to the next scene. A burst, used on a phrase. */
+  | 'colourFlip'
+  /** Both scenes share a shape or motion; the cut lands inside the movement. */
+  | 'matchCut'
+  /** Quick dip through the background colour. The quietest way to change subject. */
+  | 'dip';
+
+export type TransitionDirection = 'left' | 'right' | 'up' | 'down';
+
+export const TRANSITION_PRESETS: Record<
+  TransitionKind,
+  {dur: Dur; travel: number; blur: boolean; scale?: number; flash?: string; note: string}
+> = {
+  whipPan: {dur: 'fast', travel: 1.0, blur: true, note: 'Between unrelated shots. Never twice in a row.'},
+  push: {dur: 'base', travel: 1.0, blur: true, note: 'Moving forward through a list or a sequence.'},
+  maskWipe: {dur: 'slow', travel: 0.35, blur: false, note: 'Calm reveal. Pairs with a soft sound.'},
+  colourFlip: {dur: 'instant', travel: 0, blur: false, flash: COLOR.accent, note: 'A burst on a phrase. Two or three, then back to smooth.'},
+  matchCut: {dur: 'base', travel: 0.12, blur: true, scale: 1.08, note: 'Only when both shots share a shape or a direction.'},
+  dip: {dur: 'fast', travel: 0, blur: false, flash: COLOR.surfaceAlt, note: 'Changing subject without drama.'},
+};
+
+export type CaptionVariant =
+  /** Crisp white with a soft shadow. The default. */
+  | 'clean'
+  /** Each word on an accent block. Loud, good on busy footage. */
+  | 'block'
+  /** The spoken word is accent-coloured, the rest stays white. */
+  | 'highlight'
+  /** Words arrive with a small scale pop. Use on fast, energetic cuts. */
+  | 'pop';
+
+export const CAPTION_PRESETS: Record<
+  CaptionVariant,
+  {activeColor?: string; background?: string; padding?: string; radius?: number; scaleFrom?: number; note: string}
+> = {
+  clean: {note: 'Default. Works over almost anything.'},
+  block: {
+    background: COLOR.accent,
+    activeColor: COLOR.fg,
+    padding: '0.06em 0.22em',
+    radius: RADIUS.sm,
+    note: 'Busy or bright footage, where white alone would get lost.',
+  },
+  highlight: {activeColor: COLOR.accent, note: 'Keeps the eye on the word being said right now.'},
+  pop: {scaleFrom: 0.94, note: 'Fast edits. Do not combine with heavy motion behind the text.'},
+};