@waits/cadence 0.2.0

package/scripts/theme.ts

@@ -0,0 +1,97 @@
+/**
+ * `cadence study` — brand extraction → a theme. Give a brand accent (or a URL to
+ * guess it from), get a full ThemeConfig JSON (+ a portable design.md) you render
+ * with `--theme-file`.
+ *
+ *   cadence study --accent "#10b981" --name emerald
+ *   cadence study --from-url https://example.com --name acme
+ *   cadence create <beats> --theme-file themes/emerald.json
+ *
+ * Screenshot → theme: this script extracts from a hex/URL only. To build a theme
+ * from a screenshot, hand the image to your agent (Claude/Cursor/Codex) — it reads
+ * the palette and writes a themes/<name>.json. See the cadence skill.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { deriveTheme } from "../src/theme/derive";
+
+const args = process.argv.slice(2);
+const flag = (n: string) => {
+  const eq = args.find((a) => a.startsWith(`${n}=`));
+  if (eq) return eq.split("=")[1];
+  const i = args.indexOf(n);
+  return i >= 0 && !args[i + 1]?.startsWith("--") ? args[i + 1] : undefined;
+};
+
+const parseHex = (hex: string) => {
+  let h = hex.replace("#", "");
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) };
+};
+const saturated = (hex: string) => {
+  const { r, g, b } = parseHex(hex);
+  const mx = Math.max(r, g, b), mn = Math.min(r, g, b), l = (mx + mn) / 2;
+  return mx - mn > 55 && l > 40 && l < 220;
+};
+
+async function accentFromUrl(url: string): Promise<string | undefined> {
+  const html = await fetch(url).then((r) => r.text());
+  const meta = html.match(/<meta[^>]+name=["']theme-color["'][^>]+content=["'](#[0-9a-fA-F]{3,6})["']/i);
+  if (meta) return meta[1].toLowerCase();
+  const counts = new Map<string, number>();
+  for (const m of html.matchAll(/#([0-9a-fA-F]{6})\b/g)) {
+    const h = "#" + m[1].toLowerCase();
+    if (saturated(h)) counts.set(h, (counts.get(h) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+}
+
+let accent = flag("--accent");
+const fromUrl = flag("--from-url");
+if (!accent && fromUrl) {
+  accent = await accentFromUrl(fromUrl);
+  console.error(accent ? `· extracted accent ${accent} from ${fromUrl}` : `· couldn't find an accent at ${fromUrl}`);
+}
+if (!accent) {
+  console.error("usage: theme.ts --accent '#10b981' [--ink #0f172a] [--paper #f6f7f9] [--gold #c08a2e] --name <name>");
+  console.error("   or: theme.ts --from-url https://example.com --name <name>");
+  process.exit(1);
+}
+
+const name = flag("--name") ?? "brand";
+const theme = deriveTheme({ name, accent, ink: flag("--ink"), paper: flag("--paper"), gold: flag("--gold") });
+
+mkdirSync("themes", { recursive: true });
+const out = flag("--out") ?? join("themes", `${name}.json`);
+writeFileSync(out, JSON.stringify(theme, null, 2));
+
+// Portable design summary — a human-readable companion to the JSON.
+const c = theme.colors;
+const designMd = `# ${name} — design
+
+Extracted accent: \`${accent}\`
+
+## Palette
+| role | color |
+|------|-------|
+| accent (signal) | \`${c.signalBlue}\` |
+| ink (text) | \`${c.ink}\` |
+| paper (bg) | \`${c.paper}\` |
+| marker | \`${c.markerPink}\` |
+| gold (version) | \`${c.gold}\` |
+| success / warning / danger | \`${c.successGreen}\` / \`${c.warningYellow}\` / \`${c.dangerRed}\` |
+
+## Fonts
+- display: ${theme.fonts.display}
+- body: ${theme.fonts.body}
+- mono: ${theme.fonts.mono}
+
+## Use
+\`\`\`
+cadence create <beats> --theme-file ${out}
+\`\`\`
+`;
+const designOut = out.replace(/\.json$/, ".design.md");
+writeFileSync(designOut, designMd);
+
+console.log(`✓ ${name} theme (accent ${accent}) → ${out}\n  design summary → ${designOut}\n  render with:  cadence create <beats> --theme-file ${out}`);

package/src/Root.tsx

@@ -0,0 +1,51 @@
+import { Composition } from "remotion";
+import { Changelog } from "./components/Changelog";
+import { MotionReel } from "./components/MotionReel";
+import { ContactSheet } from "./components/ContactSheet";
+import { changelogSchema } from "./schema/beats";
+import { prepareChangelog } from "./prepare";
+import { waitForFonts } from "./brand/fonts";
+import streams from "./content/streams.beats";
+
+const defaultProps = changelogSchema.parse(streams);
+
+export const RemotionRoot: React.FC = () => {
+  return (
+    <>
+      <Composition
+        id="Changelog"
+        component={Changelog}
+        defaultProps={defaultProps}
+        durationInFrames={210}
+        fps={30}
+        width={1920}
+        height={1080}
+        calculateMetadata={async ({ props }) => prepareChangelog(props)}
+      />
+      <Composition
+        id="MotionReel"
+        component={MotionReel}
+        durationInFrames={180}
+        fps={30}
+        width={1920}
+        height={1080}
+        calculateMetadata={async (c) => {
+          await waitForFonts();
+          return c;
+        }}
+      />
+      <Composition
+        id="ContactSheet"
+        component={ContactSheet}
+        durationInFrames={1}
+        fps={30}
+        width={1760}
+        height={1400}
+        calculateMetadata={async (c) => {
+          await waitForFonts();
+          return c;
+        }}
+      />
+    </>
+  );
+};

package/src/adapters/index.ts

@@ -0,0 +1,72 @@
+import { extractFeatures } from "./parse";
+import type { UpdateManifest } from "./types";
+
+export { extractFeatures, cleanBullet } from "./parse";
+export type { UpdateManifest, Feature } from "./types";
+
+const stripV = (v: string) => v.replace(/^v/i, "").trim();
+
+/**
+ * Drop changesets boilerplate that isn't a user-facing change: the
+ * "Updated dependencies […]" bullet plus its indented child dep-bumps
+ * (and any multi-line bracket continuation). Real entries are untouched.
+ */
+function stripChangesetNoise(md: string): string {
+  const lines = md.split("\n");
+  const out: string[] = [];
+  let depIndent = -1; // ≥0 while inside an "Updated dependencies" block
+  for (const line of lines) {
+    const bullet = /^(\s*)[-*]\s+(.*)$/.exec(line);
+    if (depIndent >= 0) {
+      if (line.trim() === "") {
+        depIndent = -1; // blank line closes the block
+      } else if ((line.match(/^\s*/)?.[0].length ?? 0) > depIndent) {
+        continue; // child dep-bump or bracket continuation — drop it
+      } else {
+        depIndent = -1; // back to sibling depth — fall through to keep this line
+      }
+    }
+    if (bullet && /^Updated dependencies\b/i.test(bullet[2])) {
+      depIndent = bullet[1].length;
+      continue;
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+/** Build a manifest from a GitHub release (notes + tag). */
+export function manifestFromReleaseBody(opts: {
+  product: string;
+  version: string;
+  body: string;
+  date?: string;
+  install?: string;
+  repoUrl?: string;
+  max?: number;
+}): UpdateManifest {
+  const { features, dropped } = extractFeatures(opts.body ?? "", opts.max ?? 6);
+  return {
+    product: opts.product,
+    version: stripV(opts.version),
+    date: opts.date,
+    features,
+    install: opts.install,
+    repoUrl: opts.repoUrl,
+    dropped,
+  };
+}
+
+/** Build a manifest from a CHANGELOG (Keep-a-Changelog / common markdown). */
+export function manifestFromChangelogText(
+  text: string,
+  opts: { product: string; install?: string; repoUrl?: string; max?: number }
+): UpdateManifest {
+  const blocks = text.split(/^##\s+/m).slice(1);
+  const first = blocks[0] ?? text;
+  const head = first.split("\n")[0] ?? "";
+  const version = stripV((head.match(/\[?([0-9][\w.\-]*)\]?/) || [])[1] ?? "");
+  const date = (head.match(/\d{4}-\d{2}-\d{2}/) || [])[0];
+  const { features, dropped } = extractFeatures(stripChangesetNoise(first), opts.max ?? 6);
+  return { product: opts.product, version, date, features, install: opts.install, repoUrl: opts.repoUrl, dropped };
+}

package/src/adapters/parse.ts

@@ -0,0 +1,65 @@
+import type { Feature } from "./types";
+
+/** Strip list markers, PR/commit refs, emoji, markdown links, and bold to plain text. */
+export function cleanBullet(line: string): string {
+  let s = line.replace(/^\s*[-*]\s+/, "");
+  // changesets prefixes entries with the originating commit hash: "1a3a80d: …"
+  s = s.replace(/^[0-9a-f]{7,40}:\s+/i, "");
+  s = s.replace(/\*\*/g, "");
+  s = s.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1"); // [text](url) → text
+  // strip trailing "(#123)" / "(abc1234)" refs, possibly repeated
+  for (let i = 0; i < 4; i++) s = s.replace(/\s*\((#\d+|[0-9a-f]{7,40})\)\s*$/i, "");
+  s = s.replace(/^[\p{Extended_Pictographic}\s]+/u, ""); // leading emoji
+  return s.trim().replace(/[.:]+$/, "").trim();
+}
+
+const FEATURE_HEADING = /feature|^\s*#+\s*(added|new|improv|enhanc|perf|✨|⚡)/i;
+const SKIP_HEADING = /chore|build|^\s*#+\s*ci|continuous|test|refactor|depend|revert|🏗|🧹|⚙|➰/i;
+const FIX_HEADING = /fix|bug|🐞|🐛|🪲|🐜/i;
+
+const KIND = (s: string): string | undefined => {
+  const m = s.match(/^(feat|fix|perf|docs|refactor|build|chore)\b/i);
+  return m ? m[1].toLowerCase() : undefined;
+};
+
+/** Is this bullet just a bold group label like "static-cost:" with no content? */
+const isGroupLabel = (s: string) => s.length <= 24 && /[:]$/.test(s.replace(/\*\*/g, "").trim());
+
+/**
+ * Pull demo-worthy features from release-note / changelog markdown. Prefers
+ * feature/added/perf sections; falls back to bug-fix or unsectioned bullets so a
+ * fix-only release still yields beats. Reports how many bullets were dropped.
+ */
+export function extractFeatures(md: string, max = 6): { features: Feature[]; dropped: number } {
+  const lines = md.split("\n");
+  let bucket: "feature" | "fix" | "skip" | "none" = "none";
+  const feature: Feature[] = [];
+  const fix: Feature[] = [];
+  const other: Feature[] = [];
+
+  for (const raw of lines) {
+    if (/^\s*#{1,6}\s/.test(raw)) {
+      bucket = SKIP_HEADING.test(raw) ? "skip" : FEATURE_HEADING.test(raw) ? "feature" : FIX_HEADING.test(raw) ? "fix" : "none";
+      continue;
+    }
+    if (!/^\s*[-*]\s+/.test(raw)) continue;
+    if (isGroupLabel(raw)) continue;
+    const title = cleanBullet(raw);
+    if (title.length < 4) continue;
+    const f: Feature = { title, kind: KIND(title) };
+    if (bucket === "skip") continue;
+    if (bucket === "feature") feature.push(f);
+    else if (bucket === "fix") fix.push(f);
+    else other.push(f);
+  }
+
+  let chosen = feature.length ? feature : other.length ? other : fix;
+  // top up features with a couple fixes if the release is thin
+  if (chosen === feature && feature.length < 2) chosen = [...feature, ...fix];
+
+  const seen = new Set<string>();
+  const deduped = chosen.filter((f) => (seen.has(f.title) ? false : (seen.add(f.title), true)));
+  const total = feature.length + fix.length + other.length;
+  const features = deduped.slice(0, max);
+  return { features, dropped: Math.max(0, total - features.length) };
+}

package/src/adapters/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Normalized "what changed" for a repo/release — the input the brain (or a
+ * deterministic template) turns into beats. Adapters parse the messy real world
+ * (release notes, CHANGELOGs, git tags) into this shape.
+ */
+export type Feature = {
+  title: string;
+  /** Conventional-commit-ish kind if detectable: feat | fix | perf | docs | … */
+  kind?: string;
+};
+
+export type UpdateManifest = {
+  /** Package or repo name. */
+  product: string;
+  /** Latest version / tag, without a leading "v" if present. */
+  version: string;
+  date?: string;
+  features: Feature[];
+  /** Real install line, e.g. "npm i pkg", "brew install tool". */
+  install?: string;
+  repoUrl?: string;
+  /** Anything the parser dropped (kept transparent — never silently truncate). */
+  dropped?: number;
+};

package/src/brand/fonts.ts

@@ -0,0 +1,74 @@
+import { loadFont as Sora } from "@remotion/google-fonts/Sora";
+import { loadFont as Inter } from "@remotion/google-fonts/Inter";
+import { loadFont as PublicSans } from "@remotion/google-fonts/PublicSans";
+import { loadFont as Manrope } from "@remotion/google-fonts/Manrope";
+import { loadFont as SpaceGrotesk } from "@remotion/google-fonts/SpaceGrotesk";
+import { loadFont as PlusJakartaSans } from "@remotion/google-fonts/PlusJakartaSans";
+import { loadFont as Outfit } from "@remotion/google-fonts/Outfit";
+import { loadFont as DMSans } from "@remotion/google-fonts/DMSans";
+import { loadFont as Figtree } from "@remotion/google-fonts/Figtree";
+import { loadFont as Epilogue } from "@remotion/google-fonts/Epilogue";
+import { loadFont as Archivo } from "@remotion/google-fonts/Archivo";
+import { loadFont as WorkSans } from "@remotion/google-fonts/WorkSans";
+import { loadFont as Geist } from "@remotion/google-fonts/Geist";
+import { loadFont as PlayfairDisplay } from "@remotion/google-fonts/PlayfairDisplay";
+import { loadFont as Spectral } from "@remotion/google-fonts/Spectral";
+import { loadFont as Fraunces } from "@remotion/google-fonts/Fraunces";
+import { loadFont as FiraCode } from "@remotion/google-fonts/FiraCode";
+import { loadFont as JetBrainsMono } from "@remotion/google-fonts/JetBrainsMono";
+import { loadFont as IBMPlexMono } from "@remotion/google-fonts/IBMPlexMono";
+import { loadFont as SpaceMono } from "@remotion/google-fonts/SpaceMono";
+import { loadFont as GeistMono } from "@remotion/google-fonts/GeistMono";
+import { loadFont as Caveat } from "@remotion/google-fonts/Caveat";
+import { activeTheme } from "../theme";
+
+// A theme declares fonts as CSS stacks ("Sora, ui-sans-serif, …"); the first
+// token is the family we load via @remotion/google-fonts. Importing a loader is
+// cheap (just binds a function) — only the active theme's families are actually
+// fetched, so a 22-family registry costs nothing per render beyond the ~4 in use.
+// Loosely typed: each @remotion/google-fonts loader has a font-specific `style`
+// union, so we erase the param types to register them in one map.
+// biome-ignore lint/suspicious/noExplicitAny: heterogeneous loader signatures
+type GoogleLoader = (...args: any[]) => { waitUntilDone: () => Promise<void> };
+
+const LOADERS: Record<string, GoogleLoader> = {
+  Sora,
+  Inter,
+  "Public Sans": PublicSans,
+  Manrope,
+  "Space Grotesk": SpaceGrotesk,
+  "Plus Jakarta Sans": PlusJakartaSans,
+  Outfit,
+  "DM Sans": DMSans,
+  Figtree,
+  Epilogue,
+  Archivo,
+  "Work Sans": WorkSans,
+  Geist,
+  "Playfair Display": PlayfairDisplay,
+  Spectral,
+  Fraunces,
+  "Fira Code": FiraCode,
+  "JetBrains Mono": JetBrainsMono,
+  "IBM Plex Mono": IBMPlexMono,
+  "Space Mono": SpaceMono,
+  "Geist Mono": GeistMono,
+  Caveat,
+};
+
+/** First family of a CSS stack, e.g. "Sora, ui-sans-serif" → "Sora". */
+const primary = (stack: string) => stack.split(",")[0].trim();
+
+const families = new Set(
+  [activeTheme.fonts.display, activeTheme.fonts.body, activeTheme.fonts.mono, activeTheme.fonts.note].map(primary),
+);
+const loaded = [...families]
+  .map((f) => LOADERS[f])
+  .filter(Boolean)
+  .map((load) => load("normal", { subsets: ["latin"] }));
+
+/** Active font stacks (from the theme). */
+export const FONTS = activeTheme.fonts;
+
+/** Await before a still / Lambda render — fonts load async; capture real faces. */
+export const waitForFonts = () => Promise.all(loaded.map((f) => f.waitUntilDone()));

package/src/brand/tokens.ts

@@ -0,0 +1,31 @@
+import { Easing } from "remotion";
+import { activeTheme } from "../theme";
+
+/**
+ * Engine tokens. Colors + shadow come from the active theme (swappable per render
+ * via `--theme`); the easing curves and scale are engine constants.
+ */
+export const COLORS = activeTheme.colors;
+
+export const CARET_BG = activeTheme.caretBg;
+
+/** Light [from, to] gradient for the procedural default backdrop ("shapes"). */
+export const BACKDROP: [string, string] = activeTheme.backdrop ?? ["#e6edff", "#f8faff"];
+
+/**
+ * Two easings:
+ * - `smooth`: pure ease-out — the ENTRANCE curve (no overshoot).
+ * - `snappy`: a deliberate slight settle/overshoot — small UI state pops only.
+ */
+export const EASE = {
+  smooth: Easing.bezier(0.19, 1, 0.22, 1),
+  snappy: Easing.bezier(0.175, 0.885, 0.32, 1.1),
+} as const;
+
+/** No-overshoot spring for entrances (damping high so it settles, never bounces). */
+export const SPRING_ENTER = { damping: 200, mass: 1, stiffness: 100 } as const;
+
+export const RADIUS = { sm: 3, md: 6, lg: 8, xl: 10, full: 999 } as const;
+
+/** Shadow reserved for floating, dismissible chrome (windows/panels over the art). */
+export const FLOAT_SHADOW = activeTheme.floatShadow;

package/src/brand/tone.ts

@@ -0,0 +1,25 @@
+import type { Beat } from "../schema/beats";
+
+/** Relative luminance (0-1) of a hex color; non-hex → 0. */
+const lum = (hex: string): number => {
+  let h = hex.replace("#", "").trim();
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  if (h.length < 6) return 0;
+  const r = parseInt(h.slice(0, 2), 16) / 255;
+  const g = parseInt(h.slice(2, 4), 16) / 255;
+  const b = parseInt(h.slice(4, 6), 16) / 255;
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+/**
+ * Is the beat's backdrop light enough that overlaid text should be dark? The
+ * procedural default (`shapes` / no background) is always light; gradients/solids
+ * are judged by luminance; the image pack is assumed dark (keep the light-text +
+ * shadow treatment the paintings were designed for).
+ */
+export function isLightBackdrop(bg: Beat["background"]): boolean {
+  if (!bg || bg.shapes) return true;
+  if (bg.solid) return lum(bg.solid) > 0.6;
+  if (bg.gradient) return (lum(bg.gradient[0]) + lum(bg.gradient[1])) / 2 > 0.55;
+  return false;
+}

package/src/code/highlight.ts

@@ -0,0 +1,90 @@
+/**
+ * Code → themed tokens, run once per beat inside `calculateMetadata` (async, off
+ * the render hot path). Primary path is shiki with a brand light theme; if shiki
+ * fails to load (e.g. WASM under the bundler), a regex fallback keeps renders
+ * working. Output is plain JSON (lines of {content,color}) so it serializes into
+ * Remotion input props.
+ */
+import type { Highlighter } from "shiki";
+
+export type CodeToken = { content: string; color: string };
+export type CodeLine = CodeToken[];
+
+export type Lang = "ts" | "tsx" | "bash" | "json";
+
+import { activeTheme } from "../theme";
+
+const C = activeTheme.codeTheme;
+
+const FIELD_NOTEBOOK_LIGHT = {
+  name: "field-notebook-light",
+  type: "light",
+  colors: { "editor.background": activeTheme.codeBg, "editor.foreground": C.fg },
+  settings: [
+    { settings: { foreground: C.fg } },
+    { scope: ["keyword", "keyword.control", "storage", "storage.type", "storage.modifier"], settings: { foreground: C.kw } },
+    { scope: ["keyword.operator.new", "keyword.operator.expression.new"], settings: { foreground: C.nw } },
+    { scope: ["string", "string.quoted", "string.template", "constant.character"], settings: { foreground: C.str } },
+    { scope: ["constant.numeric", "constant.language"], settings: { foreground: C.num } },
+    { scope: ["entity.name.function", "support.function", "meta.function-call.identifier", "entity.name.type", "entity.name.class", "support.class"], settings: { foreground: C.fn } },
+    { scope: ["variable", "support.variable", "meta.object-literal.key", "variable.other.property"], settings: { foreground: C.punct } },
+    { scope: ["comment", "punctuation.definition.comment"], settings: { foreground: C.comment, fontStyle: "italic" } },
+    { scope: ["punctuation", "meta.brace", "keyword.operator"], settings: { foreground: C.punct } },
+  ],
+} as const;
+
+const SHIKI_LANG: Record<Lang, string> = { ts: "typescript", tsx: "tsx", bash: "bash", json: "json" };
+
+let highlighterPromise: Promise<Highlighter> | null = null;
+const getHighlighter = async () => {
+  if (!highlighterPromise) {
+    const { createHighlighter } = await import("shiki");
+    highlighterPromise = createHighlighter({
+      themes: [FIELD_NOTEBOOK_LIGHT as never],
+      langs: ["typescript", "tsx", "bash", "json"],
+    });
+  }
+  return highlighterPromise;
+};
+
+export async function tokenize(source: string, lang: Lang): Promise<CodeLine[]> {
+  try {
+    const hl = await getHighlighter();
+    const { tokens } = hl.codeToTokens(source, { lang: SHIKI_LANG[lang] as never, theme: "field-notebook-light" });
+    return tokens.map((line) => line.map((t) => ({ content: t.content, color: t.color ?? C.fg })));
+  } catch {
+    return fallbackTokenize(source, lang);
+  }
+}
+
+// ─── Regex fallback (resilience only; shiki is the real path) ─────────────────
+
+const TS_KEYWORDS = /\b(import|from|export|const|let|var|new|await|async|return|function|type|interface|for|of|if|else|class|extends)\b/;
+const fallbackTokenize = (source: string, lang: Lang): CodeLine[] =>
+  source.split("\n").map((line) => {
+    if (lang === "bash") {
+      const m = line.match(/^(\s*\$?\s*)(\S+)?(.*)$/);
+      if (!m) return [{ content: line, color: C.fg }];
+      return [
+        { content: m[1], color: C.punct },
+        { content: m[2] ?? "", color: C.fn },
+        { content: m[3] ?? "", color: C.fg },
+      ].filter((t) => t.content);
+    }
+    // crude TS: split on words/strings/numbers, color each chunk
+    const out: CodeToken[] = [];
+    const re = /("[^"]*"|'[^']*'|`[^`]*`|\b\d+(\.\d+)?\b|[A-Za-z_$][\w$]*|\s+|[^\w\s])/g;
+    for (const [tok] of line.matchAll(re)) {
+      let color: string = C.punct;
+      if (/^["'`]/.test(tok)) color = C.str;
+      else if (/^\d/.test(tok)) color = C.num;
+      else if (TS_KEYWORDS.test(tok)) color = C.kw;
+      else if (/^[A-Za-z_$]/.test(tok)) color = C.fg;
+      else if (/^\s+$/.test(tok)) color = C.fg;
+      out.push({ content: tok, color });
+    }
+    return out.length ? out : [{ content: "", color: C.fg }];
+  });
+
+/** Code window background, from the active theme. */
+export const CODE_BG = activeTheme.codeBg;

package/src/components/Background.tsx

@@ -0,0 +1,75 @@
+import { AbsoluteFill, Img, interpolate, staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+import { BACKDROP, COLORS } from "../brand/tokens";
+import type { Beat } from "../schema/beats";
+
+type BG = Beat["background"];
+
+/** hex (#abc | #aabbcc) → rgba string with alpha. */
+const hexA = (hex: string, a: number) => {
+  let h = hex.replace("#", "");
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  return `rgba(${parseInt(h.slice(0, 2), 16)},${parseInt(h.slice(2, 4), 16)},${parseInt(h.slice(4, 6), 16)},${a})`;
+};
+
+/**
+ * Backdrop style packs. The default (no `background`, or `shapes`) is a procedural,
+ * theme-colored field of soft curved arcs — no asset, no API key. Other packs: an
+ * `image` (optional painterly pack, Ken Burns + haze), an AI-free `gradient`, or a
+ * `solid`. All add a soft vignette + slow drift so they're never flat.
+ */
+export const Background: React.FC<{ bg?: BG }> = ({ bg }) => {
+  const frame = useCurrentFrame();
+  const { durationInFrames } = useVideoConfig();
+  const opacity = interpolate(frame, [0, 18], [0, 1], { extrapolateRight: "clamp" });
+
+  // Default backdrop: procedural soft arcs tinted from the active theme.
+  if (!bg || bg.shapes) {
+    const drift = interpolate(frame, [0, durationInFrames], [0, 1], { extrapolateRight: "clamp" });
+    const a = COLORS.signalBlue;
+    // A soft arc band centered off-canvas: transparent core → faint accent ring → fade.
+    const arc = (cx: number, cy: number, r: number, alpha: number) =>
+      `radial-gradient(circle at ${cx}% ${cy}%, transparent ${r}%, ${hexA(a, alpha)} ${r + 1}%, ${hexA(a, alpha * 0.35)} ${r + 9}%, transparent ${r + 18}%)`;
+    return (
+      <AbsoluteFill style={{ opacity }}>
+        <AbsoluteFill style={{ background: `linear-gradient(160deg, ${BACKDROP[0]} 0%, ${BACKDROP[1]} 100%)` }} />
+        <AbsoluteFill
+          style={{
+            background: [arc(114, 94, 40, 0.32), arc(90, 24, 32, 0.22), arc(-8, 110, 30, 0.18)].join(","),
+            transform: `translateY(${interpolate(drift, [0, 1], [0, -14])}px) scale(${interpolate(drift, [0, 1], [1, 1.05])})`,
+          }}
+        />
+        {/* gentle top wash so headlines stay legible */}
+        <AbsoluteFill style={{ background: "radial-gradient(120% 80% at 50% 14%, rgba(255,255,255,0.42) 0%, rgba(255,255,255,0) 55%)" }} />
+      </AbsoluteFill>
+    );
+  }
+
+  if (bg.solid || bg.gradient) {
+    const drift = interpolate(frame, [0, durationInFrames], [0, 1.04], { extrapolateRight: "clamp" });
+    const fill = bg.solid
+      ? bg.solid
+      : `linear-gradient(${bg.angle}deg, ${bg.gradient![0]} 0%, ${bg.gradient![1]} 100%)`;
+    return (
+      <AbsoluteFill style={{ opacity }}>
+        <AbsoluteFill style={{ background: fill, transform: `scale(${drift})` }} />
+        {/* soft vignette so panels read + the fill has depth */}
+        <AbsoluteFill style={{ background: "radial-gradient(120% 100% at 50% 30%, rgba(255,255,255,0.10), rgba(0,0,0,0.10) 100%)" }} />
+      </AbsoluteFill>
+    );
+  }
+
+  const kb = bg.treatment === "kenburns";
+  const scale = kb ? interpolate(frame, [0, durationInFrames], [1, 1.08], { extrapolateRight: "clamp" }) : 1;
+  const translateY = kb ? interpolate(frame, [0, durationInFrames], [-12, 0], { extrapolateRight: "clamp" }) : 0;
+
+  return (
+    <AbsoluteFill style={{ backgroundColor: COLORS.chrome, opacity }}>
+      <Img
+        src={staticFile(bg.src!)}
+        style={{ width: "100%", height: "100%", objectFit: "cover", transform: `scale(${scale}) translateY(${translateY}px)` }}
+      />
+      <AbsoluteFill style={{ background: "radial-gradient(120% 90% at 50% 16%, rgba(250,248,242,0.58) 0%, rgba(250,248,242,0.18) 40%, rgba(230,235,240,0) 72%)" }} />
+      <AbsoluteFill style={{ background: "linear-gradient(180deg, rgba(248,246,240,0.35) 0%, rgba(248,246,240,0) 22%, rgba(40,55,70,0.10) 100%)" }} />
+    </AbsoluteFill>
+  );
+};

package/src/components/Changelog.tsx

@@ -0,0 +1,17 @@
+import { Series } from "remotion";
+import type { ChangelogVideo } from "../schema/beats";
+import { ChangelogScene } from "./ChangelogScene";
+
+/** Top-level composition: a Series of beats. Duration/dimensions/tokens are set
+ * by `calculateMetadata` in Root before this renders. */
+export const Changelog: React.FC<ChangelogVideo> = ({ format, beats }) => {
+  return (
+    <Series>
+      {beats.map((beat) => (
+        <Series.Sequence key={beat.id} durationInFrames={beat.durationInFrames}>
+          <ChangelogScene beat={beat} format={format} />
+        </Series.Sequence>
+      ))}
+    </Series>
+  );
+};