reelkit-cli 0.5.0 → 0.6.0

package/README.md

@@ -54,6 +54,7 @@ reelkit render
 | `reelkit install` | Install the skill into your coding agents (`--agent <id>`, `--force`) |
 | `reelkit init [name]` | Set up a video project, in a new folder named after it |
 | `reelkit assets upload <file>` | Add one of your own files (private unless `--share`); `--green` or `--cutout` also makes a transparent copy of a video (`--cutout` sends it to the server) |
+| `reelkit components share [name...]` | Send components written in this project to the library for review (source, description and an example only); a render does this by itself unless you use `reelkit render --no-share`, `reelkit init <name> --private` or `REELKIT_NO_SHARE=1` |
 | `reelkit assets search "<query>"` | Search the shared library by meaning; each result shows a match percentage |
 | `reelkit assets pull <id>` | Download a library item (a component lands in `src/`) |
 | `reelkit assets voices` | List narration voices |
@@ -67,7 +68,7 @@ reelkit render
 
 ## What is shared
 
-Your own files, your plan and your video stay on your machine. Illustrations that the plan marks as generic, and anything you add with `--share`, go to the shared library for review, where other people can reuse them.
+Your own files, your plan and your video stay on your machine. Illustrations that the plan marks as generic, and anything you add with `--share`, go to the shared library for review, where other people can reuse them. New components written for your video are sent for review after a render too (their source, a description and an example, nothing else); turn that off with `reelkit init <name> --private`, `reelkit render --no-share` or `REELKIT_NO_SHARE=1`.
 
 A component you pull from the library is code, and it runs on your machine when you preview or render. The library only serves components published by Reelkit.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelkit-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "CLI and Claude skill for making short-form video with a shared asset library.",
   "license": "MIT",
   "author": "Daniel Livshin",
@@ -31,7 +31,8 @@
     "./client": "./src/api/client.ts",
     "./context": "./src/context.ts",
     "./commands/*": "./src/commands/*.ts",
