@waits/cadence 0.2.0

package/scripts/cli.ts

@@ -0,0 +1,79 @@
+/**
+ * Unified front door. `cadence <command> …` dispatches to the pieces.
+ *
+ *   cadence create --release stx-labs/clarinet --install "brew install clarinet"
+ *   cadence create src/content/x.beats.ts --format 9x16   # a beats file → video
+ *   cadence study --from-url https://acme.dev --name acme
+ *   cadence audit src/content/x.beats.ts
+ *   cadence redesign src/content/x.beats.ts --theme slate
+ */
+import { spawnSync } from "node:child_process";
+import { TEMPLATES } from "../src/templates";
+import { THEMES } from "../src/theme";
+import { binPath, pkgFile } from "./_pkg";
+
+const [rawSub, ...rest] = process.argv.slice(2);
+
+// Legacy verb aliases → canonical intent verbs.
+const ALIAS: Record<string, string> = { make: "create", theme: "study" };
+const sub = rawSub ? (ALIAS[rawSub] ?? rawSub) : rawSub;
+
+// Verb → script. `create` is resolved dynamically (repo flow vs. beats file).
+const SCRIPTS: Record<string, string> = {
+  guide: "scripts/guide.ts", // interactive walkthrough
+  render: "scripts/render.ts", // a beats file → a video (create delegates here)
+  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
+  changes: "scripts/changes.ts", // a repo → an UpdateManifest
+  art: "scripts/generate-art.ts", // optional painterly background pack
+};
+
+const HELP = `cadence — turn a repo / release into a changelog or announcement video.
+
+commands:
+  create     a repo OR a beats file → a video     cadence create --release owner/name --install "npm i pkg"
+  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
+  guide      interactive walkthrough (start here)   cadence guide
+
+utilities:
+  render     a beats file → a video (create delegates here for beats files)
+  changes    a repo → an UpdateManifest (json)
+  art        generate painterly backgrounds (optional pack, needs OPENAI_API_KEY)
+  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>`;
+
+if (!sub || sub === "help" || sub === "--help") {
+  console.log(HELP);
+  process.exit(0);
+}
+if (sub === "templates") {
+  console.log("templates:\n" + Object.keys(TEMPLATES).map((t) => `  ${t}`).join("\n"));
+  process.exit(0);
+}
+if (sub === "themes") {
+  console.log("themes:\n" + Object.keys(THEMES).map((t) => `  ${t}`).join("\n"));
+  process.exit(0);
+}
+
+// `create` merges the repo flow (make) and the beats-file flow (render): a
+// positional beats-like file routes to render; otherwise to make.
+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";
+  }
+  return SCRIPTS[verb];
+}
+
+const script = resolveScript(sub, rest);
+if (!script) {
+  console.error(`unknown command "${rawSub}".\n\n${HELP}`);
+  process.exit(1);
+}
+const res = spawnSync(binPath("tsx"), [pkgFile(script), ...rest], { stdio: "inherit" });
+process.exit(res.status ?? 0);

package/scripts/generate-art.ts

