@ossclip/core 0.1.27 → 0.1.28

package/src/retime-preview.ts

@@ -0,0 +1,331 @@
+/**
+ * The editor's live post-veto preview (cut review step 4): when the user
+ * declines a removal produce proposed, the preview's own timeline is re-cut
+ * so the player actually PLAYS the revived material, immediately, instead of
+ * marking a seam that only the next render honours.
+ *
+ * Cleanup vetoes ONLY. User `cuts[]` stay marked-not-applied, exactly the
+ * step-3 posture, for two reasons that are not the retired "no client-side
+ * TimeMap" one:
+ *  - produce alone resolves a fresh cut's `src` (the `cuts[].src` schema
+ *    contract, overrides.ts) — the editor must never apply a cut whose
+ *    source range only produce can resolve;
+ *  - a veto RESTORES content the mezzanine already has, so the editor can
+ *    honestly play it; a cut REMOVES content, and the struck band already
+ *    communicates that honestly.
+ *
+ * Pure and browser-safe by construction (the cover-headline.ts split): this
+ * module's whole import graph — cutlist, recut, timemap, and types — has
+ * zero node built-ins, so it rides `@ossclip/core/browser` into the editor
+ * bundle, and every function here is testable without a TTY or a filesystem.
+ */
+
+import type { CaptionLine } from "./captions";
+import { applyCleanupChoices, type CleanupChoices } from "./cutlist";
+import { remapPoint, subtractRangesFromCutlist, type UserCut } from "./recut";
+import type { SceneCue } from "./scene-schema";
+import type { Segment } from "./schema";
+import { mapFromKeptSpans, mapsClose, TimeMap, type KeptSpan } from "./timemap";
+import type { ZoomSegment } from "./zoom";
+
+/** `applyUserCuts`'s EPS — a JSON round-trip plus TimeMap arithmetic is
+ * noise, a real veto is never under a millisecond. */
+const EPS = 1e-6;
+
+/** Both clocks the retime needs: the one the current render-props are timed
+ * against, and the one the user's cleanup choices produce. */
+export interface LivePreviewClocks {
+  oldMap: TimeMap;
+  newMap: TimeMap;
+}
+
+/**
+ * Whether the current cleanup choices change the timeline at all — and the
+ * two clocks to retime through when they do. `null` is the identity signal:
+ * the caller must hand the props through UNTOUCHED (the regression anchor —
+ * a doc with no live veto must leave the preview byte-identical to today's).
+ *
+ * The new clock is produce's own sequence, same functions, same order:
+ * `applyCleanupChoices(proposal, choices)` then user cuts subtract from the
+ * result (`subtractRangesFromCutlist`), so a user cut drawn over a vetoed
+ * pause still cuts here exactly as it does in produce. Only cuts whose `src`
+ * is already resolved subtract — a fresh cut's source range is produce's
+ * alone to resolve (`resolveCutSourceRanges` needs the prior render-props
+ * frame), and that cut is still marked-not-applied on the timeline anyway.
+ * Skipping the subtraction entirely would be worse than incomplete: every
+ * ALREADY-APPLIED cut (src resolved by a past produce, absent from
+ * `oldSpans`) would silently come back the moment any veto went live.
+ *
+ * `null` on any degenerate input — no proposal, no old spans, choices with
+ * no actual veto — and on a proposal `TimeMap`'s constructor rejects (a
+ * hand-mangled production.json): the preview degrades to step 3's honest
+ * marks-rather-than-applies, never a crash, the same lenient posture as
+ * GET /api/cleanup itself.
+ */
+export function livePreviewMap(
+  proposal: readonly Segment[],
+  choices: CleanupChoices | undefined,
+  cuts: readonly UserCut[],
+  oldSpans: readonly KeptSpan[],
+): LivePreviewClocks | null {
+  // "Non-empty" means a veto actually present — a `reasons` map of tolerated
+  // `true` entries restates the default (the schema comment) and must take
+  // the cheap exact exit, not a float comparison of two equal maps.
+  const hasVeto =
+    Object.values(choices?.reasons ?? {}).some((v) => v === false) ||
+    (choices?.kept?.length ?? 0) > 0;
+  if (!hasVeto) return null;
+  if (proposal.length === 0 || oldSpans.length === 0) return null;
+  try {
+    const rekept = applyCleanupChoices(proposal, choices);
+    const ranges = cuts.flatMap((c) =>
+      c.src && c.src.endSec > c.src.startSec
+        ? [{ start: c.src.startSec, end: c.src.endSec }]
+        : [],
+    );
+    const newMap = new TimeMap(subtractRangesFromCutlist(rekept, ranges));
+    const oldMap = mapFromKeptSpans(oldSpans);
+    // Choices that change nothing (a veto already baked into the last
+    // produce's spans, a kept range overlapping no removal) are identity.
+    if (mapsClose(oldMap, newMap, EPS)) return null;
+    return { oldMap, newMap };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The two clocks as POINT mappers, one per direction. `retimeForPreview`
+ * below moves the player's PROPS onto the new clock in one batch, but the
+ * editor also has surfaces that read or write a SINGLE instant at a gesture
+ * — the transcript's click-to-seek, the timeline's ghost bands, the cover
+ * panel's playhead — and each of those needs the same old-output → source →
+ * new-output walk as a plain function it can be handed without knowing the
+ * recut machinery behind it.
+ */
+export interface PreviewClockMappers {
+  /** OLD-clock output seconds (the last render's own timeline — what the
+   * render props, the ghost cues and the pre-retime caption lines are timed
+   * in) → the clock the player is actually on. Exact for every live veto:
+   * vetoes only ever ADD time back, so every old moment survives on the new
+   * clock (`retimeForPreview`'s direction argument); the clamp behind it
+   * only fires for the retracted-veto shape the retime already reports. */
+  toLive: (sec: number) => number;
+  /** The reverse: the player's clock → the last render's own output seconds.
+   * A live moment inside REVIVED material has no old-clock preimage at all —
+   * the rendered mp4 never contained that frame — so it clamps to the
+   * nearest kept edge (`toOutputClamped`'s documented role), the closest
+   * moment the old clock can honestly name. */
+  fromLive: (sec: number) => number;
+  /** Whether a live instant EXISTS on the old clock at all — false exactly
+   * when `fromLive` would have to clamp: the moment sits inside REVIVED
+   * material (a vetoed removal the last render cut away). The WRITE-direction
+   * guard (the follow-up to `fromLive`'s read direction): the doc's own time
+   * slots speak the OLD clock (`splits[].at` per SplitSchema, a fresh cut's
+   * `startSec`/`endSec` per the `cuts` schema comment — overrides.ts), and a
+   * writer facing a moment this answers false for must refuse OUT LOUD
+   * rather than let the clamp silently relocate the user's gesture to the
+   * seam — the recut.ts "reported, never silently dropped" rule, applied
+   * before the write instead of after. Asked as its own question, not an ad
+   * hoc float comparison of `toLive(fromLive(sec))` against `sec` at some
+   * caller-invented tolerance. An instant exactly AT a seam counts as HAVING
+   * a preimage: `toOutput`'s containment is inclusive of both span edges
+   * (timemap.ts), so the seam moment is one the last render still contained.
+   * Always true for the identity pair — no veto, nothing revived. */
+  hasOldClockPreimage: (sec: number) => boolean;
+}
+
+/**
+ * The mappers for the current live re-cut — or the IDENTITY pair when there
+ * is none (`clocks === null`, `livePreviewMap`'s own identity signal). The
+ * identity is literally `(sec) => sec`, so a consumer's no-veto path computes
+ * bit-identical values to what it computed before the mapping existed — the
+ * same regression anchor the `live` memo's null branch holds to.
+ */
+export function previewClockMappers(clocks: LivePreviewClocks | null): PreviewClockMappers {
+  if (clocks === null) {
+    const identity = (sec: number): number => sec;
+    return { toLive: identity, fromLive: identity, hasOldClockPreimage: () => true };
+  }
+  const { oldMap, newMap } = clocks;
+  return {
+    toLive: (sec) => {
+      const src = oldMap.toSource(sec);
+      return newMap.toOutput(src) ?? newMap.toOutputClamped(src);
+    },
+    fromLive: (sec) => {
+      const src = newMap.toSource(sec);
+      return oldMap.toOutput(src) ?? oldMap.toOutputClamped(src);
+    },
+    // `fromLive`'s exact half, asked as a question: `toOutput` is null
+    // precisely when the source instant fell in a region the old map removed
+    // — i.e. the live moment is inside revived material (its own doc comment
+    // above pins the inclusive-seam semantics).
+    hasOldClockPreimage: (sec) => oldMap.toOutput(newMap.toSource(sec)) !== null,
+  };
+}
+
+/** `cutRangeToOldClock`'s verdict on a live-clock window headed for a doc
+ * `cuts[]` slot. `exact`/`shrunk` carry OLD-clock seconds ready to store;
+ * `shrunk` also carries a report (the `remapPoint` posture — a moved value
+ * says so) for the caller's feedback channel; `degenerate` means the window
+ * has NO old-clock extent at all and the write must be refused out loud. */
+export type OldClockCutRange =
+  | { kind: "exact"; startSec: number; endSec: number }
+  | { kind: "shrunk"; startSec: number; endSec: number; report: string }
+  | { kind: "degenerate" };
+
+/**
+ * Convert a cut gesture's LIVE-clock window into the OLD-clock window the
+ * doc's `cuts[]` slots speak (the schema comment on `OverrideDocSchema.cuts`:
+ * a fresh cut's `startSec`/`endSec` are drawn against the LAST render-props'
+ * frame — produce resolves `src` by mapping them through the PRIOR TimeMap,
+ * so a new-clock number stored there lands the cut the revived seconds off).
+ *
+ * Endpoints inside revived material clamp to the nearest kept edge
+ * (`fromLive`'s doc): when only ONE edge clamps the range SHRINKS there and
+ * the cut proceeds on what the old clock can express — the source range
+ * produce resolves from the shrunk window still spans the revived material
+ * BETWEEN the endpoints (a contiguous source interval), so only the revived
+ * sliver past the clamped edge is lost, and the report says so. When the
+ * whole window collapses to one point — both endpoints inside one revived
+ * region, or the window exactly covering it seam to seam (each seam HAS a
+ * preimage, but the same one twice) — there is nothing left to cut and the
+ * verdict is `degenerate`: refuse, the ⌘B-split posture, never a silent
+ * zero-length entry. Checked on the mapped WIDTH first, before the preimage
+ * question, for exactly that seam-to-seam case. The module `EPS`, not 0: the
+ * mapped ends ride TimeMap arithmetic, and a real cut is never under a
+ * microsecond.
+ *
+ * Identity mappers (no live veto) always answer `exact` with the input
+ * values untouched — the no-veto regression anchor.
+ */
+export function cutRangeToOldClock(
+  mappers: Pick<PreviewClockMappers, "fromLive" | "hasOldClockPreimage">,
+  startSec: number,
+  endSec: number,
+): OldClockCutRange {
+  const mappedStart = mappers.fromLive(startSec);
+  const mappedEnd = mappers.fromLive(endSec);
+  if (mappedEnd - mappedStart < EPS) return { kind: "degenerate" };
+  if (mappers.hasOldClockPreimage(startSec) && mappers.hasOldClockPreimage(endSec)) {
+    return { kind: "exact", startSec: mappedStart, endSec: mappedEnd };
+  }
+  return {
+    kind: "shrunk",
+    startSec: mappedStart,
+    endSec: mappedEnd,
+    report:
+      `cut ${startSec.toFixed(3)}s–${endSec.toFixed(3)}s trimmed to the last render's ` +
+      `${mappedStart.toFixed(3)}s–${mappedEnd.toFixed(3)}s — the revived material at its ` +
+      `edge isn't in the last render yet`,
+  };
+}
+
+/** The output-timed subset of the render props the retime reads. Structural
+ * on purpose — the renderer's `ProductionCompProps` satisfies it without
+ * core importing the renderer package. */
+export interface RetimeablePreviewProps {
+  outputDurationSec: number;
+  captionLines: readonly CaptionLine[];
+  sceneCues: readonly SceneCue[];
+  zoomPlan?: readonly ZoomSegment[];
+  ctaWindow?: { startSec: number; endSec: number };
+  sourceTextRegions?: readonly { y: number; h: number; startSec: number; endSec: number }[];
+}
+
+/** Exactly the fields `retimeForPreview` re-timed — the caller spreads them
+ * over the full props (`{ ...props, ...fields }`), so fields this function
+ * never touches (theme, face, framingTimeline — all source-timed or
+ * timeless) cannot be accidentally rewritten here. */
+export interface RetimedPreviewFields {
+  spans: KeptSpan[];
+  outputDurationSec: number;
+  captionLines: CaptionLine[];
+  sceneCues: SceneCue[];
+  zoomPlan?: ZoomSegment[];
+  ctaWindow?: { startSec: number; endSec: number };
+  sourceTextRegions?: { y: number; h: number; startSec: number; endSec: number }[];
+  punch: { scale: number; allowed: boolean[] };
+}
+
+export interface RetimedPreview {
+  fields: RetimedPreviewFields;
+  reports: string[];
+}
+
+/**
+ * Re-time every output-timed render prop from `oldMap`'s clock onto
+ * `newMap`'s: old-output → source → new-output, `remapPoint`'s exact
+ * algorithm — the same one produce re-anchors splits and pins with.
+ *
+ * Vetoes only ever ADD time back (a removal becomes a keep), so every moment
+ * the old clock could express survives on the new one and maps exactly. The
+ * clamped fallback still stands behind each point (`toOutputClamped`'s
+ * documented role) for the one direction that can remove time: the old spans
+ * carrying a veto the doc no longer holds — a moment inside it snaps to the
+ * nearest kept edge and is reported, never silently dropped.
+ *
+ * Word `srcStart` is already SOURCE time (§137's recut-immune key) and is
+ * carried untouched. `punch` comes back provably inert — `{scale: 1,
+ * allowed: []}`: `punchScalesFor` (punch-plan.ts) renders an allowed span's
+ * punched turn at `scale`, and scale 1 is no visible punch; an empty mask
+ * reads all-allowed, which is exactly what makes scale the only knob. It
+ * cannot pass through: `punch.allowed` is INDEXED PER SPAN, the new span
+ * list has different indices, and the face-only verdict that built the mask
+ * cannot be recomputed client-side — a punch on the wrong span (a screen
+ * share sliding) is worse than no punch for the preview's duration. The
+ * zoom plan, by contrast, IS remapped: its segments are pure output time
+ * (`zoomScaleAt` consults nothing but `startSec`/`endSec`), and a revived
+ * stretch simply falls outside every segment, which `zoomScaleAt` already
+ * renders as the static camera.
+ */
+export function retimeForPreview(
+  props: RetimeablePreviewProps,
+  oldMap: TimeMap,
+  newMap: TimeMap,
+): RetimedPreview {
+  const reports: string[] = [];
+  const at = (label: string, t: number): number => remapPoint(label, t, oldMap, newMap, reports);
+  const fields: RetimedPreviewFields = {
+    spans: newMap.spans.map((s) => ({ ...s })),
+    outputDurationSec: newMap.outputDuration,
+    captionLines: props.captionLines.map((line, i) => ({
+      ...line,
+      start: at(`caption line ${i + 1} start`, line.start),
+      end: at(`caption line ${i + 1} end`, line.end),
+      words: line.words.map((w) => ({
+        ...w,
+        start: at(`caption word "${w.text}" start`, w.start),
+        end: at(`caption word "${w.text}" end`, w.end),
+      })),
+    })),
+    sceneCues: props.sceneCues.map((c) => ({
+      ...c,
+      startSec: at(`scene "${c.id}" start`, c.startSec),
+      endSec: at(`scene "${c.id}" end`, c.endSec),
+    })),
+    punch: { scale: 1, allowed: [] },
+  };
+  if (props.zoomPlan) {
+    fields.zoomPlan = props.zoomPlan.map((seg, i) => ({
+      ...seg,
+      startSec: at(`zoom segment ${i + 1} start`, seg.startSec),
+      endSec: at(`zoom segment ${i + 1} end`, seg.endSec),
+    }));
+  }
+  if (props.ctaWindow) {
+    fields.ctaWindow = {
+      startSec: at("CTA window start", props.ctaWindow.startSec),
+      endSec: at("CTA window end", props.ctaWindow.endSec),
+    };
+  }
+  if (props.sourceTextRegions) {
+    fields.sourceTextRegions = props.sourceTextRegions.map((r, i) => ({
+      ...r,
+      startSec: at(`source text region ${i + 1} start`, r.startSec),
+      endSec: at(`source text region ${i + 1} end`, r.endSec),
+    }));
+  }
+  return { fields, reports };
+}

package/src/schema.ts

@@ -147,7 +147,26 @@ export const ProductionSchema = z.object({
     )
     .optional(),
   analysis: AnalysisSchema.optional(),
+  /**
+   * What this run ACTUALLY cut — post cleanup-choices, post user cuts. Every
+   * consumer that treats the cutlist as the applied truth (`formatCutReport`,
+   * the four NLE exporters, `analyze`'s marker count) reads this one, which
+   * is why it stays the resolved list rather than the proposal: recording the
+   * proposal here would make each of them re-apply the choices or lie.
+   */
   cutlist: z.array(SegmentSchema).optional(),
+  /**
+   * The automatic PROPOSAL (cut review step 3) — `buildCutlist`'s output
+   * before `applyCleanupChoices` vetoes and before user cuts subtract. Kept
+   * alongside because the resolution is lossy: a vetoed removal merges into
+   * a plain keep, so `cutlist` alone cannot tell the editor which categories
+   * the user declined — its checkboxes and seams re-derive the veto state
+   * from THIS list + `overrides.json`'s `cleanup`, through the same
+   * `applyCleanupChoices` produce ran. Optional: pre-step-3 files predate it
+   * and must still parse (readers fall back to `cutlist`, which back then
+   * WAS the proposal plus user cuts).
+   */
+  cutlistProposed: z.array(SegmentSchema).optional(),
   /**
    * Present on a `--clip` run (R19 §93): the target and the resolved window.
    * `startWord`/`endWord` are indices into the PRE-slice repaired transcript