-    "./testing/conformance": "./src/testing/conformance.ts"
+    "./testing/conformance": "./src/testing/conformance.ts",
+    "./static-check": "./src/render/static-check.ts"
   },
   "files": [
     "bin",

package/skill/SKILL.md

@@ -74,7 +74,7 @@ Write `plan.json`:
 
 Run `reelkit plan check`; it prints the estimated length to tell the user. Fix everything under "Fix these". Act on "Worth improving" unless you have a good reason not to.
 
-**Checkpoint.** Show the user the look, the title, the estimated length, and each scene's narration, the exact on-screen text and one line on the visual, in plain words about what they will see. Wait for a clear yes. A question or a comment is not approval: answer it and ask again.
+**Checkpoint.** Tell the user, in one sentence, that new components you write are shared with the Reelkit library for review after the render (their code, a description and an example, nothing else), and that they can say no: then use `reelkit init <name> --private` or `reelkit render --no-share`, or set REELKIT_NO_SHARE=1. Show the user the look, the title, the estimated length, and each scene's narration, the exact on-screen text and one line on the visual, in plain words about what they will see. Wait for a clear yes. A question or a comment is not approval: answer it and ask again.
 
 ### 4. Voice
 `reelkit assets voiceover --all`. It records each scene and prints the real length of the video. If the user wants a different voice, change `voiceId` in `plan.json` and run it again with `--redo`.
@@ -96,7 +96,7 @@ Read `reference/kit.md`, `reference/remotion-composition.md`, `reference/motion-
 - Write `src/Video.tsx` and any component files beside it. `Video.tsx` may import only `react`, `remotion`, `reelkit/kit` and sibling components (`./Name`).
 - `manifest.json` is the exact object passed to `Video` as the `manifest` prop. Media is referenced as `urls[path]`, where `path` is the file's path in the project, such as `urls[scene.voiceoverKey]` or `urls["assets/lib/<id>/clip.mp3"]`.
 
-Run `reelkit check` and fix every error until it passes. Then `reelkit preview` (the first preview on a machine downloads a browser once and can take a minute) and look at every frame in `out/preview/`: each scene has two, `early` (30% into the scene) and `late` (90%), so look at both frames of each scene. Look for: text cut off or overflowing, text overlapping other text or the captions, text too small or too low-contrast for a phone, an empty or broken frame, content hidden behind another layer, and any number, price or quote on screen that is not in the plan. A frame is one moment: an element mid-animation is not a problem, but anything that should be fully on screen by the late frame and is not is. Fix real problems and preview again. Go round at least twice, and finish with the studio test in `reference/motion-design.md`. `reelkit preview` also reports continuity: how many scene changes carry something across. Fix every `cut` it names, or keep it as a deliberate choice (a burst of fast hits, the end card); see `reference/continuity.md`.
+Run `reelkit check` and fix every error until it passes. Read its "Worth improving" notes as well: they say when no library component was used, when every scene is type and shapes, and when the opening has no picture. Then `reelkit preview` (the first preview on a machine downloads a browser once and can take a minute) and look at every frame in `out/preview/`: each scene has two, `early` (30% into the scene) and `late` (90%), so look at both frames of each scene. Look for: text cut off or overflowing, text overlapping other text or the captions, text too small or too low-contrast for a phone, an empty or broken frame, content hidden behind another layer, and any number, price or quote on screen that is not in the plan. A frame is one moment: an element mid-animation is not a problem, but anything that should be fully on screen by the late frame and is not is. Fix real problems and preview again. Go round at least twice, and finish with the studio test in `reference/motion-design.md`. `reelkit preview` also reports continuity: how many scene changes carry something across. Fix every `cut` it names, or keep it as a deliberate choice (a burst of fast hits, the end card); see `reference/continuity.md`.
 
 You only ever see frames, never the moving video, so the frames are your eyes: look at every one. And whoever built a video is the worst judge of it. If you can start a separate agent, give it only the user's original request and the preview frames (not your explanations) and ask for a score out of 100 per scene, a list of flaws, and a concrete fix for each, in numbers ("raise the title 60 px", "hold the label 0.4 s longer"). Fix, preview, and have the same reviewer look again until every scene passes 90. If two rounds leave a scene under 70, stop and show the user the gap instead of spending more rounds.
 
@@ -111,9 +111,9 @@ If the render fails, read the error, fix the composition, and run `reelkit check
 
 - Search before generating. Reuse beats regenerate.
 - Never generate app UI. Use the user's real screenshots.
-- The user's own files are private. Do not pass `--share` unless they ask you to contribute a file.
+- The user's own files (images, footage, sounds) stay private: pass `--share` only when they ask you to contribute a file. Components are the opposite, by default: new components you write are sent to the library for review after the render (source, description and example only), unless the user says no; then use `reelkit init <name> --private` or `reelkit render --no-share` (or REELKIT_NO_SHARE=1).
 - Pass the user's facts through unchanged. Never invent a number, statistic, price or quote.
-- Keep components driven by props, not hardcoded, so they can be reused.
+- Keep components driven by props, not hardcoded, so they can be reused: nothing of this user's text in them, and every new component starts with a one or two sentence comment saying what it shows and when to use it (`reference/component-authoring.md`).
 - One stage at a time. Do not write composition code before the user has approved the plan, and do not render before they have approved the preview.
 - Never say a video is done without having looked at its frames and checked that the file exists.
 - If a command reports that a quota is used up, tell the user what ran out and when it resets. Do not work around it. A message that says to wait a minute or an hour ("Too many searches", "Too many uploads started") is a throttle, not a used-up quota: wait and retry once instead of stopping.

package/skill/reference/beat-sync.md

@@ -43,3 +43,12 @@ const onBeat = (s: { startFrame: number; words: { startSec: number }[] }, i: num
 ```
 
 `Music` ducks under the voice by itself and fades out over the last second; do not set its volume per scene.
+
+## Sound levels
+
+Every sound you pull (`sfx` and `music`) is measured when it is pulled and levelled: a sound effect shorter than 3 seconds to a peak of -3 dBFS, a longer sound and the music to about -18 LUFS, never more than 18 dB either way. The gain is in `assets/library.json` (`gainDb`) and in the manifest's `soundGain`, and `Sfx` and `Music` apply it by themselves, so the same `volume` number sounds equally loud for every file. Then:
+
+- the voiceover is `1` (the default);
+- a sound effect is `0.2` to `0.45`; the default `0.35` is right for most, and a small tick can go lower;
+- the music is `0.5` when it plays alone and drops to `0.12` under the voice by itself (`volume` and `duckTo` on `Music`); leave both alone unless a preview of the sound is clearly wrong;
+- the render is mastered at the end to -14 LUFS with peaks under -1 dBTP, so do not try to make the whole video louder: balance the parts against each other.

package/skill/reference/component-authoring.md

@@ -16,6 +16,7 @@ Run `reelkit assets search "<description>" --kind component`. If a library compo
 - Size relative to `useVideoConfig()`, never fixed pixels.
 - Animate from the local `useCurrentFrame()`, and accept an optional `delay` prop in frames.
 - Declare the props type in the same file and export it.
+- Start every new component with a comment of one or two sentences directly above `export const Name`, saying what it shows and when to use it. It becomes the library description when the component is shared, so it must make sense without this video: "A ring that fills to a percentage with a label in the middle. Use it for one big stat."
 
 ## Keep it reusable
 Write each component so it would suit a video on an unrelated topic:
@@ -23,4 +24,14 @@ Write each component so it would suit a video on an unrelated topic:
 - **Structural** - a badge, checklist, chart, progress bar, callout, quote card, icon animation, transition.
 - **Passing** - `reelkit check` passes with it in use.
 
-Avoid one-off layouts, anything with content baked in, or a near-duplicate of a library component. Sharing components back to the library is not available yet.
+Avoid one-off layouts, anything with content baked in, or a near-duplicate of a library component.
+
+## Sharing
+After a successful `reelkit render`, every new component written in the project is sent to the library for review (its source, the comment above it as the description, and an example taken from `Video.tsx`; nothing else), and only the owner publishes it. Make that work:
+- Use the component in `Video.tsx` with plain values where you can (`<NumberBadge value={42} label="users" />`). The example is the first use there; if its props are variables or `urls[...]` or `s.words`, the component is skipped and `reelkit components share NumberBadge --example '<NumberBadge value={42} label="users" />'` sends it with an example you give.
+- Keep the text out of the file: nothing from the user's script, no `assets/user/...` path, and not the video's title. A component that has any is refused.
+- `reelkit components share [name...]` sends by hand (`--describe`, `--example`, `--tags` for one name); it does not wait for a render.
+- The user may say no: `reelkit init <name> --private` for the project, `reelkit render --no-share` for one render, or `REELKIT_NO_SHARE=1`.
+
+## What keeps a component from being shared
+A component is shared only when nothing of this video is written into it. It is skipped when it uses one of the user's files, contains the plan's title, contains any run of eight or more characters that also appears in the narration or the on-screen text, or has a whole sentence written into its code. Pass every word in as a prop, with a short neutral default ("Label", "42"), and the component is both reusable and shareable.

package/skill/reference/kit.md

@@ -109,6 +109,7 @@ ScreenOverlay { src: string; durationSec?: number; opacity?: number }
 
 Sfx { src: string; at?: number; volume?: number }
   Plays one sound effect from the shared library, starting at the frame given by "at", counted from the start of the enclosing scene. Pull one with: reelkit assets search "<description>" --kind sfx, then reelkit assets pull <id>.
+  A pulled sound is levelled when it is pulled (the manifest's soundGain), and Sfx and Music apply that by themselves: the same volume sounds equally loud for every file. Nothing to pass.
   <Sfx src={urls["assets/lib/<id>/clip.mp3"]} at={10} volume={0.35} />
 
 Music { src: string; volume?: number; duckTo?: number }

package/src/cli.ts

@@ -3,6 +3,7 @@ import { ApiFailure } from "./api/client";
 import { assetsGenClip, assetsGenImage, assetsPull, assetsSearch, assetsUpload, assetsVoiceover, assetsVoices } from "./commands/assets";
 import { authLogin, authLogout, whoami } from "./commands/auth";
 import { check, preview, render } from "./commands/build";
+import { componentsShare } from "./commands/components";
 import { init } from "./commands/init";
 import { install } from "./commands/install";
 import { openInBrowser } from "./open";
@@ -65,7 +66,7 @@ auth.command("login").description("Log in to Reelkit: opens the login page in yo
 auth.command("logout").description("Log out and remove the stored token").action(run(authLogout));
 program.command("whoami").description("Show your account, quota and contributions").action(run(whoami));
 
-program.command("init [name]").description("Set up a video project (in a new folder named after it, or in this folder)").option("--aspect <aspect>", "9:16, 16:9 or 1:1").action(run(init));
+program.command("init [name]").description("Set up a video project (in a new folder named after it, or in this folder)").option("--aspect <aspect>", "9:16, 16:9 or 1:1").option("--private", "do not share new components with the library after a render (writes shareComponents: false)").action(run(init));
 
 const assets = program.command("assets").description("Find, add and generate the files a video needs");
 assets.command("upload <file>").description("Add one of your own files to this project (private unless --share; with --cutout the video is sent to the Reelkit server to be processed)")
@@ -107,7 +108,12 @@ program.command("plan").description("Work with plan.json").command("check").desc
 program.command("check").description("Check the composition in src/ without rendering").action(run(check));
 program.command("install").description("Install the Reelkit skill into your coding agents").option("--agent <id>", "claude, codex, cursor, gemini, agents or all").option("--force", "reinstall even when up to date").action(run((ctx, opts) => install(ctx, opts)));
 program.command("preview").description("Render preview frames into out/preview/: two per scene (at 30% and 90%) and the frames either side of each scene change, with a report of what carries across").action(run((ctx) => preview(ctx)));
-program.command("render").description("Render the video to out/video.mp4").action(run((ctx) => render(ctx)));
+program.command("render").description("Render the video to out/video.mp4; new components written in this project are then shared with the library for review").option("--no-share", "do not share new components with the library after this render (also: REELKIT_NO_SHARE=1)")
+  .action(run((ctx, opts: { share?: boolean }) => render(ctx, { noShare: opts.share === false })));
+const components = program.command("components").description("Components written in this project");
+components.command("share [names...]").description("Share components written in this project with the library for review (all of them with no name): their source, a description and an example are sent, nothing else")
+  .option("--describe <text>", "what it shows and when to use it (one component)").option("--example <jsx>", "an example use with plain values, such as '<StatRing value={42} />' (one component)").option("--tags <tags>", "comma-separated tags, 3 to 6 (one component)")
+  .action(run((ctx, names: string[], opts) => componentsShare(ctx, names, opts)));
 
 // Parses argv and runs the chosen command. Importing this module parses nothing; bin/reelkit.mjs calls main.
 export async function main(argv: string[]): Promise<void> {

package/src/commands/assets.ts

@@ -9,11 +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 } {
@@ -106,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 {
@@ -201,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
@@ -262,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;
@@ -276,7 +294,7 @@ 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);
+  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 {
@@ -289,12 +307,12 @@ export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; f
 }
 
 // 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): Promise<Result> {
+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: 0 };
+  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

package/src/commands/build.ts

@@ -7,9 +7,13 @@ import type { AssetManifest, ScenePlan } from "../pipeline/schema";
 import { compareFrames, SAMPLE_WIDTH, summariseContinuity, type Boundary } from "../render/continuity";
 import { buildManifest, missingAssets } from "../project/manifest";
 import { beatReport } from "../project/music";
-import { openProject, type Project } from "../project/project";
+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 { 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";
 
@@ -46,6 +50,12 @@ function compositionNotes(project: Project, plan: ScenePlan): string[] {
   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;
 }
 
@@ -57,7 +67,7 @@ export async function check(ctx: Ctx): Promise<Result> {
   if (errors.length) return failed(errors);
   const shouldImprove = compositionNotes(project, loadPlan(project));
   return {
-    ok: true, data: { errors: [], shouldImprove },
+    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"),
   };
 }
@@ -185,7 +195,7 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
   }
 }
 
-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);
@@ -197,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"),
   };
 }