@waits/cadence 0.3.0 → 0.5.0

package/README.md

@@ -104,13 +104,19 @@ Layout: `src/schema` (the beats contract), `src/components` (scene + panels),
 `src/motion` (the lexicon), `src/theme` (themes + derivation), `src/templates`
 (the no-LLM repo→beats path), `prompts/art` (the optional painterly pack).
 
-## Optional: painterly backgrounds
+## Optional: generated backgrounds
 
-The default backdrop is procedural and needs no key. For the optional
-"Hill Country Sublime" landscape pack (see **[ART-DIRECTION.md](ART-DIRECTION.md)**):
+The default backdrop is procedural and needs no key. For custom painted
+backdrops, `cadence art` generates them from a freeform prompt — landing in your
+project's `.cadence/backgrounds/`, ready to reference as `image:<file>`:
 
 ```bash
-cadence art --landmark pennybacker --level heightened   # needs OPENAI_API_KEY
+cadence art --prompt "misty redwood coastline at dawn" --name redwood   # needs OPENAI_API_KEY
+cadence art --promote redwood                                           # candidate → backgrounds/
 ```
 
-This is the only part of the toolchain that calls an external API.
+Reusable subject sets go in a `--pack <file.json>`; the bundled "Hill Country
+Sublime" landscape pack is the default (`cadence art --all`). This is the only
+part of the toolchain that calls an external API. See
+**[docs/guides/custom-backgrounds.md](docs/guides/custom-backgrounds.md)** and
+**[ART-DIRECTION.md](ART-DIRECTION.md)**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waits/cadence",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "license": "MIT",
   "bin": {

package/prompts/art/compose.ts

@@ -3,14 +3,24 @@ import { COMPOSITION, NEGATIVES, STYLE } from "./style";
 import { LANDMARKS, type LandmarkKey } from "./landmarks";
 import { FANTASY, type FantasyLevel } from "./fantasy";
 
-/** Build the full image-gen prompt for a landmark × fantasy level × format. */
-export function composePrompt(landmark: LandmarkKey, level: FantasyLevel, format: Format): string {
+/**
+ * Build the full image-gen prompt for a freeform subject × fantasy level × format.
+ * `style`/`negatives` default to the built-in luminist look; a pack or `--style-file`
+ * can override them. `COMPOSITION` (UI-safe framing) is always engine-supplied.
+ */
+export function composePrompt(opts: {
+  subject: string;
+  level: FantasyLevel;
+  format: Format;
+  style?: string;
+  negatives?: string;
+}): string {
   return [
-    STYLE,
-    `Subject: ${LANDMARKS[landmark].subject}.`,
-    FANTASY[level],
-    COMPOSITION[format],
-    NEGATIVES,
+    opts.style ?? STYLE,
+    `Subject: ${opts.subject}.`,
+    FANTASY[opts.level],
+    COMPOSITION[opts.format],
+    opts.negatives ?? NEGATIVES,
   ].join(" ");
 }
 

package/scripts/_assets.ts

@@ -0,0 +1,31 @@
+/**
+ * Stage a merged public dir for a project render. Remotion's `--public-dir` is a
+ * single replacement dir (not an overlay), and the engine's own `public/` holds
+ * assets shipped beats reference (`mountains.jpg`, built-in `backgrounds/*.png`).
+ * So when a project supplies its own art in `<project>/.cadence/backgrounds/`, we
+ * merge the engine's `public/*` with the project's `backgrounds/` into a temp dir
+ * and point `--public-dir` there — both built-in and project images resolve.
+ *
+ * `_candidates/` is excluded (the unpromoted generation pile — not for rendering).
+ */
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pkgFile } from "./_pkg";
+import { findCadenceDir } from "./_theme";
+
+const noCandidates = (src: string) => !src.includes(`${join("backgrounds", "_candidates")}`);
+
+/** Returns an absolute staged public dir, or undefined when there's no project art. */
+export function stagePublicDir(opts: { beatsFile?: string; outDir: string }): string | undefined {
+  const start = opts.beatsFile ? dirname(resolve(opts.beatsFile)) : process.cwd();
+  const cad = findCadenceDir(start);
+  const projBg = cad ? join(cad, "backgrounds") : undefined;
+  if (!projBg || !existsSync(projBg)) return undefined;
+
+  const staged = resolve(opts.outDir, ".pub");
+  rmSync(staged, { recursive: true, force: true });
+  mkdirSync(staged, { recursive: true });
+  cpSync(pkgFile("public"), staged, { recursive: true, filter: noCandidates });
+  cpSync(projBg, join(staged, "backgrounds"), { recursive: true, filter: noCandidates });
+  return staged;
+}

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/cli.ts

@@ -47,7 +47,8 @@ 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") {

package/scripts/generate-art.ts

@@ -1,21 +1,26 @@
 /**
- * "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.
+ * Background painting generator. Builds a prompt from the art system (prompts/art/*)
+ * and calls OpenAI gpt-image-1 (base64 → PNG), then updates a manifest the
+ * ContactSheet reads. Freeform `--prompt` generates anything; with no prompt it
+ * pulls subjects from the built-in pack (the "Hill Country Sublime" landmarks).
  *
- *   bun run art --landmark pennybacker --level heightened [--format 16x9] [--quality high]
- *   bun run art --all --level heightened --format 16x9      # every landmark
+ * Output is project-local: run against a repo with a `.cadence/` dir and art lands
+ * in `<project>/.cadence/backgrounds/` (candidates under `_candidates/`); otherwise
+ * the cadence engine's own `public/backgrounds/`.
  *
- * Requires OPENAI_API_KEY. Chosen winners get moved to public/backgrounds/ (committed).
+ *   bun run art --prompt "misty redwood coastline at dawn" --name redwood
+ *   bun run art --all --level heightened --format 16x9       # every built-in subject
+ *   bun run art --promote redwood                            # candidate(s) → backgrounds/
+ *
+ * Requires OPENAI_API_KEY (except --promote, which only moves files).
  */
-import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { composePrompt, LANDMARKS, type FantasyLevel, type LandmarkKey } from "../prompts/art/compose";
+import { composePrompt, LANDMARKS, type FantasyLevel } from "../prompts/art/compose";
 import type { Format } from "../src/schema/beats";
+import { findCadenceDir } from "./_theme";
 
 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) => {
@@ -25,26 +30,95 @@ const flag = (name: string, def?: string) => {
   return i >= 0 && !args[i + 1]?.startsWith("--") ? args[i + 1] : def;
 };
 const has = (name: string) => args.includes(name);
+const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+// T4: project-local art base. A project's `.cadence/backgrounds/` if present
+// (discovered from cwd), else the engine's committed `public/backgrounds/`.
+const cad = findCadenceDir(process.cwd());
+const ART_BASE = cad ? join(cad, "backgrounds") : "public/backgrounds";
+const CANDIDATES = join(ART_BASE, "_candidates");
+const MANIFEST = join(CANDIDATES, "manifest.json");
+
+const level = flag("--level", "heightened") as FantasyLevel;
+const format = flag("--format", "16x9") as Format;
+const quality = flag("--quality", "medium")!;
+
+type Entry = { file: string; subject: string; level: string; format: string; name: string };
+mkdirSync(CANDIDATES, { recursive: true });
+const manifest: Entry[] = existsSync(MANIFEST) ? JSON.parse(readFileSync(MANIFEST, "utf8")) : [];
+
+// T6: promote — move a chosen candidate (by slug or filename) to backgrounds/,
+// and drop it from the candidates manifest (its path would otherwise go stale).
+const promote = flag("--promote");
+if (promote) {
+  const key = slugify(promote);
+  const matches = manifest.filter((m) => m.name === promote || m.name.startsWith(`${key}-`));
+  if (!matches.length) {
+    console.error(`✗ no candidate matching "${promote}" in ${CANDIDATES}`);
+    process.exit(1);
+  }
+  mkdirSync(ART_BASE, { recursive: true });
+  for (const m of matches) {
+    const from = join(CANDIDATES, m.name);
+    if (existsSync(from)) {
+      renameSync(from, join(ART_BASE, m.name));
+      console.log(`✓ promoted ${m.name} → ${ART_BASE}/  (reference as image:${m.name})`);
+    }
+  }
+  const promoted = new Set(matches.map((m) => m.name));
+  writeFileSync(MANIFEST, JSON.stringify(manifest.filter((m) => !promoted.has(m.name)), null, 2));
+  process.exit(0);
+}
+
+// Subject source: a user-supplied pack (`--pack file.json`) or the built-in
+// landmark pack. A pack may also override the style/negatives (else engine defaults).
+type Pack = { style?: string; negatives?: string; subjects: Record<string, { name: string; subject: string }> };
+const packFile = flag("--pack");
+const pack: Pack = packFile ? JSON.parse(readFileSync(packFile, "utf8")) : { subjects: LANDMARKS };
+const styleFile = flag("--style-file");
+const style = styleFile ? readFileSync(styleFile, "utf8") : pack.style;
+const negatives = pack.negatives;
 
-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)];
+// A job = one image to generate. Freeform `--prompt` (needs `--name`) wins;
+// otherwise pull subjects from the pack via --landmark/--all.
+type Job = { subject: string; slug: string; label: string };
+const promptText = flag("--prompt");
+let jobs: Job[];
+if (promptText) {
+  const name = flag("--name");
+  if (!name) {
+    console.error("✗ --prompt requires --name <slug> (used for the filename + manifest label)");
+    process.exit(1);
+  }
+  jobs = [{ subject: promptText, slug: slugify(name), label: name }];
+} else {
+  const keys = has("--all") ? Object.keys(pack.subjects) : [flag("--landmark", Object.keys(pack.subjects)[0])!];
+  jobs = keys.map((k) => {
+    const s = pack.subjects[k];
+    if (!s) {
+      console.error(`✗ "${k}" not in pack (have: ${Object.keys(pack.subjects).join(", ")})`);
+      process.exit(1);
+    }
+    return { subject: s.subject, slug: k, label: s.name };
+  });
+}
+
+// Cost guard: batch runs cost real money — require explicit --yes after an estimate.
+const COST: Record<string, number> = { low: 0.02, medium: 0.06, high: 0.19 }; // ~USD/image, approx
+if (jobs.length > 1 && !has("--yes")) {
+  const est = (COST[quality] ?? 0.06) * jobs.length;
+  console.error(`⚠ ${jobs.length} images at quality "${quality}" ≈ $${est.toFixed(2)} (approx). Re-run with --yes to proceed.`);
+  process.exit(1);
+}
 
 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`;
+async function generate(job: Job) {
+  const prompt = composePrompt({ subject: job.subject, level, format, style, negatives });
+  const fname = `${job.slug}-${level}-${format}.png`;
   process.stdout.write(`· ${fname} … `);
   const res = await fetch("https://api.openai.com/v1/images/generations", {
     method: "POST",
@@ -59,14 +133,15 @@ async function generate(landmark: LandmarkKey) {
   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 entry: Entry = { file: `backgrounds/_candidates/${fname}`, subject: job.label, level, format, name: fname };
   const idx = manifest.findIndex((m) => m.name === fname);
-  if (idx >= 0) manifest[idx] = entry; else manifest.push(entry);
+  if (idx >= 0) manifest[idx] = entry;
+  else manifest.push(entry);
   console.log("ok");
 }
 
-for (const lm of landmarks) {
-  await generate(lm);
+for (const job of jobs) {
+  await generate(job);
 }
 writeFileSync(MANIFEST, JSON.stringify(manifest, null, 2));
-console.log(`\n✓ ${landmarks.length} image(s) → ${CANDIDATES}/  (manifest: ${manifest.length} total)`);
+console.log(`\n✓ ${jobs.length} image(s) → ${CANDIDATES}/  (manifest: ${manifest.length} total)`);

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) => {
@@ -68,18 +69,21 @@ const beats = template(manifest, {
 console.error(`· ${manifest.product} ${manifest.version}: ${manifest.features.length} features${manifest.dropped ? ` (+${manifest.dropped} dropped)` : ""} → ${templateName}`);
 
 // 3. Write beats JSON, then render — or, with --dry-run, storyboard it (preview
-// sheet + plan, no MP4).
-mkdirSync("out", { recursive: true });
-const jsonPath = join("out", `make-${manifest.product}.beats.json`);
+// 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], { stdio: "inherit" });
+  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

@@ -7,12 +7,13 @@
  *   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 { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { type Format } from "../src/schema/beats";
-import { THEMES } from "../src/theme";
+import { stagePublicDir } from "./_assets";
 import { loadBeats } from "./_beats";
 import { binPath, pkgFile } from "./_pkg";
+import { resolveOutDir, resolveTheme } from "./_theme";
 
 const args = process.argv.slice(2);
 const getFlag = (name: string) => {
@@ -34,26 +35,26 @@ 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}` : "";
+// Stage a merged public dir when the project supplies its own backgrounds.
+const staged = stagePublicDir({ beatsFile: file, outDir });
+const pub = staged ? [`--public-dir=${staged}`] : [];
 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}`, ...pub], { stdio: "inherit", env })
+  : spawnSync(bin, ["render", ...common, join(outDir, `${name}-${parsed.format}${suffix}.mp4`), `--props=${propsPath}`, "--image-format=jpeg", ...pub], { stdio: "inherit", env });
+if (staged) rmSync(staged, { recursive: true, force: true });
 
 process.exit(res.status ?? 0);

package/scripts/storyboard.ts

@@ -15,10 +15,11 @@ import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync }
 import { basename, join } from "node:path";
 import { type Beat, type Format } from "../src/schema/beats";
 import type { StoryboardCell, StoryboardProps } from "../src/components/Storyboard";
-import { THEMES } from "../src/theme";
+import { stagePublicDir } from "./_assets";
 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) => {
@@ -34,12 +35,7 @@ if (!file) {
   process.exit(1);
 }
 
-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 });
 
 /** Short label for a beat's backdrop (omitted background = the procedural default). */
 const bgTag = (b: Beat): string => {
@@ -83,14 +79,18 @@ const env: NodeJS.ProcessEnv = { ...process.env };
 if (theme) env.REMOTION_VIDEO_THEME = theme;
 if (themeFile) env.REMOTION_VIDEO_THEME_JSON = readFileSync(themeFile, "utf8");
 
-mkdirSync("out", { recursive: true });
-const tmp = join("out", `.sb-${name}`);
+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");
+// Stage a merged public dir so project backgrounds resolve in the per-beat stills.
+const staged = stagePublicDir({ beatsFile: file, outDir });
+const pub = staged ? [`--public-dir=${staged}`] : [];
 const TRANSPARENT_PX =
   "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==";
 
@@ -99,7 +99,7 @@ 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"],
+    ["still", entry, "Changelog", out, `--props=${propsPath}`, `--frame=${timings[i].mid}`, "--scale=0.33", ...pub],
     { stdio: ["ignore", "ignore", "inherit"], env },
   );
   let img = TRANSPARENT_PX;
@@ -115,12 +115,13 @@ const sheetProps: StoryboardProps = { format: fmt, name, cells };
 const sheetPropsPath = join(tmp, "sheet.json");
 writeFileSync(sheetPropsPath, JSON.stringify(sheetProps));
 
-const outPng = join("out", `${name}.storyboard.png`);
+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 (staged) rmSync(staged, { recursive: true, force: true });
 
 if (sheet.status !== 0) {
   console.error("\n✗ storyboard sheet render failed");

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/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/ContactSheet.tsx

@@ -3,13 +3,13 @@ import { AbsoluteFill, Img, continueRender, delayRender, staticFile } from "remo
 import { COLORS, RADIUS } from "../brand/tokens";
 import { FONTS } from "../brand/fonts";
 
-type Entry = { file: string; landmark: string; level: string; format: string; name: string };
+type Entry = { file: string; subject: string; level: string; format: string; name: string };
 
 /**
- * Review board for generated paintings. Reads the candidates manifest written by
- * `bun run art` and lays them out in a labeled grid. Render with
- * `remotion still ContactSheet out/contact.png` to pick winners, then move the
- * chosen files from _candidates/ to committed public/backgrounds/.
+ * Review board for generated backgrounds. Reads the candidates manifest written
+ * by `cadence art` and lays them out in a labeled grid. Render with
+ * `remotion still ContactSheet out/contact.png` to pick winners, then promote the
+ * chosen files from _candidates/ to backgrounds/ (`cadence art --promote`).
  */
 export const ContactSheet: React.FC = () => {
   const [handle] = useState(() => delayRender("manifest"));
@@ -24,16 +24,16 @@ export const ContactSheet: React.FC = () => {
 
   return (
     <AbsoluteFill style={{ background: COLORS.paper, padding: 64, fontFamily: FONTS.body }}>
-      <div style={{ fontFamily: FONTS.display, fontSize: 44, fontWeight: 600, letterSpacing: "-0.02em", color: COLORS.ink }}>Hill Country Sublime</div>
+      <div style={{ fontFamily: FONTS.display, fontSize: 44, fontWeight: 600, letterSpacing: "-0.02em", color: COLORS.ink }}>Background candidates</div>
       <div style={{ fontFamily: FONTS.note, fontSize: 26, color: COLORS.signalBlue, marginBottom: 32 }}>
-        {items.length ? `${items.length} candidates — pick winners → public/backgrounds/` : "no candidates yet — run `bun run art --all`"}
+        {items.length ? `${items.length} candidates — pick winners → backgrounds/` : "no candidates yet — run `cadence art --prompt … --name …`"}
       </div>
       <div style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 24 }}>
         {items.map((it) => (
           <div key={it.name} style={{ borderRadius: RADIUS.lg, overflow: "hidden", border: `1px solid ${COLORS.hairline}`, background: COLORS.paperElevated }}>
             <Img src={staticFile(it.file)} style={{ width: "100%", aspectRatio: "16 / 9", objectFit: "cover", display: "block" }} />
             <div style={{ display: "flex", justifyContent: "space-between", alignItems: "baseline", padding: "12px 16px" }}>
-              <span style={{ fontSize: 18, fontWeight: 600, color: COLORS.ink }}>{it.landmark}</span>
+              <span style={{ fontSize: 18, fontWeight: 600, color: COLORS.ink }}>{it.subject}</span>
               <span style={{ fontFamily: FONTS.mono, fontSize: 12, textTransform: "uppercase", letterSpacing: "0.06em", color: COLORS.textMuted }}>{it.level} · {it.format}</span>
             </div>
           </div>

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];
 };