@@ -0,0 +1,72 @@
+/**
+ * "Hill Country Sublime" painting generator. Builds a prompt from the art system
+ * (prompts/art/*) and calls OpenAI gpt-image-1 (base64 response → PNG). Writes to
+ * public/backgrounds/_candidates/ and updates a manifest the ContactSheet reads.
+ *
+ *   bun run art --landmark pennybacker --level heightened [--format 16x9] [--quality high]
+ *   bun run art --all --level heightened --format 16x9      # every landmark
+ *
+ * Requires OPENAI_API_KEY. Chosen winners get moved to public/backgrounds/ (committed).
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { composePrompt, LANDMARKS, type FantasyLevel, type LandmarkKey } from "../prompts/art/compose";
+import type { Format } from "../src/schema/beats";
+
+const SIZE: Record<Format, string> = { "16x9": "1536x1024", "1x1": "1024x1024", "9x16": "1024x1536" };
+const CANDIDATES = "public/backgrounds/_candidates";
+const MANIFEST = join(CANDIDATES, "manifest.json");
+
+const args = process.argv.slice(2);
+const flag = (name: string, def?: 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]?.startsWith("--") ? args[i + 1] : def;
+};
+const has = (name: string) => args.includes(name);
+
+const level = (flag("--level", "heightened") as FantasyLevel);
+const format = (flag("--format", "16x9") as Format);
+const quality = flag("--quality", "high")!;
+const landmarks: LandmarkKey[] = has("--all")
+  ? (Object.keys(LANDMARKS) as LandmarkKey[])
+  : [(flag("--landmark", "pennybacker") as LandmarkKey)];
+
+if (!process.env.OPENAI_API_KEY) {
+  console.error("✗ OPENAI_API_KEY not set");
+  process.exit(1);
+}
+
+mkdirSync(CANDIDATES, { recursive: true });
+type Entry = { file: string; landmark: string; level: string; format: string; name: string };
+const manifest: Entry[] = existsSync(MANIFEST) ? JSON.parse(readFileSync(MANIFEST, "utf8")) : [];
+
+async function generate(landmark: LandmarkKey) {
+  const prompt = composePrompt(landmark, level, format);
+  const fname = `${landmark}-${level}-${format}.png`;
+  process.stdout.write(`· ${fname} … `);
+  const res = await fetch("https://api.openai.com/v1/images/generations", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ model: "gpt-image-1", prompt, size: SIZE[format], quality, n: 1 }),
+  });
+  if (!res.ok) {
+    console.log("FAILED");
+    console.error(await res.text());
+    return;
+  }
+  const json = await res.json();
+  const b64 = json.data[0].b64_json as string;
+  writeFileSync(join(CANDIDATES, fname), Buffer.from(b64, "base64"));
+  const entry: Entry = { file: `backgrounds/_candidates/${fname}`, landmark: LANDMARKS[landmark].name, level, format, name: fname };
+  const idx = manifest.findIndex((m) => m.name === fname);
+  if (idx >= 0) manifest[idx] = entry; else manifest.push(entry);
+  console.log("ok");
+}
+
+for (const lm of landmarks) {
+  await generate(lm);
+}
+writeFileSync(MANIFEST, JSON.stringify(manifest, null, 2));
+console.log(`\n✓ ${landmarks.length} image(s) → ${CANDIDATES}/  (manifest: ${manifest.length} total)`);

package/scripts/guide.ts

@@ -0,0 +1,114 @@
+/**
+ * Interactive walkthrough. Run on any project to (a) make a video, (b) understand
+ * the pipeline as you go, (c) learn where to adjust each piece.
+ *
+ *   bun run cli guide
+ */
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { resolve } from "node:path";
+import { TEMPLATES } from "../src/templates";
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+const cancel = () => {
+  console.log("\n\n  cancelled — run `bun run cli guide` any time.\n");
+  rl.close();
+  process.exit(0);
+};
+rl.on("SIGINT", cancel);
+
+const ask = async (q: string, def = "") => (await rl.question(`${q}${def ? ` [${def}]` : ""}: `)).trim() || def;
+const say = (s = "") => console.log(s);
+const rule = () => say("─".repeat(64));
+const tsx = (args: string[], opts: { capture?: boolean } = {}) =>
+  spawnSync(resolve("node_modules/.bin/tsx"), args, { stdio: opts.capture ? ["ignore", "pipe", "inherit"] : "inherit", encoding: "utf8" });
+
+async function main() {
+  rule();
+  say("  cadence — interactive walkthrough");
+  rule();
+  say(`
+This turns a repo / release into a changelog or announcement video. The pipeline:
+
+   repo → [adapter] → manifest → [template] → beats → [engine] → mp4
+                                      ▲             ▲
+                                  themeable     honest, no LLM
+
+We'll walk it one stage at a time. Press enter to accept the [defaults].
+`);
+
+  // ── 1. Source ────────────────────────────────────────────────────────────
+  rule();
+  say("STEP 1 — what changed?  (adapters: src/adapters/)");
+  say("Point at a GitHub repo's latest release. The adapter parses the notes into");
+  say("a normalized manifest (it strips emoji/PR-refs and reports what it dropped).\n");
+  const repo = await ask("GitHub repo (owner/name)", "stx-labs/clarinet");
+  const tag = await ask("release tag (blank = latest)");
+  say("\n→ running: cli changes --release " + repo + (tag ? ` --tag ${tag}` : ""));
+  tsx(["scripts/changes.ts", "--release", repo, ...(tag ? ["--tag", tag] : [])]);
+  say("\nThat JSON is the 'UpdateManifest' — every later stage reads from it.");
+  say("Tweak parsing in src/adapters/parse.ts.\n");
+
+  // ── 2. Template ──────────────────────────────────────────────────────────
+  rule();
+  say("STEP 2 — the arc.  (templates: src/templates/)");
+  say("A template maps the manifest to beats, deterministically and honestly");
+  say("(no fabricated code). Available: " + Object.keys(TEMPLATES).join(", ") + ".\n");
+  const template = await ask("template", "changelog-reel");
+  const install = await ask("real install line for the closer (e.g. 'brew install clarinet')");
+
+  // ── 3. Look ──────────────────────────────────────────────────────────────
+  rule();
+  say("STEP 3 — the look.  (themes: src/theme/ · style packs: Background.tsx)");
+  say("Background style packs: gradient / solid / image (a painting). Theme sets");
+  say("the colors, fonts, and code palette — try 'default' or 'slate', or extract");
+  say("a brand's color from a URL with: cli study --from-url <site> --name <name>.\n");
+  const format = await ask("format (16x9 / 1x1 / 9x16)", "16x9");
+  const background = await ask("background (gradient:#a,#b | solid:#hex | image:file.png)", "gradient:#312e81,#0b1120");
+  const theme = await ask("theme (default / slate)", "default");
+
+  const makeArgs = (extra: string[]) => [
+    "scripts/make.ts", "--release", repo, ...(tag ? ["--tag", tag] : []),
+    "--template", template, "--format", format, "--background", background, "--theme", theme,
+    ...(install ? ["--install", install] : []), ...extra,
+  ];
+
+  // ── 4. Preview ───────────────────────────────────────────────────────────
+  rule();
+  say("STEP 4 — preview a single frame (fast, ~5s) before the full render.\n");
+  tsx(makeArgs(["--frame", "200"]));
+  say("\n→ open the .png in out/ to eyeball it. Adjust the template/background/theme above if needed.");
+
+  const again = (await ask("\nrender the full video now? (y/n)", "y")).toLowerCase();
+  if (again.startsWith("y")) {
+    rule();
+    say("STEP 5 — full render.\n");
+    tsx(makeArgs([]));
+    say("\n→ the mp4 is in out/.");
+  }
+
+  // ── Close ────────────────────────────────────────────────────────────────
+  rule();
+  say("WHERE TO GO NEXT");
+  rule();
+  say(`
+Understand it      WALKTHROUGH.md (architecture + how to adjust each part)
+Honest code        the 'cadence' skill reads a repo's types to add real
+                   code snippets (the LLM path, vs the deterministic templates here)
+Add a panel        src/components/panels/  → register in panels/index.tsx + schema
+Add a template     src/templates/          → register in templates/index.ts
+Brand colors       cli study --from-url <site> --name <n>  → --theme-file themes/<n>.json
+Ship on release    docs/github-action.md   (auto-render on every release, free)
+
+Run again any time:  bun run cli guide
+`);
+  rl.close();
+}
+
+main().catch((e) => {
+  if (e?.code === "ABORT_ERR" || e?.name === "AbortError") cancel(); // Ctrl+C / Ctrl+D mid-prompt
+  console.error(e);
+  rl.close();
+  process.exit(1);
+});

