reelkit-cli 0.4.0 → 0.6.0

package/src/commands/assets.ts

@@ -9,10 +9,13 @@ import { GreenTooDullError, keyGreen } from "../project/chromakey";
 import { buildManifest, voiceoverStale, type ClipRecord, type Voiceover } from "../project/manifest";
 import { loadPlan } from "./plan";
 import { FILE_NAME } from "../render/validate";
+import { levelOf } from "../project/loudness";
+import { measureMusic, type MusicRecord } from "../project/music";
 import { probeFile } from "../project/probe";
 import { FILES, openProject, type Project } from "../project/project";
 
-export type LibraryEntry = { path: string; kind: string; title: string; meta: Record<string, unknown> };
+// gainDb is the levelling of a sound (sfx or music), in dB, measured when it was pulled: see src/project/loudness.ts.
+export type LibraryEntry = { path: string; kind: string; title: string; meta: Record<string, unknown>; gainDb?: number };
 
 // A failure to lay out the timeline after a paid call must not hide that the call succeeded and was saved.
 function tryManifest(project: Project, plan: ScenePlan): { manifest?: AssetManifest; note?: string } {
@@ -105,7 +108,7 @@ export async function assetsUpload(
   if (opts.green && opts.cutout) return { ok: false, summary: "Use --green or --cutout, not both: --green keys a green background on this machine for free, --cutout removes any background on the server." };
   if (opts.resume && !opts.cutout) return { ok: false, summary: "--resume goes with --cutout: it keeps waiting for a cutout that was already started." };
   if (opts.resume) return resumeUploadCutout(ctx, project, file, opts.resume, deps);
-  if (opts.share && opts.kind === "component") return { ok: false, summary: "Components cannot be shared from the CLI yet. Share images, overlays, sound effects, music or clips." };
+  if (opts.share && opts.kind === "component") return { ok: false, summary: "Components are shared with `reelkit components share`, not with assets upload. Share images, overlays, sound effects, music or clips here." };
   const source = resolve(ctx.cwd, file);
   let probe: Awaited<ReturnType<typeof probeFile>>;
   try {
@@ -200,10 +203,23 @@ async function resumeUploadCutout(ctx: Ctx, project: Project, file: string, id:
   return { ...finished, summary: `Resumed ${record.filename} (${record.id}). ${finished.summary}` };
 }
 
+export type SearchRecord = { q: string; kind: string | null; at: string; top: { id: string; match: number }[] };
+const MAX_SEARCHES = 50;
+
+// What was searched for in this project, so `reelkit check` can say whether the library was looked at. A search outside a project is not recorded.
+function recordSearch(ctx: Ctx, q: string, kind: string | null, items: { id: string; match: number }[]) {
+  try {
+    const project = openProject(ctx.cwd);
+    const all = project.readJsonOr<SearchRecord[]>(FILES.searches, []);
+    project.writeJson(FILES.searches, [...all, { q, kind, at: new Date().toISOString(), top: items.slice(0, 3).map((i) => ({ id: i.id, match: i.match })) }].slice(-MAX_SEARCHES));
+  } catch { /* not a project, or the file is unreadable: the search itself still works */ }
+}
+
 export async function assetsSearch(ctx: Ctx, query: string, opts: { kind?: string; limit?: string }): Promise<Result> {
   const kind = opts.kind === undefined ? undefined : LibraryKindSchema.safeParse(opts.kind);
   if (kind && !kind.success) return { ok: false, summary: `Unknown kind "${opts.kind}". Use one of: ${LibraryKindSchema.options.join(", ")}.` };
   const { items } = await client(ctx)("librarySearch", { q: query, ...(kind?.success ? { kind: kind.data } : {}), ...(opts.limit ? { limit: Number(opts.limit) } : {}) });
+  recordSearch(ctx, query, kind?.success ? kind.data : null, items);
   return {
     ok: true, data: { items },
     summary: items.length
@@ -228,7 +244,7 @@ function setSceneClip(project: Project, sceneId: string, record: ClipRecord) {
   project.writeJson(FILES.clips, { ...project.readJsonOr<Record<string, ClipRecord>>(FILES.clips, {}), [sceneId]: record });
 }
 
-export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; force?: boolean }, deps: ClipDeps = {}): Promise<Result> {
+export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; force?: boolean; music?: boolean }, deps: ClipDeps = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) return { ok: false, summary: `"${id}" is not a library id. Copy the id from \`reelkit assets search\`.` };
   if (opts.scene) {
@@ -240,7 +256,9 @@ export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; f
       return { ok: false, summary: `Scene ${opts.scene} is not an illustration scene in plan.json. ${illustrations.length ? `The illustration scenes are: ${illustrations.join(", ")}.` : "The plan has no illustration scenes."}${clipScenes.length ? ` The clip scenes are: ${clipScenes.join(", ")}.` : ""}` };
     }
   }
+  if (opts.music && opts.scene) return { ok: false, summary: "--music makes the item the video's track, not a scene's picture. Use --music or --scene, not both." };
   const pulled = await client(ctx)("libraryPull", { id });
+  if (opts.music && pulled.item.kind !== "music") return { ok: false, summary: `${id} is ${pulled.item.kind}, not music, so it cannot be the video's track. Search with --kind music.` };
   if (unsafeName(pulled.filename, pulled.item.kind)) return { ok: false, summary: `The library returned an unsafe file name for ${id}, so nothing was written. Report this item.` };
   if (opts.scene) {
     const treatment = loadPlan(project).scenes.find((x) => x.id === opts.scene)?.treatment;
@@ -259,7 +277,10 @@ export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; f
   }
   const path = `assets/lib/${id}/${pulled.filename}`;
   await download(pulled.url, project.path(path));
-  recordPull(project, id, { path, kind: pulled.item.kind, title: pulled.item.title, meta: pulled.item.meta });
+  // A sound is levelled when it is pulled, so that the same volume number sounds equally loud for every file. A file that cannot be
+  // measured is used as it is.
+  const level = pulled.item.kind === "sfx" || pulled.item.kind === "music" ? await levelOf(project.path(path)) : undefined;
+  recordPull(project, id, { path, kind: pulled.item.kind, title: pulled.item.title, meta: pulled.item.meta, ...(level ? { gainDb: level.gainDb } : {}) });
   // A clip filmed on green also comes keyed, so it can be laid over a background.
   const green = pulled.item.kind === "clip" && pulled.item.meta.greenScreen === true;
   const keyedPath = green ? keyedPathOf(path) : undefined;
@@ -273,16 +294,36 @@ export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; f
     } else setSceneImage(project, opts.scene, path);
     if (project.exists(FILES.plan)) note = tryManifest(project, loadPlan(project)).note;
   }
