reelkit-cli 0.12.2 → 0.12.4

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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.4 - 2026-10-09
+
+- A template's timeline shows the music and its beats to the end of the film when the track repeats, not only for the track's own length.
+
+## 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelkit-cli",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "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.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`.
+This skill targets `reelkit-cli` 0.12.4 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

@@ -61,7 +61,7 @@ export function filmOf(project: Project): TemplateFilm | undefined {
         ...(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.id ? { id: cut(music.id, 128) } : {}) } } : {}),
+    ...(music ? { music: musicOf(music, manifest, seconds) } : {}),
     ...(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 } : {}),
@@ -69,6 +69,19 @@ export function filmOf(project: Project): TemplateFilm | undefined {
   };
 }
 
+// The music as it plays in the film. A track shorter than the film is repeated by the composition, and the manifest holds every beat
+// that falls inside the film (the repeats too), so those are the beats shown; the track then runs to the film's end. Without them the
+// track's own beats and length are used.
+function musicOf(music: MusicRecord, manifest: AssetManifest, seconds: number): NonNullable<TemplateFilm["music"]> {
+  const inFilm = (manifest.music?.beatFrames ?? []).map((f) => Math.round((f / manifest.fps) * 1000) / 1000).filter((b) => b >= 0 && b <= seconds);
+  const beats = (inFilm.length ? inFilm : music.beats.filter((b) => b >= 0 && b <= seconds)).slice(0, 4000);
+  const repeats = inFilm.length > 0 && inFilm[inFilm.length - 1]! > music.durationSec;
+  return {
+    title: music.title.slice(0, 200), seconds: repeats ? seconds : Math.min(music.durationSec, seconds), ...(music.bpm ? { bpm: music.bpm } : {}), beats,
+    ...(music.id ? { id: music.id.slice(0, 128) } : {}),
+  };
+}
+
 // The sound effects by name, from what the last render recorded (out/sounds.json): every sound that is not the music or a scene's
 // voice, with the title it has in the library when it was pulled from there, or its file name.
 function cuesOf(project: Project, manifest: AssetManifest, musicKey: string | undefined): Pick<TemplateFilm, "cues"> {

package/src/project/scene-components.ts

@@ -3,10 +3,12 @@ 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.
+// 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.
@@ -32,13 +34,20 @@ export function componentsOf(source: string, opts: { sceneIds: string[]; pulled?
 
   // 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) => {
-      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);
-      }
+      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);
     };
@@ -61,28 +70,96 @@ export function componentsOf(source: string, opts: { sceneIds: string[]; pulled?
   // 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>) => {
+  // 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 : inherited;
+      here = own.size ? own : here;
       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);
-      }
+      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]); }
-    ts.forEachChild(node, (child) => visit(child, here));
+    // 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());
+  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)) }))