@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/templates/default/openvidstudio-core/src/TransitionOverlay.tsx

@@ -0,0 +1,194 @@
+// Transition overlays: drawn ON TOP of a hard cut, never in place of it.
+//
+// A cut moves no scene and shifts no beat boundary, so the Series, the bar-snapped timing and
+// every audio join stay exactly where beats.json put them. stitch_composition mounts one of
+// these in a Sequence centred on a beat's start; the first frame of the new scene is the
+// overlay's peak, which is why a hard cut underneath it can't be seen. The overlay is a pure
+// function of frame and of the colour tokens, so it renders the same on every machine and
+// follows a brand applied with applyBrand.
+
+import React from "react";
+import { AbsoluteFill, Easing, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
+import { E } from "./motion";
+import { color } from "./tokens";
+
+export type TransitionType = "fade" | "whip" | "push" | "wipe" | "light-leak";
+
+/** Every name beats.json's `transition` field may carry, "cut" being the absence of an overlay. */
+export const TRANSITION_TYPES = ["cut", "whip", "fade", "push", "wipe", "light-leak"] as const;
+
+/**
+ * How present the overlay is at a frame: 0 at its first and last frames, 1 on the cut frame
+ * (the middle of the overlay). Reaching 0 one frame early on each side, rather than on the
+ * frame the Sequence unmounts, is what keeps the overlay from popping off: the last frame it
+ * is mounted on is already invisible.
+ */
+export function transitionEnvelope(frame: number, length: number): number {
+  const half = length / 2;
+  const reach = Math.max(1, half - 1);
+  return 1 - Math.min(1, Math.abs(frame - half) / reach);
+}
+
+/** "#rgb" or "#rrggbb" to [r, g, b], or null when the token is not plain hex. */
+function parseHex(hex: string): [number, number, number] | null {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})/i.exec(hex.trim());
+  if (!m) return null;
+  const h = m[1]!.length === 3 ? m[1]!.split("").map((c) => c + c).join("") : m[1]!;
+  return [0, 2, 4].map((i) => Number.parseInt(h.slice(i, i + 2), 16)) as [number, number, number];
+}
+
+function withAlpha(hex: string, alpha: number): string {
+  const rgb = parseHex(hex);
+  return rgb ? `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${alpha})` : hex;
+}
+
+/** Hue in degrees of a hex colour, or a warm orange when the token is not plain hex. */
+function hueOf(hex: string): number {
+  const rgb = parseHex(hex);
+  if (!rgb) return 28;
+  const [r, g, b] = rgb.map((v) => v / 255) as [number, number, number];
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  if (max === min) return 28;
+  const d = max - min;
+  const h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+  return (h * 60 + 360) % 360;
+}
+
+const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
+
+/** Which way a travelling panel is on its way: in before the cut, out after it. */
+const side = (frame: number, length: number) => (frame < length / 2 ? 1 : -1);
+
+/**
+ * A transition drawn over the cut. Mount it in a Sequence that starts `length / 2` frames
+ * before the cut, `layout="none"`; the cut is then local frame `length / 2`.
+ *
+ *  - fade: dips to the brand background and back.
+ *  - whip: heavy backdrop blur and an accent streak that crosses the frame at the cut.
+ *  - push: a panel slides in from the right, covers the frame at the cut, leaves to the left.
+ *  - wipe: a skewed band with an accent edge crosses left to right.
+ *  - light-leak: warm light, hue taken from the accent, drifts across and peaks at the cut.
+ *
+ * `length` is the overlay's total frames, centred on the cut. It defaults to the surrounding
+ * Sequence's length, which is what stitch_composition sizes it to.
+ */
+export const TransitionOverlay: React.FC<{ type: TransitionType | "cut"; length?: number }> = ({ type, length }) => {
+  const frame = useCurrentFrame();
+  const { width, height, durationInFrames } = useVideoConfig();
+  const total = length ?? durationInFrames;
+  const k = clamp01(transitionEnvelope(frame, total));
+  if (k <= 0) return null;
+
+  if (type === "fade") {
+    return <AbsoluteFill style={{ background: color.bg0, opacity: clamp01(E.drift(k)), pointerEvents: "none" }} />;
+  }
+
+  if (type === "whip") {
+    // The ease makes the blur arrive late and leave early, so the frames beside the cut are
+    // the ones that sell the speed.
+    const kw = clamp01(E.whip(k));
+    const sweep = interpolate(frame, [0, total], [-0.4, 1.4], { easing: Easing.inOut(Easing.cubic), extrapolateLeft: "clamp", extrapolateRight: "clamp" });
+    const accent = color.accent;
+    return (
+      <AbsoluteFill
+        style={{
+          pointerEvents: "none",
+          backdropFilter: `blur(${Math.round(64 * kw * 10) / 10}px)`,
+          WebkitBackdropFilter: `blur(${Math.round(64 * kw * 10) / 10}px)`,
+        }}
+      >
+        <AbsoluteFill style={{ background: withAlpha(accent, 0.28 * kw) }} />
+        <div
+          style={{
+            position: "absolute",
+            top: -height * 0.1,
+            bottom: -height * 0.1,
+            left: `${sweep * 100}%`,
+            width: "58%",
+            transform: "translateX(-50%) skewX(-18deg)",
+            opacity: clamp01(kw * 1.5),
+            mixBlendMode: "screen",
+            background: `linear-gradient(90deg, ${withAlpha(accent, 0)} 0%, ${withAlpha(accent, 0.75)} 34%, rgba(255,255,255,0.95) 50%, ${withAlpha(accent, 0.75)} 66%, ${withAlpha(accent, 0)} 100%)`,
+          }}
+        />
+      </AbsoluteFill>
+    );
+  }
+
+  if (type === "push" || type === "wipe") {
+    // The wipe uses the symmetric ease: a ballistic one covers the frame in two frames and reads as
+    // a black flash rather than a band crossing it.
+    const s = clamp01(type === "push" ? E.cinematic(k) : E.drift(k));
+    if (type === "push") {
+      // A panel exactly the frame's size: fully covering at the cut, fully off screen at the edges.
+      const tx = side(frame, total) * (1 - s) * width;
+      return (
+        <AbsoluteFill style={{ pointerEvents: "none", overflow: "hidden" }}>
+          <div
+            style={{
+              position: "absolute",
+              inset: 0,
+              transform: `translateX(${tx}px)`,
+              background: color.bg1,
+              boxShadow: `${-side(frame, total) * 60}px 0 120px rgba(0,0,0,0.5)`,
+            }}
+          >
+            <div
+              style={{
+                position: "absolute",
+                top: 0,
+                bottom: 0,
+                ...(side(frame, total) > 0 ? { left: 0 } : { right: 0 }),
+                width: 8,
+                background: color.accent,
+              }}
+            />
+          </div>
+        </AbsoluteFill>
+      );
+    }
+    // Wipe: a band wide enough that its skewed corners still cover the frame at the cut.
+    const skew = 12;
+    const lean = Math.tan((skew * Math.PI) / 180) * height;
+    const bandWidth = width + lean * 2 + 40;
+    const travel = (width + bandWidth) / 2 + lean / 2 + 20;
+    const tx = -side(frame, total) * (1 - s) * travel;
+    const edge = 10;
+    return (
+      <AbsoluteFill style={{ pointerEvents: "none", overflow: "hidden" }}>
+        <div
+          style={{
+            position: "absolute",
+            top: -4,
+            bottom: -4,
+            left: (width - bandWidth) / 2,
+            width: bandWidth,
+            transform: `translateX(${tx}px) skewX(${-skew}deg)`,
+            background: color.bg0,
+          }}
+        >
+          <div style={{ position: "absolute", top: 0, bottom: 0, right: 0, width: edge, background: color.accent, boxShadow: `0 0 40px ${withAlpha(color.accent, 0.8)}` }} />
+          <div style={{ position: "absolute", top: 0, bottom: 0, left: 0, width: edge, background: color.accent, opacity: 0.6 }} />
+        </div>
+      </AbsoluteFill>
+    );
+  }
+
+  if (type === "light-leak") {
+    const o = clamp01(E.drift(k));
+    const t = frame / Math.max(1, total);
+    const hue = hueOf(color.accent);
+    const hsla = (h: number, sat: number, light: number, a: number) => `hsla(${Math.round(h) % 360}, ${sat}%, ${light}%, ${a})`;
+    // Three overlapping lights that slide in opposite directions, plus a hot core that carries
+    // the peak, so the frame at the cut is bright enough to hide whatever is underneath.
+    const a = `radial-gradient(ellipse 85% 120% at ${12 + 70 * t}% ${28 + 22 * Math.sin(t * Math.PI)}%, ${hsla(hue, 100, 62, 0.95)} 0%, ${hsla(hue, 100, 55, 0.55)} 38%, ${hsla(hue, 100, 50, 0)} 74%)`;
+    const b = `radial-gradient(ellipse 75% 110% at ${96 - 76 * t}% ${74 - 20 * Math.sin(t * Math.PI)}%, ${hsla(hue + 28, 100, 60, 0.9)} 0%, ${hsla(hue + 28, 100, 52, 0.5)} 40%, ${hsla(hue + 28, 100, 50, 0)} 72%)`;
+    const core = `radial-gradient(ellipse 130% 160% at 50% 50%, ${hsla(hue + 14, 95, 86, 0.92)} 0%, ${hsla(hue + 14, 100, 70, 0.7)} 55%, ${hsla(hue + 14, 100, 60, 0.4)} 100%)`;
+    return (
+      <AbsoluteFill style={{ pointerEvents: "none", mixBlendMode: "screen", opacity: o, background: `${a}, ${b}, ${core}` }} />
+    );
+  }
+
+  return null;
+};

