reelkit-cli 0.12.0 → 0.12.3

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.3 - 2026-10-09
+
+- A template's components are tied to scenes in more of the ways compositions are written: a project's own helper that is handed a scene's id, a lookup by id, a list that pairs ids with components, a branch on a scene's id, and components the file declares for itself.
+
+## 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.3",
   "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.3 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,167 @@
+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 placed and timed.
+// A call that is handed a scene's id as a string (`sceneById(manifest, "ask")`, a project's own `scene("ask", <>...</>)` or
+// `at("ask")`), or a lookup by it (`s["ask"]`), is about that scene. A variable made from such an expression stands for the scene, and
+// so does one computed from it. A component is counted for a scene when it is written inside such a call, or when its props (or its
+// enclosing element's props) mention one. A component placed by plain numbers, or by nothing, is counted 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>>();
+  // The scene ids this one node names outright: a string argument of a call, or the key of a lookup. With the plan's ids known, any
+  // call counts; without them only `sceneById`, so an ordinary string is never taken for a scene.
+  const named = (n: ts.Node): string[] => {
+    if (ts.isCallExpression(n)) {
+      if (!known.size) { const arg = ts.isIdentifier(n.expression) && n.expression.text === "sceneById" ? n.arguments[1] : undefined; return arg && ts.isStringLiteralLike(arg) ? [arg.text] : []; }
+      return n.arguments.filter((a): a is ts.StringLiteralLike => ts.isStringLiteralLike(a) && known.has(a.text)).map((a) => a.text);
+    }
+    if (ts.isElementAccessExpression(n) && ts.isStringLiteralLike(n.argumentExpression) && known.has(n.argumentExpression.text)) return [n.argumentExpression.text];
+    return [];
+  };
+  const idsIn = (node: ts.Node): Set<string> => {
+    const found = new Set<string>();
+    const walk = (n: ts.Node) => {
+      for (const id of named(n)) found.add(id);
+      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);
+
+  // The components the file declares for itself (a `const HookShot = () => ...`): what is written inside one belongs to the scenes that
+  // one is used in. The composition itself (`Video`) is not one of them.
+  const local = new Map<string, ts.Node>();
+  const collect = (node: ts.Node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && /^[A-Z]/.test(node.name.text) && node.initializer && (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer))) local.set(node.name.text, node.initializer);
+    if (ts.isFunctionDeclaration(node) && node.name && /^[A-Z]/.test(node.name.text)) local.set(node.name.text, node);
+    ts.forEachChild(node, collect);
+  };
+  collect(sf);
+  local.delete("Video");
+
+  type Use = { scenes: Set<string>; owner: string };
+  const uses = new Map<string, Use[]>();        // imported components
+  const localUses = new Map<string, Use[]>();   // the file's own components
+  const note = (map: Map<string, Use[]>, name: string, scenes: Set<string>, owner: string) => map.set(name, [...(map.get(name) ?? []), { scenes: new Set(scenes), owner }]);
+  // The ids a condition compares against: `scene.id === "hook"`.
+  const compared = (node: ts.Node): Set<string> => {
+    const found = new Set<string>();
+    const walk = (n: ts.Node) => {
+      if (ts.isBinaryExpression(n) && (n.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken || n.operatorToken.kind === ts.SyntaxKind.EqualsEqualsToken)) {
+        for (const side of [n.left, n.right]) if (ts.isStringLiteralLike(side) && known.has(side.text)) found.add(side.text);
+      }
+      ts.forEachChild(n, walk);
+    };
+    walk(node);
+    return found;
+  };
+  const visit = (node: ts.Node, inherited: Set<string>, owner: string) => {
+    let here = inherited;
+    let inside = owner;
+    for (const [name, body] of local) if (body === node) { inside = name; here = new Set(); }
+    const opening = ts.isJsxSelfClosingElement(node) ? node : ts.isJsxElement(node) ? node.openingElement : undefined;
+    if (opening) {
+      const own = idsIn(opening.attributes);
+      here = own.size ? own : here;
+      const tag = opening.tagName.getText(sf);
+      const root = tag.split(".")[0]!;
+      if (local.has(root)) note(localUses, root, here, inside);
+      else if (origin.get(root) && !PLUMBING.has(tag) && /^[A-Z]/.test(tag)) note(uses, tag, here, inside);
+    }
+    // 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]); }
+    // What is written inside a call that names a scene (`scene("ask", <>...</>)`) is that scene's.
+    const direct = named(node);
+    if (direct.length) here = new Set(direct);
+    // A list that pairs a scene's id with a component (`["hook", HookShot]`), or an object keyed by scene ids, places that component.
+    if (ts.isArrayLiteralExpression(node)) {
+      const ids = node.elements.filter((e): e is ts.StringLiteralLike => ts.isStringLiteralLike(e) && known.has(e.text)).map((e) => e.text);
+      if (ids.length) { here = new Set(ids); for (const e of node.elements) if (ts.isIdentifier(e) && local.has(e.text)) note(localUses, e.text, here, inside); }
+    }
+    if (ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name)) && known.has(node.name.text)) {
+      here = new Set([node.name.text]);
+      if (ts.isIdentifier(node.initializer) && local.has(node.initializer.text)) note(localUses, node.initializer.text, here, inside);
+    }
+    // The branch taken when a scene's id is the one compared against is that scene's.
+    if (ts.isConditionalExpression(node) || ts.isIfStatement(node)) {
+      const cond = ts.isConditionalExpression(node) ? node.condition : node.expression;
+      const then = ts.isConditionalExpression(node) ? node.whenTrue : node.thenStatement;
+      const ids = compared(cond);
+      if (ids.size) {
+        ts.forEachChild(node, (child) => visit(child, child === then ? ids : here, inside));
+        return;
+      }
+    }
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+      const ids = compared(node.left);
+      if (ids.size) { visit(node.left, here, inside); visit(node.right, ids, inside); return; }
+    }
+    if (ts.isCaseClause(node) && ts.isStringLiteralLike(node.expression) && known.has(node.expression.text)) here = new Set([node.expression.text]);
+    ts.forEachChild(node, (child) => visit(child, here, inside));
+  };
+  visit(sf, new Set(), "");
+
+  // The scenes of each of the file's own components: where it is placed, or, when it is placed inside another of them with no scene
+  // of its own, wherever that one is. Repeated until nothing changes, so nesting of any depth is followed.
+  const scenesOfLocal = new Map<string, Set<string>>([...local.keys()].map((name) => [name, new Set<string>()]));
+  for (let changed = true, rounds = 0; changed && rounds < 12; rounds++) {
+    changed = false;
+    for (const [name, list] of localUses) {
+      const mine = scenesOfLocal.get(name)!;
+      for (const use of list) for (const id of use.scenes.size ? use.scenes : (scenesOfLocal.get(use.owner) ?? [])) if (!mine.has(id)) { mine.add(id); changed = true; }
+    }
+  }
+  const used = new Map<string, { uses: number; scenes: Set<string> }>();
+  for (const [tag, list] of uses) {
+    const scenes = new Set<string>();
+    for (const use of list) for (const id of use.scenes.size ? use.scenes : (scenesOfLocal.get(use.owner) ?? [])) scenes.add(id);
+    used.set(tag, { uses: list.length, scenes });
+  }
+
+  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)));
+}