@ossclip/core 0.1.6 → 0.1.9

package/src/overrides.ts

@@ -23,6 +23,19 @@ export const ElementTransformSchema = z.object({
   dx: z.number().optional(),
   dy: z.number().optional(),
   scale: z.number().positive().optional(),
+  /**
+   * The element is deleted — SOFTLY (PLAN Task 2, one level down from
+   * `SceneOverrideSchema.hidden` below): `editStyle`
+   * (packages/scenes/src/editable.ts) suppresses it at the one chokepoint
+   * every component's leaf renders its edit style through, so no
+   * per-component change is needed and the remaining siblings close the
+   * gap on their own — the same delete semantics a whole SCENE gets,
+   * scoped to one of its elements. The backing array
+   * (`props.messages`/`lines`/`nodes`/`items`) is never touched — ids are
+   * positional, so hiding `message-1` can't renumber `message-2` out from
+   * under its own edits.
+   */
+  hidden: z.boolean().optional(),
 });
 export type ElementTransform = z.infer<typeof ElementTransformSchema>;
 
@@ -169,6 +182,51 @@ export const OverrideDocSchema = z.object({
    * split lands on graphic cues and takes alike.
    */
   splits: z.array(z.number().nonnegative()).default([]),
+  /**
+   * User cuts — ranges of the OUTPUT to remove, in the output seconds of the
+   * CURRENT render-props (what the user saw when they cut) (PLAN 2026-08-04
+   * Task 4). Optional-with-default like `splits` above, so an `overrides.json`
+   * written before this field existed still parses unchanged. Consumed by
+   * `produce.ts` (subtracted from the automatic cutlist's keep-spans) and by
+   * `recut.ts`'s `remapOverridesThroughRecut`, which re-anchors every OTHER
+   * absolute-output-seconds value in this doc through the resulting re-cut —
+   * see that module's docstring for why a bare "shift everything after the
+   * cut point" is not the actual rule.
+   *
+   * `src` (review fix wave, PLAN 2026-08-04 Task 4): a cut's `startSec`/
+   * `endSec` alone are meaningless without knowing WHICH render-props they
+   * were drawn against — a bare output-seconds pair has no faithful
+   * representation once its own cut has happened (Task 4b's Bug A: remapping
+   * it through the very recut it caused collapses it to a zero-width point).
+   * `src` is the cut's resolved SOURCE-time range, computed once — the first
+   * produce run that sees a `src`-less cut resolves it against the
+   * render-props the user was looking at, and the write-back records it here
+   * — and used directly, unconverted, on every run after that. `startSec`/
+   * `endSec` are left exactly as the user drew them even once `src` exists:
+   * a historical record of what render-props they were looking at, never
+   * authoritative again once `src` is present.
+   *
+   * The editor (PLAN 2026-08-04 Task 4c) MUST NEVER WRITE OR
+   * PRESERVE-AND-MODIFY `src` ITSELF — resolving it is produce's job alone.
+   * Creating a cut writes ONLY `{startSec, endSec}`; if a cut's range is
+   * ever edited/moved (not currently exposed, but the rule holds for any
+   * future gesture that would), its `src` is DELETED rather than carried
+   * forward, so the next produce re-resolves it against the render-props
+   * current at that point rather than an anchor drawn for a range that no
+   * longer means the same thing; Restore removes the WHOLE entry, `src`
+   * included — there is no "not cut" state for one array entry to hold.
+   */
+  cuts: z
+    .array(
+      z.object({
+        startSec: z.number().nonnegative(),
+        endSec: z.number().nonnegative(),
+        src: z
+          .object({ startSec: z.number().nonnegative(), endSec: z.number().nonnegative() })
+          .optional(),
+      }),
+    )
+    .default([]),
 });
 export type OverrideDoc = z.infer<typeof OverrideDocSchema>;
 
@@ -364,6 +422,33 @@ export function dropHiddenCues(cues: readonly SceneCue[], doc: OverrideDoc): Dro
   return { cues: out, hidden };
 }
 