+  if (pulled.item.kind === "music" && opts.music) return pullMusic(project, id, pulled.item.title, path, level?.gainDb ?? 0);
+  const musicHint = pulled.item.kind === "music" ? ` To make it the video's track, with scene changes on its beat, run \`reelkit assets pull ${id} --music\`.` : "";
   const refs = keyedPath ? ` The original is urls["${path}"]; the keyed copy with a transparent background is urls["${keyedPath}"].` : ` Reference it in the composition as urls["${path}"].`;
   return {
     ok: true, data: { path, kind: pulled.item.kind, ...(keyedPath ? { keyedPath } : {}) },
     summary: [
-      opts.scene ? `Pulled ${id} as the ${sceneIsClip ? "clip" : "image"} for scene ${opts.scene}.${keyedPath ? refs : ""}` : `Pulled ${id} to ${path}.${refs}`,
+      opts.scene ? `Pulled ${id} as the ${sceneIsClip ? "clip" : "image"} for scene ${opts.scene}.${keyedPath ? refs : ""}` : `Pulled ${id} to ${path}.${refs}${musicHint}`,
       ...(note ? [note] : []),
     ].join("\n"),
   };
 }
 
+// Makes a pulled track the video's one music track: measured here, saved in assets/music.json, and the timeline is laid out again around it.
+async function pullMusic(project: Project, id: string, title: string, path: string, gainDb: number): Promise<Result> {
+  let measured: Awaited<ReturnType<typeof measureMusic>>;
+  try { measured = await measureMusic(project.path(path)); }
+  catch (e) { return { ok: false, summary: `${id} was downloaded to ${path} but could not be read as audio (${e instanceof Error ? e.message : String(e)}). Pull a different track.` }; }
+  const previous = project.readJsonOr<MusicRecord | undefined>(FILES.music, undefined);
+  const record: MusicRecord = { key: path, id, title, ...measured, gainDb };
+  project.writeJson(FILES.music, record);
+  const note = project.exists(FILES.plan) ? tryManifest(project, loadPlan(project)).note : undefined;
+  const beat = record.bpm
+    ? `about ${Math.round(record.bpm)} BPM; scene changes will land on its beat.`
+    : "no clear tempo was found, so scene changes stay where the narration puts them.";
+  return {
+    ok: true, data: { path, kind: "music", music: record },
+    summary: [`Pulled ${id} as the video's music track${previous && previous.id !== id ? ` (it replaces ${previous.id})` : ""}: ${record.durationSec.toFixed(1)}s, ${beat} Place it once with <Music src={urls["${path}"]} />.`, ...(note ? [note] : [])].join("\n"),
+  };
+}
+
 export async function assetsVoices(ctx: Ctx): Promise<Result> {
   const { voices } = await client(ctx)("voices", {});
   return {

package/src/commands/build.ts

@@ -3,12 +3,18 @@ import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import type { Ctx, Result } from "../context";
-import type { AssetManifest } from "../pipeline/schema";
+import type { AssetManifest, ScenePlan } from "../pipeline/schema";
+import { compareFrames, SAMPLE_WIDTH, summariseContinuity, type Boundary } from "../render/continuity";
 import { buildManifest, missingAssets } from "../project/manifest";
-import { openProject, type Project } from "../project/project";
+import { beatReport } from "../project/music";
+import { FILES, openProject, type Project } from "../project/project";
+import { structureNotes } from "../pipeline/review";
+import type { SearchRecord } from "./assets";
+import { libraryUse, shareAfterRender } from "./components";
 import { mediaUrls, serveDir } from "../project/serve";
 import { bundleProject, disposeBundle, ensureRenderBrowser, renderStills, renderVideo, writeEntry, type EnsureBrowser } from "../render/render";
-import { FILE_NAME, MAIN_FILE, staticCheck, typecheck } from "../render/validate";
+import { MASTER_LUFS, MASTER_TRUE_PEAK_DB, masterLoudness, type Master, type Mastered } from "../render/master";
+import { FILE_NAME, MAIN_FILE, jsxUses, staticCheck, typecheck } from "../render/validate";
 import { loadPlan } from "./plan";
 
 const exec = promisify(execFile);
@@ -36,11 +42,34 @@ function inspect(project: Project): { errors: string[]; manifest?: AssetManifest
   return manifest ? { errors: [], manifest } : { errors: ["The manifest could not be built. Run `reelkit assets voiceover --all`."] };
 }
 
+// Advice about a composition that passes: never an error.
+function compositionNotes(project: Project, plan: ScenePlan): string[] {
+  const notes: string[] = [];
+  const names = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f));
+  const sources = names.map((n) => [n, readFileSync(project.path(join("src", n)), "utf8")] as const);
+  const rendersCaptions = sources.some(([n, src]) => jsxUses(src, n, "Captions").length > 0);
+  if (plan.captions === "none" && rendersCaptions) notes.push('The plan says captions: "none" but the composition renders <Captions>. Remove them, or change the plan if the user wants captions.');
+  if ((plan.captions === "word" || plan.captions === "phrase") && !rendersCaptions) notes.push(`The plan asks for captions (${plan.captions}) but the composition renders no <Captions>. Add <Captions words={s.words} group={manifest.captions} /> in each scene, or set captions to "none" in the plan if the user does not want them.`);
+  notes.push(...structureNotes(plan, { footage: project.footage() }));
+  const { pulled, written } = libraryUse(project);
+  if (!pulled.length && plan.scenes.length >= 4) {
+    const searched = project.readJsonOr<SearchRecord[]>(FILES.searches, []).filter((s) => s.kind === "component").length;
+    notes.push(`No library component is used (${searched === 0 ? "no component search was made" : `${searched} component search${searched === 1 ? "" : "es"} made`} in this project). Search before writing: \`reelkit assets search "<what the scene shows>" --kind component\`.`);
+  }
+  return notes;
+}
+
 const failed = (errors: string[]): Result => ({ ok: false, data: { errors }, summary: `${errors.length} problem(s):\n- ${errors.join("\n- ")}` });
 
 export async function check(ctx: Ctx): Promise<Result> {
-  const { errors } = inspect(openProject(ctx.cwd));
-  return errors.length ? failed(errors) : { ok: true, data: { errors: [] }, summary: "The composition passes. Run `reelkit preview` to see it." };
+  const project = openProject(ctx.cwd);
+  const { errors } = inspect(project);
+  if (errors.length) return failed(errors);
+  const shouldImprove = compositionNotes(project, loadPlan(project));
+  return {
+    ok: true, data: { errors: [], shouldImprove, library: libraryUse(project) },
+    summary: ["The composition passes. Run `reelkit preview` to see it.", ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : [])].join("\n"),
+  };
 }
 
 // Bundles the composition and serves the project's media for as long as fn runs.
