ossclip 0.1.31 → 0.1.34

package/src/produce.ts

@@ -11,7 +11,7 @@ import {
   statSync,
 } from "node:fs";
 import { cpus } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { z } from "zod/v4";
 import {
   LayoutSchema,
@@ -28,6 +28,7 @@ import {
   remapSceneOverrides,
   assembleScenes,
   buildCaptionLines,
+  captionPackingFor,
   buildCutlist,
   canonicalizeDictionaryCasing,
   captionsNeedNastaliq,
@@ -45,6 +46,9 @@ import {
   COVER_PROVENANCE_BASENAME,
   coverDecision,
   coverHeadline,
+  coverInVideoWindow,
+  COVER_IN_VIDEO_CAP_SEC,
+  COVER_IN_VIDEO_FLOOR_SEC,
   readCoverProvenance,
   writeCoverProvenance,
   cropFilter,
@@ -97,6 +101,10 @@ import {
   thumbnailImageCacheName,
   applyCleanupChoices,
   vetoedRemovals,
+  dismissedRemovals,
+  carveKeptTakes,
+  resolveSplitPoints,
+  resolveSrcTimingPins,
   applyUserCuts,
   pruneHidesInsideCuts,
   loadConfig,
@@ -158,7 +166,12 @@ import {
   AGY_PRINT_TIMEOUT,
   type Production,
   ossclipOutputPathFor,
+  resolveOutputFrame,
+  RESOLUTION_CHOICES,
+  smallestSource,
+  ResolutionChoiceSchema,
   type ProviderName,
+  type ResolutionChoice,
   type Scene,
   type SceneComponentId,
   type Segment,
@@ -248,6 +261,14 @@ export const TranscriptKeySchema = z.object({
    * runs) means "no biasing".
    */
   dictionary: z.array(z.string()).optional(),
+  /**
+   * Whether whisper ran its TRANSLATE task (`-tr`, 2026-08-29). It changes
+   * the decoded TEXT — Urdu speech comes back as English words — so it
+   * re-keys the cache exactly like the language does, or a warm workdir
+   * serves the Urdu-script transcript to a translate run. Absent (old key
+   * files) means "no translation", the `dictionary` contract.
+   */
+  translate: z.boolean().optional(),
 });
 export type TranscriptKey = z.infer<typeof TranscriptKeySchema>;
 
@@ -272,6 +293,9 @@ export function transcriptCacheReusable(
       // "" and absent both mean whisper's en default — program.ts rejects an
       // empty code, but a key file predating that guard must not wedge.
       (effective.language ?? "") === (requested.language ?? "") &&
+      // Absent and false are the same "no translation", so pre-flag key
+      // files reuse under a non-translate request.
+      (effective.translate ?? false) === (requested.translate ?? false) &&
       // ORDER-SENSITIVE by choice: the dictionary becomes whisper's --prompt
       // text verbatim, so a reordered list genuinely is a different decoder
       // input — treating it as equal would serve a transcript biased by a
@@ -529,6 +553,13 @@ export interface ProduceOptions {
    * decodes garbage (Urdu field test 2026-08-05).
    */
   whisperLanguage?: string;
+  /**
+   * `--whisper-translate`: whisper's TRANSLATE task (`-tr`) — non-English
+   * speech decoded straight to ENGLISH text. Distinct from
+   * `whisperLanguage`, which says what is SPOKEN; the two are passed
+   * together (whisper decodes better knowing the source language).
+   */
+  whisperTranslate?: boolean;
   /**
    * Vocabulary terms for this run (`--dictionary`, F4 2026-08-16), already
    * split/trimmed by the action. Wholesale beats the config's `dictionary`
@@ -576,6 +607,16 @@ export interface ProduceOptions {
    * platform chrome to dodge and a landscape source needs no cropping at all.
    */
   aspect?: "9:16" | "16:9";
+  /**
+   * `--resolution <height>`: how big the output actually renders. `auto`
+   * keeps what the source has (capped at 2160); an explicit height scales the
+   * 1080-wide composition to it. Already validated by commander (or by
+   * `ResolutionChoiceSchema` when it comes from the config), so this is a
+   * choice, never a raw string. `resolveOutputFrame` owns the math and the
+   * why; the value reaches THREE stages that would otherwise each pin 1080p:
+   * the folder-concat target, the mezzanine, and the render's own scale.
+   */
+  resolution?: ResolutionChoice;
   /**
    * `--concurrency <n>`: how many browser tabs the render opens at once,
    * beating the config's `renderConcurrency` and the cpus-2 default
@@ -613,6 +654,15 @@ export interface ProduceOptions {
    * a free-tier limitation; this is voluntary attribution.
    */
   watermark?: boolean;
+  /**
+   * `--cover-in-video` / `--no-cover-in-video` tri-state, the watermark's
+   * contract verbatim: true/false when TYPED, undefined when not — undefined
+   * lets the config's `coverInVideo` key supply the default
+   * (`resolveCoverInVideo`). Default OFF: the overlay paints over the first
+   * fraction of the hook, which only earns its place on the platforms that
+   * ignore an uploaded cover.
+   */
+  coverInVideo?: boolean;
   /**
    * `--youtube` / `--no-youtube` tri-state, the watermark's exact contract:
    * true/false when TYPED, undefined when not — undefined lets the config's
@@ -692,6 +742,92 @@ export function resolveWatermark(
   return flag ?? configValue === true;
 }
 
+/**
+ * The effective `--resolution` — `resolveWatermark`'s precedence verbatim: a
+ * TYPED flag always wins, and only then does the config supply the default.
+ *
+ * The config side is ZOD-PARSED rather than trusted: `loadConfig` hands back
+ * whatever the hand-editable JSON held, and an unparsed `"4k"` would reach
+ * `Number("4k")` inside `resolveOutputFrame` as NaN and size the whole render
+ * off it. A malformed value earns one warning naming the key and falls back
+ * to 1080 — the value every existing run already produces, so a typo costs a
+ * message rather than a surprise 4K render (CLAUDE.md: parse, never coerce).
+ * Pure, so the flag × config matrix is testable without a config file.
+ */
+export function resolveResolution(
+  flag: ResolutionChoice | undefined,
+  configValue: unknown,
+): ResolutionChoice {
+  if (flag !== undefined) return flag;
+  if (configValue === undefined) return "1080";
+  const parsed = ResolutionChoiceSchema.safeParse(configValue);
+  if (parsed.success) return parsed.data;
+  console.log(
+    `⚠ config resolution ignored — expected one of ${RESOLUTION_CHOICES.join(", ")}, using 1080`,
+  );
+  return "1080";
+}
+
+/**
+ * The effective `--cover-in-video` switch — resolveWatermark's semantics
+ * verbatim: a TYPED flag always wins (so `--no-cover-in-video` beats a
+ * config-on), and only then does the config supply the default. The config
+ * side is `=== true`, never truthiness: a hand-edited `"coverInVideo": "yes"`
+ * must not coerce an overlay onto the first frames of every render
+ * (parse-don't-coerce, CLAUDE.md). Pure, so the whole flag × config matrix is
+ * testable without a config file on disk.
+ */
+export function resolveCoverInVideo(
+  flag: boolean | undefined,
+  configValue: boolean | undefined,
+): boolean {
+  return flag ?? configValue === true;
+}
+
+/**
+ * Where the cover image lives right now, most-specific first — the EDITOR
+ * panel's ladder (`currentCoverImage` in edit.ts), deliberately the same one:
+ * the destination the last cover render used (`cover.json`'s `out`), else
+ * this run's `<out>.cover.jpg`. Two surfaces disagreeing about which file IS
+ * the project's cover is how the overlay would end up showing a stale image
+ * the panel says was replaced.
+ *
+ * Pure — the caller owns the `existsSync` walk — so the ladder is assertable
+ * without a workdir. Note what it CANNOT return: the cover this run is about
+ * to write, which does not exist yet (produce renders the cover after the
+ * video). See the staging site for why that is the intended behavior.
+ */
+export function coverInVideoCandidates(p: {
+  provenanceOut?: string | null;
+  outPath: string;
+}): string[] {
+  const out: string[] = [];
+  if (p.provenanceOut) out.push(p.provenanceOut);
+  out.push(artifactPath(p.outPath, ".cover.jpg"));
+  return out;
+}
+
+/**
+ * Fixed subfolder the staged cover overlay lands in, never the public dir's
+ * root — `SIDE_IMAGE_SUBDIR`'s reasoning applied to a file produce names
+ * itself: the public dir can BE the user's own input folder (a --no-mezzanine
+ * file run), and a root-level `cover-in-video.jpg` would silently overwrite a
+ * file of theirs that happened to share the name. Nothing else writes into
+ * this subfolder, so a collision is impossible by construction.
+ */
+export const COVER_IN_VIDEO_SUBDIR = "cover-in-video";
+
+/**
+ * The staged overlay's SERVED name, from the cover image being copied. Keeps
+ * the source's own extension (lowercased) so a `.png` cover is not served as
+ * a `.jpg`, and stays POSIX-literal — never `path.join` — because this string
+ * is a URL read back by `staticFile()` and the editor's `/media/` mount, both
+ * of which split on `/` only (sideImageDestRel's Windows lesson).
+ */
+export function coverInVideoFileName(source: string): string {
+  return `${COVER_IN_VIDEO_SUBDIR}/cover${extname(source).toLowerCase()}`;
+}
+
 /**
  * The effective `--youtube` switch — resolveWatermark's semantics verbatim:
  * a TYPED flag always wins (so `--no-youtube` beats a config-on), and only
@@ -1634,14 +1770,10 @@ export function resolveCaptionsHidden(
  * stay byte-identical. Pure so the matrix is testable without a produce
  * run.
  */
-export function captionPackingFor(landscape: boolean): {
-  maxWordsPerLine: number;
-  maxLineDuration: number;
-} {
-  return landscape
-    ? { maxWordsPerLine: 6, maxLineDuration: 2.4 }
-    : { maxWordsPerLine: 3, maxLineDuration: 1.2 };
-}
+// Moved to core (captions.ts) so the editor's live caption rebuild packs
+// with the SAME matrix (cut-review rework follow-up: captions over revived
+// material). Re-exported here so existing imports and tests keep working.
+export { captionPackingFor } from "@ossclip/core";
 
 function sha1File(path: string): Promise<string> {
   return new Promise((res, rej) => {
@@ -2005,6 +2137,46 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
 
   const tools = { ffmpegPath: cfg.ffmpegPath, ffprobePath: cfg.ffprobePath };
 
+  // `--resolution` (2026-08-27), resolved before ANY stage that sizes pixels:
+  // the folder concat, the mezzanine and the render each used to pin 1080p
+  // independently, so a 4K take lost three quarters of its pixels before
+  // anything looked at it. `auto` needs the SOURCE's size, which for a folder
+  // means probing the clips here — the concat target is chosen before the
+  // concatenated file (and its probe) exists.
+  const resolution = resolveResolution(opts.resolution, cfg.resolution);
+  const autoSource = async (): Promise<{ width: number; height: number } | null> => {
+    if (resolution !== "auto") return null;
+    if (isFolder && folderListing) {
+      // Metadata-only probes, and only under `auto`: the default path adds no
+      // ffprobe calls at all (the 4m32s probe-storm lesson, concat.ts:272).
+      const sizes: Array<{ width: number; height: number }> = [];
+      for (const entry of folderListing.entries) {
+        try {
+          const p = await probe(tools, join(input, entry.name));
+          sizes.push({ width: p.width, height: p.height });
+        } catch {
+          // A clip that will not probe is the concat guard's problem, not
+          // this sizing pass's — skip it rather than fail the run here.
+        }
+      }
+      return smallestSource(sizes);
+    }
+    try {
+      const p = await probe(tools, input);
+      return { width: p.width, height: p.height };
+    } catch {
+      return null;
+    }
+  };
+  const output = resolveOutputFrame({
+    frame,
+    source: (await autoSource()) ?? { width: 0, height: 0 },
+    resolution,
+  });
+  if (output.scale !== 1) {
+    console.log(`▸ resolution: ${output.width}x${output.height} (${resolution})`);
+  }
+
   // Resolved ONCE for the whole run — whisper biasing, repair vouching and
   // caption casing must all see the same list, or the passes disagree about
   // what a term is spelled like. A typed --dictionary wholesale beats the
@@ -2109,9 +2281,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   if (isFolder && folderListing) {
     const sort = opts.sort ?? "name";
     const result = await phases.time("ffmpeg", () =>
+      // The concat target carries the RESOLVED size, not the base frame:
+      // letterboxing every take into 1080p here would throw the pixels away
+      // before the mezzanine or the render ever saw them (`--resolution`).
       concatFolder(tools, input, folderListing!, work, sort, {
-        w: frame.width,
-        h: frame.height,
+        w: output.width,
+        h: output.height,
       }),
     );
     console.log(
@@ -2231,6 +2406,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   const requestedKey: TranscriptKey = {
     model: requestedModel,
     ...(whisperLang.language !== undefined ? { language: whisperLang.language } : {}),
+    // Omitted when off, so a non-translate run's key stays byte-identical to
+    // every pre-flag key file (the dictionary posture).
+    ...(opts.whisperTranslate === true ? { translate: true } : {}),
     // Omitted when empty, not written as [] — pre-dictionary key files have
     // no `dictionary` at all, and transcriptCacheReusable reads absent and
     // empty as the same "no biasing", so old workdirs must not re-transcribe.
@@ -2301,6 +2479,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
           language: requestedKey.language,
           // Vocabulary biasing (F4) — undefined for an empty dictionary, so
           // the spawned args stay byte-identical to every pre-dictionary run.
+          // From the KEY, like the language: whatever re-keys the cache is
+          // what actually ran, so the two can never disagree.
+          ...(requestedKey.translate === true ? { translate: true } : {}),
           prompt: whisperPromptFor(dictionary),
         },
         audioPath,
@@ -3132,10 +3313,21 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // a duration hint a few seconds short — never a wrong cut.
   const cutlistProposed = cutlist;
   const cleanupVetoed = vetoedRemovals(cutlist, overrideDoc.cleanup);
-  if (cleanupVetoed.length > 0) {
+  // Dismissed proposals ("not a retake", cut-review rework 2026-08-26)
+  // re-keep exactly like vetoes — applyCleanupChoices owns the union — but
+  // get their own line: a dismissal is "the classification was wrong", not
+  // "kept this once", and the two must not read as one number.
+  const cleanupDismissed = dismissedRemovals(cutlist, overrideDoc.cleanup);
+  if (cleanupVetoed.length > 0 || cleanupDismissed.length > 0) {
     cutlist = applyCleanupChoices(cutlist, overrideDoc.cleanup);
     map = new TimeMap(cutlist);
-    console.log(cleanupChoicesLine(cleanupVetoed, map.outputDuration));
+    if (cleanupVetoed.length > 0) console.log(cleanupChoicesLine(cleanupVetoed, map.outputDuration));
+    if (cleanupDismissed.length > 0) {
+      const sec = cleanupDismissed.reduce((s, seg) => s + (seg.srcOut - seg.srcIn), 0);
+      console.log(
+        `▸ dismissed ${cleanupDismissed.length} marker(s) — ${sec.toFixed(1)}s kept as footage`,
+      );
+    }
   }
   // `applyUserCuts`'s `priorMap`: a cut's `startSec`/`endSec` (when it has
   // no `src` yet) and any already-re-anchored splits/pins are expressed
@@ -3164,6 +3356,26 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   cutlist = cutResult.cutlist;
   map = cutResult.map;
   overrideDoc = cutResult.doc;
+  // Backfill `splits[].src` ONCE for src-less legacy entries (cut-review
+  // rework, 2026-08-26) — the `resolveCutSourceRanges` posture applied to
+  // splits: after `applyUserCuts`, a legacy `at` speaks THIS run's clock
+  // (remapped when the frames differed), so `map.toSource(at)` is exact.
+  // Gated on `priorMap` like the cuts resolution: with no prior render-props
+  // the frame `at` was drawn against is unknowable, and a guessed src would
+  // be a wrong anchor forever. `at` stays verbatim — the historical record,
+  // per SplitSchema.
+  let splitSrcResolved = false;
+  if (priorMap !== null) {
+    const withSrc = overrideDoc.splits.map((s) => {
+      if (s.src !== undefined || s.at === undefined) return s;
+      splitSrcResolved = true;
+      return { ...s, src: Math.round(map.toSource(s.at) * 1000) / 1000 };
+    });
+    if (splitSrcResolved) {
+      overrideDoc = { ...overrideDoc, splits: withSrc };
+      console.log(`▸ anchored ${withSrc.filter((s) => s.src !== undefined).length} split(s) to source time`);
+    }
+  }
   if (overrideDoc.cuts.length > 0) {
     console.log(
       `▸ ${overrideDoc.cuts.length} user cut(s) removed ${cutResult.removedSec.toFixed(1)}s ` +
@@ -3402,7 +3614,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // reshape `map` in time) — applied here, AFTER assembly and routing, so
   // hand edits sit on top of whatever the producer just planned. Never
   // written to production.json — that file is ours to overwrite.
-  const { cues: editedCues } = applyOverrides(routed.cues, overrideDoc);
+  // Src-anchored pins (SceneTimingSchema) resolved onto THIS run's clock
+  // before anything merges them — the same posture as `resolveSplitPoints`
+  // below, and the reason `applyOverrides` never takes a map. A LOCAL doc,
+  // deliberately not written back over `overrideDoc`: its `timing` entries
+  // are now output seconds, and letting one of those reach the sanctioned
+  // overrides.json write would spend the source anchor and put the pin back
+  // on a clock the next re-cut moves.
+  const pinnedDoc = resolveSrcTimingPins(overrideDoc, map);
+  for (const r of pinnedDoc.reports) console.log(`  ⚠ ${r}`);
+  const { cues: editedCues } = applyOverrides(routed.cues, pinnedDoc.doc);
   // Scenes the user deleted in the editor drop here — their windows become
   // plain takes in the fill below, which is Task C's payoff for Task A.
   // `splitThenDropHidden`, not a bare `dropHiddenCues`: this runs before
@@ -3439,10 +3660,31 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // are reported from THIS pass: only now does the id universe include the
   // takes, so a `take-2-1` edit whose take merged away reports here instead
   // of every take id reporting on the first pass.
-  const filled = fillPlainCues(reclamped, {
+  // Kept/dismissed removal edges ride along as extra clipStarts (cut-review
+  // rework, 2026-08-26): a veto merges two kept spans into one, which would
+  // otherwise change the clip count and silently re-target every `take-N`
+  // framing edit after it (§155's misapply class). With the edges preserved,
+  // the fill still cuts where the boundaries were, and `carveKeptTakes`
+  // below owns the revived middle.
+  const keptRangesForCarve = [
+    ...cleanupVetoed.map((seg) => ({ srcIn: seg.srcIn, srcOut: seg.srcOut })),
+    ...cleanupDismissed.map((seg) => ({ srcIn: seg.srcIn, srcOut: seg.srcOut, dismissed: true })),
+  ];
+  const keptEdgeStarts = keptRangesForCarve.flatMap((r) => {
+    const a = map.toOutput(r.srcIn);
+    const b = map.toOutput(r.srcOut);
+    return [...(a !== null ? [a] : []), ...(b !== null ? [b] : [])];
+  });
+  const filled0 = fillPlainCues(reclamped, {
     outputDurationSec: map.outputDuration,
-    clipStarts: map.spans.map((s) => s.outIn),
+    clipStarts: [...map.spans.map((s) => s.outIn), ...keptEdgeStarts],
   });
+  // Revived material as a first-class block — same carve the editor previews
+  // with (`carveKeptTakes`'s one-implementation-two-callers doc), so
+  // `take-kept-*` ids exist server-side and framing edits on them land in
+  // the second override pass below instead of orphaning.
+  const { cues: filled, reports: carveReports } = carveKeptTakes(filled0, keptRangesForCarve, map);
+  for (const r of carveReports) console.log(`  ⚠ ${r}`);
   // User splits (R16 §61) — after the fill so takes split like scenes, and
   // before the final override pass so edits on the `id@<split id>` halves land
   // (the suffix is the split's own minted id, §137, not its time). A
@@ -3451,11 +3693,20 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // is a no-op for that scene (the split point sits exactly on the joint
   // between the two halves, matching neither), so this call stays the one
   // that actually cuts TAKE ids, which don't exist until the fill just ran.
-  const split = splitCues(filled, overrideDoc.splits);
+  // Resolved onto THIS run's clock: `src` (the recut-immune anchor) wins,
+  // src-less legacy entries pass their re-anchored `at` through, and a src
+  // sitting in removed material is inert with a report (resolveSplitPoints'
+  // doc owns the posture).
+  const resolvedSplits = resolveSplitPoints(overrideDoc.splits, map);
+  for (const r of resolvedSplits.reports) console.log(`  ⚠ ${r}`);
+  const split = splitCues(filled, resolvedSplits.points);
   if (overrideDoc.splits.length > 0) {
     console.log(`▸ ${overrideDoc.splits.length} scene split(s) from the edit layer`);
   }
-  const { cues: mergedCues, orphans: rawOrphans } = applyOverrides(split, overrideDoc);
+  // `pinnedDoc.doc` again, not `overrideDoc`: this pass is on the SAME clock
+  // as the first (the split above does not move time), and a src pin that
+  // reached here unresolved would be ignored rather than applied.
+  const { cues: mergedCues, orphans: rawOrphans } = applyOverrides(split, pinnedDoc.doc);
   // Halves of a TAKE the user deleted after splitting: a take id only exists
   // once the fill above runs, so its `id@<split id>` half couldn't have been seen by
   // `splitThenDropHidden` earlier (that pass only ever saw graphic scenes).
@@ -3686,7 +3937,11 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     scenes: scenes.length > 0 ? scenes : undefined,
     producer: producerStamp,
     theme,
-    render: { ...frame, fps: 30 },
+    // The EFFECTIVE output size, not the base frame (`--resolution`): this is
+    // what the file on disk actually is, and it is read downstream by the
+    // mezzanine's scale decision, the NLE exports and the editor — all of
+    // which would otherwise describe a 1080p file that isn't there.
+    render: { width: output.width, height: output.height, fps: 30 },
   };
   await writeFile(join(work, "production.json"), JSON.stringify(production, null, 2));
 
@@ -3821,7 +4076,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // by name below, and a run that cannot anchor one today is not permission to
   // delete it — the next run, against a different cut, may place it (final
   // review, Critical 1).
-  const captionWork = reconcileCaptionEdits(overrideDoc, baseCaptionLines);
+  const captionWork = reconcileCaptionEdits(overrideDoc, baseCaptionLines, map);
   overrideDoc = captionWork.doc;
   const captionLines = captionWork.lines;
   const captionKeysReanchored = captionWork.reanchored;
@@ -4155,6 +4410,71 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     );
   }
 
+  // ---- Cover overlay on the opening frames (`--cover-in-video`) -----------
+  // Resolved and staged HERE, next to the props it feeds, the watermark's
+  // posture: one ▸ line when it is on, so a config-sourced overlay never
+  // surprises the author on upload.
+  //
+  // THE STAGED FILE IS THE CURRENT COVER AT RENDER TIME, and that is the
+  // whole state model: this run's own cover has not been rendered yet
+  // (produce writes it after the video, from the finished render's own
+  // geometry), so what gets copied is the cover the project has RIGHT NOW —
+  // the one `ossclip cover`, the editor's regenerate button, or the previous
+  // produce left behind, resolved down the panel's own ladder
+  // (`coverInVideoCandidates`). A regenerated cover therefore lands in the
+  // NEXT render and preview with no extra plumbing, exactly like a headline
+  // edit in `cover.json`. A project with no cover on disk at all (the first
+  // ever run) gets one ⚠ line and NO prop — an absent key is the
+  // absent-means-off contract, so the render is byte-identical to an
+  // overlay-less one rather than half-wired.
+  //
+  // Staged into the render's public dir AND the workdir when they differ, for
+  // the Nastaliq font's reason verbatim: the render bundles
+  // `dirname(renderVideo)`, `ossclip edit` serves the workdir at `/media/`,
+  // and both mounts fetch the same name.
+  const coverInVideoOn = resolveCoverInVideo(opts.coverInVideo, cfg.coverInVideo);
+  let coverInVideo: { fileName: string; durationSec: number } | undefined;
+  if (coverInVideoOn) {
+    const candidates = coverInVideoCandidates({
+      provenanceOut: (await readCoverProvenance(work))?.out,
+      outPath,
+    });
+    const source = candidates.find((p) => existsSync(p));
+    if (source === undefined) {
+      // Deliberately does NOT promise this run's cover: `--no-cover` may mean
+      // there will not be one, and a produce that says "next time" and then
+      // never delivers is worse than one that names what it looked for.
+      console.log(
+        `  ⚠ cover in video: no cover image yet (looked for ` +
+          `${candidates.join(", ")}) — no overlay this run; ` +
+          `it uses the cover a previous run or \`ossclip cover\` leaves behind`,
+      );
+    } else {
+      const fileName = coverInVideoFileName(source);
+      for (const dir of new Set([renderPublicDirPath, work])) {
+        // `join` on the filesystem side where `fileName` itself stays
+        // POSIX-literal — these are paths, that is a served URL (the
+        // Nastaliq staging's exact split).
+        const dest = join(dir, fileName);
+        mkdirSync(dirname(dest), { recursive: true });
+        copyFileSync(source, dest);
+      }
+      // The window is derived from the OUTPUT clock's first word — the same
+      // caption words the renderer draws, post-cut (core's coverInVideoWindow
+      // owns the bounds). The first line WITH words, not `captionLines[0]`:
+      // an empty leading line would read as "no speech" and take the cap.
+      const durationSec = coverInVideoWindow(
+        captionLines.find((l) => l.words.length > 0)?.words ?? [],
+        { capSec: COVER_IN_VIDEO_CAP_SEC, floorSec: COVER_IN_VIDEO_FLOOR_SEC },
+      );
+      coverInVideo = { fileName, durationSec };
+      console.log(
+        `▸ cover in video: ${basename(source)} over the first ${durationSec.toFixed(2)}s` +
+          `${opts.coverInVideo === undefined ? " (from config; --no-cover-in-video overrides)" : ""}`,
+      );
+    }
+  }
+
   const props = {
     videoFileName: basename(renderVideo),
     spans: [...map.spans],
@@ -4175,7 +4495,15 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // ~/.ossclip/config.json's theme the first time anyone touched a color.
     baseTheme: configBaseTheme,
     baseCaptionLines,
-    settings: production.render,
+    // The COMPOSITION's size, which is the BASE frame — never
+    // `production.render` (2026-08-27). `production.render` describes the
+    // FILE, and under `--resolution` those differ by the render's `scale`:
+    // Remotion enlarges this composition by that factor, so sizing the
+    // composition from the scaled dims applies it TWICE (2160×3840 became
+    // 4320×7680 frames, which h264_videotoolbox refuses outright, at stitch
+    // time, after every frame had been paid for). The Player reads these too,
+    // and previewing at the base size is what keeps the editor cheap.
+    settings: { ...frame, fps: production.render.fps },
     outputDurationSec: map.outputDuration,
     // The aspect travels with the measurement because the crop math needs it:
     // `object-fit: cover` spills vertically for a portrait source and
@@ -4269,6 +4597,11 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     // an off run's render-props.json stays byte-identical to a pre-watermark
     // one, so nothing downstream can tell the feature ever shipped.
     ...(watermark ? { watermark: true } : {}),
+    // Written only when the overlay is BOTH switched on and backed by a file
+    // that exists (the staging block above): absent means no overlay, so an
+    // off run's render-props.json — and its rendered pixels — stay identical
+    // to a pre-feature one.
+    ...(coverInVideo ? { coverInVideo } : {}),
     // Same absent-means-default contract, polarity flipped (captions default
     // ON): written only when hidden, so a normal run's render-props.json
     // stays byte-identical to a pre-feature one. `captionsHiddenByFlag` is
@@ -4335,7 +4668,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // right in memory but wrong on disk, and every re-keyed entry was just
   // printed by name. It does NOT spend the `.bak` — the remap moves keys, it
   // rewrites no values a user would need to recover.
-  if (cutResult.changed || captionKeysReanchored || hidesPruned || sceneKeysRemapped) {
+  // `splitSrcResolved` joins for the sceneKeysRemapped reason: the source
+  // anchor exists in memory but not on disk, and skipping the write would
+  // re-resolve (and re-announce) it every run. It does NOT spend the `.bak`
+  // — backfilling adds an anchor, it rewrites no value a user would need to
+  // recover.
+  if (cutResult.changed || captionKeysReanchored || hidesPruned || sceneKeysRemapped || splitSrcResolved) {
     await writeOverrideDoc(overridesPath, overrideDoc, { refreshBackup: cutResult.changed });
     console.log(overridesWriteLine(cutResult.changed));
   }
@@ -4417,6 +4755,9 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // Jump-cuts pin: the RESOLVED mode, but only its typed states reach the
   // argv — "auto" has no flag spelling and stays unpinned (see
   // recordedProduceArgs for why that is safe today).
+  // Cover-overlay pin: the watermark's config-dependent-default rationale
+  // again, on the flag that paints the first frames — an unpinned record
+  // would gain or lose the overlay under a later `coverInVideo` config edit.
   // Youtube pin: the watermark's config-dependent-default rationale exactly —
   // resolved both ways, so a later config edit can't flip what Render
   // replays. Portrait and dictionary pin the RESOLVED values (a path and
@@ -4430,6 +4771,13 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     llmEffort,
     clipWindow: clipWindow ? `${clipWindow.startWord}:${clipWindow.endWord}` : undefined,
     watermark,
+    // The SWITCH's resolved state (`coverInVideoOn`), not "did an overlay
+    // actually happen": a run whose cover was simply missing yet still
+    // records `--cover-in-video` is correct — the pin exists so the replay
+    // resolves the same way this run did, and by then the cover may well be
+    // on disk. Same distinction the captions pin draws between the flag and
+    // the editor's override.
+    coverInVideo: coverInVideoOn,
     captions: opts.captions ?? true,
     jumpCuts: jumpCutsMode,
     dictionary,
@@ -4662,6 +5010,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         outPath: rawPath,
         browserExecutable: cfg.browserExecutable,
         concurrency: renderConcurrency.concurrency,
+        // The composition stays 1080-wide and Remotion renders it larger
+        // (`--resolution`) — rebuilding the stage at 2160 would keep
+        // `captionFontSizeFor`'s absolute 64px and draw quarter-size captions.
+        scale: output.scale,
         cancelSignal: renderCancel.cancelSignal,
         onPhase: (phase: RenderPhase) => {
           signalPhase = renderSignalPhaseOf(phase);