ossclip 0.1.30 → 0.1.33

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,
@@ -23,8 +23,12 @@ import {
   analyze,
   applyOverrides,
   applyRepairs,
+  isParkedOverrideKey,
+  parkedOverrideBaseKey,
+  remapSceneOverrides,
   assembleScenes,
   buildCaptionLines,
+  captionPackingFor,
   buildCutlist,
   canonicalizeDictionaryCasing,
   captionsNeedNastaliq,
@@ -42,6 +46,9 @@ import {
   COVER_PROVENANCE_BASENAME,
   coverDecision,
   coverHeadline,
+  coverInVideoWindow,
+  COVER_IN_VIDEO_CAP_SEC,
+  COVER_IN_VIDEO_FLOOR_SEC,
   readCoverProvenance,
   writeCoverProvenance,
   cropFilter,
@@ -94,6 +101,10 @@ import {
   thumbnailImageCacheName,
   applyCleanupChoices,
   vetoedRemovals,
+  dismissedRemovals,
+  carveKeptTakes,
+  resolveSplitPoints,
+  resolveSrcTimingPins,
   applyUserCuts,
   pruneHidesInsideCuts,
   loadConfig,
@@ -610,6 +621,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
@@ -689,6 +709,66 @@ export function resolveWatermark(
   return flag ?? configValue === true;
 }
 
+/**
+ * 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
@@ -1631,14 +1711,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) => {
@@ -1894,6 +1970,20 @@ export function layoutSlotAspects(frame: {
   });
 }
 
+/**
+ * One orphaned scene edit, one honest sentence. A parked key (`…#orphaned`,
+ * handoff-edit-anchoring) matches no cue BY DESIGN, so it surfaces in
+ * `applyOverrides`' orphan list on every run — and "dropped" would tell the
+ * user an edit is gone while the doc still holds it, anchor intact, waiting
+ * for a plan that has its words again. Pure so both sentences are testable
+ * without a produce run.
+ */
+export function orphanEditLine(id: string): string {
+  return isParkedOverrideKey(id)
+    ? `  ⚠ edit for ${parkedOverrideBaseKey(id)} is parked — its words are not in this plan`
+    : `  ⚠ edit for ${id} dropped — the plan no longer has that scene`;
+}
+
 async function preflight(bin: string, hint: string): Promise<void> {
   try {
     await run(bin, ["-version"], { allowNonZero: true });
@@ -3115,10 +3205,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
@@ -3147,6 +3248,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 ` +
@@ -3180,6 +3301,24 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   const { cues: assembled, dropped } = assembleScenes(scenes, transcript, map);
   for (const d of dropped) console.log(`  ⚠ scene ${d.id} dropped: ${d.reason}`);
 
+  // Re-key scene edits whose positional id no longer means the moment they
+  // were made on (handoff-edit-anchoring; §137 is the caption precedent — in
+  // the field, scene-4 was a TerminalMock in one plan and a FlowDiagram in
+  // the next, and the user's edit landed on the impostor). Placed HERE,
+  // before ANY consumer of `overrideDoc.scenes`: the first `applyOverrides`
+  // pass, `splitThenDropHidden` and the pinned-timing reclamp all join by id,
+  // and a stale key at any of them bakes the misapply this plan exists to
+  // kill — a `hidden` on a renumbered scene would hide the impostor, not the
+  // moved moment. `assembled` is enough for the match: the remap reads only
+  // anchored graphic cues, and take ids (which don't exist until the fill)
+  // carry no anchors and are left untouched by design. Notes are non-empty
+  // exactly when the doc changed, which is what earns the write-back its
+  // turn at the sanctioned write below.
+  const sceneRemap = remapSceneOverrides(overrideDoc, assembled);
+  overrideDoc = sceneRemap.doc;
+  for (const n of sceneRemap.notes) console.log(`  ▸ ${n}`);
+  const sceneKeysRemapped = sceneRemap.notes.length > 0;
+
   // ---- Framing plan → props (2026-08-16 incident) --------------------------
   // The plan used to be BAKED here: every window cropped, scaled and
   // re-encoded into a content-<hash>.mp4 that replaced the source for the
@@ -3367,7 +3506,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
@@ -3404,10 +3552,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
@@ -3416,11 +3585,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).
@@ -3438,7 +3616,7 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     console.log(`▸ applied your edits to ${editedCount - orphans.length - hiddenIds.length} scene(s)`);
   }
   for (const id of orphans) {
-    console.log(`  ⚠ edit for ${id} dropped — the plan no longer has that scene`);
+    console.log(orphanEditLine(id));
   }
 
   const graphicCues = sceneCues.filter((c) => c.kind !== "plain");
@@ -3786,7 +3964,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;
@@ -4120,6 +4298,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],
@@ -4234,6 +4477,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
@@ -4295,7 +4543,17 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // re-report "the cut removed it" on every later run. It does NOT spend the
   // `.bak` — retiring a redundant key is not the cut re-anchoring the backup
   // exists to survive.
-  if (cutResult.changed || captionKeysReanchored || hidesPruned) {
+  // `sceneKeysRemapped` joins for the caption-migration reason: a scene edit
+  // that followed its anchor to a new id (handoff-edit-anchoring) is keyed
+  // 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.
+  // `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));
   }
@@ -4377,6 +4635,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
@@ -4390,6 +4651,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,

package/src/program.ts

@@ -10,6 +10,7 @@ import { ExportFormatSchema, runAnalyze } from "./analyze";
 import { expandHome } from "./paths";
 import { phaseBucketProps } from "./phase-timing";
 import { dictionaryFlag, jumpCutsFlag, produce, reviewFlag } from "./produce";
+import { accountsFlag, atFlag, platformsFlag } from "./publish";
 // The one interactive import that is STATIC rather than `await import()`: the
 // `resetInputSource()` run boundary in `buildProgram` has to run synchronously
 // while the program is being built, and `buildProgram` cannot await. The graph
@@ -406,6 +407,19 @@ export function buildProgram(): Command {
     .option("--no-watermark", "no wordmark, even when the config turns it on")
     // Same tri-state shape as --watermark above (positive declared first so
     // commander's default stays undefined = "not typed"): the config's
+    // `coverInVideo` key supplies the default (resolveCoverInVideo), and a
+    // typed --no-cover-in-video still beats a config-on. A separate key from
+    // --cover/--no-cover, which is about WRITING the cover file at all.
+    .option(
+      "--cover-in-video",
+      "overlay the cover image on the video's first frames, for the platforms that ignore " +
+        "an uploaded cover and use frame 1. Nothing is inserted — the overlay ends at the " +
+        "first spoken word (max 0.5s), so no timing moves " +
+        "(set it once with coverInVideo: true in ~/.ossclip/config.json)",
+    )
+    .option("--no-cover-in-video", "no cover overlay, even when the config turns it on")
+    // Same tri-state shape as --watermark above (positive declared first so
+    // commander's default stays undefined = "not typed"): the config's
     // `youtube` key supplies the default (resolveYoutube), and a typed
     // --no-youtube still beats a config-on.
     .option(
@@ -644,6 +658,9 @@ export function buildProgram(): Command {
           zoom: opts.zoom,
           // undefined = "not typed", so produce can let the config decide.
           watermark: opts.watermark,
+          // The watermark's tri-state again, resolved by resolveCoverInVideo
+          // at the use site against the config's `coverInVideo`.
+          coverInVideo: opts.coverInVideo,
           // The same tri-state contract as watermark, resolved by
           // resolveYoutube at the use site; --portrait rides along untyped =
           // undefined so the config's path can supply it.
@@ -991,6 +1008,52 @@ export function buildProgram(): Command {
       });
     });
 
+  program
+    .command("publish")
+    .description(
+      "push the finished render to your social accounts through your own self-hosted " +
+        "Postiz instance — now, or scheduled with --at",
+    )
+    // Optional like `edit`'s and `cover`'s: no argument resolves the run
+    // under the CURRENT directory.
+    .argument("[workdir]", "a work directory, or the folder you produced in")
+    .option(
+      "--at <iso>",
+      "schedule instead of publishing now — an ISO-8601 time in the future " +
+        "(e.g. 2026-09-01T08:00:00+02:00)",
+      // Wrapped: commander's parseArg passes (value, previous), and atFlag's
+      // second parameter is its injectable clock — not a place for `previous`.
+      (v: string) => atFlag(v),
+    )
+    .option(
+      "--platforms <list>",
+      "only these platforms, comma-separated (linkedin,instagram,tiktok,x,facebook,youtube)",
+      platformsFlag,
+    )
+    .option("--accounts <ids>", "explicit Postiz integration ids, comma-separated (the no-TTY path)", accountsFlag)
+    .option("--all", "every connected account (after --platforms, when both are given)", false)
+    .option("--dry-run", "print the targets and the exact payload; send nothing", false)
+    .option("-y, --yes", "skip the confirmation prompt", false)
+    .option("--force", "publish again even though this workdir already has a publish receipt", false)
+    .action(async (workdir: string | undefined, opts) => {
+      const { runPublish } = await import("./publish");
+      const target = await resolveWorkdirArgument(workdir ?? ".", "publish");
+      await runPublish(target, {
+        at: opts.at,
+        platforms: opts.platforms,
+        accounts: opts.accounts,
+        all: opts.all,
+        dryRun: opts.dryRun,
+        yes: opts.yes,
+        force: opts.force,
+      });
+      telemetry.record("publish_run", {
+        scheduled: opts.at !== undefined,
+        dry_run: opts.dryRun === true,
+      });
+      await telemetry.flush();
+    });
+
   program
     .command("setup")
     .description(