package/scripts/make.ts

@@ -0,0 +1,76 @@
+/**
+ * One command: a repo → a video, no LLM. Reads the latest release/changelog,
+ * applies a template, and renders.
+ *
+ *   tsx scripts/make.ts --release stx-labs/clarinet --install "brew install clarinet"
+ *   tsx scripts/make.ts --release owner/name --template changelog-reel --background "gradient:#312e81,#0b1120" --format 9x16
+ *   tsx scripts/make.ts --changelog ./CHANGELOG.md --product my-pkg --install "npm i my-pkg" --frame 230
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { manifestFromChangelogText, manifestFromReleaseBody } from "../src/adapters";
+import type { BackgroundSpec } from "../src/templates";
+import { TEMPLATES } from "../src/templates";
+import { binPath, pkgFile } from "./_pkg";
+
+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;
+};
+
+function parseBackground(s?: string): BackgroundSpec | undefined {
+  if (!s) return undefined;
+  if (s === "shapes") return { shapes: true };
+  const [kind, rest] = [s.slice(0, s.indexOf(":")), s.slice(s.indexOf(":") + 1)];
+  if (kind === "gradient") {
+    const [from, to] = rest.split(",");
+    return { gradient: [from, to], angle: 155, treatment: "kenburns" };
+  }
+  if (kind === "solid") return { solid: rest, treatment: "static" };
+  if (kind === "image") return { src: rest.includes("/") ? rest : `backgrounds/${rest}`, treatment: "kenburns" };
+  return undefined;
+}
+
+// 1. Source → manifest
+const release = flag("--release");
+const changelog = flag("--changelog");
+const install = flag("--install");
+let manifest;
+if (release) {
+  const tag = flag("--tag");
+  const res = spawnSync("gh", ["release", "view", ...(tag ? [tag] : []), "--repo", release, "--json", "tagName,name,publishedAt,body"], { encoding: "utf8" });
+  if (res.status !== 0) { console.error(res.stderr); process.exit(1); }
+  const r = JSON.parse(res.stdout);
+  manifest = manifestFromReleaseBody({ product: flag("--product") ?? basename(release), version: r.tagName ?? r.name ?? "", body: r.body ?? "", date: r.publishedAt?.slice(0, 10), install, repoUrl: `https://github.com/${release}` });
+} else if (changelog) {
+  manifest = manifestFromChangelogText(readFileSync(changelog, "utf8"), { product: flag("--product") ?? "package", install });
+} else {
+  console.error("usage: make.ts --release <owner/name> | --changelog <path> [--template T] [--background B] [--format F] [--theme T] [--frame N]");
+  process.exit(1);
+}
+
+// 2. Template → beats
+const templateName = flag("--template") ?? "changelog-reel";
+const template = TEMPLATES[templateName];
+if (!template) { console.error(`unknown template "${templateName}". have: ${Object.keys(TEMPLATES).join(", ")}`); process.exit(1); }
+const statValue = flag("--stat-value");
+const beats = template(manifest, {
+  format: flag("--format") as never,
+  background: parseBackground(flag("--background")),
+  headline: flag("--headline"),
+  stat: statValue ? { value: statValue, label: flag("--stat-label") ?? "", sub: flag("--stat-sub") } : undefined,
+});
+
+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`);
+writeFileSync(jsonPath, JSON.stringify(beats));
+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" });
+process.exit(res.status ?? 0);

package/scripts/redesign.ts

@@ -0,0 +1,83 @@
+/**
+ * `cadence redesign <beats>` — re-skin an existing beats file: override the
+ * background / motion fingerprint and theme while preserving all content
+ * (headlines, code, panels). Writes a new beats JSON to out/ and renders it.
+ *
+ *   cadence redesign src/content/mainnet-launch.beats.ts --theme slate
+ *   cadence redesign x.beats.ts --background "gradient:#312e81,#0b1120" --enter rise
+ */
+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 Beat } from "../src/schema/beats";
+import { ENTER_PRESETS, EXIT_PRESETS } from "../src/motion/names";
+import { binPath, pkgFile } from "./_pkg";
+
+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 file = args.find((a) => !a.startsWith("-"));
+if (!file) {
+  console.error("usage: cadence redesign <beats.ts|.json> [--background B] [--enter E] [--exit X] [--theme T] [--format F] [--frame N]");
+  process.exit(1);
+}
+
+// Same background mini-DSL as `make`: gradient:#a,#b | solid:#hex | image:file.png
+function parseBackground(s: string): Beat["background"] {
+  if (s === "shapes") return { shapes: true, treatment: "static", angle: 160 };
+  const kind = s.slice(0, s.indexOf(":"));
+  const rest = s.slice(s.indexOf(":") + 1);
+  if (kind === "gradient") {
+    const [from, to] = rest.split(",");
+    return { gradient: [from, to], angle: 155, treatment: "kenburns" };
+  }
+  if (kind === "solid") return { solid: rest, angle: 160, treatment: "static" };
+  if (kind === "image") return { src: rest.includes("/") ? rest : `backgrounds/${rest}`, angle: 160, treatment: "kenburns" };
+  console.error(`unknown --background "${s}" (gradient:#a,#b | solid:#hex | image:file.png)`);
+  process.exit(1);
+}
+
+const bg = flag("--background");
+const bgSpec = bg ? parseBackground(bg) : undefined;
+const enter = flag("--enter");
+const exit = flag("--exit");
+if (enter && !(ENTER_PRESETS as readonly string[]).includes(enter)) {
+  console.error(`unknown --enter "${enter}". have: ${ENTER_PRESETS.join(", ")}`);
+  process.exit(1);
+}
+if (exit && !(EXIT_PRESETS as readonly string[]).includes(exit)) {
+  console.error(`unknown --exit "${exit}". have: ${EXIT_PRESETS.join(", ")}`);
+  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);
+
+// Re-skin: override style fields, preserve content (headline/eyebrow/code/panel).
+const enterVal = enter as (typeof ENTER_PRESETS)[number] | undefined;
+const exitVal = exit as (typeof EXIT_PRESETS)[number] | undefined;
+parsed.beats = parsed.beats.map((b) => ({
+  ...b,
+  ...(bgSpec ? { background: bgSpec } : {}),
+  ...(enterVal || exitVal
+    ? { headlineMotion: { ...(b.headlineMotion ?? {}), ...(enterVal ? { enter: enterVal } : {}), ...(exitVal ? { exit: exitVal } : {}) } }
+    : {}),
+}));
+
+mkdirSync("out", { recursive: true });
+const name = basename(file).replace(/\.beats\.(ts|js|json)$/, "").replace(/\.(ts|js|json)$/, "");
+const outBeats = join("out", `${name}.redesign.beats.json`);
+writeFileSync(outBeats, JSON.stringify(parsed));
+console.error(`· redesigned ${name} → ${outBeats}`);
+
+const passthru = ["--theme", "--theme-file", "--format", "--frame"].flatMap((f) => (flag(f) ? [f, flag(f)!] : []));
+const res = spawnSync(binPath("tsx"), [pkgFile("scripts/render.ts"), outBeats, ...passthru], { stdio: "inherit" });
+process.exit(res.status ?? 0);