@@ -72,7 +101,7 @@ export async function ensureBrowserWithNotice(ctx: Ctx, ensure: EnsureBrowser =
 
 const ffmpegToJpeg = (png: string, jpg: string) => exec("ffmpeg", ["-y", "-loglevel", "error", "-i", png, "-vf", "scale=540:-2", "-q:v", "5", jpg]).then(() => undefined);
 
-type PreviewPoint = { sceneId: string; point: "early" | "late" | "middle"; frame: number; name: string };
+type PreviewPoint = { sceneId: string; point: "early" | "late" | "middle" | "end" | "start"; frame: number; name: string };
 
 // Two frames per scene, at 30% and 90% of its length, so what enters late in a scene is seen as well as what opens it.
 // A scene under 4 frames has no room for two distinct frames and gets its middle one. The scene's number leads each name
@@ -86,6 +115,30 @@ export function previewPoints(scenes: { id: string; startFrame: number; duration
   });
 }
 
+type BoundaryPoint = { from: string; to: string; end: PreviewPoint; start: PreviewPoint };
+
+// SceneFrame fades each scene in and out over up to 8 frames, so the very last and very first frames of two scenes are nearly empty.
+// The frames that show what a scene really holds are the last one at full strength and the first one at full strength: those are the two
+// either side of every change. The files are named by the change, b01-end-<scene> then b01-start-<scene>, so that they sort in order.
+export function boundaryPoints(scenes: { id: string; startFrame: number; durationFrames: number }[]): BoundaryPoint[] {
+  const edge = (d: number) => Math.max(1, Math.min(8, Math.floor(d / 2)));
+  return scenes.slice(0, -1).map((a, i) => {
+    const b = scenes[i + 1]!;
+    const n = `b${String(i + 1).padStart(2, "0")}`;
+    return {
+      from: a.id, to: b.id,
+      end: { sceneId: a.id, point: "end", frame: a.startFrame + Math.max(0, a.durationFrames - edge(a.durationFrames)), name: `${n}-end-${a.id}` },
+      start: { sceneId: b.id, point: "start", frame: b.startFrame + Math.min(b.durationFrames - 1, edge(b.durationFrames)), name: `${n}-start-${b.id}` },
+    };
+  });
+}
+
+// A small grey copy of a frame as plain pixels, for the continuity measurement.
+async function decodeGray(png: string, width: number, height: number): Promise<Uint8Array> {
+  const { stdout } = await exec("ffmpeg", ["-v", "error", "-i", png, "-vf", `scale=${width}:${height}:flags=area,format=gray`, "-f", "rawvideo", "-pix_fmt", "gray", "-"], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024 });
+  return new Uint8Array(stdout);
+}
+
 export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: string) => Promise<void>; ensureBrowser?: EnsureBrowser } = {}): Promise<Result> {
   const toJpeg = deps.toJpeg ?? ffmpegToJpeg;
   const project = openProject(ctx.cwd);
@@ -94,11 +147,13 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
   const dir = project.path("out/preview");
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
-  const points = previewPoints(manifest.scenes);
+  const sceneFrames = previewPoints(manifest.scenes);
+  const boundaries = boundaryPoints(manifest.scenes);
+  const points = [...sceneFrames, ...boundaries.flatMap((b) => [b.end, b.start])];
   try {
     try {
       await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
-      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, points.map((p) => p.frame), dir));
+      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, [...new Set(points.map((p) => p.frame))], dir));
     } catch (e) {
       return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
     }
@@ -113,14 +168,34 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
     } catch {
       return failed(["Could not write the preview frames: ffmpeg failed. Check that ffmpeg is installed (macOS: `brew install ffmpeg`) and run `reelkit preview` again."]);
     }
