@waits/cadence 0.4.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.4.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/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/render.ts

@@ -7,9 +7,10 @@
  *   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 { stagePublicDir } from "./_assets";
 import { loadBeats } from "./_beats";
 import { binPath, pkgFile } from "./_pkg";
 import { resolveOutDir, resolveTheme } from "./_theme";
@@ -48,8 +49,12 @@ 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(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 });
+  ? 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,6 +15,7 @@ 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 { stagePublicDir } from "./_assets";
 import { auditBeats, ICON, rankFindings } from "./_audit";
 import { beatTimings, FPS, loadBeats } from "./_beats";
 import { binPath, pkgFile } from "./_pkg";
@@ -87,6 +88,9 @@ 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==";
 
@@ -95,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;
@@ -117,6 +121,7 @@ const sheet = spawnSync(bin, ["still", entry, "Storyboard", outPng, `--props=${s
   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/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>