@ossclip/core 0.1.26 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -45,5 +45,72 @@ export {
 // types only). The editor's load-path repair needs the MAP, not the raw span
 // array, to decide whether a repair is possible at all — see
 // `anchorCaptionLines` (§137): a non-empty array can still build an empty map.
-export { mapFromKeptSpans, TimeMap, type KeptSpan } from "./timemap";
-export type { Probe, Production, RenderSettings, Segment, Transcript, Word } from "./schema";
+// `mapsClose` rides along since cut review step 4: the editor's playhead
+// hand-off across a live re-cut needs "did the clock actually change" to be
+// the SAME float-tolerant comparison `livePreviewMap`'s identity gate uses,
+// or a 1-ulp drift could seek the player for nothing.
+export { mapFromKeptSpans, mapsClose, TimeMap, type KeptSpan } from "./timemap";
+// The §35 cover word cap. The editor's CoverPanel shows the trimmed headline
+// live as you type, and restating the trimming rules there would drift from
+// the one the regenerate endpoint actually renders with. Imported from
+// ./cover-headline, NOT ./cover — that module is node all the way down
+// (node:fs, ./exec), which is exactly what this surface exists to keep out.
+export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
+// The cleanup veto layer (cut review step 3), VALUE exports and browser-safe:
+// cutlist.ts imports nothing but types from ./schema — verified before this
+// export, zero node built-ins in its graph. The editor marks vetoed seams
+// with the SAME `applyCleanupChoices` produce renders with (the
+// buildCoverRender one-implementation-two-callers pattern); a browser copy is
+// how the preview and the render would drift. `buildCutlist` itself rides
+// along in the module graph but stays unexported here on purpose — the
+// editor must never rebuild the proposal, only apply choices to the one
+// produce recorded.
+export {
+  applyCleanupChoices,
+  cleanupVetoable,
+  vetoedRemovals,
+  type CleanupChoices,
+} from "./cutlist";
+// The live post-veto preview (cut review step 4), VALUE exports and
+// browser-safe: retime-preview.ts composes cutlist + recut + timemap — all
+// already in this surface's runtime graph (recut.ts imports only overrides
+// and timemap, zero node built-ins, verified before this export). The editor
+// re-cuts its preview clock with the SAME `applyCleanupChoices` +
+// `subtractRangesFromCutlist` sequence produce runs and re-times every prop
+// through the SAME `remapPoint` produce re-anchors with — one implementation,
+// two callers, so the preview cannot drift from the render.
+// `previewClockMappers` rides along (step 4 follow-up): the surfaces that
+// speak in single instants — transcript seeks, ghost bands, the cover
+// panel's playhead — need the same walk as a point function, identity when
+// no re-cut is live, threaded by App so no consumer learns the machinery.
+// `cutRangeToOldClock` is the WRITE direction's range half (the follow-up's
+// follow-up): a cut gesture's live window converted to the old-clock frame
+// `doc.cuts` speaks, shared by the Inspector's button and App's delete
+// modal so the shrink/refuse verdict cannot drift between the two.
+export {
+  cutRangeToOldClock,
+  livePreviewMap,
+  previewClockMappers,
+  retimeForPreview,
+  type LivePreviewClocks,
+  type OldClockCutRange,
+  type PreviewClockMappers,
+  type RetimeablePreviewProps,
+  type RetimedPreviewFields,
+} from "./retime-preview";
+export type {
+  Probe,
+  Production,
+  // `RemovalReason` rides along with `Segment` (cut review step 2): the
+  // editor's reason→colour map is a `Record<RemovalReason, string>` precisely
+  // so a NEW reason in the vocabulary fails typecheck in the editor instead
+  // of silently drawing an uncoloured seam. (Since step 3 the schema module
+  // is in the runtime graph anyway — ./overrides imports RemovalReasonSchema
+  // for the `cleanup` key — but schema.ts is zod + scene-schema only, both
+  // already on this surface, so it stays browser-safe.)
+  RemovalReason,
+  RenderSettings,
+  Segment,
+  Transcript,
+  Word,
+} from "./schema";

package/src/config.ts

@@ -19,6 +19,16 @@ export interface OssclipConfig {
    * sheet always uses the main model. "same" disables tiering (FINDINGS §37).
    */
   fastModel?: string;
+  /**
+   * Reasoning effort for the antigravity provider — low | medium | high,
+   * agy's own `--effort` vocabulary. Consumed ONLY by antigravity today
+   * (§143: exposed after the hang incident — the knob existed and we passed
+   * nothing); every other provider ignores it. `--llm-effort` wins over this
+   * per run. File-only like `dictionary`; validated at the consumer
+   * (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` is one
+   * warning and an ignored key, never a coerced effort level.
+   */
+  llmEffort?: string;
   /**
    * Download URLs for models the ggerganov mirror doesn't host, keyed by the
    * bare model name — a user's own fine-tune needs one line:
@@ -196,6 +206,11 @@ export function loadConfig(): OssclipConfig {
     modelDir: process.env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
     model: process.env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
     fastModel: process.env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
+    // File-only, the `dictionary` posture — and deliberately NO env spelling
+    // (flag + config are the whole interface): validated where it is USED
+    // (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` earns one
+    // warning there and agy's default, never a coerced effort.
+    llmEffort: fileCfg.llmEffort,
     speaker: process.env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
     openEditorAfterProduce: (process.env.OSSCLIP_OPEN_EDITOR ??
       fileCfg.openEditorAfterProduce) as OpenEditorPref | undefined,

package/src/cover-headline.ts

@@ -0,0 +1,68 @@
+/**
+ * The cover banner's word cap, and nothing else.
+ *
+ * Split out of `./cover` (2026-08-19) for the reason `content-rect` is split
+ * from `content-rect-detect`: the EDITOR's cover panel shows the trimmed
+ * headline live as you type, so it needs this function at RUNTIME — and it
+ * imports `@ossclip/core/browser`, whose whole contract is "no node built-ins
+ * anywhere in this module graph". `./cover` is node all the way down
+ * (`node:fs`, `./exec`'s child_process), so re-exporting `coverHeadline` from
+ * there would have put ffmpeg's process runner in the Vite bundle.
+ *
+ * Restating the trimming rules in the editor was the alternative and is
+ * strictly worse: the server re-caps whatever the panel sends, so a second
+ * copy would drift into showing a preview the render disagrees with.
+ *
+ * `./cover` re-exports this file, so `@ossclip/core`'s surface is unchanged.
+ */
+
+/**
+ * A cover banner is a headline, not a sentence (FINDINGS §35). The producer
+ * shipped 13 words across five lines by reusing the video's hook verbatim; at
+ * grid-tile size that is unreadable. The reference covers run 4-9 words.
+ *
+ * Stated in the schema AND enforced here, because a `.describe()` is a request
+ * and this is a constraint — the same reason `normalizeBeatSheet` exists.
+ */
+export const COVER_MAX_WORDS = 9;
+
+/**
+ * Trailing words that cannot end a headline — the truncation reads as broken.
+ * Auxiliaries dangle exactly like prepositions: a real run (2026-08-22)
+ * truncated to "AI Gave Me Too Many Ideas. I Had" because the set had none.
+ * "i" is here for the same incident: popping "Had" alone leaves "…Ideas. I",
+ * a subject with its sentence cut off.
+ */
+const DANGLING = new Set([
+  "a", "an", "and", "as", "at", "but", "by", "for", "from", "in", "is", "it",
+  "of", "on", "or", "the", "to", "with", "that", "this", "my", "your", "so",
+  "had", "has", "have", "was", "were", "will", "can", "should", "i",
+]);
+
+/**
+ * Cut a headline down to `maxWords`, preferring a natural break.
+ *
+ * A dash or colon usually separates a complete claim from its elaboration, so
+ * the first clause is a real headline rather than a sentence with its end
+ * lopped off. Only when that is still too long does this truncate — and then
+ * it refuses to stop on a preposition or article, which is what makes a
+ * truncation look like a bug instead of an edit.
+ */
+export function coverHeadline(text: string, maxWords = COVER_MAX_WORDS): string {
+  const clean = text.trim().replace(/\s+/g, " ");
+  if (!clean) return clean;
+  const words = (s: string): string[] => s.split(" ").filter(Boolean);
+  if (words(clean).length <= maxWords) return clean;
+
+  // First clause, if it stands on its own — never a two-word fragment. Even
+  // when the clause is itself too long it is the better thing to cut down,
+  // since truncating it can never wander past the dash into the elaboration.
+  const clause = clean.split(/\s*[—–:]\s*|\s+-\s+/)[0]!.trim();
+  const base = words(clause).length >= 3 ? clause : clean;
+  const out = words(base).slice(0, maxWords);
+  while (out.length > 3 && DANGLING.has(out[out.length - 1]!.toLowerCase().replace(/\W/g, ""))) {
+    out.pop();
+  }
+  // A clause that ended on its own punctuation keeps it; a cut does not.
+  return out.join(" ").replace(/[,;:—–-]+$/, "");
+}

package/src/cover.ts

@@ -1,5 +1,7 @@
-import { readFile, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { z } from "zod/v4";
 import { run } from "./exec";
 
 /**
@@ -15,49 +17,12 @@ import { run } from "./exec";
  * This module picks WHICH frame. The banner is drawn by the renderer.
  */
 
-/**
- * A cover banner is a headline, not a sentence (FINDINGS §35). The producer
- * shipped 13 words across five lines by reusing the video's hook verbatim; at
- * grid-tile size that is unreadable. The reference covers run 4-9 words.
- *
- * Stated in the schema AND enforced here, because a `.describe()` is a request
- * and this is a constraint — the same reason `normalizeBeatSheet` exists.
- */
-export const COVER_MAX_WORDS = 9;
-
-/** Trailing words that cannot end a headline — the truncation reads as broken. */
-const DANGLING = new Set([
-  "a", "an", "and", "as", "at", "but", "by", "for", "from", "in", "is", "it",
-  "of", "on", "or", "the", "to", "with", "that", "this", "my", "your", "so",
-]);
-
-/**
- * Cut a headline down to `maxWords`, preferring a natural break.
- *
- * A dash or colon usually separates a complete claim from its elaboration, so
- * the first clause is a real headline rather than a sentence with its end
- * lopped off. Only when that is still too long does this truncate — and then
- * it refuses to stop on a preposition or article, which is what makes a
- * truncation look like a bug instead of an edit.
- */
-export function coverHeadline(text: string, maxWords = COVER_MAX_WORDS): string {
-  const clean = text.trim().replace(/\s+/g, " ");
-  if (!clean) return clean;
-  const words = (s: string): string[] => s.split(" ").filter(Boolean);
-  if (words(clean).length <= maxWords) return clean;
-
-  // First clause, if it stands on its own — never a two-word fragment. Even
-  // when the clause is itself too long it is the better thing to cut down,
-  // since truncating it can never wander past the dash into the elaboration.
-  const clause = clean.split(/\s*[—–:]\s*|\s+-\s+/)[0]!.trim();
-  const base = words(clause).length >= 3 ? clause : clean;
-  const out = words(base).slice(0, maxWords);
-  while (out.length > 3 && DANGLING.has(out[out.length - 1]!.toLowerCase().replace(/\W/g, ""))) {
-    out.pop();
-  }
-  // A clause that ended on its own punctuation keeps it; a cut does not.
-  return out.join(" ").replace(/[,;:—–-]+$/, "");
-}
+// The §35 word cap lives in ./cover-headline — this file is node all the way
+// down (node:fs, ./exec's child_process) and the EDITOR's cover panel needs
+// `coverHeadline` at runtime through @ossclip/core/browser, which forbids a
+// node built-in anywhere in its graph. Re-exported here so `@ossclip/core`'s
+// surface is exactly what it was.
+export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
 
 /**
  * What the cover step should emit.
@@ -190,6 +155,56 @@ export interface PickCoverOptions {
   subject?: "face" | "screen";
 }
 
+/**
+ * Measure ONE candidate frame: extract it at `timeSec` through the crop math,
+ * score its sharpness, and locate the face in the cover's own geometry.
+ *
+ * Extracted from `pickCoverFrame`'s sampling loop because `ossclip cover --at
+ * <t>` needs exactly this for a single timestamp. A second implementation of
+ * the cover crop would drift from this one — and a drifted crop puts the
+ * banner against geometry the cover does not have, which is the whole reason
+ * `COVER_CROP_VF` exists rather than face.ts's plain `scale`.
+ *
+ * Returns null on a short read: ffmpeg seeking past the end (or onto a
+ * corrupt packet) writes fewer bytes than the detection frame, and measuring
+ * that is measuring padding.
+ */
+export async function measureCoverFrame(
+  tools: { ffmpegPath: string },
+  videoPath: string,
+  timeSec: number,
+  opts: {
+    cacheDir?: string;
+    cropVf?: string;
+    detectFace?: PickCoverOptions["detectFace"];
+    /** Scratch file name — the sampler keeps one per sample so a crashed run
+     * leaves no ambiguity about which frame it died on. */
+    frameName?: string;
+  } = {},
+): Promise<{ timeSec: number; sharpness: number; hasFace: boolean; face?: CoverFace } | null> {
+  const framePath = join(opts.cacheDir ?? ".", opts.frameName ?? "cover-frame.gray");
+  await run(tools.ffmpegPath, [
+    "-v", "error",
+    "-ss", timeSec.toFixed(3),
+    "-i", videoPath,
+    "-frames:v", "1",
+    "-vf", `${opts.cropVf ? `${opts.cropVf},` : ""}${COVER_CROP_VF}`,
+    "-pix_fmt", "gray",
+    "-f", "rawvideo",
+    "-y", framePath,
+  ]);
+  const pixels = new Uint8Array(await readFile(framePath));
+  await unlink(framePath).catch(() => {});
+  if (pixels.length < DET_W * DET_H) return null;
+  const face = opts.detectFace?.(pixels, DET_W, DET_H) ?? undefined;
+  return {
+    timeSec,
+    sharpness: laplacianVariance(pixels, DET_W, DET_H),
+    hasFace: face !== undefined,
+    face,
+  };
+}
+
 /**
  * Pick the best cover frame from the take: sharp, face present, early.
  *
@@ -217,27 +232,13 @@ export async function pickCoverFrame(
 
   for (let i = 0; i < samples; i++) {
     const t = (window * (i + 0.5)) / samples;
-    const framePath = join(opts.cacheDir ?? ".", `cover-frame-${i}.gray`);
-    await run(tools.ffmpegPath, [
-      "-v", "error",
-      "-ss", t.toFixed(3),
-      "-i", videoPath,
-      "-frames:v", "1",
-      "-vf", `${opts.cropVf ? `${opts.cropVf},` : ""}${COVER_CROP_VF}`,
-      "-pix_fmt", "gray",
-      "-f", "rawvideo",
-      "-y", framePath,
-    ]);
-    const pixels = new Uint8Array(await readFile(framePath));
-    await unlink(framePath).catch(() => {});
-    if (pixels.length < DET_W * DET_H) continue;
-    const face = opts.detectFace?.(pixels, DET_W, DET_H) ?? undefined;
-    raw.push({
-      timeSec: t,
-      sharpness: laplacianVariance(pixels, DET_W, DET_H),
-      hasFace: face !== undefined,
-      face,
+    const measured = await measureCoverFrame(tools, videoPath, t, {
+      cacheDir: opts.cacheDir,
+      cropVf: opts.cropVf,
+      detectFace: opts.detectFace,
+      frameName: `cover-frame-${i}.gray`,
     });
+    if (measured) raw.push(measured);
   }
   if (raw.length === 0) return null;
 
@@ -251,3 +252,122 @@ export async function pickCoverFrame(
   candidates.sort((a, b) => b.score - a.score);
   return candidates[0]!;
 }
+
+// ---- Cover provenance (`<workdir>/cover.json`) ----------------------------
+// Until this file existed, the ONLY thing that survived a cover render was the
+// JPEG: changing a headline therefore meant a full re-render to re-derive the
+// pick. Everything a faithful rebuild needs is recorded here so a regeneration
+// is `renderCover` against a still that is already on disk.
+
+/** The file the workdir keeps its cover provenance in. */
+export const COVER_PROVENANCE_BASENAME = "cover.json";
+
+/**
+ * Annotated as `z.ZodType<CoverFace>` so the persisted shape and the in-memory
+ * one cannot drift apart silently — adding a fraction to `CoverFace` without
+ * adding it here is then a compile error, not a field that quietly stops
+ * round-tripping.
+ */
+const CoverFaceSchema: z.ZodType<CoverFace> = z.object({
+  centerXFrac: z.number(),
+  centerYFrac: z.number(),
+  sizeFrac: z.number(),
+});
+
+export const CoverProvenanceSchema = z.object({
+  version: z.literal(1),
+  /** The banner text as SHIPPED — already through `coverHeadline`, and "" for
+   * the §34 case where the frame carried its own title. What was rendered,
+   * not what was proposed. */
+  text: z.string(),
+  /** "user" means a headline someone typed, which a later produce must not
+   * quietly overwrite with a fresh beat sheet's `coverText`. */
+  textSource: z.enum(["beatsheet", "user"]),
+  frame: z.object({
+    /** Which video the still came from: the finished render or the source. */
+    source: z.enum(["final", "source"]),
+    timeSec: z.number(),
+    /**
+     * The load-bearing field. This is the COVER-CROP geometry — deliberately
+     * NOT face.json's source-geometry measurement (see the `COVER_CROP_VF`
+     * doc comment for why the two are different numbers). Without it nothing
+     * can place the banner where the shipped cover placed it, and re-deriving
+     * it costs an ffmpeg extraction plus a cascade sweep. That single fact is
+     * what forced this whole file to exist.
+     */
+    face: CoverFaceSchema.nullable(),
+    hasFace: z.boolean(),
+    sharpness: z.number(),
+    /** The still already on disk in the workdir (`cover-frame.png`) — a
+     * text-only regeneration reuses it verbatim and runs no ffmpeg at all. */
+    fileName: z.string(),
+    /**
+     * The ORIGINAL TAKE, and nothing else. Workdir-relative when the video
+     * lives in the workdir (a folder run's `mezzanine.mp4`), absolute
+     * otherwise: a workdir that moved must still resolve its own
+     * intermediates.
+     *
+     * Nullable, and never overwritten by a regeneration (2026-08-19): this
+     * field once recorded "whichever video the current frame was read from",
+     * so one `ossclip cover` on its default `--from final` rewrote a
+     * `mezzanine.mp4` here into the FINISHED render's path — after which
+     * `--from source` silently re-cut the cover from the finished video,
+     * burned-in captions, graphics and watermark included, while telling the
+     * user it was reading the clean source. It also destroyed the only
+     * on-disk record of where the take lives. `frame.source` already says
+     * which video the current still came from, so this one has no second
+     * job. Null means the take is genuinely unknown (a first regeneration off
+     * the final video, with no prior provenance) — `--from source` then says
+     * so instead of lying.
+     */
+    sourceVideo: z.string().nullable(),
+    /** produce's `cropFilter(detection.uniform)`, and the SOURCE's — it is
+     * meaningless against a final-video frame, so it travels with
+     * `sourceVideo` under the same preserve-never-overwrite rule. Persisted
+     * because it is NOT reconstructible from anything else on disk: the
+     * letterbox detection that produced it is cached per source, and
+     * re-picking a frame without it frames two-thirds baked-in black bar. */
+    cropVf: z.string().nullable(),
+  }),
+  /** The OUTPUT frame the cover belongs to (R16 §76) — a landscape render
+   * gets a landscape cover, and a rebuild must not revert to 1080×1920. */
+  size: z.object({ width: z.number(), height: z.number() }),
+  /** Absolute path of the written `.cover.jpg`. */
+  out: z.string(),
+});
+
+export type CoverProvenance = z.infer<typeof CoverProvenanceSchema>;
+
+/**
+ * Read `<work>/cover.json`, or null when it is absent, corrupt, or fails the
+ * schema. Never throws: a pre-feature workdir has no such file at all, and a
+ * half-written one must degrade to "re-pick the frame" rather than brick the
+ * command — the same GET-path posture as `readApprovedConcept`.
+ */
+export async function readCoverProvenance(work: string): Promise<CoverProvenance | null> {
+  const path = join(work, COVER_PROVENANCE_BASENAME);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = CoverProvenanceSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write `<work>/cover.json` atomically: tmp file, then rename.
+ *
+ * The editor and a `ossclip cover` run may read this at any moment, and a
+ * half-written document would be worse than a stale one — the same reasoning
+ * as the overrides save in edit.ts.
+ */
+export async function writeCoverProvenance(
+  work: string,
+  provenance: CoverProvenance,
+): Promise<void> {
+  const path = join(work, COVER_PROVENANCE_BASENAME);
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, JSON.stringify(provenance, null, 2));
+  await rename(tmp, path);
+}

package/src/cutlist.ts

@@ -329,3 +329,112 @@ export function buildCutlist({
 
   return segments;
 }
+
+/**
+ * The user's veto layer over the automatic cutlist (cut review step 3):
+ * `buildCutlist` PROPOSES removals, this is how the user DECLINES some of
+ * them — per category ("keep all pauses") and per individual span. Persisted
+ * as `overrides.json`'s `cleanup` key (`OverrideDocSchema.cleanup`, which
+ * owns the on-disk contract); this structural interface is what the pure
+ * functions below accept, so this module stays free of zod and of the
+ * overrides module — callable from produce AND from the editor bundle with
+ * nothing but the schema's own types.
+ */
+export interface CleanupChoices {
+  /**
+   * Category master switches. `false` = do not remove this reason's spans;
+   * absent (or a tolerated `true` on disk) = the default, remove as proposed.
+   */
+  reasons?: Partial<Record<RemovalReason, boolean>>;
+  /** Individual vetoes, SOURCE seconds — see `vetoedRemovals` for the
+   * overlap-based matching rule. */
+  kept?: readonly { srcIn: number; srcOut: number }[];
+}
+
+/**
+ * Whether a removal reason CAN be declined at all. `user` cuts come from the
+ * `cuts[]` array — declining your own cut is Restore on the cut, an existing
+ * gesture, and a second way to undo it would leave the entry behind as dead
+ * weight (there is no "not cut" state for a `cuts` entry to hold, per its
+ * schema comment). `clip` is the `--clip` window, a selection decision, not a
+ * cleanup — "keeping" a clip removal would silently un-clip the video. One
+ * predicate, exported, so produce, the panel's checkboxes and the timeline's
+ * seam handler cannot disagree about what is toggleable.
+ */
+export function cleanupVetoable(reason: RemovalReason | undefined): boolean {
+  return reason !== "user" && reason !== "clip";
+}
+
+/**
+ * The `remove` spans of `cutlist` that `choices` declines — the shared
+ * predicate under `applyCleanupChoices` (which re-keeps exactly these) and
+ * the editor's vetoed-seam state / produce's "kept N pause removal(s)" line
+ * (which both NAME them). One list, computed once, so what the seam shows as
+ * "will be kept" and what the render actually keeps cannot drift.
+ *
+ * Individual vetoes match by OVERLAP, deliberately NOT by float equality of
+ * endpoints: a re-produce can shift a removal's boundary by a frame (a
+ * changed silence threshold, a repair that re-stamps a word), and an
+ * exact-match veto that silently stops matching is the failure mode — the
+ * pause the user declined would quietly start being cut again. A partial
+ * overlap re-keeps the WHOLE removal span: a removal is one decision, not
+ * divisible.
+ */
+export function vetoedRemovals(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  if (!choices) return [];
+  const kept = choices.kept ?? [];
+  return cutlist.filter(
+    (seg) =>
+      seg.kind === "remove" &&
+      cleanupVetoable(seg.reason) &&
+      ((seg.reason !== undefined && choices.reasons?.[seg.reason] === false) ||
+        kept.some((k) => k.srcIn < seg.srcOut && k.srcOut > seg.srcIn)),
+  );
+}
+
+/**
+ * Apply the user's cleanup choices to the automatic cutlist: every vetoed
+ * removal (see `vetoedRemovals`) becomes a keep again, and adjacent keeps
+ * merge so the result stays the same canonical shape `buildCutlist` emits —
+ * a full partition of the input's range with no gaps, no overlaps, monotonic
+ * (the invariants `TimeMap`'s constructor checks). The partition holds BY
+ * CONSTRUCTION: spans are only relabelled and merged, never moved, so the
+ * covered range cannot change.
+ *
+ * `undefined`/empty choices return the input content unchanged — the
+ * regression anchor: an overrides.json with no `cleanup` key must produce a
+ * byte-identical render.
+ *
+ * ONE implementation, two callers (the `buildCoverRender` pattern): produce
+ * calls this between `buildCutlist` and the `TimeMap`; the editor calls it
+ * (via `@ossclip/core/browser`) to mark vetoed seams. A preview that
+ * disagrees with the render is worse than no preview.
+ */
+export function applyCleanupChoices(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  const vetoed = new Set(vetoedRemovals(cutlist, choices));
+  if (vetoed.size === 0) return [...cutlist];
+  const out: Segment[] = [];
+  for (const seg of cutlist) {
+    // A re-kept span drops `reason`/`confidence` — they described a removal
+    // that is no longer happening, and a keep carrying "pause" would read as
+    // a seventh segment kind everywhere the partition is consumed.
+    const next: Segment = vetoed.has(seg)
+      ? { srcIn: seg.srcIn, srcOut: seg.srcOut, kind: "keep" }
+      : seg;
+    const prev = out[out.length - 1];
+    if (prev !== undefined && prev.kind === "keep" && next.kind === "keep") {
+      // Merge in place — `prev` is always this function's own object (pushed
+      // below as a fresh literal when it is a keep), never the caller's.
+      prev.srcOut = next.srcOut;
+      continue;
+    }
+    out.push(next.kind === "keep" ? { srcIn: next.srcIn, srcOut: next.srcOut, kind: "keep" } : next);
+  }
+  return out;
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./concat";
 export * from "./transcribe";
 export * from "./analyze";
 export * from "./cutlist";
+export * from "./retime-preview";
 export * from "./clip";
 export * from "./blooper";
 export * from "./retake";

package/src/overrides.ts

@@ -7,6 +7,7 @@ import {
   type SceneComponentId,
   type Theme,
 } from "./scene-schema";
+import { RemovalReasonSchema } from "./schema";
 import { resolveSceneProps } from "./scene-registry";
 import type { CaptionLine, CaptionWord } from "./captions";
 
@@ -435,6 +436,42 @@ export const OverrideDocSchema = z.object({
       }),
     )
     .default([]),
+  /**
+   * The user's VETO over the automatic cutlist (cut review step 3). `cuts`
+   * above is the user ADDING a removal; this is the user DECLINING one the
+   * pipeline proposed — opposite directions, deliberately not merged.
+   * Consumed by `applyCleanupChoices` (cutlist.ts, which owns the matching
+   * semantics), in produce and in the editor alike.
+   *
+   * `reasons` are the category master switches ("keep all pauses"). Only
+   * `false` is ever WRITTEN — a `true` entry restates the default, and the
+   * editor DELETES the key instead (the `hidden`/`captionsHidden` rule: an
+   * override with nothing to say). A `true` on disk is still parsed and
+   * means default, tolerantly. `user` and `clip` keys parse but are inert
+   * (`cleanupVetoable`): declining your own cut is Restore on the cut, and
+   * "keeping" the --clip window's removal would silently un-clip the video.
+   *
+   * `kept` are individual vetoes, in SOURCE seconds — and that anchoring is
+   * the whole trick, same as `cuts[].src` above: a bare output-seconds pair
+   * is meaningless once its own re-cut has happened, while source time is
+   * stable across every re-cut. This layer is therefore RECUT-IMMUNE BY
+   * CONSTRUCTION and — unlike `splits` and `scenes[*].timing` — needs NO
+   * entry in `remapOverridesThroughRecut`. Matching against the (possibly
+   * re-produced) cutlist is by OVERLAP, never float equality of endpoints;
+   * `vetoedRemovals` (cutlist.ts) states why.
+   *
+   * Optional-with-default like `splits`/`cuts`, so every overrides.json
+   * written before the key existed parses byte-identically; absent means
+   * today's behaviour exactly.
+   */
+  cleanup: z
+    .object({
+      reasons: z.partialRecord(RemovalReasonSchema, z.boolean()).default({}),
+      kept: z
+        .array(z.object({ srcIn: z.number().nonnegative(), srcOut: z.number().nonnegative() }))
+        .default([]),
+    })
+    .default({ reasons: {}, kept: [] }),
 });
 export type OverrideDoc = z.infer<typeof OverrideDocSchema>;