-    return { ok: true, data: { frames }, summary: `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}` };
+    // Whether anything survives each scene change is advice. If it cannot be measured, the preview is still the preview.
+    let continuity: { score: number | null; boundaries: Boundary[] } | undefined;
+    let continuityLines: string[] = [];
+    try {
+      const h = Math.round((SAMPLE_WIDTH * manifest.height) / manifest.width);
+      const measured: Boundary[] = [];
+      for (const b of boundaries) {
+        const [a, c] = await Promise.all([decodeGray(join(dir, `still-${b.end.frame}.png`), SAMPLE_WIDTH, h), decodeGray(join(dir, `still-${b.start.frame}.png`), SAMPLE_WIDTH, h)]);
+        const r = compareFrames(a, c, SAMPLE_WIDTH, h);
+        measured.push({ from: b.from, to: b.to, survived: Math.round(r.survived * 100) / 100, kind: r.kind });
+      }
+      if (measured.length) {
+        const summary = summariseContinuity(measured);
+        continuity = { score: summary.score === null ? null : Math.round(summary.score * 100) / 100, boundaries: measured };
+        continuityLines = summary.lines;
+      }
+    } catch { /* no continuity report */ }
+    const sceneLines = `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.filter((f) => f.point !== "end" && f.point !== "start").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}`;
+    const changeLines = boundaries.length ? `\nThe last and first frames either side of each scene change are saved too (b01-end-<scene>, b01-start-<scene>, ...), so that you can see what carries across:\n${frames.filter((f) => f.point === "end" || f.point === "start").map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}` : "";
+    const beat = beatReport(manifest);
+    return { ok: true, data: { frames, ...(continuity ? { continuity } : {}), ...(beat ? { beat: { bpm: beat.bpm, boundariesOnBeat: beat.boundariesOnBeat, boundaries: beat.boundaries } } : {}) }, summary: `${sceneLines}${changeLines}${continuityLines.length ? `\nContinuity: ${continuityLines.join("\n")}` : ""}${beat ? `\nBeat: ${beat.line}.` : ""}` };
   } finally {
     // The full-size stills are only inputs; none stays behind however this ends.
     for (const f of readdirSync(dir)) if (/^still-\d+\.png$/.test(f)) rmSync(join(dir, f), { force: true });
   }
 }
 
-export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser } = {}): Promise<Result> {
+export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser; master?: Master; noShare?: boolean } = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
   if (!manifest) return failed(errors);
@@ -132,5 +207,18 @@ export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser } =
     return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
   }
   const seconds = manifest.totalFrames / manifest.fps;
-  return { ok: true, data: { path, seconds }, summary: `Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height})` };
+  // One last pass brings the whole programme to the loudness platforms play at. If it fails the render is still the render.
+  let loudness: Mastered | undefined;
+  let masterNote = "";
+  try {
+    loudness = await (deps.master ?? masterLoudness)(project.path(path));
+    masterNote = ` Mastered to ${loudness.outputLufs} LUFS (it was ${loudness.inputLufs}), peaks under ${MASTER_TRUE_PEAK_DB} dBTP.`;
+  } catch (e) {
+    masterNote = ` It was not mastered to ${MASTER_LUFS} LUFS (${e instanceof Error ? e.message : String(e)}); the video is kept as rendered.`;
+  }
+  const share = await shareAfterRender(ctx, project, { noShare: deps.noShare });
+  return {
+    ok: true, data: { path, seconds, ...(loudness ? { loudness } : {}), ...(share.data ? { shared: share.data.shared.map((s) => s.name) } : {}) },
+    summary: [`Video: ${project.path(path)} (${seconds.toFixed(1)}s, ${manifest.width}x${manifest.height}).${masterNote}`, ...share.lines].join("\n"),
+  };
 }