package/scripts/render.ts

@@ -0,0 +1,62 @@
+/**
+ * Render a beats module to MP4. Remotion `--props` accepts JSON only, so this
+ * imports the authored `.ts`, validates it against the schema, serializes to a
+ * temp JSON file, and hands that to the Remotion CLI. Code tokenization +
+ * duration + dimensions happen in the composition's calculateMetadata.
+ *
+ *   bun run render src/content/streams.beats.ts [--format 16x9|1x1|9x16] [--frame N]
+ */
+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 { binPath, pkgFile } from "./_pkg";
+
+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: bun run render <beats.ts> [--format 16x9|1x1|9x16] [--frame N]");
+  process.exit(1);
+}
+
+// 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 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 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 name = basename(file).replace(/\.beats\.(ts|js|json)$/, "").replace(/\.(ts|js|json)$/, "");
+const propsPath = join("out", `.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 });
+
+process.exit(res.status ?? 0);

package/scripts/smoke.ts

@@ -0,0 +1,43 @@
+/**
+ * Render smoke test — re-renders a matrix of key stills (panels × themes ×
+ * formats) and fails if any errors. Cheap regression gate for CI. (A perceptual
+ * pixel-diff against committed references is the stronger follow-up.)
+ *
+ *   bun run check:render
+ */
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+
+type Case = { file: string; frame: number; theme?: string; format?: string; note: string };
+
+const CASES: Case[] = [
+  { file: "src/content/streams-launch.beats.ts", frame: 470, note: "proof panel + typed code" },
+  { file: "src/content/streams-launch.beats.ts", frame: 850, note: "fork panel" },
+  { file: "src/content/streams-launch.beats.ts", frame: 660, note: "stream-resume panel" },
+  { file: "src/content/gradient-demo.beats.ts", frame: 230, note: "gradient pack + stat (no art)" },
+  { file: "src/content/clarinet-3.18.beats.ts", frame: 320, theme: "slate", note: "status + slate code theme" },
+  { file: "src/content/sdk-6.5-mempool.beats.ts", frame: 330, format: "9x16", note: "data-table, vertical reflow" },
+];
+
+const bin = resolve("node_modules/.bin/tsx");
+let failed = 0;
+for (const c of CASES) {
+  const args = ["scripts/render.ts", c.file, "--frame", String(c.frame)];
+  if (c.theme) args.push("--theme", c.theme);
+  if (c.format) args.push("--format", c.format);
+  process.stdout.write(`· ${c.note} … `);
+  const res = spawnSync(bin, args, { stdio: ["ignore", "ignore", "pipe"], encoding: "utf8" });
+  if (res.status === 0) {
+    console.log("ok");
+  } else {
+    failed++;
+    console.log("FAIL");
+    console.error((res.stderr || "").split("\n").slice(-6).join("\n"));
+  }
+}
+
+if (failed) {
+  console.error(`\n✗ ${failed}/${CASES.length} render cases failed`);
+  process.exit(1);
+}
+console.log(`\n✓ ${CASES.length} render cases ok`);

package/scripts/sync-skill.ts

@@ -0,0 +1,43 @@
+/**
+ * Sync the canonical skill to the formats other editors expect, so there's one
+ * source of truth and no hand-maintained copies.
+ *
+ *   source:  .claude/skills/cadence/   (Claude Code; what you edit)
+ *   →  skills/cadence/                  (the `npx skills add <repo>` layout)
+ *   →  .cursor/rules/cadence.mdc        (Cursor rule)
+ *
+ * Codex reads the same `skills/<name>/` layout via `npx skills add`, so no separate
+ * copy is committed. Run after editing the skill:  bun run sync-skill
+ */
+import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { PKG_ROOT } from "./_pkg";
+
+const NAME = "cadence";
+const SRC = join(PKG_ROOT, ".claude/skills", NAME);
+
+// 1. Frontmatter (name, description) + body from the canonical SKILL.md.
+const skill = readFileSync(join(SRC, "SKILL.md"), "utf8");
+const fm = skill.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+if (!fm) {
+  console.error("✗ SKILL.md is missing frontmatter");
+  process.exit(1);
+}
+const description = (fm[1].match(/^description:\s*(.*)$/m)?.[1] ?? "").trim();
+const body = fm[2].trimStart();
+
+// 2. Distribution copy at the repo-root `skills/<name>/` layout.
+const distDir = join(PKG_ROOT, "skills", NAME);
+rmSync(distDir, { recursive: true, force: true });
+mkdirSync(distDir, { recursive: true });
+cpSync(SRC, distDir, { recursive: true });
+console.log(`✓ skills/${NAME}/  (npx skills add layout)`);
+
+// 3. Cursor rule — an agent-requested rule carrying the same body.
+const cursorDir = join(PKG_ROOT, ".cursor/rules");
+mkdirSync(cursorDir, { recursive: true });
+const mdc = `---\ndescription: ${description}\nalwaysApply: false\n---\n\n${body}`;
+writeFileSync(join(cursorDir, `${NAME}.mdc`), mdc);
+console.log(`✓ .cursor/rules/${NAME}.mdc`);
+
+console.log("\nEdit the skill in .claude/skills/, then re-run `bun run sync-skill`.");