+/**
+ * Split at the stored split points BEFORE dropping hidden cues (PLAN
+ * 2026-08-04 Task 1, bug 3).
+ *
+ * `dropHiddenCues` matches by the EXACT id the user deleted, and a split
+ * root's `hidden` is meant to apply only to "the root's own post-split
+ * segment (the half that still carries the bare id)" per `effectiveOverride`
+ * above — but `produce.ts` and the editor's live memo both called
+ * `dropHiddenCues` on the ROOT cues, before `splitCues` had run. That erased
+ * the ENTIRE pre-split window (both halves at once); the plain fill then
+ * covered it with one take, and the later `splitCues` call cut that PLAIN
+ * take into two plain pieces — killing the graphic on the half the user
+ * never asked to delete (field case: `scene-6` deleted, `scene-6@36400` died
+ * with it). Splitting first means a hidden root id only ever matches the
+ * post-split cue that kept the bare id, exactly the exception
+ * `effectiveOverride` already promises. Safe to call again after the fill's
+ * own `splitCues` pass — re-splitting at a boundary that already exists is a
+ * no-op (the split point sits exactly on the joint, so neither piece's
+ * window contains it).
+ */
+export function splitThenDropHidden(
+  cues: readonly SceneCue[],
+  doc: OverrideDoc,
+): DropHiddenResult {
+  return dropHiddenCues(splitCues(cues, doc.splits), doc);
+}
+
 export interface AppliedCaptionEdits {
   lines: CaptionLine[];
   /** Edits whose guard failed — the word at that index is not what they knew. */
@@ -434,6 +519,43 @@ export function clearElementTransform(
   return { ...doc, scenes: { ...doc.scenes, [sceneId]: { ...scene, elements: rest } } };
 }
 
+/**
+ * Un-hide ONE element: DELETE only the `hidden` key (PLAN Task 2), so a
+ * nudge/scale made before the delete survives the restore — the
+ * element-level mirror of `restoreScene`'s "delete the key, don't write a
+ * false-ish value" rule below. `clearElementTransform` above stays the FULL
+ * reset (nudges included); this is the narrower "bring it back as it was"
+ * gesture the element panel's Restore button offers.
+ */
+export function restoreElement(
+  doc: OverrideDoc,
+  sceneId: string,
+  elementId: string,
+): OverrideDoc {
+  const scene = doc.scenes[sceneId];
+  const entry = scene?.elements[elementId];
+  if (!scene || !entry?.hidden) return doc;
+  const { hidden: _dropped, ...rest } = entry;
+  // `elements` merges per ID, not per FIELD (`effectiveOverride` above:
+  // `elements: { ...base.elements, ...own.elements }` replaces a shared id
+  // WHOLESALE, unlike `video`/`pip`, which merge field by field). Review
+  // fix wave, PLAN Task 2: a half whose own entry was ONLY `{hidden:true}`
+  // would otherwise be left with the empty leftover `{}` once `hidden` is
+  // stripped — and that empty object still wins the wholesale merge,
+  // permanently shadowing whatever nudge the split ROOT had for this id,
+  // even though "restore keeps nudges" is exactly this function's promise.
+  // Dropping the key entirely once nothing but `hidden` was ever on it lets
+  // the root's own entry (if any) show through again — same "delete rather
+  // than leave an inert key" instinct as clearVideo/clearTiming.
+  const { [elementId]: _own, ...withoutEntry } = scene.elements;
+  const elements =
+    Object.keys(rest).length > 0 ? { ...scene.elements, [elementId]: rest } : withoutEntry;
+  return {
+    ...doc,
+    scenes: { ...doc.scenes, [sceneId]: { ...scene, elements } },
+  };
+}
+
 /**
  * Un-pin: DELETE the `timing` override so the scene goes back to tracking its
  * word anchors. Distinct from setting a timing that happens to match the
@@ -469,6 +591,25 @@ export interface ReclampResult {
   adjusted: string[];
 }
 
+/**
+ * The scene a cue id belongs to, stripping a split half's `@ms` suffix —
+ * same idiom `splitCues` itself uses to derive a later half's id from its
+ * root, and the same one `effectiveOverride` above inlines to find a half's
+ * root entry. Two cues sharing a root are the SAME scene, cut in two.
+ *
+ * Exported (PLAN Task 2 review fix) for the editor's own use: a hidden
+ * ELEMENT on a split half can be inherited from the root (`elements`
+ * merges per id in `effectiveOverride`, and `elements` is NOT in that
+ * function's inheritance-exclusion list the way `timing`/`hidden` are) —
+ * Inspector.tsx's per-row Restore has to know whether the `hidden` it's
+ * offering to undo lives on the half's own doc entry or the root's, and
+ * this is the same root-id derivation either side of that decision needs.
+ */
+export function splitRootId(id: string): string {
+  const at = id.indexOf("@");
+  return at === -1 ? id : id.slice(0, at);
+}
+
 /**
  * Re-clamp every PINNED cue's absolute timing against its current neighbours
  * in the array, in order.
@@ -492,8 +633,22 @@ export function reclampPinnedTiming(cues: readonly SceneCue[]): ReclampResult {
     if (!cue.pinned) continue;
     const prev = out[i - 1];
     const next = out[i + 1];
-    const lo = prev ? prev.endSec + PINNED_GAP_SEC : 0;
-    const hi = next ? next.startSec - PINNED_GAP_SEC : Number.POSITIVE_INFINITY;
+    // Two adjacent pinned cues that are split halves of the SAME scene are
+    // not independent neighbours (PLAN 2026-08-04 Task 1 follow-up, found in
+    // review): `splitThenDropHidden` now runs `splitCues` before this
+    // function, so a pinned+split scene reaches here as two entries, both
+    // still `pinned: true`, with an EXACT boundary (`left.endSec ===
+    // right.startSec`) that `splitCues` already cut. Applying the usual
+    // `PINNED_GAP_SEC` buffer between them would carve a sliver out of the
+    // seam that `fillPlainCues` then fills with a spurious plain take
+    // spliced between the two halves — bug 3 again, one layer up, even
+    // though the cue array itself looks correctly split.
+    const prevIsSibling = prev?.pinned === true && splitRootId(prev.id) === splitRootId(cue.id);
+    const nextIsSibling = next?.pinned === true && splitRootId(next.id) === splitRootId(cue.id);
+    const lo = prev ? prev.endSec + (prevIsSibling ? 0 : PINNED_GAP_SEC) : 0;
+    const hi = next
+      ? next.startSec - (nextIsSibling ? 0 : PINNED_GAP_SEC)
+      : Number.POSITIVE_INFINITY;
     let s = Math.min(Math.max(cue.startSec, lo), Math.max(lo, hi - MIN_PINNED_SCENE_SEC));
     let e = Math.max(Math.min(cue.endSec, hi), s + MIN_PINNED_SCENE_SEC);
     if (e > hi) {

package/src/phonetics.ts

@@ -69,7 +69,12 @@ function phraseKey(text: string): string {
     .join("");
 }
 
-function levenshtein(a: string, b: string): number {
+// Exported: blooper.ts reuses this directly for the marker fuzzy-match arm
+// (Task 3, editor-dogfood-fixes plan) instead of a second copy — plain edit
+// distance on the raw normalized word, not the phonetic key `soundsLike`
+// compares, because "blooper"/"looker" fails the onset test below yet is
+// exactly the mishearing the marker match needs to catch.
+export function levenshtein(a: string, b: string): number {
   if (a === b) return 0;
   if (a.length === 0) return b.length;
   if (b.length === 0) return a.length;

package/src/recut.ts

@@ -0,0 +1,335 @@
+import type { OverrideDoc } from "./overrides";
+import type { Segment } from "./schema";
+import { mapsClose, TimeMap } from "./timemap";
+
+/**
+ * What `remapOverridesThroughRecut` hands back alongside the re-anchored doc.
+ * `reports` is never used to gate anything — it exists purely so a value that
+ * got pushed onto a cut edge is SAID out loud (PLAN 2026-08-04 Task 4a),
+ * rather than the user discovering a pin silently moved next time they open
+ * the editor.
+ */
+export interface RecutRemap {
+  doc: OverrideDoc;
+  reports: string[];
+}
+
+/**
+ * Remap ONE absolute-output-seconds value through a re-cut, via source time.
+ *
+ * `oldMap.toSource` is total — output time is always contiguous (TimeMap's
+ * own doc comment) — so every stored value has a source instant under the
+ * map it was recorded against. `newMap.toOutput` of that same source instant
+ * returns null exactly when the NEW cut removed it; `toOutputClamped` is the
+ * identical "snap to the nearest kept edge" TimeMap already uses for
+ * caption/overlay boundaries, so a value pushed onto a cut lands exactly
+ * where the timeline's own dead-region rendering shows the cut's edge.
+ * `label` is only for the report string — it carries no behavior.
+ */
+function remapPoint(
+  label: string,
+  t: number,
+  oldMap: TimeMap,
+  newMap: TimeMap,
+  reports: string[],
+): number {
+  const src = oldMap.toSource(t);
+  const out = newMap.toOutput(src);
+  if (out !== null) return out;
+  const clamped = newMap.toOutputClamped(src);
+  reports.push(
+    `${label} at ${t.toFixed(3)}s fell inside the new cut — snapped to ${clamped.toFixed(3)}s`,
+  );
+  return clamped;
+}
+
+/** Re-anchor output-second decisions through source time across a re-cut.
+ * Every stored absolute-output-seconds value (splits, pinned timing, cuts
+ * recorded against an older output) maps old-output → source via the OLD
+ * TimeMap, then source → new-output via the NEW TimeMap. A value whose
+ * source moment was itself removed by the new cut maps to the cut's edge
+ * and is reported, never silently dropped. */
+export function remapOverridesThroughRecut(
+  doc: OverrideDoc,
+  oldMap: TimeMap,
+  newMap: TimeMap,
+): RecutRemap {
+  const reports: string[] = [];
+
+  const splits = doc.splits.map((t) => remapPoint("split", t, oldMap, newMap, reports));
+
+  // Record-shaped: rebuild key by key rather than mutate, matching every
+  // other `OverrideDoc`-shaping function in overrides.ts (e.g.
+  // `reclampPinnedTiming`) — the doc is the user's own data, never edited
+  // in place.
+  const scenes = Object.fromEntries(
+    Object.entries(doc.scenes).map(([id, scene]) => {
+      if (!scene.timing) return [id, scene];
+      const startSec = remapPoint(`"${id}" pinned start`, scene.timing.startSec, oldMap, newMap, reports);
+      const endSec = remapPoint(`"${id}" pinned end`, scene.timing.endSec, oldMap, newMap, reports);
+      return [id, { ...scene, timing: { startSec, endSec } }];
+    }),
+  );
+
+  // `doc.cuts` is deliberately NOT remapped here (PLAN 2026-08-04 Task 4c
+  // prerequisite cleanup; review fix wave finding 1 is what made the old
+  // comment here wrong). The design this function was first written against
+  // ("a cut is exactly as stale as a split or a pin, remap it the same way")
+  // changed under it: `resolveCutSourceRanges` is what interprets a cut now,
+  // through `priorMap` — a bare old→source→new point remap through the very
+  // recut a cut CAUSED collapses it to a zero-width point at its own edge
+  // (Task 4b's Bug A), and doing that here would also silently DROP any
+  // resolved `src` the caller's `doc` already carries, since this function
+  // has no way to know a cut's `src` is settled and irreplaceable (schema
+  // comment on `OverrideDocSchema.cuts`). `applyUserCuts` is the only place
+  // `cuts` gets resolved, and its one call into this function passes
+  // `cuts: []` specifically so this function is never asked to make that
+  // call — the spread below carries the caller's `cuts` through untouched,
+  // whatever they are.
+  return { doc: { ...doc, splits, scenes }, reports };
+}
+
+/** One entry of `OverrideDoc.cuts` — see the schema comment on `src`. */
+export type UserCut = OverrideDoc["cuts"][number];
+
+/**
+ * Deep-equal with float tolerance — a "did this actually change" check for
+ * values that passed through TimeMap arithmetic and a JSON round-trip, where
+ * exact equality flags noise (review fix wave, PLAN 2026-08-04 Task 4,
+ * finding "Minor"): a 1-ulp drift is not a user edit, and treating it as one
+ * rewrites `overrides.json` — a user-owned file whose timestamp and diffs
+ * matter — on every produce run for nothing.
+ */
+function closeEnough(a: unknown, b: unknown, eps: number): boolean {
+  if (typeof a === "number" && typeof b === "number") return Math.abs(a - b) <= eps;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => closeEnough(v, b[i], eps));
+  }
+  if (a && b && typeof a === "object" && typeof b === "object") {
+    const ak = Object.keys(a).sort();
+    const bk = Object.keys(b).sort();
+    if (ak.length !== bk.length || ak.some((k, i) => k !== bk[i])) return false;
+    return ak.every((k) =>
+      closeEnough((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k], eps),
+    );
+  }
+  return a === b;
+}
+
+/** Tolerance for every float comparison in this module — generous enough to
+ * absorb a JSON round-trip and a chain of TimeMap arithmetic, tight enough
+ * that a genuine sub-millisecond user nudge still counts as a change. */
+const EPS = 1e-6;
+
+/**
+ * Resolve each user cut to a SOURCE-time range to remove, and to a `src`
+ * value worth persisting.
+ *
+ * A cut WITH `src` already is stable and settled: `src` is used directly,
+ * unconverted, every run, forever — it is never re-derived from
+ * `startSec`/`endSec` again, because there is no map left that could
+ * re-derive it correctly (review fix wave finding 1's Bug A: a cut's own
+ * source range has no faithful representation in any output frame taken
+ * AFTER that cut's own removal).
+ *
+ * A cut WITHOUT `src` is fresh — drawn by the user against `priorMap`, the
+ * render-props they were looking at (the schema comment's "output seconds of
+ * the CURRENT render-props") — so it converts through `priorMap.toSource`,
+ * NOT `map` (this run's freshly-rebuilt automatic cutlist, which has no
+ * relationship to what the user was looking at once anything has drifted:
+ * confirmed on the dogfood workdir, where an unrelated automatic-cutlist
+ * change put "output 31s in `map`" 5.8s away from "output 31s in
+ * `priorMap`"). `priorMap` missing entirely (no readable render-props.json —
+ * a first-ever produce, or a corrupt workdir) falls back to `map`, WITH a
+ * report — never silently, per the same "nothing moves without saying so"
+ * rule as `remapPoint`.
+ */
+export interface ResolvedCuts {
+  /** Source-time ranges to remove, one per cut with a non-degenerate result. */
+  ranges: { start: number; end: number }[];
+  /** `cuts`, each carrying a resolved `src` — the only thing about a cut
+   * that ever changes on write-back; `startSec`/`endSec` are untouched. */
+  cuts: UserCut[];
+  reports: string[];
+}
+
+export function resolveCutSourceRanges(
+  cuts: readonly UserCut[],
+  priorMap: TimeMap | null,
+  map: TimeMap,
+): ResolvedCuts {
+  const reports: string[] = [];
+  const resolved: UserCut[] = [];
+  const ranges: { start: number; end: number }[] = [];
+  for (const cut of cuts) {
+    let src = cut.src;
+    if (!src) {
+      let anchor = priorMap;
+      if (!anchor) {
+        reports.push(
+          `cut ${cut.startSec.toFixed(3)}–${cut.endSec.toFixed(3)}s has no render-props to ` +
+            "anchor to — used this run's automatic cutlist instead; verify placement",
+        );
+        anchor = map;
+      }
+      src = { startSec: anchor.toSource(cut.startSec), endSec: anchor.toSource(cut.endSec) };
+    }
+    resolved.push(src === cut.src ? cut : { ...cut, src });
+    if (src.endSec > src.startSec) ranges.push({ start: src.startSec, end: src.endSec });
+  }
+  return { ranges, cuts: resolved, reports };
+}
+
+/**
+ * Subtract source-time `ranges` from a cutlist's `keep` segments.
+ *
+ * `remove` segments already in the cutlist pass through untouched; a `keep`
+ * segment is split around every range that overlaps it. New `remove`
+ * segments carry `reason: "user"` (`RemovalReasonSchema` already has this
+ * value) so `formatCutReport` — which walks `production.cutlist` — lists a
+ * user cut exactly like an automatic one, with no separate report path
+ * needed for "what got removed."
+ */
+export function subtractRangesFromCutlist(
+  cutlist: readonly Segment[],
+  ranges: readonly { start: number; end: number }[],
+): Segment[] {
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  if (sorted.length === 0) return [...cutlist];
+
+  const out: Segment[] = [];
+  for (const seg of cutlist) {
+    if (seg.kind !== "keep") {
+      out.push(seg);
+      continue;
+    }
+    // Carve every overlapping range out of this ONE keep segment, left to
+    // right, so the result stays sorted and non-overlapping the way
+    // `TimeMap`'s constructor requires — a range that also touches a
+    // NEIGHBOURING keep segment (separated by an existing automatic cut) is
+    // simply considered again there, on its own bounds.
+    let cursor = seg.srcIn;
+    for (const r of sorted) {
+      const overlapStart = Math.max(cursor, r.start);
+      const overlapEnd = Math.min(seg.srcOut, r.end);
+      if (overlapStart >= overlapEnd) continue;
+      if (overlapStart > cursor) out.push({ srcIn: cursor, srcOut: overlapStart, kind: "keep" });
+      out.push({ srcIn: overlapStart, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      cursor = overlapEnd;
+    }
+    if (cursor < seg.srcOut) out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "keep" });
+  }
+  return out;
+}
+
+/** What applying the user's `cuts` to a cutlist hands back to `produce.ts`. */
+export interface ApplyUserCutsResult {
+  /** `subtractRangesFromCutlist`'s result — `[...cutlist]` unchanged when
+   * `doc.cuts` is empty. */
+  cutlist: Segment[];
+  /** `new TimeMap(cutlist)`, handed back so the caller doesn't rebuild it. */
+  map: TimeMap;
+  /**
+   * The doc with `cuts[*].src` resolved and `splits`/pinned
+   * `scenes[id].timing` re-anchored where drift was found. `cuts[*].startSec`/
+   * `endSec` are always the user's original values — see `resolveCutSourceRanges`.
+   */
+  doc: OverrideDoc;
+  /** Every report worth surfacing — missing-anchor fallbacks (always) plus
+   * remap reports (only when a re-anchor actually happened). Shown
+   * regardless of `changed`: these are about DECISIONS, not about whether a
+   * file got written. */
+  reports: string[];
+  /**
+   * Whether `doc` actually differs from what was read (a cut resolved its
+   * `src` for the first time, and/or splits/pins moved). The write-back
+   * guard (PLAN 2026-08-04 Task 4 + review fix wave finding 3): an untouched
+   * `overrides.json` must not be rewritten on every produce run.
+   */
+  changed: boolean;
+  /** Total duration this run's cuts removed, for the produce report's headline. */
+  removedSec: number;
+}
+
+/**
+ * Subtract the user's `cuts` from `cutlist`, then re-anchor `splits`/pinned
+ * timing through whatever drift is found between `priorMap` (the frame the
+ * doc's stored values are CURRENTLY anchored to — `produce.ts` reconstructs
+ * this from the last-written `render-props.json`) and this run's final map
+ * (PLAN 2026-08-04 Task 4). This is the ONE sanctioned write to
+ * `overrides.json` — every other file `produce.ts` writes is derived and
+ * safe to overwrite every run, but this rewrites the user's OWN decisions,
+ * and does so because the timeline those decisions are anchored to keeps
+ * moving out from under them. Rewriting them here is what keeps them meaning
+ * the same thing, not silently landing somewhere else the next time the
+ * editor opens.
+ *
+ * Two gates, deliberately independent (review fix wave finding 3):
+ *  - Subtracting cuts from the cutlist only happens when `doc.cuts` is
+ *    non-empty — nothing to subtract otherwise.
+ *  - Re-anchoring `splits`/`scenes[*].timing` happens whenever `priorMap` is
+ *    available AND differs (span-for-span, float-tolerant) from this run's
+ *    final map — REGARDLESS of whether `cuts` is empty. A doc with cuts
+ *    already applied, then emptied again (the editor's Restore gesture), has
+ *    splits/pins still sitting in last run's POST-cut frame with nothing in
+ *    `cuts` left to drive a re-anchor off of; gating on `cuts.length` alone
+ *    stranded them. The same gate also catches the automatic cutlist itself
+ *    drifting for a reason that has nothing to do with the user's cuts at
+ *    all (a `--cleanup` change, a repair-pass improvement) — confirmed for
+ *    real on the dogfood workdir during verification.
+ *
+ * `priorMap === null` (no readable render-props.json: first-ever produce, or
+ * a corrupt workdir) skips re-anchoring entirely — there is nothing to
+ * compare against — but a `src`-less cut still resolves, falling back to
+ * `map` with a report (see `resolveCutSourceRanges`).
+ */
+export function applyUserCuts(
+  doc: OverrideDoc,
+  cutlist: readonly Segment[],
+  map: TimeMap,
+  priorMap: TimeMap | null,
+): ApplyUserCutsResult {
+  let newCutlist: Segment[] = [...cutlist];
+  let cuts = doc.cuts;
+  let reports: string[] = [];
+  if (doc.cuts.length > 0) {
+    const resolved = resolveCutSourceRanges(doc.cuts, priorMap, map);
+    newCutlist = subtractRangesFromCutlist(cutlist, resolved.ranges);
+    cuts = resolved.cuts;
+    reports = resolved.reports;
+  }
+  const newMap = new TimeMap(newCutlist);
+  const removedSec = map.outputDuration - newMap.outputDuration;
+  const cutsChanged = !closeEnough(cuts, doc.cuts, EPS);
+
+  let finalDoc: OverrideDoc = { ...doc, cuts };
+  let reanchored = false;
+  if (priorMap !== null && !mapsClose(priorMap, newMap, EPS)) {
+    // `cuts: []` going IN: this function re-anchors `splits`/pinned timing
+    // only — see `resolveCutSourceRanges` above for why `cuts` itself is
+    // handled separately and never round-tripped through `remapPoint`
+    // (remapping a cut through the very recut it caused collapses it to a
+    // zero-width point at its own edge, the identical "landed on a cut
+    // edge" case reported for splits/pins — and reporting THAT would tell
+    // the user their cut moved when it didn't).
+    const { doc: remapped, reports: remapReports } = remapOverridesThroughRecut(
+      { ...doc, cuts: [] },
+      priorMap,
+      newMap,
+    );
+    if (!closeEnough(remapped.splits, doc.splits, EPS) || !closeEnough(remapped.scenes, doc.scenes, EPS)) {
+      finalDoc = { ...remapped, cuts };
+      reports = [...reports, ...remapReports];
+      reanchored = true;
+    }
+  }
+
+  return {
+    cutlist: newCutlist,
+    map: newMap,
+    doc: finalDoc,
+    reports,
+    changed: cutsChanged || reanchored,
+    removedSec,
+  };
+}