package/src/commands/components.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import ts from "typescript";
+import { uploadTo } from "../api/client";
+import { client, type Ctx, type Result } from "../context";
+import { MAX_COMPONENT_BYTES, MAX_COMPONENT_EXAMPLE, MIN_COMPONENT_DESCRIPTION } from "../contract";
+import { configDir, loadCredentials } from "../credentials";
+import { FILES, openProject, type Project } from "../project/project";
+import { componentName, FILE_NAME, jsxUses, MAIN_FILE, staticCheck } from "../render/validate";
+
+export type SharedRecord = { name: string; libraryId: string; hash: string };
+type Prepared = { name: string; file: string; source: string; hash: string; description: string; example: string; tags: string[] };
+export type ShareOutcome = { shared: { name: string; libraryId: string; file: string; description: string; example: string }[]; skipped: { name: string; reason: string }[]; failed?: string };
+
+const STOP_WORDS = new Set(["that", "this", "with", "from", "when", "have", "your", "into", "than", "then", "each", "show", "shows", "used", "uses", "use", "very", "which", "there", "their", "about", "over", "under", "while", "where", "also", "onto"]);
+
+// The components in src/ that came from the library, and the ones written in this project.
+export function libraryUse(project: Project): { pulled: string[]; written: string[] } {
+  const entries = Object.values(project.readJsonOr<Record<string, { path: string; kind: string }>>(FILES.library, {}));
+  const names = readdirSync(project.path("src")).filter((f) => FILE_NAME.test(f) && f !== MAIN_FILE);
+  const pulled = names.filter((n) => entries.some((e) => e.kind === "component" && e.path === `src/${n}`));
+  return { pulled: pulled.map(componentName), written: names.filter((n) => !pulled.includes(n)).map(componentName) };
+}
+
+const sf = (source: string, file: string) => ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+// The comment block directly above `export const <name>`, as plain words.
+export function leadingComment(source: string, name: string): string | undefined {
+  const file = sf(source, `${name}.tsx`);
+  const stmt = file.statements.find((s) => ts.isVariableStatement(s) && s.declarationList.declarations.some((d) => ts.isIdentifier(d.name) && d.name.text === name));
+  if (!stmt) return undefined;
+  const ranges = ts.getLeadingCommentRanges(source, stmt.getFullStart()) ?? [];
+  const block: ts.CommentRange[] = [];
+  for (let i = ranges.length - 1; i >= 0; i--) {
+    const r = ranges[i]!;
+    // Only a comment with no blank line between it and what follows belongs to the declaration.
+    const gap = source.slice(r.end, i === ranges.length - 1 ? stmt.getStart() : ranges[i + 1]!.pos);
+    if ((gap.match(/\n/g) ?? []).length > 1) break;
+    block.unshift(r);
+  }
+  const text = block.map((r) => source.slice(r.pos, r.end).replace(/^\/\*+|\*+\/$/g, "").split("\n").map((l) => l.replace(/^\s*(\/\/+|\*+)\s?/, "").trim()).join(" ")).join(" ").replace(/\s+/g, " ").trim();
+  return text || undefined;
+}
+
+// Every piece of text a file writes out: strings, template text and JSX text. Names and comments are not text.
+export function literalTexts(source: string, file: string): string[] {
+  const out: string[] = [];
+  const visit = (n: ts.Node) => {
+    if (ts.isStringLiteralLike(n)) out.push(n.text);
+    else if (ts.isTemplateHead(n) || ts.isTemplateMiddle(n) || ts.isTemplateTail(n)) out.push(n.text);
+    else if (ts.isJsxText(n) && n.text.trim()) out.push(n.text.trim());
+    ts.forEachChild(n, visit);
+  };
+  visit(sf(source, file));
+  return out;
+}
+
+const cutShort = (t: string) => (t.length > 40 ? `${t.slice(0, 40)}…` : t);
+
+const sharesRun = (a: string, b: string, n: number): boolean => {
+  for (let i = 0; i + n <= b.length; i++) if (a.includes(b.slice(i, i + n))) return true;
+  return false;
+};
+
+// A cheap guard against sharing something that belongs to this user: their own files, their video's title, their words.
+export function privateReason(source: string, file: string, plan: { title?: string; scenes?: { narration?: string; onScreenText?: string[] }[] }): string | undefined {
+  const texts = literalTexts(source, file);
+  if (texts.some((t) => t.startsWith("assets/user/"))) return "it uses one of your own files (assets/user/...). A shared component takes its pictures and text from props.";
+  const title = plan.title?.trim().toLowerCase();
+  if (title && title.length >= 4 && texts.some((t) => t.toLowerCase().includes(title))) return "it contains this video's title. A shared component takes its text from props.";
+  const norm = (s: string) => s.replace(/\s+/g, " ").trim();
+  for (const t of texts.map(norm).filter((t) => t.length > 60)) {
+    if ((plan.scenes ?? []).some((s) => sharesRun(norm(s.narration ?? ""), t, 61) || sharesRun(t, norm(s.narration ?? ""), 61))) return "it contains a long piece of this video's narration. A shared component takes its text from props.";
+  }
+  // Anything written into the component leaves the machine with it, so a component that carries this video's own words is not
+  // shared at all, however short they are: a customer's name or a headline is eight characters as easily as eighty. Two rules, both
+  // erring toward not sharing: text that also appears in the plan, and any whole sentence written into the code.
+  const low = (v: string) => norm(v).toLowerCase();
+  const planTexts = (plan.scenes ?? []).flatMap((sc) => [sc.narration ?? "", ...(sc.onScreenText ?? [])]).map(low).filter(Boolean);
+  for (const t of texts.map(low)) {
+    if (t.length >= 8 && planTexts.some((p) => p.includes(t))) return `it contains words from this video ("${cutShort(t)}"). A shared component takes its text from props.`;
+    // A font stack, a transform or a gradient is several words too: text with code punctuation, or a comma list of short items, is not a sentence.
+    const codeLike = /[():;%#{}=<>]/.test(t) || (t.split(",").length >= 3 && t.split(",").every((part) => part.trim().split(" ").length <= 3));
+    if (!codeLike && t.split(" ").filter((w) => /\p{L}{2,}/u.test(w)).length >= 5) return `it has a sentence written into it ("${cutShort(t)}"). A shared component takes its text from props.`;
+  }
+  return undefined;
+}
+
+// Lowercase words, 3 to 6: the words of the name first, then the longer words of the description.
+export function deriveTags(name: string, description: string): string[] {
+  const fromName = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/\s+/);
+  const fromText = description.toLowerCase().match(/[a-z]{4,}/g) ?? [];
+  const tags = [...new Set([...fromName, ...fromText.filter((w) => !STOP_WORDS.has(w))])].filter((t) => t.length <= 40);
+  for (const filler of ["component", "motion", "video"]) if (tags.length < 3 && !tags.includes(filler)) tags.push(filler);
+  return tags.slice(0, 6);
+}
+
+function prepare(project: Project, name: string, opts: { describe?: string; example?: string; tags?: string }, plan: Parameters<typeof privateReason>[2], siblings: string[]): Prepared | { name: string; reason: string } {
+  const file = `${name}.tsx`;
+  const skip = (reason: string) => ({ name, reason });
+  if (!FILE_NAME.test(file) || file === MAIN_FILE || !project.exists(`src/${file}`)) return skip(`there is no component file src/${file}.`);
+  const source = readFileSync(project.path(`src/${file}`), "utf8");
+  if (Buffer.byteLength(source) > MAX_COMPONENT_BYTES) return skip(`it is larger than ${MAX_COMPONENT_BYTES / 1024} KB.`);
+  const problems = staticCheck(source, file, siblings);
+  if (problems.length) return skip(`it does not pass the check (${problems[0]}). Fix it with \`reelkit check\` first.`);
+  const reason = privateReason(source, file, plan);
+  if (reason) return skip(reason);
+  const description = (opts.describe ?? leadingComment(source, name) ?? "").trim();
+  if (description.length < MIN_COMPONENT_DESCRIPTION) return skip(`it has no description. Put a sentence or two above \`export const ${name}\` saying what it shows and when to use it${opts.describe === undefined ? ", or pass --describe" : ""}.`);
+  let example = opts.example?.trim();
+  if (opts.example !== undefined && !example?.startsWith(`<${name}`)) return skip(`--example must start with <${name}.`);
+  if (!example) {
+    const main = project.exists(`src/${MAIN_FILE}`) ? readFileSync(project.path(`src/${MAIN_FILE}`), "utf8") : "";
+    const use = jsxUses(main, MAIN_FILE, name)[0];
+    if (!use) return skip(`<${name}> is not used in src/${MAIN_FILE}, so there is no example to take. Pass --example '<${name} ... />'.`);
+    if (!use.literal) return skip(`its use in src/${MAIN_FILE} has props that are not plain values (variables or data from the video). Pass --example '<${name} ... />' with plain values.`);
+    example = use.example;
+  }
+  if (example.length > MAX_COMPONENT_EXAMPLE) return skip(`its example is longer than ${MAX_COMPONENT_EXAMPLE} characters. Pass a shorter --example.`);
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean) : deriveTags(name, description);
+  return { name, file, source, hash: createHash("sha256").update(source).digest("hex"), description, example, tags };
+}
+
+// Which components a share would send, and why any other is left out. Nothing is sent here.
+export function prepareShare(project: Project, names: string[] | undefined, opts: { describe?: string; example?: string; tags?: string } = {}): { ready: Prepared[]; skipped: { name: string; reason: string }[] } {
+  const plan = project.readJsonOr<Parameters<typeof privateReason>[2]>(FILES.plan, {});
+  const siblings = readdirSync(project.path("src")).filter((f) => f.endsWith(".tsx"));
+  const { pulled, written } = libraryUse(project);
+  const done = project.readJsonOr<SharedRecord[]>(FILES.shared, []);
+  const ready: Prepared[] = [], skipped: { name: string; reason: string }[] = [];
+  for (const name of names?.length ? names : written) {
+    if (pulled.includes(name)) { skipped.push({ name, reason: "it was pulled from the library, so it is already there." }); continue; }
+    const p = prepare(project, name, names?.length === 1 ? opts : {}, plan, siblings);
+    if ("reason" in p) { skipped.push(p); continue; }
+    // The same source is not sent twice.
+    if (done.some((d) => d.name === name && d.hash === p.hash)) continue;
+    ready.push(p);
+  }
+  return { ready, skipped };
+}
+
+async function send(ctx: Ctx, project: Project, ready: Prepared[]): Promise<ShareOutcome["shared"]> {
+  const api = client(ctx);
+  const shared: ShareOutcome["shared"] = [];
+  for (const c of ready) {
+    // Only the component's own name, source, description, example and tags leave this machine: no project name, path or plan text.
+    const bytes = new TextEncoder().encode(c.source);
+    const up = await api("libraryUpload", { kind: "component", title: c.name, description: c.description, tags: c.tags, meta: { example: c.example }, filename: c.file, contentType: "text/plain", bytes: bytes.length, shareable: true });
+    await uploadTo(up.uploadUrl, new Uint8Array(bytes), "text/plain");
+    const libraryId = (await api("libraryCommit", { id: up.id })).item.id;
+    project.writeJson(FILES.shared, [...project.readJsonOr<SharedRecord[]>(FILES.shared, []).filter((d) => d.name !== c.name), { name: c.name, libraryId, hash: c.hash }]);
+    shared.push({ name: c.name, libraryId, file: c.file, description: c.description, example: c.example });
+  }
+  return shared;
+}
+
+export const STOP_SHARING = "To stop this, run `reelkit render --no-share`, set REELKIT_NO_SHARE=1, or start new projects with `reelkit init <name> --private`.";
+
+const sentLines = (shared: ShareOutcome["shared"]) => shared.map((s) => `  ${s.file}: ${s.description} Example: ${s.example}`);
+const skippedLines = (skipped: ShareOutcome["skipped"]) => skipped.map((s) => `  Not shared: ${s.name}: ${s.reason}`);
+
+// `reelkit components share [name...]`: an explicit request, so it shares at once.
+export async function componentsShare(ctx: Ctx, names: string[], opts: { describe?: string; example?: string; tags?: string }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  if (names.length !== 1 && (opts.describe !== undefined || opts.example !== undefined || opts.tags !== undefined)) return { ok: false, summary: "--describe, --example and --tags go with exactly one component name: reelkit components share StatRing --describe \"...\"." };
+  if (!loadCredentials(ctx.env)) return { ok: false, summary: "You are not logged in. Run `reelkit auth login`, then share again." };
+  const { ready, skipped } = prepareShare(project, names, opts);
+  const shared = await send(ctx, project, ready);
+  const data: ShareOutcome = { shared, skipped };
+  if (!shared.length && !skipped.length) return { ok: true, data, summary: "Nothing to share: every component written in this project has already been shared, or there are none." };
+  return {
+    ok: shared.length > 0 || skipped.length === 0, data,
+    summary: [
+      shared.length ? `Shared ${shared.length} component${shared.length === 1 ? "" : "s"} with the Reelkit library for review: ${shared.map((s) => s.name).join(", ")}. Nothing else from this project was sent.` : "No component was shared.",
+      ...sentLines(shared), ...skippedLines(skipped),
+    ].join("\n"),
+  };
+}
+
+// The notice a person sees once per machine before components start to be shared by a render.
+export const SHARING_NOTICE = `New components you write are shared with the Reelkit library for review after a render, starting with the next one: each component's source, a description and an example, and nothing else (no project name, file paths or script). ${STOP_SHARING}`;
+
+const noticesPath = (env: Ctx["env"]) => join(configDir(env), "notices.json");
+function sharingNoticeShown(env: Ctx["env"]): boolean {
+  try { return typeof (JSON.parse(readFileSync(noticesPath(env), "utf8")) as { componentSharing?: unknown }).componentSharing === "string"; } catch { return false; }
+}
+function recordSharingNotice(env: Ctx["env"]): boolean {
+  try {
+    let all: Record<string, unknown> = {};
+    try { all = JSON.parse(readFileSync(noticesPath(env), "utf8")) as Record<string, unknown>; } catch { /* a new file */ }
+    mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+    writeFileSync(noticesPath(env), JSON.stringify({ ...all, componentSharing: new Date().toISOString() }, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+// After a render: share the new components unless the person has opted out. It never fails the render; it returns the lines to add to its summary.
+export async function shareAfterRender(ctx: Ctx, project: Project, opts: { noShare?: boolean }): Promise<{ lines: string[]; data?: ShareOutcome }> {
+  const off = ctx.env.REELKIT_NO_SHARE;
+  if (opts.noShare || (off && off !== "0" && off.toLowerCase() !== "false") || project.config().shareComponents === false) return { lines: ["No components were shared with the Reelkit library (sharing is turned off)."] };
+  if (!existsSync(project.path("src"))) return { lines: [] };
+  try {
+    const { ready, skipped } = prepareShare(project, undefined);
+    const notShared = skippedLines(skipped);
+    if (!ready.length) return { lines: [...notShared, ...(notShared.length ? [] : ["No new components to share with the Reelkit library."])] };
+    if (!loadCredentials(ctx.env)) return { lines: ["Components were not shared with the Reelkit library: you are not logged in.", ...notShared] };
+    if (!sharingNoticeShown(ctx.env)) {
+      // The first time on this machine: say what will happen, and share from the next render on.
+      return { lines: recordSharingNotice(ctx.env) ? [SHARING_NOTICE, ...notShared] : [`Components were not shared: ${"the notice could not be saved in " + configDir(ctx.env)}.`] };
+    }
+    const shared = await send(ctx, project, ready);
+    return {
+      data: { shared, skipped },
+      lines: [`Shared ${shared.length} new component${shared.length === 1 ? "" : "s"} with the Reelkit library for review: ${shared.map((s) => s.name).join(", ")}. Nothing else from this project was sent. ${STOP_SHARING}`, ...sentLines(shared), ...notShared],
+    };
+  } catch (e) {
+    return { lines: [`Components were not shared with the Reelkit library (${e instanceof Error ? e.message : String(e)}). The video is not affected.`] };
+  }
+}

package/src/commands/init.ts

@@ -10,7 +10,7 @@ import { FILES, Project } from "../project/project";
 const exec = promisify(execFile);
 const DIRS = ["assets", "refs", "src", "out"];
 
-export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?: string }): Promise<Result> {
+export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?: string; private?: boolean }): Promise<Result> {
   const slug = name === undefined ? undefined : name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   if (slug === "") return { ok: false, summary: "Give the project a name with letters or digits, for example: reelkit init launch-video" };
   const aspect = AspectSchema.safeParse(opts.aspect ?? "9:16");
@@ -22,11 +22,17 @@ export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?:
   if (slug && existsSync(dir) && !statSync(dir).isDirectory()) return { ok: false, summary: `A file named ${slug} is in the way. Choose another project name or remove it.` };
   const project = new Project(dir);
   for (const d of DIRS) mkdirSync(project.path(d), { recursive: true });
-  if (!project.exists(FILES.config)) project.writeJson(FILES.config, { aspect: aspect.data, ...(name !== undefined && { name }) });
+  if (!project.exists(FILES.config)) project.writeJson(FILES.config, { aspect: aspect.data, ...(name !== undefined && { name }), ...(opts.private && { shareComponents: false }) });
+  else if (opts.private) project.writeJson(FILES.config, { ...project.config(), shareComponents: false });
   if (!existsSync(project.path(".gitignore"))) writeFileSync(project.path(".gitignore"), ".reelkit\nout\nrefs\n");
   ensureSkill(ctx);
   return {
     ok: true, data: { dir, config: project.config() },
-    summary: `Project ready in ${dir} (${project.config().aspect}).${slug ? ` Next: cd ${slug}` : ""}`,
+    summary: [
+      `Project ready in ${dir} (${project.config().aspect}).${slug ? ` Next: cd ${slug}` : ""}`,
+      project.config().shareComponents === false
+        ? "Nothing from this project is shared automatically."
+        : "After a render, new components written in this project are sent to the Reelkit library for review (their source, a description and an example; nothing else). To turn this off: `reelkit init <name> --private` for a new project, `reelkit render --no-share`, or REELKIT_NO_SHARE=1.",
+    ].join("\n"),
   };
 }

package/src/commands/plan.ts

@@ -1,6 +1,6 @@
 import { client, type Ctx, type Result } from "../context";
 import { loadCredentials } from "../credentials";
-import { estimateLength, reviewPlan } from "../pipeline/review";
+import { estimateLength, lengthVariation, reviewPlan, sceneSeconds } from "../pipeline/review";
 import { ScenePlanSchema, validatePlan, type ScenePlan } from "../pipeline/schema";
 import { FILES, issueLines, openProject, type Project } from "../project/project";
 
@@ -58,11 +58,13 @@ export async function planCheck(ctx: Ctx): Promise<Result> {
   const shouldImprove = mustFix.length ? [] : [...reviewPlan(parsed.data, { footage }), ...ref.improve];
   const length = estimateLength(parsed.data);
   const estimatedSeconds = Math.round(length.seconds);
+  const perScene = sceneSeconds(parsed.data).map((s) => ({ id: s.id, seconds: Math.round(s.seconds * 10) / 10 }));
+  const variation = Math.round(lengthVariation(sceneSeconds(parsed.data).map((s) => s.seconds)) * 100) / 100;
   const lines = [
     mustFix.length ? `Fix these:\n- ${mustFix.join("\n- ")}` : "The plan is valid.",
     `Estimated length: about ${estimatedSeconds}s (${length.words} words).`,
     ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : []),
     ...(voiceIds ? [] : ["The voice was not checked because you are not logged in. Run `reelkit auth login`."]),
   ];
-  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove, estimatedSeconds, words: length.words }, summary: lines.join("\n") };
+  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove, estimatedSeconds, words: length.words, sceneSeconds: perScene, lengthVariation: variation }, summary: lines.join("\n") };
 }

