reelkit-cli 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 What changed in each published version of `reelkit-cli`, newest first. A push to `main` publishes the version in
 `package.json` when it is not on npm yet, and it must have an entry here.
 
+## 0.12.2 - 2026-10-09
+
+- You can keep 50 templates (it was 20).
+
+## 0.12.1 - 2026-10-09
+
+- A pushed template now carries, for each scene, the plan's visual direction and the components the composition times to it, and for the film every component it uses (written for the project, pulled from the library or from the kit).
+- Sound effects and the music track carry their library ids, so a template's timeline can copy the command that pulls each one.
+- Scene pictures are sharper (640 pixels wide).
+
 ## 0.12.0 - 2026-10-09
 
 - Templates: `reelkit template push` saves a whole project in your private files (the plan, the composition, everything under `assets/` and the rendered video), and `reelkit template clone <id>` unpacks one into a new project to continue or remix. `reelkit template list` and `reelkit template delete <id>` manage them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelkit-cli",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "CLI and Claude skill for making short-form video with a shared asset library.",
   "license": "MIT",
   "author": "Daniel Livshin",

package/skill/SKILL.md

@@ -15,7 +15,7 @@ For image or video cutouts, editable Blender product shots, custom 3D materials,
 
 To implement a chosen style, read its row in `reference/style-recipes.md` for action, timing, sound and proof. `reference/style-components.md` maps the shared components and built-in kit to shot roles; inspect the selected source before using its props.
 
-This skill targets `reelkit-cli` 0.12.0 and its HyperFrames kit. Check the installed version with `reelkit --version`; in a source checkout, invoke its `bin/reelkit.mjs` with Node. Use the matching CLI before authoring with `reelkit/frame`.
+This skill targets `reelkit-cli` 0.12.2 and its HyperFrames kit. Check the installed version with `reelkit --version`; in a source checkout, invoke its `bin/reelkit.mjs` with Node. Use the matching CLI before authoring with `reelkit/frame`.
 
 ## What decides whether the film is accepted
 

package/src/commands/template.ts

@@ -11,6 +11,8 @@ import type { MusicRecord } from "../project/music";
 import { FILES, openProject, Project } from "../project/project";
 import { SOUND_MAP, type SoundMapEntry } from "./build";
 import { decodeMono } from "../project/refmeasure";
+import { componentsOf } from "../project/scene-components";
+import { leadingComment } from "./components";
 import { AUDIO_RATE, hitTimes, swells } from "../project/soundreport";
 
 const sh = promisify(execFile);
