@waits/cadence 0.2.0 → 0.4.0

package/README.md

@@ -21,16 +21,22 @@ no generic AI-video look, no hosted service. Free and open source.
 npx skills add ryanwaits/cadence   # adds the skill to Claude Code / Cursor / Codex
 ```
 
-Then just ask your agent. Or drive the CLI directly:
+Then just ask your agent. Or drive the CLI directly — install the `cadence`
+binary globally, or run it with `npx` (no install):
 
 ```bash
-npx cadence create --release owner/name --install "npm i your-pkg"   # a repo → a video
-npx cadence create my.beats.json --format 9x16                       # a beats file → a video
-npx cadence themes                                                   # list built-in themes
+npm i -g @waits/cadence                                              # a persistent `cadence` binary
+cadence create --release owner/name --install "npm i your-pkg"       # a repo → a video
+cadence create my.beats.json --format 9x16                           # a beats file → a video
+cadence themes                                                       # list built-in themes
+
+npx @waits/cadence create --release owner/name --install "npm i …"   # …or run without installing
 ```
 
 A render runs entirely on your machine (or your own GitHub Actions) — free, no API key.
 
+→ **New here? Start with the [guides](docs/guides/)** — install, changelog, announcement, milestone, branding, and CI walkthroughs.
+
 ## Why it doesn't look AI-generated
 
 Most AI video either fabricates a fake product or reaches for the same neon-on-black
@@ -60,6 +66,7 @@ milestones. The agent (via the skill) writes the beats; you tweak and render.
 Panels visualize what a change *produces* — pick by result:
 `feed · data-table · status · stat · proof · stream-resume · fork · upload-progress · diagram`.
 
+- **[docs/guides/](docs/guides/)** — task-oriented walkthroughs (install, changelog, announcement, milestone, branding, iterate, CI).
 - **[docs/recipes.md](docs/recipes.md)** — worked examples (changelog, announcement, showcase, brand-from-URL, CI).
 - **[docs/gallery.md](docs/gallery.md)** — the same engine, visibly different videos.
 - **[WALKTHROUGH.md](WALKTHROUGH.md)** — architecture + how to adjust each part.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waits/cadence",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -53,6 +53,7 @@
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
     "@changesets/cli": "^2.31.0",
+    "@types/node": "22",
     "@types/react": "19.2.16",
     "typescript": "5.7.3"
   }

package/scripts/_audit.ts

@@ -0,0 +1,53 @@
+/**
+ * Heuristic beats checks, as a pure function so both `cadence audit` and
+ * `cadence storyboard` can surface them. Advisory only — no auto-fix. Mirrors
+ * the authoring guidance in the cadence skill (3-6 beats, ~2-10s each, short
+ * declarative headlines, an install/CTA closer).
+ */
+import type { Beat } from "../src/schema/beats";
+import { FPS } from "./_beats";
+
+export type Level = "error" | "warn" | "info";
+export type Finding = { level: Level; msg: string };
+
+/** Ranked findings for a parsed beats array. */
+export function auditBeats(beats: Beat[]): Finding[] {
+  const findings: Finding[] = [];
+  const add = (level: Level, msg: string) => findings.push({ level, msg });
+
+  // 1. Beat count — skill guidance is to keep it tight (3-6).
+  if (beats.length < 2) add("warn", `only ${beats.length} beat — most videos want 3-6`);
+  if (beats.length > 7) add("warn", `${beats.length} beats — tighten toward 3-6; long videos lose attention`);
+
+  // 2. Per-beat duration (≈2-10s at 30fps).
+  beats.forEach((b, i) => {
+    const s = (b.durationInFrames / FPS).toFixed(1);
+    if (b.durationInFrames < 45) add("warn", `beat ${i + 1} "${b.headline}" is ${s}s — too short to read`);
+    else if (b.durationInFrames > 360) add("warn", `beat ${i + 1} "${b.headline}" is ${s}s — likely too long`);
+  });
+
+  // 3. Headline length — short + declarative.
+  beats.forEach((b, i) => {
+    if (b.headline.length > 48)
+      add("warn", `beat ${i + 1} headline is ${b.headline.length} chars — shorten ("${b.headline.slice(0, 40)}…")`);
+  });
+
+  // 4. Motion monotony — every beat with an explicit enter uses the same one.
+  const enters = beats.map((b) => b.headlineMotion?.enter).filter(Boolean);
+  if (enters.length >= 3 && new Set(enters).size === 1)
+    add("info", `every headline uses the "${enters[0]}" enter — vary it for rhythm`);
+
+  // 5. Install/CTA closer — heuristic: last beat centered with a bash command or a badge/caption.
+  const last = beats[beats.length - 1];
+  const isCloser = last.layout === "center" && (last.code?.lang === "bash" || !!last.badge || !!last.caption);
+  if (!isCloser) add("info", "last beat doesn't look like an install/CTA closer (centered + install command)");
+
+  return findings;
+}
+
+const order: Record<Level, number> = { error: 0, warn: 1, info: 2 };
+/** Ranked error → warn → info (stable copy). */
+export const rankFindings = (findings: Finding[]): Finding[] =>
+  [...findings].sort((a, b) => order[a.level] - order[b.level]);
+
+export const ICON: Record<Level, string> = { error: "✗", warn: "▲", info: "·" };

package/scripts/_beats.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared beats helpers: load + validate a beats module, and compute per-beat
+ * timings. Used by render / audit / storyboard so the "how do I read a beats
+ * file" logic lives in one place. Beats are laid end-to-end by the Changelog
+ * composition (`<Series.Sequence durationInFrames>`), so a beat's start frame is
+ * the running sum of prior durations — see `src/components/Changelog.tsx`.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { changelogSchema, type Beat, type ChangelogVideo } from "../src/schema/beats";
+
+export const FPS = 30;
+
+/** Load a `.ts`/`.js` module (default export) or a `.json` file, then validate. */
+export async function loadBeats(file: string): Promise<ChangelogVideo> {
+  const raw = file.endsWith(".json")
+    ? JSON.parse(readFileSync(resolve(file), "utf8"))
+    : (await import(pathToFileURL(resolve(file)).href)).default;
+  return changelogSchema.parse(raw);
+}
+
+export type BeatTiming = { start: number; mid: number; dur: number };
+
+/**
+ * Per-beat `{start, mid, dur}` frames + total. `mid` (start + ⌊dur/2⌋) is the
+ * representative frame for a still — entrance motion has settled by then.
+ */
+export function beatTimings(beats: Beat[]): { timings: BeatTiming[]; totalFrames: number } {
+  let start = 0;
+  const timings = beats.map((b) => {
+    const dur = b.durationInFrames;
+    const t = { start, mid: start + Math.floor(dur / 2), dur };
+    start += dur;
+    return t;
+  });
+  return { timings, totalFrames: start };
+}

package/scripts/_theme.ts

@@ -0,0 +1,74 @@
+/**
+ * Project-local `.cadence/` resolution shared by render / storyboard / make.
+ *
+ * A repo captures its own cadence setup under `<project>/.cadence/`:
+ *   - `theme.json` — brand (colors, mono font, code syntax theme, code chrome)
+ * cadence discovers it automatically when run against the project, and writes
+ * **outputs alongside it** (`<project>/.cadence/out/`) so renders are anchored to
+ * the project, not the current directory. No project-specific files live in the
+ * cadence engine itself.
+ *
+ * Theme precedence:  --theme-file  >  --theme <name>  >  .cadence/theme.json  >  default.
+ * Output dir:        --out <dir>   >  <project>/.cadence/out               >  ./out.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { THEMES } from "../src/theme";
+
+/** Walk up from `start` (max 6 levels) for a `.cadence` directory. */
+export function findCadenceDir(start: string): string | undefined {
+  let dir = resolve(start);
+  for (let i = 0; i < 6; i++) {
+    const p = join(dir, ".cadence");
+    if (existsSync(p)) return p;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+/** A project's `.cadence/theme.json`, if one exists near `start`. */
+export function discoverProjectTheme(start: string): string | undefined {
+  const cad = findCadenceDir(start);
+  if (!cad) return undefined;
+  const p = join(cad, "theme.json");
+  return existsSync(p) ? p : undefined;
+}
+
+/**
+ * Where renders are written. Precedence: an explicit `--out <dir>` > a project's
+ * `<project>/.cadence/out` (so outputs are anchored to the project regardless of
+ * cwd) > `./out`. `beatsFile` (when present) anchors discovery near the beats
+ * file; otherwise discovery starts from the current directory.
+ */
+export function resolveOutDir(opts: { outFlag?: string; beatsFile?: string }): string {
+  if (opts.outFlag) return resolve(opts.outFlag);
+  const start = opts.beatsFile ? dirname(resolve(opts.beatsFile)) : process.cwd();
+  const cad = findCadenceDir(start);
+  return cad ? join(cad, "out") : "out";
+}
+
+/**
+ * Resolve which theme to use. Returns the (possibly auto-discovered) `themeFile`
+ * and/or named `theme`. Exits on an unknown named theme. Logs when a project
+ * theme is auto-discovered so it's never a silent surprise.
+ */
+export function resolveTheme(opts: { theme?: string; themeFile?: string; beatsFile?: string }): {
+  theme?: string;
+  themeFile?: string;
+} {
+  let { theme, themeFile } = opts;
+  if (!themeFile && !theme && opts.beatsFile) {
+    const found = discoverProjectTheme(dirname(resolve(opts.beatsFile)));
+    if (found) {
+      themeFile = found;
+      console.error(`· using project theme ${found}`);
+    }
+  }
+  if (theme && !themeFile && !THEMES[theme]) {
+    console.error(`unknown --theme "${theme}". have: ${Object.keys(THEMES).join(", ")}`);
+    process.exit(1);
+  }
+  return { theme, themeFile };
+}

package/scripts/audit.ts

@@ -1,14 +1,12 @@
 /**
  * `cadence audit <beats>` — static, heuristic checks on a beats file. Advisory
  * only: ranked findings, no auto-fix (edit content by hand; use `redesign` to
- * re-skin). Mirrors the authoring guidance in the cadence skill.
+ * re-skin). The checks live in `_audit.ts` so `storyboard` can reuse them.
  *
  *   cadence audit src/content/streams-launch.beats.ts
  */
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { changelogSchema } from "../src/schema/beats";
+import { loadBeats } from "./_beats";
+import { auditBeats, ICON, rankFindings } from "./_audit";
 
 const file = process.argv.slice(2).find((a) => !a.startsWith("-"));
 if (!file) {
@@ -16,48 +14,9 @@ if (!file) {
   process.exit(1);
 }
 
-const raw = file.endsWith(".json")
-  ? JSON.parse(readFileSync(resolve(file), "utf8"))
-  : (await import(pathToFileURL(resolve(file)).href)).default;
-const parsed = changelogSchema.parse(raw);
+const parsed = await loadBeats(file);
 const beats = parsed.beats;
-const FPS = 30;
-
-type Level = "error" | "warn" | "info";
-const findings: { level: Level; msg: string }[] = [];
-const add = (level: Level, msg: string) => findings.push({ level, msg });
-
-// 1. Beat count — skill guidance is to keep it tight (3-6).
-if (beats.length < 2) add("warn", `only ${beats.length} beat — most videos want 3-6`);
-if (beats.length > 7) add("warn", `${beats.length} beats — tighten toward 3-6; long videos lose attention`);
-
-// 2. Per-beat duration (≈2-10s at 30fps).
-beats.forEach((b, i) => {
-  const s = (b.durationInFrames / FPS).toFixed(1);
-  if (b.durationInFrames < 45) add("warn", `beat ${i + 1} "${b.headline}" is ${s}s — too short to read`);
-  else if (b.durationInFrames > 360) add("warn", `beat ${i + 1} "${b.headline}" is ${s}s — likely too long`);
-});
-
-// 3. Headline length — short + declarative.
-beats.forEach((b, i) => {
-  if (b.headline.length > 48)
-    add("warn", `beat ${i + 1} headline is ${b.headline.length} chars — shorten ("${b.headline.slice(0, 40)}…")`);
-});
-
-// 4. Motion monotony — every beat with an explicit enter uses the same one.
-const enters = beats.map((b) => b.headlineMotion?.enter).filter(Boolean);
-if (enters.length >= 3 && new Set(enters).size === 1)
-  add("info", `every headline uses the "${enters[0]}" enter — vary it for rhythm`);
-
-// 5. Install/CTA closer — heuristic: last beat centered with a bash command or a badge/caption.
-const last = beats[beats.length - 1];
-const isCloser = last.layout === "center" && (last.code?.lang === "bash" || !!last.badge || !!last.caption);
-if (!isCloser) add("info", "last beat doesn't look like an install/CTA closer (centered + install command)");
-
-// Report, ranked: error → warn → info. "Issues" = error+warn; info are notes.
-const order: Record<Level, number> = { error: 0, warn: 1, info: 2 };
-findings.sort((a, b) => order[a.level] - order[b.level]);
-const icon: Record<Level, string> = { error: "✗", warn: "▲", info: "·" };
+const findings = rankFindings(auditBeats(beats));
 const issues = findings.filter((f) => f.level !== "info").length;
 
 if (issues === 0) {
@@ -66,4 +25,4 @@ if (issues === 0) {
 } else {
   console.log(`${file}: ${issues} issue${issues > 1 ? "s" : ""} across ${beats.length} beats`);
 }
-for (const f of findings) console.log(`  ${icon[f.level]} ${f.msg}`);
+for (const f of findings) console.log(`  ${ICON[f.level]} ${f.msg}`);

package/scripts/cli.ts

@@ -22,6 +22,7 @@ const sub = rawSub ? (ALIAS[rawSub] ?? rawSub) : rawSub;
 const SCRIPTS: Record<string, string> = {
   guide: "scripts/guide.ts", // interactive walkthrough
   render: "scripts/render.ts", // a beats file → a video (create delegates here)
+  storyboard: "scripts/storyboard.ts", // a beats file → a preview sheet (no MP4)
   study: "scripts/theme.ts", // brand color / URL / screenshot → a theme
   audit: "scripts/audit.ts", // check a beats file for issues
   redesign: "scripts/redesign.ts", // re-skin a beats file
@@ -33,6 +34,7 @@ const HELP = `cadence — turn a repo / release into a changelog or announcement
 
 commands:
   create     a repo OR a beats file → a video     cadence create --release owner/name --install "npm i pkg"