package/templates/default/openvidstudio-core/src/atmosphere.tsx

@@ -0,0 +1,109 @@
+// Background and transition primitives: soft drifting color fields, a faint texture grid,
+// a hit flash, a hard black hold, and letterbox bars. Ported from reference/launch-video's
+// lib/fx.tsx (minus PixelWipe, which pairs with the pixel-grid family in pixel.tsx) and
+// generalized: colors come from this package's tokens by default, not one video's palette.
+
+import React from "react";
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import { E, tween } from "./motion";
+import { color } from "./tokens";
+
+/** Soft drifting color fields behind everything. One radial blob per color, slowly orbiting. */
+export const Atmosphere: React.FC<{
+  intensity?: number;
+  colors?: string[];
+  seed?: number;
+}> = ({ intensity = 1, colors = [color.accent, color.accentAlt, color.success, color.warn], seed = 2 }) => {
+  const frame = useCurrentFrame();
+  return (
+    <AbsoluteFill style={{ overflow: "hidden" }}>
+      {colors.map((c, i) => {
+        const ph = frame / 240 + i * 1.7 + seed;
+        const x = 50 + Math.sin(ph) * 32;
+        const y = 50 + Math.cos(ph * 0.8 + i) * 28;
+        return (
+          <div
+            key={i}
+            style={{
+              position: "absolute",
+              left: `${x}%`,
+              top: `${y}%`,
+              width: 900,
+              height: 900,
+              marginLeft: -450,
+              marginTop: -450,
+              borderRadius: "50%",
+              background: `radial-gradient(circle, ${c}${Math.round(34 * intensity).toString(16).padStart(2, "0")} 0%, transparent 65%)`,
+              filter: "blur(40px)",
+            }}
+          />
+        );
+      })}
+    </AbsoluteFill>
+  );
+};
+
+/**
+ * A faint dot grid on the stage, for a texture pass behind constructed (non-capture) panels.
+ * Covers the composition by default (1920x1080 in 16:9, 1080x1920 in 9:16); w/h override it for
+ * a grid that fills a bigger stage than the frame.
+ */
+export const DotGrid: React.FC<{
+  gap?: number;
+  color?: string;
+  opacity?: number;
+  w?: number;
+  h?: number;
+}> = ({ gap = 36, color: dotColor = "#ffffff", opacity = 0.05, w, h }) => {
+  const video = useVideoConfig();
+  return (
+    <div
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: w ?? video.width,
+        height: h ?? video.height,
+        opacity,
+        backgroundImage: `radial-gradient(${dotColor} 1.4px, transparent 1.6px)`,
+        backgroundSize: `${gap}px ${gap}px`,
+      }}
+    />
+  );
+};
+
+/** Brief exposure flash on a hard hit (a cut, a reveal landing). */
+export const Flash: React.FC<{
+  at: number;
+  color?: string;
+  strength?: number;
+  dur?: number;
+}> = ({ at, color: flashColor = "#ffffff", strength = 0.55, dur = 10 }) => {
+  const frame = useCurrentFrame();
+  if (frame < at || frame > at + dur) return null;
+  const o = tween(frame, [at, at + dur], [strength, 0], E.cinematic);
+  return <AbsoluteFill style={{ background: flashColor, opacity: o, mixBlendMode: "screen", pointerEvents: "none" }} />;
+};
+
+/** Holds solid black (a hard cut to nothing) from `from` until `to`, or forever if omitted. */
+export const Black: React.FC<{ from: number; to?: number }> = ({ from, to }) => {
+  const frame = useCurrentFrame();
+  if (frame < from || (to !== undefined && frame >= to)) return null;
+  return <AbsoluteFill style={{ background: "#000" }} />;
+};
+
+/**
+ * Letterbox bars for a cinematic moment. `amount` scales the bar height, 1 = 64px on a 1080px
+ * tall frame. The bars are a share of the frame height (64/1080), so a 1920px tall 9:16 frame gets
+ * bars of about 114px and a 1080p frame gets exactly the 64px it always did.
+ */
+export const Letterbox: React.FC<{ amount?: number }> = ({ amount = 1 }) => {
+  const { height } = useVideoConfig();
+  const bar = 64 * amount * (height / 1080);
+  return (
+    <>
+      <div style={{ position: "absolute", left: 0, right: 0, top: 0, height: bar, background: "#000" }} />
+      <div style={{ position: "absolute", left: 0, right: 0, bottom: 0, height: bar, background: "#000" }} />
+    </>
+  );
+};