package/src/commands/ref.ts

@@ -10,7 +10,7 @@ import { loadCredentials } from "../credentials";
 import { analyzeBeats, cutsOnBeat } from "../project/beats";
 import { openProject, type Project } from "../project/project";
 import {
-  audioDuration, decodeMono, detectCuts, extractFrame, extractMp3, loudnessLufs, nearestAspect, paletteOfFrames, paletteOfVideo, probeVideo, REF_ASPECTS, toMp4,
+  audioDuration, coefficientOfVariation, decodeMono, detectCuts, extractFrame, extractMp3, loudnessLufs, nearestAspect, paletteOfFrames, paletteOfVideo, probeVideo, REF_ASPECTS, stillnessOfVideo, toMp4,
 } from "../project/refmeasure";
 
 // A reference is for learning how a video is built, so ten minutes is more than it needs and keeps every step quick.
@@ -29,7 +29,11 @@ export type Breakdown = {
   scenes: { index: number; startSec: number; endSec: number; durationSec: number; frames: string[]; palette: string[] }[];
   // True when the video has more cuts than the 40 scenes listed: the last scene then holds everything after the 39th cut.
   scenesCapped?: boolean;
-  pacing: { cuts: number; averageShotSec: number; shortestShotSec: number; longestShotSec: number; cutsPerSecond: number; firstCutSec?: number; cutsOnBeat?: number };
+  pacing: { cuts: number; averageShotSec: number; shortestShotSec: number; longestShotSec: number; cutsPerSecond: number; firstCutSec?: number; cutsOnBeat?: number;
+    // How uneven the shot lengths are (standard deviation over the mean); left out with fewer than 3 shots. High means a quarter-second hit beside a long hold.
+    shotLengthVariation?: number };
+  // The share of the video's time in which the picture barely changes from frame to frame, and the longest such stretch. Missing from breakdowns saved by older versions.
+  stillness?: { share: number; longestSec: number };
   palette: string[];
   audio: { hasAudio: boolean; loudnessLufs?: number; tempoBpm?: number; beatConfidence: number };
   beats?: number[];
@@ -245,7 +249,10 @@ async function measure(ctx: Ctx, project: Project, ref: RefRecord): Promise<Brea
   const pacing: Breakdown["pacing"] = {
     cuts: cuts.length, averageShotSec: round2(ref.durationSec / shots.length), shortestShotSec: round2(Math.min(...shots)), longestShotSec: round2(Math.max(...shots)),
     cutsPerSecond: round2(cuts.length / ref.durationSec), ...(cuts.length ? { firstCutSec: round2(cuts[0]!) } : {}),
+    ...(shots.length >= 3 ? { shotLengthVariation: round2(coefficientOfVariation(shots)) } : {}),
   };
+  ctx.log("Measuring how much of the time the picture is still.");
+  const still = await stillnessOfVideo(video, ref.width, ref.height);
 
   const audio: Breakdown["audio"] = { hasAudio: ref.hasAudio, beatConfidence: 0 };
   let beats: number[] | undefined;
@@ -264,7 +271,7 @@ async function measure(ctx: Ctx, project: Project, ref: RefRecord): Promise<Brea
       }
     } catch { /* no tempo */ }
   }