@@ -38,6 +40,13 @@ export function filmOf(project: Project): TemplateFilm | undefined {
   const music = project.readJsonOr<MusicRecord | undefined>(FILES.music, undefined);
   const seconds = manifest.totalFrames / manifest.fps;
   const cut = (s: string, max: number) => (s.length > max ? s.slice(0, max) : s);
+  // The components, from the composition's source: which ones it uses, and which scenes time each of them.
+  const pulled = Object.values(project.readJsonOr<Record<string, { path?: string; kind?: string }>>(FILES.library, {})).filter((p) => p.kind === "component" && p.path).map((p) => basename(p.path!).replace(/\.tsx$/, ""));
+  let used: ReturnType<typeof componentsOf> = [];
+  try { if (project.exists("src/Video.tsx")) used = componentsOf(readFileSync(project.path("src/Video.tsx"), "utf8"), { sceneIds: plan.scenes.map((s) => s.id), pulled }); } catch { used = []; }
+  const about = (name: string): string | undefined => {
+    try { return project.exists(`src/${name}.tsx`) ? leadingComment(readFileSync(project.path(`src/${name}.tsx`), "utf8"), name)?.replace(/\s+/g, " ").trim() : undefined; } catch { return undefined; }
+  };
   return {
     aspect: plan.aspect, fps: manifest.fps, width: manifest.width, height: manifest.height, totalFrames: Math.round(manifest.totalFrames),
     scenes: manifest.scenes.slice(0, 200).map((m) => {
@@ -48,9 +57,12 @@ export function filmOf(project: Project): TemplateFilm | undefined {
         id: cut(m.id, 80), start: Math.max(0, Math.round(m.startFrame)), frames: Math.max(0, Math.round(m.durationFrames)),
         ...(p?.treatment ? { treatment: cut(p.treatment, 60) } : {}), ...(narration ? { narration: cut(narration, 4000) } : {}),
         ...(text.length ? { text } : {}), ...(m.words.length ? { words: m.words.slice(0, 600).map((w) => Math.max(0, Math.round(w.startSec * 1000) / 1000)) } : {}),
+        ...(p?.notes?.trim() ? { notes: cut(p.notes.trim(), 2000) } : {}),
+        ...(used.some((c) => c.scenes.includes(m.id)) ? { components: used.filter((c) => c.scenes.includes(m.id)).map((c) => cut(c.name, 80)).slice(0, 60) } : {}),
       };
     }),
-    ...(music ? { music: { title: cut(music.title, 200), seconds: music.durationSec, ...(music.bpm ? { bpm: music.bpm } : {}), beats: music.beats.filter((b) => b >= 0 && b <= seconds).slice(0, 4000) } } : {}),
+    ...(music ? { music: { title: cut(music.title, 200), seconds: music.durationSec, ...(music.bpm ? { bpm: music.bpm } : {}), beats: music.beats.filter((b) => b >= 0 && b <= seconds).slice(0, 4000), ...(music.id ? { id: cut(music.id, 128) } : {}) } } : {}),
+    ...(used.length ? { components: used.slice(0, 300).map((c) => { const text = c.from === "kit" ? undefined : about(c.name); return { name: cut(c.name, 80), from: c.from, uses: c.uses, ...(text ? { about: cut(text, 400) } : {}) }; }) } : {}),
     voice: plan.voice !== "none",
     ...(manifest.captions ? { captions: manifest.captions } : {}),
     ...cuesOf(project, manifest, music?.key),
@@ -62,7 +74,7 @@ export function filmOf(project: Project): TemplateFilm | undefined {
 function cuesOf(project: Project, manifest: AssetManifest, musicKey: string | undefined): Pick<TemplateFilm, "cues"> {
   const map = project.readJsonOr<SoundMapEntry[]>(SOUND_MAP, []);
   if (!Array.isArray(map) || !map.length) return {};
-  const pulled = Object.values(project.readJsonOr<Record<string, { path?: string; kind?: string; title?: string; meta?: { durationSec?: number } }>>(FILES.library, {}));
+  const pulled = Object.entries(project.readJsonOr<Record<string, { path?: string; kind?: string; title?: string; meta?: { durationSec?: number } }>>(FILES.library, {})).map(([id, p]) => ({ ...p, id }));
   const voice = new Set(manifest.scenes.map((s) => s.voiceoverKey).filter(Boolean));
   const cues = map.filter((e) => e && typeof e.path === "string" && e.path !== musicKey && e.path !== manifest.music?.key && !voice.has(e.path)).flatMap((e) => {
     const lib = pulled.find((p) => p.path === e.path);
@@ -71,7 +83,7 @@ function cuesOf(project: Project, manifest: AssetManifest, musicKey: string | un
     // A sound is registered until the end of the stretch it sits in, which is often the rest of the film: its own length is the file's.
     const own = typeof lib?.meta?.durationSec === "number" && lib.meta.durationSec > 0 ? lib.meta.durationSec : 0;
     const seconds = Math.max(0, Math.round(Math.min(own || 0, Math.max(0, e.end - e.start)) * 1000) / 1000);
-    return [{ at: Math.max(0, e.start), seconds, title, ...(lib?.kind ? { kind: lib.kind.slice(0, 24) } : {}) }];
+    return [{ at: Math.max(0, e.start), seconds, title, ...(lib?.kind ? { kind: lib.kind.slice(0, 24) } : {}), ...(lib?.id ? { id: lib.id.slice(0, 128) } : {}) }];
   }).slice(0, 1500);
   return cues.length ? { cues } : {};
 }
@@ -84,7 +96,7 @@ async function thumbsOf(video: string, film: TemplateFilm, dir: string): Promise
     const at = (scene.start + scene.frames / 2) / film.fps;
     const file = join(dir, `thumb-${i}.jpg`);
     try {
-      await sh("ffmpeg", ["-nostdin", "-v", "error", "-y", "-ss", at.toFixed(3), "-i", video, "-frames:v", "1", "-vf", "scale=320:-2", "-q:v", "7", file]);
+      await sh("ffmpeg", ["-nostdin", "-v", "error", "-y", "-ss", at.toFixed(3), "-i", video, "-frames:v", "1", "-vf", "scale=640:-2", "-q:v", "6", file]);
       const bytes = readFileSync(file);
       if (!bytes.length || bytes.length > MAX_TEMPLATE_THUMB_BYTES) break;
       out.push(new Uint8Array(bytes));

package/src/contract/index.ts

@@ -176,7 +176,7 @@ const Empty = z.object({});
 // A template is a whole video project kept in its owner's private files: the bundle (the project folder as a .tgz, without out/, refs/
 // and caches), the rendered video when there is one, a small picture per scene, and `film`, a summary of the timeline that a page can
 // draw without opening the bundle. Only its owner can list, read, clone or delete it. Nothing here reaches the shared library.
-export const MAX_TEMPLATES = 20;
+export const MAX_TEMPLATES = 50;
 export const MAX_TEMPLATE_THUMBS = 60;
 export const MAX_TEMPLATE_THUMB_BYTES = 200_000;
 export const TEMPLATE_BUNDLE_TYPE = "application/gzip";
@@ -194,9 +194,12 @@ export const TemplateFilmSchema = z.object({
   scenes: z.array(z.object({
     id: text(80), start: frames, frames, treatment: text(60).optional(), narration: text(4000).optional(),
     text: z.array(text(400)).max(20).optional(), words: z.array(z.number().min(0)).max(600).optional(),
+    // The plan's visual direction for the scene, and the components the composition times to it (read from its source).
+    notes: text(2000).optional(), components: z.array(text(80)).max(60).optional(),
   })).min(1).max(200),
   // The music track, with the seconds at which its beats fall inside the film.
-  music: z.object({ title: text(200), seconds: z.number().min(0), bpm: z.number().optional(), beats: z.array(z.number().min(0)).max(4000).optional() }).optional(),
+  // `id` is the track's id in the library, when it was pulled from there.
+  music: z.object({ title: text(200), seconds: z.number().min(0), bpm: z.number().optional(), beats: z.array(z.number().min(0)).max(4000).optional(), id: text(128).optional() }).optional(),
   voice: z.boolean().optional(),
   captions: z.string().max(16).optional(),
   // What a listener hears besides the voice and the music's pulse, measured from the rendered film's sound: the seconds at which a hit
@@ -204,7 +207,11 @@ export const TemplateFilmSchema = z.object({
   hits: z.array(z.number().min(0)).max(3000).optional(),
   swells: z.array(z.object({ start: z.number().min(0), length: z.number().min(0) })).max(600).optional(),
   // The sound effects by name, when the render recorded them: each one's title, when it starts and how long it plays, in seconds.
-  cues: z.array(z.object({ at: z.number().min(0), seconds: z.number().min(0), title: text(200), kind: text(24).optional() })).max(1500).optional(),
+  // `id` is the sound's id in the library, when it was pulled from there.
+  cues: z.array(z.object({ at: z.number().min(0), seconds: z.number().min(0), title: text(200), kind: text(24).optional(), id: text(128).optional() })).max(1500).optional(),
+  // Every component the composition uses: one written in the project, one pulled from the library, or one of the kit's. `uses` is how
+  // many times it appears, and `about` is the comment above a project component.
+  components: z.array(z.object({ name: text(80), from: z.enum(["project", "library", "kit"]), uses: z.number().int().min(1), about: text(400).optional() })).max(300).optional(),
 });
 export type TemplateFilm = z.infer<typeof TemplateFilmSchema>;
 export const TemplateSchema = z.object({

package/src/project/scene-components.ts

@@ -0,0 +1,90 @@
+import ts from "typescript";
+import { sourceFile } from "../render/static-check";
+
+// Which components a composition uses, and in which scenes, read from its source without running it.
+//
+// A composition is one tree, not a file per scene, so "this component belongs to that scene" is read from how it is timed: a variable
+// made with `sceneById(manifest, "id")` stands for a scene, a variable computed from one stands for the same scene, and a component
+// whose props (or whose enclosing element's props) mention such a variable is counted for that scene. A component timed by plain
+// numbers, or by nothing, is counted for the film as a whole and for no scene. It is a reading of the code, not a measurement.
+export type UsedComponent = { name: string; from: "project" | "kit" | "library"; uses: number; scenes: string[] };
+
+// Tags that are plumbing rather than something the film shows.
+const PLUMBING = new Set(["Sequence", "AbsoluteFill", "Series", "Fragment", "React.Fragment", "Audio", "Img", "Video", "OffthreadVideo", "Loop", "Freeze"]);
+
+export function componentsOf(source: string, opts: { sceneIds: string[]; pulled?: string[] } = { sceneIds: [] }): UsedComponent[] {
+  const sf = sourceFile(source, "Video.tsx");
+  const known = new Set(opts.sceneIds);
+  const pulled = new Set(opts.pulled ?? []);
+  // Where each imported name comes from.
+  const origin = new Map<string, UsedComponent["from"]>();
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier) || !stmt.importClause) continue;
+    const spec = stmt.moduleSpecifier.text;
+    const from: UsedComponent["from"] | undefined = spec === "reelkit/kit" ? "kit" : spec.startsWith("./") ? "project" : undefined;
+    if (!from) continue;
+    const names: string[] = [];
+    if (stmt.importClause.name) names.push(stmt.importClause.name.text);
+    const bindings = stmt.importClause.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) for (const el of bindings.elements) if (!el.isTypeOnly) names.push(el.name.text);
+    for (const name of names) origin.set(name, from === "project" && pulled.has(name) ? "library" : from);
+  }
+
+  // Variables that stand for a scene: `const grow = sceneById(manifest, "grow")`, then anything computed from one, in source order.
+  const sceneOf = new Map<string, Set<string>>();
+  const idsIn = (node: ts.Node): Set<string> => {
+    const found = new Set<string>();
+    const walk = (n: ts.Node) => {
+      if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === "sceneById") {
+        const arg = n.arguments[1];
+        if (arg && ts.isStringLiteralLike(arg) && (!known.size || known.has(arg.text))) found.add(arg.text);
+      }
+      if (ts.isIdentifier(n)) for (const id of sceneOf.get(n.text) ?? []) found.add(id);
+      ts.forEachChild(n, walk);
+    };
+    walk(node);
+    return found;
+  };
+  const declare = (node: ts.Node) => {
+    if (ts.isVariableDeclaration(node) && node.initializer) {
+      const ids = idsIn(node.initializer);
+      if (ids.size) {
+        const bind = (name: ts.BindingName) => {
+          if (ts.isIdentifier(name)) sceneOf.set(name.text, new Set([...(sceneOf.get(name.text) ?? []), ...ids]));
+          else for (const el of name.elements) if (ts.isBindingElement(el)) bind(el.name);
+        };
+        bind(node.name);
+      }
+    }
+    ts.forEachChild(node, declare);
+  };
+  // Twice, so a variable computed from one declared further down (a helper above its data) is still followed.
+  declare(sf); declare(sf);
+
+  const used = new Map<string, { uses: number; scenes: Set<string> }>();
+  const visit = (node: ts.Node, inherited: Set<string>) => {
+    let here = inherited;
+    const opening = ts.isJsxSelfClosingElement(node) ? node : ts.isJsxElement(node) ? node.openingElement : undefined;
+    if (opening) {
+      const own = idsIn(opening.attributes);
+      here = own.size ? own : inherited;
+      const tag = opening.tagName.getText(sf);
+      const from = origin.get(tag.split(".")[0]!);
+      if (from && !PLUMBING.has(tag) && /^[A-Z]/.test(tag)) {
+        const entry = used.get(tag) ?? { uses: 0, scenes: new Set<string>() };
+        entry.uses += 1;
+        for (const id of here) entry.scenes.add(id);
+        used.set(tag, entry);
+      }
+    }
+    // A block of JSX produced inside an expression that mentions a scene (a `.map` over that scene's items, a condition on its frame)
+    // belongs to that scene too.
+    if (ts.isJsxExpression(node) && node.expression) { const own = idsIn(node.expression); if (own.size && !ts.isJsxElement(node.expression)) here = new Set([...own]); }
+    ts.forEachChild(node, (child) => visit(child, here));
+  };
+  visit(sf, new Set());
+
+  const order = opts.sceneIds;
+  return [...used].map(([name, u]) => ({ name, from: origin.get(name.split(".")[0]!)!, uses: u.uses, scenes: [...u.scenes].sort((a, b) => order.indexOf(a) - order.indexOf(b)) }))
+    .sort((a, b) => (a.from === b.from ? b.uses - a.uses || a.name.localeCompare(b.name) : ["project", "library", "kit"].indexOf(a.from) - ["project", "library", "kit"].indexOf(b.from)));
+}