+  storyboard a beats file → a preview sheet         cadence storyboard x.beats.ts   (or: cadence create … --dry-run)
   study      a brand color / URL → a theme         cadence study --from-url https://acme.dev --name acme
   audit      check a beats file for issues          cadence audit src/content/x.beats.ts
   redesign   re-skin a beats file (new look)        cadence redesign x.beats.ts --theme slate
@@ -45,7 +47,9 @@ utilities:
   templates  list available templates
   themes     list available themes
 
-flags shared by create/render/redesign: --format 16x9|1x1|9x16, --theme <name>, --theme-file <path>, --frame <n>`;
+flags shared by create/render/redesign: --format 16x9|1x1|9x16, --theme <name>, --theme-file <path>, --frame <n>, --out <dir>
+outputs: written to <project>/.cadence/out when run against a repo with a .cadence/ dir, else ./out (override with --out)
+preview before rendering: cadence storyboard <beats>  ·  cadence create … --dry-run  (plan + one still per beat, no MP4)`;
 
 if (!sub || sub === "help" || sub === "--help") {
   console.log(HELP);
@@ -65,7 +69,11 @@ if (sub === "themes") {
 function resolveScript(verb: string, args: string[]): string | undefined {
   if (verb === "create") {
     const beatsFile = args.find((a) => !a.startsWith("-") && /\.(beats\.)?(ts|js|json)$/.test(a));
-    return beatsFile ? "scripts/render.ts" : "scripts/make.ts";
+    const dryRun = args.includes("--dry-run");
+    // beats-file flow: --dry-run → storyboard (preview sheet), else render (MP4).
+    if (beatsFile) return dryRun ? "scripts/storyboard.ts" : "scripts/render.ts";
+    // repo flow: make.ts handles --dry-run itself (generates beats → storyboard).
+    return "scripts/make.ts";
   }
   return SCRIPTS[verb];
 }

package/scripts/make.ts

@@ -13,6 +13,7 @@ import { manifestFromChangelogText, manifestFromReleaseBody } from "../src/adapt
 import type { BackgroundSpec } from "../src/templates";
 import { TEMPLATES } from "../src/templates";
 import { binPath, pkgFile } from "./_pkg";
+import { resolveOutDir } from "./_theme";
 
 const args = process.argv.slice(2);
 const flag = (n: string) => {
@@ -67,10 +68,22 @@ const beats = template(manifest, {
 
 console.error(`· ${manifest.product} ${manifest.version}: ${manifest.features.length} features${manifest.dropped ? ` (+${manifest.dropped} dropped)` : ""} → ${templateName}`);
 
-// 3. Write beats JSON + render
-mkdirSync("out", { recursive: true });
-const jsonPath = join("out", `make-${manifest.product}.beats.json`);
+// 3. Write beats JSON, then render — or, with --dry-run, storyboard it (preview
+// sheet + plan, no MP4). Outputs go to the project's .cadence/out (or --out).
+const outDir = resolveOutDir({ outFlag: flag("--out") });
+mkdirSync(outDir, { recursive: true });
+const jsonPath = join(outDir, `make-${manifest.product}.beats.json`);
 writeFileSync(jsonPath, JSON.stringify(beats));
+// Pin the child to the same out dir so beats + renders colocate.
+const outArgs = ["--out", outDir];
+
+if (args.includes("--dry-run")) {
+  // repo → storyboard. --frame is meaningless here; --theme-file is supported.
+  const passthru = ["--format", "--theme", "--theme-file"].flatMap((f) => (flag(f) ? [f, flag(f)!] : []));
+  const res = spawnSync(binPath("tsx"), [pkgFile("scripts/storyboard.ts"), jsonPath, ...passthru, ...outArgs], { stdio: "inherit" });
+  process.exit(res.status ?? 0);
+}
+
 const passthru = ["--format", "--theme", "--frame"].flatMap((f) => (flag(f) ? [f, flag(f)!] : []));
-const res = spawnSync(binPath("tsx"), [pkgFile("scripts/render.ts"), jsonPath, ...passthru], { stdio: "inherit" });
+const res = spawnSync(binPath("tsx"), [pkgFile("scripts/render.ts"), jsonPath, ...passthru, ...outArgs], { stdio: "inherit" });
 process.exit(res.status ?? 0);

package/scripts/render.ts

@@ -9,10 +9,10 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { changelogSchema, type Format } from "../src/schema/beats";
-import { THEMES } from "../src/theme";
+import { type Format } from "../src/schema/beats";
+import { loadBeats } from "./_beats";
 import { binPath, pkgFile } from "./_pkg";
+import { resolveOutDir, resolveTheme } from "./_theme";
 
 const args = process.argv.slice(2);
 const getFlag = (name: string) => {
@@ -29,34 +29,27 @@ if (!file) {
 }
 
 // Accept either a `.beats.ts` module or a plain `.json` beats file.
-const raw = file.endsWith(".json")
-  ? JSON.parse(readFileSync(resolve(file), "utf8"))
-  : (await import(pathToFileURL(resolve(file)).href)).default;
-const parsed = changelogSchema.parse(raw);
+const parsed = await loadBeats(file);
 
 const fmt = getFlag("--format") as Format | undefined;
 if (fmt) parsed.format = fmt;
 const frame = getFlag("--frame");
-const theme = getFlag("--theme");
-const themeFile = getFlag("--theme-file");
-if (theme && !themeFile && !THEMES[theme]) {
-  console.error(`unknown --theme "${theme}". have: ${Object.keys(THEMES).join(", ")}`);
-  process.exit(1);
-}
+const { theme, themeFile } = resolveTheme({ theme: getFlag("--theme"), themeFile: getFlag("--theme-file"), beatsFile: file });
 const env: NodeJS.ProcessEnv = { ...process.env };
 if (theme) env.REMOTION_VIDEO_THEME = theme;
 if (themeFile) env.REMOTION_VIDEO_THEME_JSON = readFileSync(resolve(themeFile), "utf8");
 
-mkdirSync("out", { recursive: true });
+const outDir = resolveOutDir({ outFlag: getFlag("--out"), beatsFile: file });
+mkdirSync(outDir, { recursive: true });
 const name = basename(file).replace(/\.beats\.(ts|js|json)$/, "").replace(/\.(ts|js|json)$/, "");
-const propsPath = join("out", `.props-${name}-${parsed.format}.json`);
+const propsPath = join(outDir, `.props-${name}-${parsed.format}.json`);
 writeFileSync(propsPath, JSON.stringify(parsed));
 
 const bin = binPath("remotion");
 const common = [pkgFile("src/index.ts"), "Changelog"];
 const suffix = theme && theme !== "default" ? `-${theme}` : "";
 const res = frame
-  ? spawnSync(bin, ["still", ...common, join("out", `${name}-${parsed.format}${suffix}-f${frame}.png`), `--props=${propsPath}`, `--frame=${frame}`], { stdio: "inherit", env })
-  : spawnSync(bin, ["render", ...common, join("out", `${name}-${parsed.format}${suffix}.mp4`), `--props=${propsPath}`, "--image-format=jpeg"], { stdio: "inherit", env });
+  ? spawnSync(bin, ["still", ...common, join(outDir, `${name}-${parsed.format}${suffix}-f${frame}.png`), `--props=${propsPath}`, `--frame=${frame}`], { stdio: "inherit", env })
+  : spawnSync(bin, ["render", ...common, join(outDir, `${name}-${parsed.format}${suffix}.mp4`), `--props=${propsPath}`, "--image-format=jpeg"], { stdio: "inherit", env });
 
 process.exit(res.status ?? 0);

package/scripts/smoke.ts

@@ -6,6 +6,7 @@
  *   bun run check:render
  */
 import { spawnSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
 import { resolve } from "node:path";
 
 type Case = { file: string; frame: number; theme?: string; format?: string; note: string };
@@ -36,8 +37,25 @@ for (const c of CASES) {
   }
 }
 
+let total = CASES.length;
+
+// Storyboard: the dry-run preview path (plan + one still per beat → a sheet).
+// The only automated guard for the data-URI contact-sheet render.
+total++;
+process.stdout.write("· storyboard sheet (clarinet-3.18) … ");
+const sbOut = resolve("out/clarinet-3.18.storyboard.png");
+rmSync(sbOut, { force: true });
+const sb = spawnSync(bin, ["scripts/storyboard.ts", "src/content/clarinet-3.18.beats.ts"], { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
+if (sb.status === 0 && existsSync(sbOut)) {
+  console.log("ok");
+} else {
+  failed++;
+  console.log("FAIL");
+  console.error((sb.stderr || "").split("\n").slice(-6).join("\n"));
+}
+
 if (failed) {
-  console.error(`\n✗ ${failed}/${CASES.length} render cases failed`);
+  console.error(`\n✗ ${failed}/${total} cases failed`);
   process.exit(1);
 }
-console.log(`\n✓ ${CASES.length} render cases ok`);
+console.log(`\n✓ ${total} cases ok`);

package/scripts/storyboard.ts

@@ -0,0 +1,125 @@
+/**
+ * `cadence storyboard <beats>` — a dry-run / mock: print the whole video plan
+ * (beat-by-beat outline + pacing) AND render a single contact-sheet PNG with one
+ * representative still per beat — no MP4. The cheap artifact a user + the skill
+ * iterate on (features, theme, background) before committing to a full render.
+ *
+ * Per-beat stills are rendered at the beat's mid frame (entrance motion settled),
+ * downscaled, encoded as data URIs, and laid into the `Storyboard` composition —
+ * data URIs (not staticFile/public) so it works from a global install too.
+ *
+ *   cadence storyboard src/content/streams-launch.beats.ts [--theme slate] [--format 9x16]
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { type Beat, type Format } from "../src/schema/beats";
+import type { StoryboardCell, StoryboardProps } from "../src/components/Storyboard";
+import { auditBeats, ICON, rankFindings } from "./_audit";
+import { beatTimings, FPS, loadBeats } from "./_beats";
+import { binPath, pkgFile } from "./_pkg";
+import { resolveOutDir, resolveTheme } from "./_theme";
+
+const args = process.argv.slice(2);
+const getFlag = (name: string) => {
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq) return eq.split("=")[1];
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const file = args.find((a) => !a.startsWith("-"));
+if (!file) {
+  console.error("usage: cadence storyboard <beats.ts|.json> [--theme <name>] [--theme-file <path>] [--format 16x9|1x1|9x16]");
+  process.exit(1);
+}
+
+const { theme, themeFile } = resolveTheme({ theme: getFlag("--theme"), themeFile: getFlag("--theme-file"), beatsFile: file });
+
+/** Short label for a beat's backdrop (omitted background = the procedural default). */
+const bgTag = (b: Beat): string => {
+  const bg = b.background;
+  if (!bg) return "shapes";
+  if (bg.src) return "image";
+  if (bg.gradient) return "gradient";
+  if (bg.solid) return "solid";
+  return "shapes";
+};
+
+const parsed = await loadBeats(file);
+const fmt = (getFlag("--format") as Format | undefined) ?? parsed.format;
+parsed.format = fmt;
+const themeLabel = themeFile ? `custom (${basename(themeFile)})` : (theme ?? "default");
+const { timings, totalFrames } = beatTimings(parsed.beats);
+const name = basename(file).replace(/\.beats\.(ts|js|json)$/, "").replace(/\.(ts|js|json)$/, "");
+
+// --- 1. The plan (text) ---
+console.log(`\nstoryboard: ${file}`);
+console.log(`  ${parsed.beats.length} beats · ${(totalFrames / FPS).toFixed(1)}s · ${fmt} · theme ${themeLabel}\n`);
+
+parsed.beats.forEach((b, i) => {
+  const t = timings[i];
+  const start = `${(t.start / FPS).toFixed(1)}s`.padStart(6);
+  const dur = `${(t.dur / FPS).toFixed(1)}s`.padStart(5);
+  const layout = b.layout.padEnd(6);
+  const panel = (b.panel?.kind ?? "—").padEnd(14);
+  const bg = bgTag(b).padEnd(8);
+  console.log(`  ${String(i + 1).padStart(2)}  @${start}  ${dur}  ${layout}  ${panel}  ${bg}  ${b.headline}`);
+});
+
+const findings = rankFindings(auditBeats(parsed.beats));
+if (findings.length) {
+  console.log("");
+  for (const f of findings) console.log(`  ${ICON[f.level]} ${f.msg}`);
+}
+
+// --- 2. The sheet (one still per beat → a single PNG) ---
+const env: NodeJS.ProcessEnv = { ...process.env };
+if (theme) env.REMOTION_VIDEO_THEME = theme;
+if (themeFile) env.REMOTION_VIDEO_THEME_JSON = readFileSync(themeFile, "utf8");
+
+const outDir = resolveOutDir({ outFlag: getFlag("--out"), beatsFile: file });
+mkdirSync(outDir, { recursive: true });
+const tmp = join(outDir, `.sb-${name}`);
+mkdirSync(tmp, { recursive: true });
+const propsPath = join(tmp, "props.json");
+writeFileSync(propsPath, JSON.stringify(parsed));
+
+const bin = binPath("remotion");
+const entry = pkgFile("src/index.ts");
+const TRANSPARENT_PX =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==";
+
+console.log(`\nrendering ${parsed.beats.length} stills…`);
+const cells: StoryboardCell[] = parsed.beats.map((b, i) => {
+  const out = join(tmp, `beat-${i}.png`);
+  const res = spawnSync(
+    bin,
+    ["still", entry, "Changelog", out, `--props=${propsPath}`, `--frame=${timings[i].mid}`, "--scale=0.33"],
+    { stdio: ["ignore", "ignore", "inherit"], env },
+  );
+  let img = TRANSPARENT_PX;
+  if (res.status === 0 && existsSync(out) && statSync(out).size > 0) {
+    img = `data:image/png;base64,${readFileSync(out).toString("base64")}`;
+  } else {
+    console.warn(`  ! beat ${i + 1} still failed — placeholder used`);
+  }
+  return { img, headline: b.headline, panel: b.panel?.kind ?? "—", seconds: `${(b.durationInFrames / FPS).toFixed(1)}s` };
+});
+
+const sheetProps: StoryboardProps = { format: fmt, name, cells };
+const sheetPropsPath = join(tmp, "sheet.json");
+writeFileSync(sheetPropsPath, JSON.stringify(sheetProps));
+
+const outPng = join(outDir, `${name}.storyboard.png`);
+const sheet = spawnSync(bin, ["still", entry, "Storyboard", outPng, `--props=${sheetPropsPath}`], {
+  stdio: ["ignore", "ignore", "inherit"],
+  env,
+});
+rmSync(tmp, { recursive: true, force: true });
+
+if (sheet.status !== 0) {
+  console.error("\n✗ storyboard sheet render failed");
+  process.exit(sheet.status ?? 1);
+}
+console.log(`\n→ ${outPng}\n`);

package/src/Root.tsx

@@ -2,6 +2,7 @@ import { Composition } from "remotion";
 import { Changelog } from "./components/Changelog";
 import { MotionReel } from "./components/MotionReel";
 import { ContactSheet } from "./components/ContactSheet";
+import { Storyboard, sheetLayout, type StoryboardProps } from "./components/Storyboard";
 import { changelogSchema } from "./schema/beats";
 import { prepareChangelog } from "./prepare";
 import { waitForFonts } from "./brand/fonts";
@@ -9,6 +10,18 @@ import streams from "./content/streams.beats";
 
 const defaultProps = changelogSchema.parse(streams);
 
+// A 1×1 transparent PNG — keeps the Storyboard sample props tiny + self-contained.
+const TRANSPARENT_PX =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==";
+const storyboardSample: StoryboardProps = {
+  format: "16x9",
+  name: "storyboard preview",
+  cells: [
+    { img: TRANSPARENT_PX, headline: "First beat.", panel: "—", seconds: "5.0s" },
+    { img: TRANSPARENT_PX, headline: "Second beat.", panel: "data-table", seconds: "6.0s" },
+  ],
+};
+
 export const RemotionRoot: React.FC = () => {
   return (
     <>
@@ -46,6 +59,20 @@ export const RemotionRoot: React.FC = () => {
           return c;
         }}
       />
+      <Composition
+        id="Storyboard"
+        component={Storyboard}
+        defaultProps={storyboardSample}
+        durationInFrames={1}
+        fps={30}
+        width={1600}
+        height={900}
+        calculateMetadata={async (c) => {
+          await waitForFonts();
+          const { width, height } = sheetLayout(c.props.format, c.props.cells.length);
+          return { ...c, width, height };
+        }}
+      />
     </>
   );
 };

package/src/brand/tokens.ts

@@ -9,6 +9,9 @@ export const COLORS = activeTheme.colors;
 
 export const CARET_BG = activeTheme.caretBg;
 
+/** Code window chrome — `"window"` (floating editor) or `"minimal"` (docs-style). */
+export const CODE_CHROME = activeTheme.codeChrome ?? "window";
+
 /** Light [from, to] gradient for the procedural default backdrop ("shapes"). */
 export const BACKDROP: [string, string] = activeTheme.backdrop ?? ["#e6edff", "#f8faff"];
 

package/src/components/Changelog.tsx

@@ -1,17 +1,66 @@
-import { Series } from "remotion";
-import type { ChangelogVideo } from "../schema/beats";
+import { AbsoluteFill, Sequence, Series } from "remotion";
+import { COLORS } from "../brand/tokens";
+import type { Beat, ChangelogVideo } from "../schema/beats";
+import { Background } from "./Background";
 import { ChangelogScene } from "./ChangelogScene";
 
-/** Top-level composition: a Series of beats. Duration/dimensions/tokens are set
- * by `calculateMetadata` in Root before this renders. */
+/** Frames of crossfade when the backdrop actually changes between beats. */
+const XFADE = 18;
+
+/** Identity key for a backdrop — beats that resolve to the same key share one
+ * continuous Background (no transition between them). Omitted background and an
+ * explicit `shapes` both resolve to the default procedural backdrop. */
+function bgKey(bg: Beat["background"]): string {
+  if (!bg || bg.shapes) return "shapes";
+  if (bg.src) return `img:${bg.src}:${bg.treatment ?? "kenburns"}`;
+  if (bg.gradient) return `grad:${bg.gradient[0]},${bg.gradient[1]}:${bg.angle ?? 160}`;
+  if (bg.solid) return `solid:${bg.solid}`;
+  return "shapes";
+}
+
+type Segment = { key: string; bg: Beat["background"]; from: number; duration: number };
+
+/** Collapse consecutive same-backdrop beats into segments laid end-to-end. */
+function backgroundSegments(beats: Beat[]): Segment[] {
+  const segs: Segment[] = [];
+  let frame = 0;
+  for (const b of beats) {
+    const key = bgKey(b.background);
+    const last = segs[segs.length - 1];
+    if (last && last.key === key) last.duration += b.durationInFrames;
+    else segs.push({ key, bg: b.background, from: frame, duration: b.durationInFrames });
+    frame += b.durationInFrames;
+  }
+  return segs;
+}
+
+/**
+ * Top-level composition. The backdrop is a **continuous layer** underneath the
+ * content: consecutive beats with the same backdrop share one Background (so it
+ * doesn't fade out/in or reset its Ken Burns between them) — only the content
+ * (headline, code, panel) transitions per beat. A real backdrop change
+ * crossfades (the next segment starts XFADE frames early and fades in on top).
+ * Duration/dimensions/tokens are set by `calculateMetadata` in Root.
+ */
 export const Changelog: React.FC<ChangelogVideo> = ({ format, beats }) => {
+  const segments = backgroundSegments(beats);
   return (
-    <Series>
-      {beats.map((beat) => (
-        <Series.Sequence key={beat.id} durationInFrames={beat.durationInFrames}>
-          <ChangelogScene beat={beat} format={format} />
-        </Series.Sequence>
-      ))}
-    </Series>
+    <AbsoluteFill style={{ backgroundColor: COLORS.ink }}>
+      {segments.map((seg, i) => {
+        const from = i === 0 ? 0 : Math.max(0, seg.from - XFADE);
+        return (
+          <Sequence key={`${seg.key}-${seg.from}`} from={from} durationInFrames={seg.from + seg.duration - from} layout="none">
+            <Background bg={seg.bg} />
+          </Sequence>
+        );
+      })}
+      <Series>
+        {beats.map((beat) => (
+          <Series.Sequence key={beat.id} durationInFrames={beat.durationInFrames}>
+            <ChangelogScene beat={beat} format={format} />
+          </Series.Sequence>
+        ))}
+      </Series>
+    </AbsoluteFill>
   );
 };

package/src/components/ChangelogScene.tsx

@@ -3,7 +3,6 @@ import { COLORS, EASE } from "../brand/tokens";
 import { FONTS } from "../brand/fonts";
 import { isLightBackdrop } from "../brand/tone";
 import type { Beat, Format } from "../schema/beats";
-import { Background } from "./Background";
 import { Headline } from "./Headline";
 import { CodeWindow, codeTypingDoneFrame } from "./CodeWindow";
 import { Panel } from "./panels";
@@ -32,9 +31,10 @@ export const ChangelogScene: React.FC<{ beat: Beat; format: Format }> = ({ beat,
   // Sequential: the output panel waits for the code to finish "running".
   const panelStart = beat.code ? codeTypingDoneFrame(beat.code.tokens ?? [], beat.code.motion) + OUTPUT_GAP : 0;
 
+  // Background is a continuous layer in Changelog (so same-bg beats don't
+  // re-fade); this scene renders only the content that transitions per beat.
   return (
-    <AbsoluteFill style={{ backgroundColor: COLORS.ink }}>
-      <Background bg={beat.background} />
+    <AbsoluteFill>
       <Headline eyebrow={beat.eyebrow} headline={beat.headline} motion={beat.headlineMotion} format={format} light={light} />
 
       <div

package/src/components/CodeWindow.tsx

@@ -1,5 +1,5 @@
 import { useCurrentFrame } from "remotion";
-import { CARET_BG, COLORS, FLOAT_SHADOW } from "../brand/tokens";
+import { CARET_BG, CODE_CHROME, COLORS, FLOAT_SHADOW } from "../brand/tokens";
 import { FONTS } from "../brand/fonts";
 import { useMotion, type MotionSpec } from "../motion/useMotion";
 import { CODE_BG, type CodeLine } from "../code/highlight";
@@ -24,6 +24,7 @@ export const codeTypingDoneFrame = (tokens: CodeLine[], motion?: MotionSpec) =>
 export const CodeWindow: React.FC<Props> = ({ filename, tokens, motion = { enter: "settle", delay: 12 }, fontSize = 22 }) => {
   const frame = useCurrentFrame();
   const style = useMotion(motion);
+  const minimal = CODE_CHROME === "minimal";
 
   const typeStart = typeStartFor(motion);
   const total = totalChars(tokens);
@@ -81,7 +82,7 @@ export const CodeWindow: React.FC<Props> = ({ filename, tokens, motion = { enter
     <div
       style={{
         width: "100%",
-        borderRadius: 20,
+        borderRadius: minimal ? 12 : 20,
         background: `${CODE_BG}f7`,
         boxShadow: FLOAT_SHADOW,
         backdropFilter: "blur(6px)",
@@ -90,11 +91,13 @@ export const CodeWindow: React.FC<Props> = ({ filename, tokens, motion = { enter
         ...style,
       }}
     >
-      <div style={{ height: 54, display: "flex", alignItems: "center", padding: "0 22px", gap: 9 }}>
-        <Dot color="#f6645f" /><Dot color="#f7bd45" /><Dot color="#2fc94e" />
-        <span style={{ flex: 1, textAlign: "center", color: "rgba(0,0,0,0.34)", fontSize: 15, fontFamily: FONTS.mono, marginRight: 60 }}>{filename}</span>
-      </div>
-      <div style={{ padding: "26px 40px 42px", fontFamily: FONTS.mono, fontSize, lineHeight: `${lineHeight}px`, color: COLORS.ink }}>
+      {!minimal && (
+        <div style={{ height: 54, display: "flex", alignItems: "center", padding: "0 22px", gap: 9 }}>
+          <Dot color="#f6645f" /><Dot color="#f7bd45" /><Dot color="#2fc94e" />
+          <span style={{ flex: 1, textAlign: "center", color: "rgba(0,0,0,0.34)", fontSize: 15, fontFamily: FONTS.mono, marginRight: 60 }}>{filename}</span>
+        </div>
+      )}
+      <div style={{ padding: minimal ? "30px 34px" : "26px 40px 42px", fontFamily: FONTS.mono, fontSize, lineHeight: `${lineHeight}px`, color: COLORS.ink }}>
         {lines}
       </div>
     </div>

package/src/components/Storyboard.tsx

@@ -0,0 +1,68 @@
+import { AbsoluteFill, Img } from "remotion";
+import { type Format } from "../schema/beats";
+import { COLORS, RADIUS } from "../brand/tokens";
+import { FONTS } from "../brand/fonts";
+
+/**
+ * A contact sheet for a beats file: one representative still per beat in a
+ * labeled grid. Pure and props-driven — images arrive as base64 data URIs in
+ * props (NOT staticFile/public, so it works from a global install), unlike
+ * ContactSheet which fetches a manifest. `scripts/storyboard.ts` renders the
+ * per-beat stills, encodes them, and renders this composition to a single PNG.
+ */
+export type StoryboardCell = { img: string; headline: string; panel: string; seconds: string };
+export type StoryboardProps = { format: Format; name: string; cells: StoryboardCell[] };
+
+const PAD = 56;
+const GAP = 24;
+const HEADER = 110;
+const CAPTION = 56;
+const WIDTH = 1600;
+
+/**
+ * Grid geometry + total canvas height for a given format and beat count. Used
+ * both by the component (columns + cell aspect) and by `calculateMetadata` in
+ * Root.tsx (canvas height) so the sheet fits its contents with no clipping.
+ */
+export function sheetLayout(format: Format, count: number) {
+  const cols = format === "9x16" ? 4 : 3;
+  const rows = Math.max(1, Math.ceil(count / cols));
+  const cellW = (WIDTH - PAD * 2 - GAP * (cols - 1)) / cols;
+  const ar = format === "16x9" ? 9 / 16 : format === "9x16" ? 16 / 9 : 1; // height / width
+  const cellH = cellW * ar + CAPTION;
+  const height = Math.round(HEADER + PAD * 2 + rows * cellH + (rows - 1) * GAP);
+  const cellAspect = format === "16x9" ? "16 / 9" : format === "9x16" ? "9 / 16" : "1 / 1";
+  return { cols, width: WIDTH, height, cellAspect };
+}
+
+export const Storyboard: React.FC<StoryboardProps> = ({ format, name, cells }) => {
+  const { cols, cellAspect } = sheetLayout(format, cells.length);
+  return (
+    <AbsoluteFill style={{ background: COLORS.paper, padding: PAD, fontFamily: FONTS.body }}>
+      <div style={{ fontFamily: FONTS.display, fontSize: 40, fontWeight: 600, letterSpacing: "-0.02em", color: COLORS.ink }}>{name}</div>
+      <div style={{ fontFamily: FONTS.note, fontSize: 22, color: COLORS.signalBlue, marginBottom: 28 }}>
+        storyboard · {cells.length} beats · {format}
+      </div>
+      <div style={{ display: "grid", gridTemplateColumns: `repeat(${cols}, 1fr)`, gap: GAP }}>
+        {cells.map((c, i) => (
+          <div key={i} style={{ borderRadius: RADIUS.lg, overflow: "hidden", border: `1px solid ${COLORS.hairline}`, background: COLORS.paperElevated }}>
+            <Img
+              src={c.img}
+              onError={() => {}}
+              delayRenderTimeoutInMilliseconds={8000}
+              style={{ width: "100%", aspectRatio: cellAspect, objectFit: "cover", display: "block", background: COLORS.paper }}
+            />
+            <div style={{ display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 12, padding: "12px 16px" }}>
+              <span style={{ fontSize: 17, fontWeight: 600, color: COLORS.ink, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                {i + 1}. {c.headline}
+              </span>
+              <span style={{ fontFamily: FONTS.mono, fontSize: 12, textTransform: "uppercase", letterSpacing: "0.06em", color: COLORS.textMuted, whiteSpace: "nowrap" }}>
+                {c.panel} · {c.seconds}
+              </span>
+            </div>
+          </div>
+        ))}
+      </div>
+    </AbsoluteFill>
+  );
+};

package/src/theme/types.ts

@@ -62,6 +62,12 @@ export type ThemeConfig = {
   caretBg: string;
   /** Syntax colors. */
   codeTheme: CodeTheme;
+  /**
+   * Code window chrome. `"window"` (default) is a floating editor with traffic-
+   * light dots + a filename tab; `"minimal"` is chromeless (just the code surface)
+   * to match a docs-style snippet component.
+   */
+  codeChrome?: "window" | "minimal";
   /** Light [from, to] gradient for the procedural default backdrop (Background "shapes"). */
   backdrop?: [string, string];
 };