reelkit-cli 0.5.0 → 0.8.0

package/src/commands/assets.ts

@@ -1,19 +1,26 @@
 import { randomUUID } from "node:crypto";
-import { copyFileSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import { copyFileSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
 import { ApiFailure, download, uploadTo } from "../api/client";
 import { client, type Ctx, type Result } from "../context";
 import { LibraryKindSchema, MAX_CUTOUT_SECONDS, MAX_UPLOAD_BYTES, UploadKindSchema, type CutoutType } from "../contract";
-import { PACE_SPEED, type AssetManifest, type AssetRecord, type ScenePlan } from "../pipeline/schema";
+import { gapSec, isVoiceless, LAST_TAIL_SEC, PACE_SPEED, type AssetManifest, type AssetRecord, type ScenePlan } from "../pipeline/schema";
 import { GreenTooDullError, keyGreen } from "../project/chromakey";
-import { buildManifest, voiceoverStale, type ClipRecord, type Voiceover } from "../project/manifest";
+import { buildManifest, sentenceGaps, voiceoverStale, type ClipRecord, type Voiceover } from "../project/manifest";
 import { loadPlan } from "./plan";
 import { FILE_NAME } from "../render/validate";
-import { measureMusic, type MusicRecord } from "../project/music";
+import { levelOf } from "../project/loudness";
+import { beatReport, measureMusic, type MusicRecord } from "../project/music";
+import { audioDuration } from "../project/refmeasure";
+import { BACKGROUND_CLIP_SENTENCE, BACKGROUND_IMAGE_SENTENCE, isVideoPath, lookFromNotes, readBackground, setBackground } from "../project/background";
 import { probeFile } from "../project/probe";
-import { FILES, openProject, type Project } from "../project/project";
+import { frameWithAlpha, measureTextZone, stillToVideo, tempDir, type LayerEntry } from "../project/layers";
+import { coverageVerdict } from "../remotion/kit/image-layers-math";
+import { svgProblem } from "../project/svgcheck";
+import { FILES, isPrivateProject, 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 } {
@@ -47,7 +54,7 @@ const shellArg = (s: string) => (/^[\w./~@%+=:,-]+$/.test(s) ? s : JSON.stringif
 
 // Sends a video to the server and starts its cutout. The seconds are reserved when the job is run, so this is the point where it becomes
 // paid for: nothing is charged by a failure before it, and the id it returns is the only handle on the job after it.
-async function startCutout(ctx: Ctx, input: CutoutInput): Promise<string> {
+export async function startCutout(ctx: Ctx, input: CutoutInput): Promise<string> {
   const api = client(ctx);
   ctx.log(`Sending ${input.filename} to the Reelkit server to cut the subject out.`);
   const up = await api("cutoutStart", { filename: input.filename.slice(-200), contentType: input.contentType, bytes: input.bytes, durationSec: input.durationSec });
@@ -61,7 +68,7 @@ type CutoutOutcome = { kind: "done" } | { kind: "failed"; message: string } | {
 
 // Asks every few seconds until the job ends (at most ten minutes), then saves the result at `dest`. A job that is not found or a login that
 // is wrong has nothing to resume and is thrown; any other trouble may be a hiccup on a job that is paid for, so it is an outcome.
-async function pollCutout(ctx: Ctx, id: string, dest: string, deps: CutoutDeps): Promise<CutoutOutcome> {
+export async function pollCutout(ctx: Ctx, id: string, dest: string, deps: CutoutDeps): Promise<CutoutOutcome> {
   const api = client(ctx);
   const now = deps.now ?? Date.now;
   const started = now();
@@ -99,14 +106,14 @@ function cutoutRefusal(file: string, probe: Awaited<ReturnType<typeof probeFile>
 
 // Registers one of the user's own files. It stays on this machine unless --share is given.
 export async function assetsUpload(
-  ctx: Ctx, file: string, opts: { describe?: string; footage?: boolean; green?: boolean; cutout?: boolean; resume?: string; share?: boolean; kind?: string; tags?: string },
+  ctx: Ctx, file: string, opts: { describe?: string; footage?: boolean; green?: boolean; cutout?: boolean; resume?: string; share?: boolean; kind?: string; tags?: string; background?: boolean },
   deps: { key?: typeof keyGreen } & CutoutDeps = {},
 ): Promise<Result> {
   const project = openProject(ctx.cwd);
   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 {
@@ -114,6 +121,8 @@ export async function assetsUpload(
   } catch (e) {
     return { ok: false, summary: e instanceof Error ? e.message : String(e) };
   }
+  if (opts.background && probe.kind === "audio") return { ok: false, summary: `${file} is audio, so it cannot be the film's background. Use a video or an image.` };
+  if (opts.background && (opts.footage || opts.green || opts.cutout)) return { ok: false, summary: "--background makes the file the ground behind everything; it does not go with --footage, --green or --cutout." };
   if (opts.footage && probe.kind !== "video") return { ok: false, summary: `${file} is ${probe.kind}, not a video, so it cannot be the footage.` };
   if (opts.green && probe.kind !== "video") return { ok: false, summary: `${file} is ${probe.kind}, not a video, so there is no green screen to key out.` };
   const refusal = opts.cutout ? cutoutRefusal(file, probe) : undefined;
@@ -141,7 +150,12 @@ export async function assetsUpload(
   }
   const record: AssetRecord = { id, filename, key, ...probe, ...(opts.describe ? { description: opts.describe } : {}), ...(keyedKey ? { keyedKey } : {}), ...(cutoutId ? { cutoutId } : {}), createdAt: new Date().toISOString() };
   project.writeJson(FILES.assetIndex, [...project.assets(), record]);
+  if (probe.kind === "image" && !/\.svg$/i.test(filename)) await recordZone(project, key, true);
   if (opts.footage) project.writeJson(FILES.config, { ...project.config(), footage: id });
+  if (opts.background) {
+    setBackground(project, { key, id, title: filename, ...(probe.kind === "video" && probe.durationSec ? { durationSec: probe.durationSec } : {}) });
+    if (project.exists(FILES.plan)) tryManifest(project, loadPlan(project));
+  }
 
   let libraryId: string | undefined;
   if (opts.share && kind?.success) {
@@ -161,7 +175,7 @@ export async function assetsUpload(
   }
   return {
     ok: true, data: { ...record, ...(libraryId ? { libraryId } : {}) },
-    summary: `Added ${filename} as ${id} (${probe.kind})${opts.footage ? ", set as the footage" : ""}${libraryId ? `, shared to the library as ${libraryId} (awaiting review)` : ", private to this project"}.${keyedKey ? ` The green is keyed out into ${keyedKey}: place it with KeyedClip as urls["${keyedKey}"].` : ""}`,
+    summary: `Added ${filename} as ${id} (${probe.kind})${opts.footage ? ", set as the footage" : ""}${opts.background ? `, set as the film's background: use manifest.background (urls["${key}"])` : ""}${libraryId ? `, shared to the library as ${libraryId} (awaiting review)` : ", private to this project"}.${keyedKey ? ` The green is keyed out into ${keyedKey}: place it with KeyedClip as urls["${keyedKey}"].` : ""}`,
   };
 }
 
@@ -201,14 +215,36 @@ 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 */ }
+}
+
+// The length and, for music, the tempo of a result, at the end of its line, when the library has them. Sounds are only useful once their length is known:
+// a riser must be as long as the build it scores, and a track must have the tempo the cuts will follow.
+export function lengthOf(item: { kind: string; meta: Record<string, unknown> }): string {
+  if (item.kind !== "music" && item.kind !== "sfx") return "";
+  const d = item.meta.durationSec, bpm = item.meta.bpm;
+  const parts = [typeof d === "number" && d > 0 ? `${Math.round(d * 10) / 10}s` : "", item.kind === "music" && typeof bpm === "number" && bpm > 0 ? `${Math.round(bpm)} BPM` : ""].filter(Boolean);
+  return parts.length ? `  (${parts.join(", ")})` : "";
+}
+
 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
-      ? items.map((i) => `${`${Math.round(i.match * 100)}%`.padStart(4)}  ${i.id}  ${i.kind}  ${i.title}: ${i.description}  [${i.tags.join(", ")}]`).join("\n")
+      ? items.map((i) => `${`${Math.round(i.match * 100)}%`.padStart(4)}  ${i.id}  ${i.kind}  ${i.title}: ${i.description}  [${i.tags.join(", ")}]${lengthOf(i)}`).join("\n")
       : "No matches in the library. Generate it instead.",
   };
 }
@@ -229,10 +265,13 @@ 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; music?: boolean }, deps: ClipDeps = {}): Promise<Result> {
+export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; force?: boolean; music?: boolean; background?: boolean; layers?: boolean }, deps: ClipDeps = {}): Promise<Result> {
+  if (opts.layers && (!opts.scene || opts.background || opts.music)) return { ok: false, summary: "--layers goes with --scene: it splits the scene's image into layers right after it is pulled." };
   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) {
+  if (opts.background && opts.music) return { ok: false, summary: "--background makes the item the ground behind the picture and --music makes it the track. Use one." };
+  if (opts.background && opts.scene && !loadPlan(project).scenes.some((s) => s.id === opts.scene)) return { ok: false, summary: `Scene ${opts.scene} is not in plan.json.` };
+  if (opts.scene && !opts.background) {
     // Checked before anything is downloaded.
     const scenes = loadPlan(project).scenes;
     const illustrations = scenes.filter((s) => s.treatment === "illustration").map((s) => s.id);
@@ -241,11 +280,13 @@ 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." };
+  if (opts.music && opts.scene && !opts.background) 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) {
+  if (opts.background && !["image", "clip", "overlay"].includes(pulled.item.kind)) return { ok: false, summary: `${id} is ${pulled.item.kind}, so it cannot be a background. Search with --kind clip, overlay or image.` };
+  if (opts.background && opts.scene && isVideoPath(pulled.filename)) return { ok: false, summary: `${id} is a video. A video is the ground of the whole film, so use --background without --scene; a scene's ground must be a picture.` };
+  if (opts.scene && !opts.background) {
     const treatment = loadPlan(project).scenes.find((x) => x.id === opts.scene)?.treatment;
     if (treatment === "clip" && pulled.item.kind !== "clip") return { ok: false, summary: `${id} is ${pulled.item.kind}, not a clip, so it cannot be scene ${opts.scene}'s clip.` };
     if (treatment !== "clip" && pulled.item.kind !== "image") return { ok: false, summary: `${id} is ${pulled.item.kind}, not an image, so it cannot be a scene's image.` };
@@ -262,43 +303,59 @@ 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 } : {}) });
+  if (opts.background) {
+    const video = isVideoPath(path);
+    let durationSec = typeof pulled.item.meta.durationSec === "number" ? pulled.item.meta.durationSec : undefined;
+    if (video && durationSec === undefined) { try { durationSec = Math.round((await audioDuration(project.path(path))) * 100) / 100; } catch { durationSec = undefined; } }
+    const previous = readBackground(project)[opts.scene ? "scenes" : "film"];
+    const had = opts.scene ? (previous as Record<string, { id?: string }>)[opts.scene] : (previous as { id?: string } | undefined);
+    setBackground(project, { key: path, id, title: pulled.item.title, ...(video && durationSec ? { durationSec } : {}) }, opts.scene);
+    const note = project.exists(FILES.plan) ? tryManifest(project, loadPlan(project)).note : undefined;
+    const where = opts.scene ? `scene ${opts.scene}'s background` : "the film's background";
+    return { ok: true, data: { path, kind: pulled.item.kind, background: true, ...(opts.scene ? { scene: opts.scene } : {}) }, summary: [`Pulled ${id} as ${where}${had?.id && had.id !== id ? ` (it replaces ${had.id})` : ""}. In the composition use ${opts.scene ? "the scene's `background.key`" : "`manifest.background`"}: <${video ? "BgVideo" : "BgImage"} src={urls["${path}"]} />. Read reference/backgrounds.md.`, ...(note ? [note] : [])].join("\n") };
+  }
   // 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;
   if (keyedPath) await (deps.key ?? keyGreen)(project.path(path), project.path(keyedPath));
   const sceneIsClip = pulled.item.kind === "clip";
   let note: string | undefined;
+  let layered: Result | undefined;
   if (opts.scene) {
     if (sceneIsClip) {
       const durationSec = typeof pulled.item.meta.durationSec === "number" ? pulled.item.meta.durationSec : 5;
       setSceneClip(project, opts.scene, { key: path, greenScreen: green, durationSec, ...(keyedPath ? { keyedKey: keyedPath } : {}) });
-    } else setSceneImage(project, opts.scene, path);
+    } else { setSceneImage(project, opts.scene, path); await recordZone(project, path, true); if (opts.layers) layered = await assetsLayers(ctx, undefined, { scene: opts.scene, redo: true }, deps); }
     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 {
-    ok: true, data: { path, kind: pulled.item.kind, ...(keyedPath ? { keyedPath } : {}) },
+    ok: true, data: { path, kind: pulled.item.kind, ...(keyedPath ? { keyedPath } : {}), ...(layered ? { layers: layered.data } : {}) },
     summary: [
       opts.scene ? `Pulled ${id} as the ${sceneIsClip ? "clip" : "image"} for scene ${opts.scene}.${keyedPath ? refs : ""}` : `Pulled ${id} to ${path}.${refs}${musicHint}`,
+      ...(layered ? [layered.summary] : []),
       ...(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): 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
-    ? `about ${Math.round(record.bpm)} BPM; scene changes will land on its beat.`
+    ? `about ${Math.round(record.bpm)} BPM; scene changes will land on its beat${project.exists(FILES.plan) && !isVoiceless(loadPlan(project)) ? " where that is within 4 frames of where the voice puts them (the others follow the voice)" : ""}.`
     : "no clear tempo was found, so scene changes stay where the narration puts them.";
   return {
     ok: true, data: { path, kind: "music", music: record },
@@ -306,11 +363,18 @@ async function pullMusic(project: Project, id: string, title: string, path: stri
   };
 }
 
+// Female voices first, then neutral and unmarked, then male, each group keeping the server's order: the first one listed is the default offer.
+export function orderVoices<T extends { gender?: string }>(voices: readonly T[]): T[] {
+  const rank = (v: T) => (/^f/i.test(v.gender ?? "") ? 0 : /^m/i.test(v.gender ?? "") ? 2 : 1);
+  return voices.map((v, i) => ({ v, i })).sort((a, b) => rank(a.v) - rank(b.v) || a.i - b.i).map((x) => x.v);
+}
+
 export async function assetsVoices(ctx: Ctx): Promise<Result> {
-  const { voices } = await client(ctx)("voices", {});
+  const listed = await client(ctx)("voices", {});
+  const voices = orderVoices(listed.voices);
   return {
     ok: true, data: { voices },
-    summary: voices.map((v) => `${v.id}  ${v.name} (${[v.gender, v.accent, v.language].filter(Boolean).join(", ")}): ${v.description}`).join("\n"),
+    summary: [...voices.map((v) => `${v.id}  ${v.name} (${[v.gender, v.accent, v.language].filter(Boolean).join(", ")}): ${v.description}`), "The plan needs a voiceId from this list (`reelkit plan check` asks for one); the first voice listed is the default offer to the user."].join("\n"),
   };
 }
 
@@ -318,6 +382,8 @@ export async function assetsVoices(ctx: Ctx): Promise<Result> {
 export async function assetsVoiceover(ctx: Ctx, opts: { scene?: string; all?: boolean; redo?: boolean }): Promise<Result> {
   const project = openProject(ctx.cwd);
   const plan = loadPlan(project);
+  // Said as success so that an agent following the older steps carries on instead of stopping.
+  if (isVoiceless(plan)) return { ok: true, data: { recorded: [], voice: "none" }, summary: "This video has no voice (voice is \"none\" in plan.json), so there is nothing to record. Go on to the music and the composition." };
   if (!opts.all && !opts.scene) return { ok: false, summary: "Say which scene with --scene <id>, or use --all." };
   const wanted = opts.all ? plan.scenes : plan.scenes.filter((s) => s.id === opts.scene);
   if (!wanted.length) return { ok: false, summary: `No scene with id ${opts.scene}. The scenes are: ${plan.scenes.map((s) => s.id).join(", ")}.` };
@@ -338,39 +404,115 @@ export async function assetsVoiceover(ctx: Ctx, opts: { scene?: string; all?: bo
   }
   const { manifest, note } = tryManifest(project, plan);
   const left = plan.scenes.filter((s) => !done[s.id] || voiceoverStale(done[s.id], s, plan)).map((s) => s.id);
+  const gaps = manifest ? sentenceGaps(manifest) : [];
+  const beat = manifest ? beatReport(manifest) : undefined;
   const recorded = `Recorded ${todo.length} scene(s)${rerecorded ? ` (${rerecorded} re-recorded because the script or voice changed)` : ""}.`;
   return {
-    ok: true, data: { recorded: todo.map((s) => s.id), rerecorded, voiceovers: done, totalSeconds: manifest ? manifest.totalFrames / manifest.fps : null },
+    ok: true, data: { recorded: todo.map((s) => s.id), rerecorded, voiceovers: done, totalSeconds: manifest ? manifest.totalFrames / manifest.fps : null, ...(manifest ? { sentenceGaps: gaps, ...(beat ? { beat: { bpm: beat.bpm, boundariesOnBeat: beat.boundariesOnBeat, boundaries: beat.boundaries } } : {}) } : {}) },
     summary: [
       manifest
-        ? `${recorded} The video runs ${(manifest.totalFrames / manifest.fps).toFixed(1)}s. Voiceover files are in assets/.${left.length ? ` Still out of date: ${left.join(", ")}. Run \`reelkit assets voiceover --all\`.` : ""}`
+        ? `${recorded} The video runs ${(manifest.totalFrames / manifest.fps).toFixed(1)}s (the last scene keeps ${LAST_TAIL_SEC}s after its last word). Voiceover files are in assets/.${left.length ? ` Still out of date: ${left.join(", ")}. Run \`reelkit assets voiceover --all\`.` : ""}\nSilence between sentences (plan gap "${plan.gap ?? "normal"}", ${gapSec(plan)}s): ${gaps.map((g) => `${g.toFixed(2)}s`).join(", ") || "none"}.${beat ? `\nBeat: ${beat.line}.` : ""}`
         : `${recorded}${left.length ? ` Still to record: ${left.join(", ")}.` : ""}`,
       ...(note ? [note] : []),
     ].join("\n"),
   };
 }
 
-export async function assetsGenImage(ctx: Ctx, prompt: string | undefined, opts: { scene: string; redo?: boolean }): Promise<Result> {
+// Said at the end of every image prompt that does not ask for text or a logo: a generated picture with letters in it is almost always wrong.
+// Added to the prompt of a scene that has on-screen text, so that the picture has a clear single subject and calm room for the words.
+export const TEXT_ROOM_SENTENCE = "One clear subject, with calm empty space on one side of the picture where words can sit.";
+export const NO_TEXT_SENTENCE = "No text, letters, numbers, logos or brand marks anywhere in the picture.";
+// What a prompt asks for when it wants writing or a logo in the picture. A clause that forbids them ("no text, no logos") does not count.
+const WANTS_TEXT = /\b(text|texts|letters?|lettering|typography|words?|caption|captions|title|headline|slogan|quote|says|saying|reads|reading|written|writing|sign|signage|label|logo|logos|wordmark|brand ?mark|brand name)\b/i;
+const FORBIDS = /\b(?:no|without|never|avoid|free of|not any|zero)\b[^.;\n]*/gi;
+export const asksForText = (prompt: string): boolean => WANTS_TEXT.test(prompt.replace(FORBIDS, " "));
+// The prompt as sent: with NO_TEXT_SENTENCE after it, unless the prompt itself asks for text or a logo.
+export const withNoText = (prompt: string): string => (asksForText(prompt) ? prompt : `${prompt.trim()}${/[.!?]$/.test(prompt.trim()) ? "" : "."} ${NO_TEXT_SENTENCE}`);
+
+export async function assetsGenImage(ctx: Ctx, prompt: string | undefined, opts: { scene?: string; redo?: boolean; background?: boolean; layers?: boolean }, deps: CutoutDeps = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   const plan = loadPlan(project);
+  if (opts.background) return genBackgroundImage(ctx, project, plan, prompt, { ...opts, format: "png" });
+  if (!opts.scene) return { ok: false, summary: "Say which scene the image is for with --scene <id>, or use --background for the film's ground." };
   const scene = plan.scenes.find((s) => s.id === opts.scene);
   if (!scene || scene.treatment !== "illustration" || !scene.imagePrompt) return { ok: false, summary: `Scene ${opts.scene} is not an illustration scene, so it does not take an image.` };
   // A scene that already has its image is not charged for again, whatever prompt is given; only --redo asks for a new one.
   const have = project.readJsonOr<Record<string, string>>(FILES.images, {})[scene.id];
-  if (have && project.exists(have) && !opts.redo) return { ok: true, data: { path: have, skipped: true }, summary: `Scene ${scene.id} already has an image at ${have}. Use --redo to generate a new one.` };
-  // Anything tied to the user's footage or uploads stays private, whatever the plan says. So does a prompt changed by hand.
-  const shareable = scene.shareable && !project.footage() && scene.userAssetIds.length === 0 && !prompt;
-  const img = await client(ctx)("images", { prompt: prompt ?? scene.imagePrompt, aspect: plan.aspect, shareable, tags: scene.imageTags });
+  if (have && project.exists(have) && !opts.redo) {
+    const layered = opts.layers ? await assetsLayers(ctx, undefined, { scene: scene.id }, deps) : undefined;
+    return { ok: true, data: { path: have, skipped: true }, summary: `Scene ${scene.id} already has an image at ${have}. Use --redo to generate a new one.${layered ? ` ${layered.summary}` : ""}` };
+  }
+  // Anything tied to the user's footage or uploads stays private, whatever the plan says. So does a prompt changed by hand, and every image of a
+  // project made with `reelkit init --private`.
+  const priv = isPrivateProject(project);
+  const shareable = scene.shareable && !priv && !project.footage() && scene.userAssetIds.length === 0 && !prompt;
+  const base = prompt ?? scene.imagePrompt;
+  const img = await client(ctx)("images", { prompt: withNoText(scene.onScreenText.length && !prompt ? `${base.trim()}${/[.!?]$/.test(base.trim()) ? "" : "."} ${TEXT_ROOM_SENTENCE}` : base), aspect: plan.aspect, shareable, tags: scene.imageTags, format: "png" });
   const path = `assets/img-${scene.id}.${img.ext}`;
   await download(img.url, project.path(path));
   setSceneImage(project, scene.id, path);
+  await recordZone(project, path, true);
+  const layered = opts.layers ? await assetsLayers(ctx, undefined, { scene: scene.id, redo: true }, deps) : undefined;
   const { note } = tryManifest(project, plan);
   return {
-    ok: true, data: { path, libraryId: img.libraryId ?? null },
-    summary: [`Generated the image for scene ${scene.id} at ${path}${img.libraryId ? `, and shared it to the library as ${img.libraryId} (awaiting review)` : ""}.`, ...(note ? [note] : [])].join("\n"),
+    ok: true, data: { path, libraryId: img.libraryId ?? null, ...(layered ? { layers: layered.data } : {}) },
+    summary: [`Generated the image for scene ${scene.id} at ${path}${img.libraryId ? `, and shared it to the library as ${img.libraryId} (awaiting review)` : ""}.`, ...(layered ? [layered.summary] : []), ...(note ? [note] : [])].join("\n"),
   };
 }
 
+// Downloads a generated vector graphic into memory first, checks it, and only then writes it, so a file that fails the check never reaches the project.
+async function saveSvg(url: string, dest: string): Promise<string | undefined> {
+  const res = await fetch(url);
+  if (!res.ok) return "The generated graphic could not be downloaded. Run the command again.";
+  const text = await res.text();
+  const problem = svgProblem(text);
+  if (problem) return problem;
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, text);
+  return undefined;
+}
+
+// A background made for the film (or for one scene, as a picture): a generic ambient image, never shared, saved and recorded as the ground.
+async function genBackgroundImage(ctx: Ctx, project: Project, plan: ScenePlan, prompt: string | undefined, opts: { scene?: string; redo?: boolean; format: "png" | "svg" }): Promise<Result> {
+  if (opts.scene && !plan.scenes.some((s) => s.id === opts.scene)) return { ok: false, summary: `Scene ${opts.scene} is not in plan.json.` };
+  const have = readBackground(project)[opts.scene ? "scenes" : "film"];
+  const existing = opts.scene ? (have as Record<string, { key: string }>)[opts.scene] : (have as { key: string } | undefined);
+  if (existing && project.exists(existing.key) && !opts.redo) return { ok: true, data: { path: existing.key, skipped: true }, summary: `${opts.scene ? `Scene ${opts.scene}` : "The film"} already has a background at ${existing.key}. Use --redo to generate a new one.` };
+  const sent = `${prompt ?? `${lookFromNotes(plan.scenes[0]?.notes)}.`} ${BACKGROUND_IMAGE_SENTENCE}`;
+  const img = await client(ctx)("images", { prompt: sent, aspect: plan.aspect, shareable: false, tags: [], format: opts.format });
+  const path = `assets/bg-${opts.scene ?? "film"}.${img.ext}`;
+  if (img.ext === "svg") { const bad = await saveSvg(img.url, project.path(path)); if (bad) return { ok: false, summary: bad }; }
+  else await download(img.url, project.path(path));
+  setBackground(project, { key: path, title: "generated background" }, opts.scene);
+  const { note } = tryManifest(project, plan);
+  return { ok: true, data: { path, prompt: sent }, summary: [`Generated ${opts.scene ? `scene ${opts.scene}'s` : "the film's"} background at ${path}. The prompt sent was: ${sent}`, ...(note ? [note] : [])].join("\n") };
+}
+
+// A vector graphic: icons, logo-like marks, simple illustrations, diagrams. It is one image against the image quota and takes about 45 seconds.
+export async function assetsGenSvg(ctx: Ctx, prompt: string, opts: { scene?: string; redo?: boolean; private?: boolean; background?: boolean }): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  const plan = loadPlan(project);
+  if (!prompt.trim()) return { ok: false, summary: "Say what the graphic shows: `reelkit assets gen svg \"a red rocket icon, flat, transparent background\"`." };
+  if (opts.background) return genBackgroundImage(ctx, project, plan, prompt, { ...opts, format: "svg" });
+  const scene = opts.scene ? plan.scenes.find((s) => s.id === opts.scene) : undefined;
+  if (opts.scene && (!scene || scene.treatment !== "illustration")) return { ok: false, summary: `Scene ${opts.scene} is not an illustration scene, so it does not take a graphic. Leave out --scene to save the file and place it yourself.` };
+  const have = scene ? project.readJsonOr<Record<string, string>>(FILES.images, {})[scene.id] : undefined;
+  if (scene && have && project.exists(have) && !opts.redo) return { ok: true, data: { path: have, skipped: true }, summary: `Scene ${scene.id} already has an image at ${have}. Use --redo to generate a new one.` };
+  // Shared for review only when the plan says the scene is generic and nothing of the user's is in it; --private always keeps it here.
+  const shareable = Boolean(scene?.shareable) && !opts.private && !isPrivateProject(project) && !project.footage() && (scene?.userAssetIds.length ?? 1) === 0;
+  ctx.log("Drawing the graphic. It takes about 45 seconds.");
+  const img = await client(ctx)("images", { prompt, aspect: plan.aspect, shareable, tags: scene?.imageTags ?? [], format: "svg" });
+  if (img.ext !== "svg") return { ok: false, summary: "The server sent a picture, not a vector graphic. Nothing was saved; run the command again." };
+  const path = scene ? `assets/img-${scene.id}.svg` : `assets/svg-${randomUUID().slice(0, 8)}.svg`;
+  const bad = await saveSvg(img.url, project.path(path));
+  if (bad) return { ok: false, summary: bad };
+  if (scene) setSceneImage(project, scene.id, path);
+  const { note } = project.exists(FILES.plan) ? tryManifest(project, plan) : { note: undefined };
+  return {
+    ok: true, data: { path, libraryId: img.libraryId ?? null },
+    summary: [`Generated the graphic at ${path}${img.libraryId ? `, and shared it to the library as ${img.libraryId} (awaiting review)` : ""}. Use it as urls["${path}"] in an <Img>. It counted as one image.`, ...(note ? [note] : [])].join("\n"),
+  };
+}
 
 const CLIP_POLL_MS = 5_000;
 const CLIP_PROGRESS_MS = 30_000;
@@ -380,17 +522,22 @@ const CLIP_TIMEOUT_MS = 10 * 60_000;
 // The id is the only handle on a paid job, so every way out after the start says it and how to resume.
 export async function assetsGenClip(
   ctx: Ctx, prompt: string | undefined,
-  opts: { scene: string; green?: boolean; cutout?: boolean; seconds?: string; share?: boolean; redo?: boolean; resume?: string },
+  opts: { scene?: string; green?: boolean; cutout?: boolean; seconds?: string; share?: boolean; redo?: boolean; resume?: string; background?: boolean },
   deps: ClipDeps = {},
 ): Promise<Result> {
   const project = openProject(ctx.cwd);
   const plan = loadPlan(project);
+  if (opts.background) return genBackgroundClip(ctx, project, plan, prompt, opts, deps);
+  if (!opts.scene) return { ok: false, summary: "Say which scene the clip is for with --scene <id>, or use --background for a clip behind the whole film." };
   const scene = plan.scenes.find((s) => s.id === opts.scene);
   if (!scene || scene.treatment !== "clip" || !scene.clipPrompt) return { ok: false, summary: `Scene ${opts.scene} is not a clip scene, so it does not take a clip. Set its treatment to "clip" and give it a clipPrompt in plan.json.` };
   if (opts.green && opts.cutout) return { ok: false, summary: "Use --green or --cutout, not both: --green asks for a green background and keys it on this machine for free, --cutout removes any background on the server." };
   const seconds = opts.seconds === undefined ? 5 : Number(opts.seconds);
   if (seconds !== 5 && seconds !== 10) return { ok: false, summary: `--seconds must be 5 or 10, not "${opts.seconds}".` };
   if (opts.resume && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(opts.resume)) return { ok: false, summary: `"${opts.resume}" is not a clip id. Copy it from the earlier message.` };
+  if (opts.share && isPrivateProject(project)) {
+    return { ok: false, summary: "This project was made with `reelkit init --private`, so nothing in it goes to the library and --share is refused. Run again without --share." };
+  }
   if (opts.share && (!scene.shareable || scene.userAssetIds.length > 0 || project.footage())) {
     return { ok: false, summary: `Scene ${scene.id} is private (it is not marked shareable in plan.json, or it shows your own files), so --share is refused. Run again without --share.` };
   }
@@ -543,3 +690,154 @@ async function keyScene(project: Project, sceneId: string, record: ClipRecord, k
   setSceneClip(project, sceneId, { ...record, greenScreen: true, keyedKey });
   return { ok: true, summary: "" };
 }
+
+// A clip meant to sit behind everything: a generic ambient loop, never shared. It uses the same clip quota and job as any clip, and `--resume` works.
+async function genBackgroundClip(ctx: Ctx, project: Project, plan: ScenePlan, prompt: string | undefined, opts: { scene?: string; green?: boolean; cutout?: boolean; seconds?: string; share?: boolean; redo?: boolean; resume?: string }, deps: ClipDeps): Promise<Result> {
+  if (opts.scene) return { ok: false, summary: "A background clip is for the whole film, so leave out --scene. A scene's own ground is a picture: `reelkit assets gen image --background --scene <id>`." };
+  if (opts.green || opts.cutout) return { ok: false, summary: "--green and --cutout are for a subject, not a background. Leave them out with --background." };
+  const seconds = opts.seconds === undefined ? 5 : Number(opts.seconds);
+  if (seconds !== 5 && seconds !== 10) return { ok: false, summary: `--seconds must be 5 or 10, not "${opts.seconds}".` };
+  if (opts.resume && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(opts.resume)) return { ok: false, summary: `"${opts.resume}" is not a clip id. Copy it from the earlier message.` };
+  const have = readBackground(project).film;
+  if (have && project.exists(have.key) && !opts.redo && !opts.resume) return { ok: true, data: { path: have.key, skipped: true }, summary: `The film already has a background at ${have.key}. Use --redo to generate a new one.` };
+  const now = deps.now ?? Date.now, api = client(ctx), started = now();
+  const sent = `${prompt ?? `${lookFromNotes(plan.scenes[0]?.notes)}.`} ${BACKGROUND_CLIP_SENTENCE}`;
+  let id = opts.resume;
+  if (!id) {
+    id = (await api("clipStart", { prompt: sent, aspect: plan.aspect, greenScreen: false, durationSec: seconds, shareable: false, tags: [] })).id;
+    ctx.log(`Started background clip ${id}. It usually takes a few minutes.`);
+  } else ctx.log(`Waiting for background clip ${id}.`);
+  const resume = `reelkit assets gen clip --background --resume ${id}`;
+  try {
+    let lastLog = started;
+    for (;;) {
+      const st = await api("clipStatus", { id });
+      if (st.status === "failed") return { ok: false, data: { id, status: "failed" }, summary: `The background clip failed: ${st.message ?? "the video provider gave no reason."} You were not charged. Change the prompt and run the command again.` };
+      if (st.status === "done") {
+        const path = `assets/bg-film.${st.ext}`;
+        await download(st.url!, project.path(path));
+        const durationSec = st.durationSec ?? seconds;
+        setBackground(project, { key: path, title: "generated background", durationSec });
+        const { note } = tryManifest(project, plan);
+        return { ok: true, data: { id, path, durationSec, prompt: sent }, summary: [`Generated the film's background clip at ${path} (${durationSec}s). The prompt sent was: ${sent} Use it with <BgVideo src={urls["${path}"]} durationSec={manifest.background?.durationSec} />.`, ...(note ? [note] : [])].join("\n") };
+      }
+      const elapsed = now() - started;
+      if (elapsed >= CLIP_TIMEOUT_MS) return { ok: false, data: { id, status: "pending" }, summary: `The background clip (id ${id}) is not ready after ${CLIP_TIMEOUT_MS / 60_000} minutes. It is still being made and is not lost: run \`${resume}\` to keep waiting for it; that does not charge again.` };
+      if (now() - lastLog >= CLIP_PROGRESS_MS) { lastLog = now(); ctx.log(`Still making the background clip (${Math.round(elapsed / 1000)}s so far)...`); }
+      await ctx.sleep(CLIP_POLL_MS);
+    }
+  } catch (e) {
+    if (e instanceof ApiFailure && (e.code === "not_found" || e.code === "unauthenticated")) throw e;
+    return { ok: false, data: { id }, summary: `Lost contact while the background clip (id ${id}) was being made: ${e instanceof Error ? e.message : String(e)} The clip is not lost: run \`${resume}\`; that does not charge again.` };
+  }
+}
+
+
+// ---- Layers: a still picture in layers, with the words as a layer of it ----
+
+// Measures where words can sit in a picture (free, on this machine) and records it beside the picture's layers. With `fresh` the record starts again, so that
+// a new picture never keeps the subject of the one it replaces. A picture ffmpeg cannot read is recorded as nothing: the layers are an addition, never a failure.
+async function recordZone(project: Project, key: string, fresh = false): Promise<LayerEntry | undefined> {
+  try {
+    const all = project.readJsonOr<Record<string, LayerEntry>>(FILES.layers, {});
+    const old = fresh ? undefined : all[key];
+    const textZone = await measureTextZone(project.path(key), old?.subjectBox);
+    const entry: LayerEntry = { ...(old ?? {}), textZone };
+    project.writeJson(FILES.layers, { ...all, [key]: entry });
+    return entry;
+  } catch { return undefined; }
+}
+
+function saveLayerEntry(project: Project, key: string, entry: LayerEntry) {
+  project.writeJson(FILES.layers, { ...project.readJsonOr<Record<string, LayerEntry>>(FILES.layers, {}), [key]: entry });
+}
+
+const subjectPathOf = (key: string) => key.replace(/\.[^./]+$/, "") + ".subject.png";
+
+// Makes the picture a scene's image is made of into layers: the subject cut out of it (a PNG with alpha beside it, `<name>.subject.png`), its box, and where words can
+// sit. It reuses the service that removes the background of a video: the still is sent as a one-second video, so it uses about 1 second of the cutout quota, and one
+// frame of the transparent video that comes back is kept. A picture with no clear subject (the cut-out covers under 3% or over 85% of it) stays flat and the command
+// still succeeds. `file` is a picture in the project; `scene` is a scene's image.
+export async function assetsLayers(ctx: Ctx, file: string | undefined, opts: { scene?: string; redo?: boolean; resume?: string }, deps: CutoutDeps = {}): Promise<Result> {
+  const project = openProject(ctx.cwd);
+  if (!file && !opts.scene) return { ok: false, summary: "Say which picture: `reelkit assets layers --scene <id>` for a scene's image, or `reelkit assets layers <file>` for a picture in the project." };
+  if (file && opts.scene) return { ok: false, summary: "Give a file or --scene, not both." };
+  if (opts.resume && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(opts.resume)) return { ok: false, summary: `"${opts.resume}" is not a cutout id. Copy it from the earlier message.` };
+  let key: string;
+  if (opts.scene) {
+    const have = project.readJsonOr<Record<string, string>>(FILES.images, {})[opts.scene];
+    if (!have || !project.exists(have)) return { ok: false, summary: `Scene ${opts.scene} has no image yet. Make one with \`reelkit assets gen image --scene ${opts.scene}\` or pull one with \`reelkit assets pull <id> --scene ${opts.scene}\`.` };
+    if (/\.(svg|mp4|webm|mov)$/i.test(have)) return { ok: false, summary: `Scene ${opts.scene}'s picture ${have} is not a photo or a raster picture, so it cannot be split into layers.` };
+    key = have;
+  } else {
+    const abs = resolve(ctx.cwd, file!);
+    const rel = relative(project.dir, abs);
+    if (rel.startsWith("..") || !project.exists(rel)) return { ok: false, summary: `${file} is not a file in this project. Add it with \`reelkit assets upload ${file}\` and give the path it is stored at.` };
+    let probe: Awaited<ReturnType<typeof probeFile>>;
+    try { probe = await probeFile(abs); } catch (e) { return { ok: false, summary: e instanceof Error ? e.message : String(e) }; }
+    if (probe.kind !== "image") return { ok: false, summary: `${file} is ${probe.kind}, not a picture, so it has no layers.` };
+    key = rel;
+  }
+  const tag = opts.scene ? ` for scene ${opts.scene}` : "";
+  const retry = `reelkit assets layers ${opts.scene ? `--scene ${opts.scene}` : shellArg(key)}`;
+  const entry0 = project.readJsonOr<Record<string, LayerEntry>>(FILES.layers, {})[key];
+  const subjectKey = subjectPathOf(key);
+  const refreshManifest = () => { if (project.exists(FILES.plan)) tryManifest(project, loadPlan(project)); };
+  // Already done: nothing is sent and nothing is charged.
+  if (!opts.redo && !opts.resume && entry0 && (entry0.noSubject || (entry0.subject && project.exists(entry0.subject)))) {
+    return { ok: true, data: { key, ...entry0, skipped: true }, summary: entry0.noSubject ? `The picture ${key} has no clear subject, so it stays flat; the words go in its ${entry0.textZone.region}. Use --redo to try again.` : `The picture ${key} already has its subject at ${entry0.subject}. Use --redo to make it again.` };
+  }
+  const zoneEntry = (await recordZone(project, key, opts.redo)) ?? { textZone: { region: "bottom" as const, luminance: 0.3, busy: 0.5 } };
+  const flat = (why: string): Result => ({ ok: true, data: { key, ...zoneEntry, noSubject: true }, summary: `${why} The picture ${key} stays one flat image; the words go in its ${zoneEntry.textZone.region} (${zoneEntry.textZone.luminance > 0.55 ? "light" : "dark"} there: use dark or light ink to match, or TextOnImage does).` });
+  const sceneNote = ` In the composition: <ImageLayers layers={s.imageLayers}><TextOnImage layers={s.imageLayers}>...</TextOnImage></ImageLayers>.`;
+
+  let id = opts.resume ?? (opts.redo ? undefined : entry0?.cutoutId);
+  const work = tempDir();
+  try {
+    if (!id) {
+      const video = `${work.dir}/still.mp4`;
+      try { await stillToVideo(project.path(key), video); } catch (e) { return flat(`The picture could not be prepared for a cut-out: ${e instanceof Error ? e.message : String(e)}`); }
+      try {
+        id = await startCutout(ctx, { source: video, filename: `${basename(key).replace(/\.[^.]+$/, "")}.mp4`.replace(/[^A-Za-z0-9._-]/g, "_"), contentType: "video/mp4", bytes: statSync(video).size, durationSec: 1 });
+      } catch (e) {
+        return { ok: false, data: { key, ...zoneEntry }, summary: `The picture ${key} stays flat: the cut-out could not be started: ${e instanceof Error ? e.message : String(e)} Nothing was charged. Run \`${retry}\` to try again.` };
+      }
+      saveLayerEntry(project, key, { ...zoneEntry, cutoutId: id });
+    } else ctx.log(`Waiting for cutout ${id} of ${key}.`);
+    const webm = `${work.dir}/subject.webm`;
+    let outcome: CutoutOutcome;
+    try { outcome = await pollCutout(ctx, id, webm, deps); } catch (e) {
+      if (!(e instanceof ApiFailure && e.code === "not_found")) throw e;
+      saveLayerEntry(project, key, { ...zoneEntry, cutoutId: undefined });
+      return { ok: false, data: { key }, summary: `The picture ${key} stays flat: the server no longer has cutout ${id}, so it was forgotten. Run \`${retry} --redo\` to start a new one.` };
+    }
+    if (outcome.kind !== "done") {
+      const resume = `${retry} --resume ${id}`;
+      if (outcome.kind === "failed") { saveLayerEntry(project, key, { ...zoneEntry, cutoutId: undefined }); return { ok: false, data: { key, status: "failed" }, summary: `The picture ${key} stays flat: the cut-out failed: ${outcome.message} You were not charged. Try \`${retry} --redo\` or a different picture. ${SENT_NOTE}` }; }
+      return { ok: false, data: { key, status: "pending", id }, summary: outcome.kind === "timeout" ? `The picture ${key} stays flat for now: the cut-out (id ${id}) is not ready after ${CUTOUT_TIMEOUT_MS / 60_000} minutes. It is not lost: run \`${resume}\`; that does not upload or charge again.` : `The picture ${key} stays flat for now: contact was lost while the cut-out (id ${id}) was being made: ${outcome.message} It is not lost: run \`${resume}\`; that does not charge again.` };
+    }
+    let cut: Awaited<ReturnType<typeof frameWithAlpha>>;
+    try { cut = await frameWithAlpha(webm, project.path(subjectKey)); } catch (e) {
+      rmSync(project.path(subjectKey), { force: true });
+      saveLayerEntry(project, key, { ...zoneEntry, cutoutId: undefined });
+      return flat(`The cut-out was made (about 1 second of your monthly cutout quota) but its subject layer could not be used: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const quota = "It used about 1 second of your monthly cutout quota.";
+    const verdict = coverageVerdict(cut.coverage);
+    if (!verdict.ok) {
+      rmSync(project.path(subjectKey), { force: true });
+      saveLayerEntry(project, key, { ...zoneEntry, noSubject: true, coverage: cut.coverage });
+      refreshManifest();
+      return { ok: true, data: { key, noSubject: true, coverage: cut.coverage, textZone: zoneEntry.textZone }, summary: `${verdict.note} ${quota} ${SENT_NOTE}` };
+    }
+    // The words' calm zone is measured again now that the subject is known, so that it is never offered behind it.
+    const textZone = await measureTextZone(project.path(key), cut.box).catch(() => zoneEntry.textZone);
+    const entry: LayerEntry = { subject: subjectKey, ...(cut.box ? { subjectBox: cut.box } : {}), textZone, coverage: Math.round(cut.coverage * 1000) / 1000 };
+    saveLayerEntry(project, key, entry);
+    refreshManifest();
+    return {
+      ok: true, data: { key, ...entry },
+      summary: `Layers${tag}: the subject is cut out into ${subjectKey} (it covers ${Math.round(cut.coverage * 100)}% of the picture) and the words have a calm ${textZone.region} (${textZone.luminance > 0.55 ? "light" : "dark"}). ${quota} ${SENT_NOTE}${opts.scene ? sceneNote : ` Use urls["${key}"] as the back and urls["${subjectKey}"] as the subject.`}`,
+    };
+  } finally { work.done(); }
+}