@waits/cadence 0.3.0 → 0.4.0

package/package.json

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

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/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

@@ -10,9 +10,9 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { type Format } from "../src/schema/beats";
-import { THEMES } from "../src/theme";
 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 +34,22 @@ 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/storyboard.ts

@@ -15,10 +15,10 @@ 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 { 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 +34,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,8 +78,9 @@ 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));
@@ -115,7 +111,7 @@ 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,

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