-  return { source: ref.source, durationSec: ref.durationSec, width: ref.width, height: ref.height, aspect: ref.aspect, fps: ref.fps, scenes, ...(cuts.length > MAX_SCENES - 1 ? { scenesCapped: true } : {}), pacing, palette, audio, ...(beats ? { beats } : {}) };
+  return { source: ref.source, durationSec: ref.durationSec, width: ref.width, height: ref.height, aspect: ref.aspect, fps: ref.fps, scenes, ...(cuts.length > MAX_SCENES - 1 ? { scenesCapped: true } : {}), pacing, stillness: still, palette, audio, ...(beats ? { beats } : {}) };
 }
 
 // A short text a person or an agent can read at once.
@@ -274,6 +281,7 @@ function digest(id: string, b: Breakdown, notes: string[]): string {
     b.pacing.cuts
       ? `Shape: ${b.scenes.length}${b.scenesCapped ? "+" : ""} scenes, ${b.pacing.cuts} cuts; average shot ${fmt(b.pacing.averageShotSec)}s (shortest ${fmt(b.pacing.shortestShotSec)}s, longest ${fmt(b.pacing.longestShotSec)}s); first cut at ${fmt(b.pacing.firstCutSec!)}s.`
       : "Shape: one continuous shot, no cuts found.",
+    ...(b.stillness ? [`Still ${Math.round(b.stillness.share * 100)}% of the time; longest hold ${fmt(b.stillness.longestSec)} s.${b.pacing.shotLengthVariation !== undefined ? ` Shot lengths vary by ${b.pacing.shotLengthVariation} (the spread over the average).` : ""}`] : []),
     `Palette: ${b.palette.join(", ")}.`,
     !b.audio.hasAudio ? "Audio: none."
       : `Audio:${b.audio.loudnessLufs !== undefined ? ` ${b.audio.loudnessLufs} LUFS;` : ""} ${b.audio.tempoBpm !== undefined ? `tempo about ${Math.round(b.audio.tempoBpm)} BPM (confidence ${b.audio.beatConfidence})` : "no clear beat"}${b.pacing.cutsOnBeat !== undefined ? `; ${Math.round(b.pacing.cutsOnBeat * b.pacing.cuts)} of ${b.pacing.cuts} cuts land on a beat` : ""}.`,