package/templates/default/openvidstudio-core/src/camera.tsx

@@ -22,7 +22,10 @@ export type CamKeyframe = {
 
 type CamState = Required<Omit<CamKeyframe, "easing" | "frame">>;
 
-const CameraContext = createContext<CamState | null>(null);
+/** What useCamera() returns: the camera plus the size of the stage it is looking at. */
+export type CameraInfo = CamState & { stageWidth: number; stageHeight: number };
+
+const CameraContext = createContext<CameraInfo | null>(null);
 
 const resolve = (kfs: CamKeyframe[], frame: number): CamState => {
   const sorted = [...kfs].sort((a, b) => a.frame - b.frame);
@@ -62,29 +65,75 @@ const resolve = (kfs: CamKeyframe[], frame: number): CamState => {
   };
 };
 
+/** Where the camera is at `frame`, by the same interpolation CameraRig renders with. */
+export const resolveCamera = resolve;
+
+/** The rig's CSS perspective, in px. Layer's depth compensation and projectToScreen both use it. */
+export const CAMERA_PERSPECTIVE = 1400;
+
+/**
+ * Where a point on the stage lands on screen, through the same chain of transforms CameraRig
+ * applies (translate to the frame centre, rotateX/Y/Z, scale, translate by the focal point) and
+ * the same perspective. Pure, so overlays that must line up with the picture (a blur mask, a
+ * protected region) can place themselves without measuring the DOM.
+ */
+export const projectToScreen = (
+  cam: Pick<CamState, "x" | "y" | "scale" | "rotX" | "rotY" | "rotZ">,
+  viewportWidth: number,
+  viewportHeight: number,
+  px: number,
+  py: number,
+): { x: number; y: number } => {
+  const rad = (deg: number) => (deg * Math.PI) / 180;
+  let x = (px - cam.x) * cam.scale;
+  let y = (py - cam.y) * cam.scale;
+  let z = 0;
+  // CSS applies the transform list right to left, so the point meets rotateZ, then rotateY, then rotateX.
+  const cz = Math.cos(rad(cam.rotZ));
+  const sz = Math.sin(rad(cam.rotZ));
+  [x, y] = [x * cz - y * sz, x * sz + y * cz];
+  const cy = Math.cos(rad(cam.rotY));
+  const sy = Math.sin(rad(cam.rotY));
+  [x, z] = [x * cy + z * sy, -x * sy + z * cy];
+  const cx = Math.cos(rad(cam.rotX));
+  const sx = Math.sin(rad(cam.rotX));
+  [y, z] = [y * cx - z * sx, y * sx + z * cx];
+  const k = CAMERA_PERSPECTIVE / Math.max(1, CAMERA_PERSPECTIVE - z);
+  return { x: viewportWidth / 2 + x * k, y: viewportHeight / 2 + y * k };
+};
+
 export const CameraRig: React.FC<{
   keyframes: CamKeyframe[];
   /** stage size in px; content is laid out at this size, camera crops into it */
   stageWidth?: number;
   stageHeight?: number;
+  /**
+   * The size of the window the camera looks through. Defaults to the composition's own size;
+   * a rig nested inside a smaller box (DirectedShot) passes that box's size instead.
+   */
+  viewportWidth?: number;
+  viewportHeight?: number;
   children: React.ReactNode;
-}> = ({ keyframes, stageWidth = 1920, stageHeight = 1080, children }) => {
+}> = ({ keyframes, stageWidth = 1920, stageHeight = 1080, viewportWidth, viewportHeight, children }) => {
   const frame = useCurrentFrame();
-  const { width, height } = useVideoConfig();
+  const video = useVideoConfig();
+  const width = viewportWidth ?? video.width;
+  const height = viewportHeight ?? video.height;
   const cam = resolve(keyframes, frame);
 
   return (
-    <CameraContext.Provider value={cam}>
+    <CameraContext.Provider value={{ ...cam, stageWidth, stageHeight }}>
       <div
         style={{
           width,
           height,
           overflow: "hidden",
-          perspective: 1400,
+          perspective: CAMERA_PERSPECTIVE,
           perspectiveOrigin: "50% 50%",
         }}
       >
         <div
+          data-ovs-camera-stage=""
           style={{
             width: stageWidth,
             height: stageHeight,
@@ -109,9 +158,21 @@ export const CameraRig: React.FC<{
 
 export const useCamera = () => useContext(CameraContext);
 
+/** How far back (in px) one unit of Layer depth sits. Larger is a deeper scene and stronger parallax. */
+export const Z_STEP = 170;
+
 /**
- * Parallax + depth-of-field layer. depth 0 = focal plane (sharp, no parallax).
- * Positive depth = "behind" (moves less, blurred). Negative = foreground (moves more, blurred).
+ * A layer at a place in space: depth 0 is the focal plane, positive depth sits behind it, negative
+ * depth in front. Parallax comes from the rig's real CSS perspective, so a layer 1 unit back moves
+ * 1400 / (1400 + 170) = 0.89 as far as the focal plane when the camera pans, 2 units back 0.80, and
+ * a foreground layer moves more than 1.
+ *
+ * Each layer is scaled about the stage centre by the amount the perspective shrinks (or grows) it,
+ * so with the camera at rest on the stage centre every depth shows the same picture. Layers also
+ * blur with distance from the focal plane (`maxBlur` px per unit of depth; 0 turns it off).
+ *
+ * Layers have to be direct children of the rig's stage: a plain wrapper div in between flattens
+ * the depth. Depth orders layers in space, so a layer behind stays behind however the JSX is ordered.
  */
 export const Layer: React.FC<{
   depth?: number;
@@ -120,17 +181,16 @@ export const Layer: React.FC<{
   style?: React.CSSProperties;
   children: React.ReactNode;
 }> = ({ depth = 0, maxBlur = 10, style, children }) => {
-  const cam = useCamera();
-  const parallax = 0.06; // fraction of camera offset transferred per unit depth
-  const dx = cam ? (cam.x - 960) * depth * parallax : 0;
-  const dy = cam ? (cam.y - 540) * depth * parallax : 0;
   const blur = Math.abs(depth) * maxBlur;
+  const z = -depth * Z_STEP;
+  // Behind, the perspective divides by (P + |z|) / P; scaling by exactly that cancels it at rest.
+  const compensate = (CAMERA_PERSPECTIVE - z) / CAMERA_PERSPECTIVE;
   return (
     <div
       style={{
         position: "absolute",
         inset: 0,
-        transform: `translate(${dx}px, ${dy}px)`,
+        transform: depth === 0 ? undefined : `translateZ(${z}px) scale(${compensate})`,
         filter: blur > 0.2 ? `blur(${blur.toFixed(1)}px)` : undefined,
         ...style,
       }}

package/templates/default/openvidstudio-core/src/designSystem.ts

@@ -0,0 +1,179 @@
+// Design system as code (C2). A per-video DesignSystem is a self-contained object a scene
+// reads from directly, layered ON TOP of the global brand tokens (tokens.ts's color/font,
+// already mutated by applyBrand if extract_brand ran) rather than replacing them: brand
+// tokens seed a design system, they don't dictate it. The agent writes
+// src/videos/<name>/design.ts calling defineDesignSystem(overrides) from the brief
+// (C1) -- a signature motif derived from the brand, a type pairing and scale, the layout
+// grid, texture, transition vocabulary and a motion personality. Components (C4's
+// primitive library, hand-authored bespoke scenes) import that video's design.ts and read
+// from it; validators (C7) check contrast and minimum text size against its own typeScale,
+// not a hardcoded global.
+//
+// Same "read at call time, not module scope" rule as tokens.ts's font/color: a design
+// system built at module scope in design.ts runs before applyBrand has mutated anything
+// it seeds from, so design.ts should export a DesignSystem *value* built by calling
+// defineDesignSystem() at its own module scope is fine (design.ts is imported after
+// brand.ts, same Root.tsx import order tokens.ts already relies on) -- the rule that
+// matters is: don't build a SECOND, earlier design system before brand.ts has run.
+
+import { color as defaultColor, font as defaultFont, type Brand } from "./tokens";
+
+export interface TypeScale {
+  /** [min, max] px, for the biggest on-screen text: a hook's slammed title, a stat callout. */
+  display: [number, number];
+  /** [min, max] px, section headers and card titles. */
+  headline: [number, number];
+  /** [min, max] px, body copy and captions. */
+  body: [number, number];
+  /** [min, max] px, terminal/code text. */
+  mono: [number, number];
+}
+
+export interface LayoutGrid {
+  /** Side margins, px. DEFAULT_GRID is the 1920x1080 stage's; defineDesignSystem scales it to `stage`. */
+  marginX: number;
+  marginTop: number;
+  /** Bottom margin, reserved for a ChapterHud or caption bar even when neither is present. */
+  marginBottom: number;
+}
+
+export type CameraEnergy = "subtle" | "normal" | "energetic";
+
+export interface MotionPersonality {
+  /** Name of an E.* preset from motion.ts (e.g. "drift", "pop", "spring"), looked up by the
+   * component, not a function reference, so a DesignSystem stays JSON-serializable. */
+  easing: string;
+  /** Milliseconds between staggered element reveals (word-by-word text, card lists). */
+  staggerMs: number;
+  cameraEnergy: CameraEnergy;
+  /** [min, max] seconds a shot holds before the next cut, per STYLE.md's cut-rhythm rule. */
+  cutRhythmSeconds: [number, number];
+}
+
+/**
+ * A signature motif lifted from the brand: the visual idea a transition or a recurring
+ * shape expresses. "pixel-grid" pairs with PixelWipe/PixelLogo (C4) for a brand whose logo
+ * is built from square rects; the others are named for extract_brand (A10) to map a brand's
+ * shape language onto, and for a bespoke scene to key off deliberately. "void-spark" is Supernova
+ * mode's: a flat dark field with one luminous point (see @openvidstudio/stem).
+ */
+export type Motif = "pixel-grid" | "rounded-soft" | "geometric" | "editorial" | "void-spark";
+
+export interface Texture {
+  /** 0-1. STYLE.md's default range is 0.04-0.06. */
+  grainOpacity: number;
+  /** 0-1 edge darkening. STYLE.md's default range is 0.25-0.40. */
+  vignetteStrength: number;
+}
+
+export interface DesignSystem {
+  color: typeof defaultColor;
+  font: typeof defaultFont;
+  typeScale: TypeScale;
+  grid: LayoutGrid;
+  motif: Motif;
+  motion: MotionPersonality;
+  /** Named transitions this video actually uses, in preference order. A bespoke scene or a
+   * motif-aware primitive (C4) picks from this list rather than inventing a new one per cut. */
+  transitions: string[];
+  texture: Texture;
+}
+
+export const DEFAULT_TYPE_SCALE: TypeScale = {
+  display: [120, 220],
+  headline: [56, 84],
+  body: [26, 34],
+  mono: [15, 22],
+};
+
+/** The stage a design system's margins are laid out for, px. */
+export interface StageSize {
+  width: number;
+  height: number;
+}
+
+export const DEFAULT_STAGE: StageSize = { width: 1920, height: 1080 };
+
+export const DEFAULT_GRID: LayoutGrid = {
+  marginX: 150,
+  marginTop: 130,
+  marginBottom: 110,
+};
+
+/**
+ * DEFAULT_GRID scaled to another stage: side margins follow the width, top and bottom follow the
+ * height, so the proportions of a 1920x1080 layout carry over. 1920x1080 gives DEFAULT_GRID
+ * back exactly; a 1080x1920 reel gets 84 / 231 / 196. A reel that has to clear Instagram's UI
+ * wants more at the bottom than that (see PIPELINE.md's native vertical section), which is what
+ * the `grid` override is for.
+ */
+export function gridForStage(stage: StageSize): LayoutGrid {
+  if (!(stage.width > 0) || !(stage.height > 0) || !Number.isFinite(stage.width) || !Number.isFinite(stage.height)) {
+    throw new Error(`defineDesignSystem: stage must be a positive width and height in px, got ${stage.width}x${stage.height}.`);
+  }
+  return {
+    marginX: Math.round((DEFAULT_GRID.marginX * stage.width) / DEFAULT_STAGE.width),
+    marginTop: Math.round((DEFAULT_GRID.marginTop * stage.height) / DEFAULT_STAGE.height),
+    marginBottom: Math.round((DEFAULT_GRID.marginBottom * stage.height) / DEFAULT_STAGE.height),
+  };
+}
+
+export const DEFAULT_MOTION: MotionPersonality = {
+  easing: "drift",
+  staggerMs: 60,
+  cameraEnergy: "normal",
+  cutRhythmSeconds: [1.5, 5],
+};
+
+export const DEFAULT_TEXTURE: Texture = {
+  grainOpacity: 0.05,
+  vignetteStrength: 0.3,
+};
+
+export const DEFAULT_TRANSITIONS = ["cut", "whip", "fade", "push", "wipe", "light-leak"];
+
+/**
+ * Builds a video's DesignSystem. Call this from src/videos/<name>/design.ts with whatever
+ * the brief (C1) decided to override; everything else falls back to the current brand
+ * tokens (color/font, already brand-applied if extract_brand ran before this module
+ * evaluates) and the STYLE.md-matching defaults above. The result is a plain object, not a
+ * live binding into tokens.ts -- a design system is frozen at the point design.ts is
+ * imported, which is deliberate: unlike the global brand tokens (meant to apply uniformly
+ * forever), a per-video design system is a one-time creative decision, not something a
+ * later applyBrand call should silently reach into.
+ *
+ * `stage` is the frame the video renders at (1080x1920 for a native vertical reel); the layout
+ * grid's margins are scaled to it. Leave it out for 1920x1080. An explicit `grid` wins.
+ */
+export function defineDesignSystem(overrides: Partial<DesignSystem> & { stage?: StageSize } = {}): DesignSystem {
+  return {
+    color: { ...defaultColor, ...overrides.color },
+    font: { ...defaultFont, ...overrides.font },
+    typeScale: { ...DEFAULT_TYPE_SCALE, ...overrides.typeScale },
+    grid: { ...gridForStage(overrides.stage ?? DEFAULT_STAGE), ...overrides.grid },
+    motif: overrides.motif ?? "rounded-soft",
+    motion: { ...DEFAULT_MOTION, ...overrides.motion },
+    transitions: overrides.transitions ?? [...DEFAULT_TRANSITIONS],
+    texture: { ...DEFAULT_TEXTURE, ...overrides.texture },
+  };
+}
+
+/**
+ * Relative luminance -> WCAG contrast ratio between two hex colours, for C7's render-based
+ * validator (and anything else that wants to check a DesignSystem's own colour pairings
+ * before render, not after). Returns a value from 1 (no contrast) to 21 (black on white).
+ */
+export function contrastRatio(hexA: string, hexB: string): number {
+  const luminance = (hex: string): number => {
+    const n = hex.replace("#", "");
+    const full = n.length === 3 ? n.split("").map((c) => c + c).join("") : n;
+    const [r, g, b] = [0, 2, 4].map((i) => Number.parseInt(full.slice(i, i + 2), 16) / 255);
+    const lin = (c: number) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+  };
+  const [l1, l2] = [luminance(hexA), luminance(hexB)].sort((a, b) => b - a);
+  return (l1 + 0.05) / (l2 + 0.05);
+}
+
+/** Re-exported so design.ts can seed from a brand without importing tokens.ts directly. */
+export type { Brand };