@ossclip/core 0.1.24 → 0.1.25

package/src/content-rect.ts

@@ -153,6 +153,75 @@ export interface ContentRectSegment {
   rect: ContentRect;
 }
 
+/**
+ * One stretch of the RENDER-TIME framing plan — the props-based successor to
+ * the destructive normalization bake (2026-08-16 incident: the bake's crop
+ * could only be undone by deleting the re-encoded file; expressed as data,
+ * the same window renders as a transform the editor can see and counteract).
+ * Emitted into render-props.json as `framingTimeline`; absent means "no plan"
+ * and every pre-existing render-props renders unchanged.
+ */
+export interface FramingSegment {
+  /** Source seconds — intersects the content timeline and kept spans directly. */
+  startSec: number;
+  endSec: number;
+  /** Crop window in SOURCE pixels, all windows sharing one aspect. */
+  window: { x: number; y: number; w: number; h: number };
+  /** What the window is anchored on; "screen" windows are centered clips. */
+  subject: "face" | "screen";
+  /** The subject's anchor point inside the window, 0..1 both axes. */
+  bias: { x: number; y: number };
+}
+
+/**
+ * Rescale framing windows from TRUE source pixels into the pixel space of a
+ * display-sized mezzanine (2026-08-17 render-speed pass). `planNormalization`
+ * keeps working in true source pixels — analysis runs on the source — and
+ * the render-props emission scales the windows so window space === the space
+ * of the file the render actually plays. Per-axis factors, not one scalar:
+ * yuv420 even-rounding makes the two axes' ratios differ by a fraction of a
+ * percent, and scaling both by one axis's factor could push a right-edge
+ * window past the scaled file's width. Times, subject and bias are
+ * scale-invariant and pass through untouched.
+ */
+export function scaleFramingWindows(
+  timeline: readonly FramingSegment[],
+  factor: { x: number; y: number },
+): FramingSegment[] {
+  return timeline.map((s) => ({
+    ...s,
+    window: {
+      x: s.window.x * factor.x,
+      y: s.window.y * factor.y,
+      w: s.window.w * factor.x,
+      h: s.window.h * factor.y,
+    },
+  }));
+}
+
+/**
+ * The same rescale for the fit-fallback's content timeline — its rects are
+ * source pixels too, and they reach the renderer only alongside a
+ * `sourceSize` that must describe the played file (see the render-props
+ * emission in produce.ts). `full` survives the scale: it means "this rect IS
+ * the whole frame", which a uniform resample does not change.
+ */
+export function scaleContentTimeline(
+  timeline: readonly ContentRectSegment[],
+  factor: { x: number; y: number },
+): ContentRectSegment[] {
+  return timeline.map((s) => ({
+    ...s,
+    rect: {
+      ...s.rect,
+      x: s.rect.x * factor.x,
+      y: s.rect.y * factor.y,
+      w: s.rect.w * factor.x,
+      h: s.rect.h * factor.y,
+    },
+  }));
+}
+
 /**
  * A framing run must survive BOTH of these to be believed. Together they are
  * what replaces the union rule's protection (PLAN Task C, step C2).
@@ -270,6 +339,148 @@ export function contentRectTimeline(
   }));
 }
 
+/**
+ * Materiality thresholds (2026-08-16 landscape screen-recording over-crop — a
+ * 72px dark strip (2.08% inset, 1px past SNAP_FRAC's 69.1px tolerance) plus a
+ * 15.4s/1435s outlier segment destroyed 55% of the picture).
+ *
+ * SNAP_FRAC decides whether a bar is worth TRIMMING; this bound decides
+ * whether a rect difference is worth calling a FRAMING CHANGE — a far more
+ * destructive claim, because a mixed-framing verdict sends the whole take
+ * into normalization. The incident's jitter measured 2.0–2.3% per side, so
+ * the bound sits at 3.5%: comfortably above jitter, comfortably below any
+ * real letterbox (the motivating 144bbfb strip insets 34% per side).
+ */
+export const MATERIAL_INSET_FRAC = 0.035;
+
+/**
+ * A rect keeping at least this share of the frame's area, at (within
+ * MATERIAL_ASPECT_TOL of) the frame's own aspect, is the frame minus
+ * measurement noise — treating it as a distinct framing would re-crop every
+ * downstream geometry to chase pixels nobody can see missing.
+ */
+export const MATERIAL_AREA_FRAC = 0.92;
+const MATERIAL_ASPECT_TOL = 0.05;
+
+/**
+ * A framing class — every segment sharing one rect, contiguous or not —
+ * totalling under this share of the runtime is an anomaly, not a framing
+ * change. MIN_RUN_SEC only guards a single run; the incident's 15.4s outlier
+ * (1.1% of 1435s) sailed past it and single-handedly set the canvas aspect
+ * for the whole take.
+ */
+export const MIN_FRAMING_CLASS_FRAC = 0.05;
+
+/**
+ * Re-judge a measured timeline against what a framing change must AMOUNT TO
+ * before it is believed (2026-08-16 incident above).
+ *
+ * Two passes. First, per segment: a rect whose every side inset is under
+ * MATERIAL_INSET_FRAC, or that keeps MATERIAL_AREA_FRAC of the frame at the
+ * frame's own aspect, is reclassified as the full frame — it differs from the
+ * frame by less than a framing change is worth. Second, per CLASS: framing
+ * classes totalling under MIN_FRAMING_CLASS_FRAC of the runtime are absorbed
+ * into their longer neighbour, same shape as the run-absorption loop in
+ * `contentRectTimeline` (drop one, retry until stable, then merge agreeing
+ * neighbours). A uniform source comes out as exactly one segment.
+ *
+ * Pure — applied on top of the cached raw timeline, so an already-measured
+ * source re-classifies on replay without a cache version bump.
+ */
+export function materializeTimeline(
+  timeline: readonly ContentRectSegment[],
+  width: number,
+  height: number,
+  durationSec: number,
+): ContentRectSegment[] {
+  if (timeline.length === 0 || width <= 0 || height <= 0) {
+    return timeline.map((s) => ({ ...s }));
+  }
+  const whole: ContentRect = { x: 0, y: 0, w: width, h: height, full: true };
+  const frameAspect = width / height;
+
+  const immaterial = (r: ContentRect): boolean => {
+    if (r.full) return true;
+    const insets = [
+      r.x / width,
+      r.y / height,
+      (width - (r.x + r.w)) / width,
+      (height - (r.y + r.h)) / height,
+    ];
+    if (insets.every((f) => f < MATERIAL_INSET_FRAC)) return true;
+    const areaFrac = (r.w * r.h) / (width * height);
+    const aspectDelta = Math.abs(r.w / r.h - frameAspect) / frameAspect;
+    return areaFrac >= MATERIAL_AREA_FRAC && aspectDelta < MATERIAL_ASPECT_TOL;
+  };
+
+  const segs = timeline.map((s) => ({
+    startSec: s.startSec,
+    endSec: s.endSec,
+    rect: immaterial(s.rect) ? whole : s.rect,
+  }));
+
+  // Duration of each segment's whole CLASS — the outlier that motivated this
+  // appeared as one contiguous run, but a strip flickering in and out would
+  // split into several, and each alone dodging the threshold must not let the
+  // class as a whole survive.
+  const classTotals = (list: typeof segs): number[] => {
+    const reps: ContentRect[] = [];
+    const totals: number[] = [];
+    const ids = list.map((s) => {
+      let id = reps.findIndex((r) => sameFraming(r, s.rect, width, height));
+      if (id === -1) {
+        id = reps.length;
+        reps.push(s.rect);
+        totals.push(0);
+      }
+      totals[id]! += s.endSec - s.startSec;
+      return id;
+    });
+    return ids.map((id) => totals[id]!);
+  };
+
+  // Absorb, then retry until stable: dropping one segment changes its
+  // neighbours' class totals and can make them adjacent and mergeable.
+  let changed = true;
+  while (changed && segs.length > 1) {
+    changed = false;
+    const totals = classTotals(segs);
+    for (let i = 0; i < segs.length; i++) {
+      if (totals[i]! >= MIN_FRAMING_CLASS_FRAC * durationSec) continue;
+      const r = segs[i]!;
+      // Absorb into the LONGER neighbour — the one more likely to be the truth.
+      const prev = segs[i - 1];
+      const next = segs[i + 1];
+      const into = !prev
+        ? next
+        : !next
+          ? prev
+          : prev.endSec - prev.startSec >= next.endSec - next.startSec
+            ? prev
+            : next;
+      if (!into) continue;
+      into.startSec = Math.min(into.startSec, r.startSec);
+      into.endSec = Math.max(into.endSec, r.endSec);
+      segs.splice(i, 1);
+      changed = true;
+      break;
+    }
+  }
+
+  // Merge neighbours that now agree, so a source whose every segment was
+  // reclassified collapses to the single-segment (uniform) shape callers test.
+  const merged: typeof segs = [];
+  for (const s of segs) {
+    const last = merged[merged.length - 1];
+    if (last && sameFraming(last.rect, s.rect, width, height)) {
+      last.endSec = Math.max(last.endSec, s.endSec);
+    } else {
+      merged.push({ ...s });
+    }
+  }
+  return merged;
+}
+
 /**
  * The exact framing-change instant inside a densely-sampled window
  * (NORMALIZE plan, boundary refinement).

package/src/cover.ts

@@ -136,9 +136,17 @@ export function laplacianVariance(pixels: Uint8Array, w: number, h: number): num
 }
 
 /**
- * Score a candidate. A face is close to mandatory — a cover without the
- * speaker is a cover for a different video — and among frames that have one,
- * sharpness decides. Earlier frames win ties so the cover matches the opening.
+ * Score a candidate. On a "face" take a face is close to mandatory — a cover
+ * without the speaker is a cover for a different video — and among frames
+ * that have one, sharpness decides. Earlier frames win ties so the cover
+ * matches the opening.
+ *
+ * On a "screen" take the face weight drops to ZERO (2026-08-16): a Facebook
+ * reel playing inside a 21-minute screen recording put a STRANGER'S face on
+ * the cover, because face×2 hunts any face at all and on a screen-subject
+ * take every face in frame is content, not the speaker. Sharpness and
+ * earliness alone pick that cover. Default "face" so portrait/talking-head
+ * runs score exactly as before.
  */
 export function scoreCandidate(c: {
   timeSec: number;
@@ -146,11 +154,13 @@ export function scoreCandidate(c: {
   sharpness: number;
   hasFace: boolean;
   maxSharpness: number;
+  subject?: "face" | "screen";
 }): number {
+  const faceWeight = c.subject === "screen" ? 0 : 2;
   const face = c.hasFace ? 1 : 0;
   const sharp = c.maxSharpness > 0 ? c.sharpness / c.maxSharpness : 0;
   const earliness = 1 - Math.min(1, c.timeSec / Math.max(1e-6, c.durationSec));
-  return face * 2 + sharp + earliness * 0.3;
+  return face * faceWeight + sharp + earliness * 0.3;
 }
 
 export interface PickCoverOptions {
@@ -172,6 +182,12 @@ export interface PickCoverOptions {
    * canvas that is two-thirds baked-in black bar.
    */
   cropVf?: string;
+  /**
+   * The take's whole-frame subject (`faceSubject`'s verdict). "screen" zeroes
+   * the face weight in `scoreCandidate` — see its doc comment for the
+   * 2026-08-16 stranger's-face incident. Default "face".
+   */
+  subject?: "face" | "screen";
 }
 
 /**
@@ -229,7 +245,7 @@ export async function pickCoverFrame(
   for (const r of raw) {
     candidates.push({
       ...r,
-      score: scoreCandidate({ ...r, durationSec: window, maxSharpness }),
+      score: scoreCandidate({ ...r, durationSec: window, maxSharpness, subject: opts.subject }),
     });
   }
   candidates.sort((a, b) => b.score - a.score);

package/src/cutlist.ts

@@ -42,6 +42,18 @@ const SILENCE_PAD_IN = 0.06;
 const SILENCE_PAD_OUT = 0.1;
 /** Kept fragments shorter than this (holding no word) are folded into the cut. */
 const MIN_KEEP = 0.25;
+/**
+ * A WORDED kept gap up to this long is still folded when a flanking removal
+ * is a `retake` cut (2026-08-16 incident): whisper stamped a debris "And" at
+ * 670.0–670.4 between a marker-terminated blooper cut and the silence cut
+ * that followed, and `hasProtectedWordInside` — correctly — refused the
+ * wordless fold, so a 0.4s one-word sliver of an abandoned sentence shipped
+ * as a choppy blip. A retake cut already means "this whole attempt is
+ * unusable", so a sub-0.35s word fragment glued to it is debris of that same
+ * attempt, not content. Silence/silence neighbors get NO such license: their
+ * worded gaps stay protected exactly as §124's follow-up demands.
+ */
+const MIN_KEEP_AFTER_RETAKE = 0.35;
 
 interface Removal {
   start: number;
@@ -74,8 +86,19 @@ export interface BuildCutlistArgs {
    * still has no judgement of its own about what a bad take looks like, it
    * just folds whichever spans two independent detectors handed it into the
    * one partition.
+   *
+   * `confidence` optionally overrides the 0.9 default below — the
+   * exact-prefix restart rule (retake.ts, RESTART_PREFIX_CONFIDENCE) earns
+   * 0.85, one notch less than a full similarity match, and the caller is the
+   * one who knows which rule found the span.
    */
-  retakes?: readonly { startWord: number; endWord: number; startSec: number; endSec: number }[];
+  retakes?: readonly {
+    startWord: number;
+    endWord: number;
+    startSec: number;
+    endSec: number;
+    confidence?: number;
+  }[];
 }
 
 export function buildCutlist({
@@ -88,9 +111,9 @@ export function buildCutlist({
 }: BuildCutlistArgs): Segment[] {
   const keepAll: Segment[] = [{ srcIn: 0, srcOut: duration, kind: "keep" }];
   // `exact` means exact: it is the escape hatch for "touch nothing", and a
-  // blooper or retake cut is still a cut. --blooper-marker or
-  // --collapse-retakes with --cleanup exact is a contradiction, and the flag
-  // the user typed second does not get to win.
+  // blooper or retake cut is still a cut. --blooper-marker (which also
+  // switches on retake collapse, 2026-08-16 gate) with --cleanup exact is a
+  // contradiction, and the flag the user typed second does not get to win.
   if (level === "exact") return keepAll;
   const policy = POLICIES[level];
   const words = transcript.words;
@@ -126,7 +149,7 @@ export function buildCutlist({
       start: r.startSec,
       end: r.endSec,
       reason: "retake",
-      confidence: 0.9,
+      confidence: r.confidence ?? 0.9,
       source: "acoustic",
     });
   }
@@ -268,7 +291,16 @@ export function buildCutlist({
     const overlapping = prev !== undefined && gap <= 1e-6;
     const wordless = prev !== undefined && !hasProtectedWordInside(prev.end, r.start);
     const foldableGap = wordless && gap <= Math.max(MIN_KEEP, policy.pauseMin);
-    if (prev && (overlapping || foldableGap)) {
+    // The one exception to word protection (MIN_KEEP_AFTER_RETAKE's why): a
+    // worded sliver this short survives only between two cuts, and when one
+    // of those cuts is a retake the sliver is debris of the discarded
+    // attempt. Requires the retake FLANK, not just the length — a worded gap
+    // between two silence removals must never fold, whatever its size.
+    const retakeSliver =
+      prev !== undefined &&
+      gap <= MIN_KEEP_AFTER_RETAKE &&
+      (prev.reason === "retake" || r.reason === "retake");
+    if (prev && (overlapping || foldableGap || retakeSliver)) {
       const prevDur = prev.end - prev.start;
       const curDur = r.end - r.start;
       prev.end = Math.max(prev.end, r.end);

package/src/dictionary.ts

@@ -0,0 +1,56 @@
+import type { Transcript } from "./schema";
+
+/**
+ * Deterministic casing for the user's dictionary (F4, 2026-08-16).
+ *
+ * Whisper biasing and the LLM repair pass get a word's SPELLING right; what
+ * neither guarantees is its CASE — a decoder nudged into "json" has still
+ * lost the acronym. This pass is the deterministic last word: any token that
+ * IS a dictionary term (exact case-insensitive match, punctuation aside)
+ * takes the term's canonical casing.
+ *
+ * Deliberately exact-match only: "Jason" is NEVER touched, even with "JSON"
+ * in the dictionary — deciding that a different word is a mishearing of a
+ * term is phonetic judgement, and that is the LLM repair pass's job, behind
+ * its guards. A deterministic pass that rewrote near-misses would be the
+ * un-gated rewrite pass §17 exists to forbid.
+ *
+ * Not on the browser surface: only `produce` runs it, and keeping it out of
+ * browser.ts keeps the Remotion bundle's import graph untouched.
+ */
+
+/**
+ * The same leading/trailing bounds `normalizeToken` (analyze.ts) strips, but
+ * keeping the pieces: the punctuation must survive the swap ("json." →
+ * "JSON.", quotes and commas intact), so the strip is a split here, not a
+ * deletion.
+ */
+const TOKEN_BOUNDS = /^([^\p{L}\p{N}]*)([\s\S]*?)([^\p{L}\p{N}-]*)$/u;
+
+export function canonicalizeDictionaryCasing(
+  transcript: Transcript,
+  dictionary: readonly string[],
+): Transcript {
+  // Keyed on the term's own lowercase, valued with its typed casing. A later
+  // duplicate (differing only in case) loses to the first — the user's list
+  // order is the only precedence signal there is.
+  const canonical = new Map<string, string>();
+  for (const raw of dictionary) {
+    const term = raw.trim();
+    const key = term.toLowerCase();
+    if (term && !canonical.has(key)) canonical.set(key, term);
+  }
+  if (canonical.size === 0) return transcript;
+  return {
+    ...transcript,
+    words: transcript.words.map((w) => {
+      const [, lead = "", core = "", trail = ""] = TOKEN_BOUNDS.exec(w.text) ?? [];
+      const want = canonical.get(core.toLowerCase());
+      // `want !== core` also guards the degenerate empty core; strict
+      // equality-of-lowercase above means this is a CASING change only —
+      // never a respelling, never added punctuation.
+      if (want === undefined || want === core) return w;
+      return { ...w, text: `${lead}${want}${trail}` };
+    }),
+  };
+}

package/src/export-premiere-project.ts

@@ -39,22 +39,34 @@ export interface PremiereProjectInput {
   zoomPlan: readonly ZoomSegment[];
   /** render-props' flag: true disables BOTH motion layers (zoom AND punch). */
   staticCamera?: boolean;
+  /**
+   * render-props' `punch` — the face-only jump-cut plan (2026-08-16, scenes'
+   * punch-plan.ts): its scale replaces the legacy 1.07 and its mask gates
+   * which spans punch. Absent means the LEGACY contract, so a pre-feature
+   * workdir exports exactly the camera its render had.
+   */
+  punch?: { scale: number; allowed: readonly boolean[] } | null;
   /** The OUTPUT frame (production.render), e.g. 1080×1920. */
   frame: { width: number; height: number };
 }
 
 /**
- * The render's jump-cut concealer, replicated from EdlVideo.tsx:41-51 — the
- * alternating toggle, the srcIn−prev.srcOut gap, and the INCLUSIVE >=
- * threshold must all match, or the exported project punches different clips
- * than the render did. Defaults mirror EdlVideoProps; they are parameters so
- * a drift in either place shows up as a failing hand-computed test, not a
- * silent divergence.
+ * The render's jump-cut concealer, replicated from scenes' `punchScalesFor`
+ * (punch-plan.ts, the loop EdlVideo renders) — the alternating toggle, the
+ * srcIn−prev.srcOut gap, and the INCLUSIVE >= threshold must all match, or
+ * the exported project punches different clips than the render did. The
+ * `allowed` mask must match too, down to the parity rule: the toggle flips
+ * on EVERY qualifying gap, masked spans included (stable indexing), and a
+ * masked span renders its punched turn at 1. `allowed[i] !== false` so a
+ * short mask reads as allowed, same as no mask at all. Defaults mirror
+ * EdlVideoProps; they are parameters so a drift in either place shows up as
+ * a failing hand-computed test, not a silent divergence.
  */
 export function punchScales(
   spans: readonly KeptSpan[],
   punchInScale = 1.07,
   punchThresholdSec = 0.15,
+  allowed?: readonly boolean[] | null,
 ): number[] {
   const out: number[] = [];
   let punched = false;
@@ -62,7 +74,7 @@ export function punchScales(
     const prev = spans[i - 1];
     const gap = prev ? spans[i]!.srcIn - prev.srcOut : 0;
     if (i > 0 && gap >= punchThresholdSec) punched = !punched;
-    out.push(punched ? punchInScale : 1);
+    out.push(punched && (!allowed || allowed[i] !== false) ? punchInScale : 1);
   }
   return out;
 }
@@ -174,7 +186,7 @@ export function srtFromCaptionLines(lines: readonly SrtLine[]): string {
 const fmt = (n: number): string => String(Number(n.toFixed(4)));
 
 export function buildPremiereProject(input: PremiereProjectInput): { xml: string; srt: string } {
-  const { production, spans, captionLines, zoomPlan, staticCamera, frame } = input;
+  const { production, spans, captionLines, zoomPlan, staticCamera, punch, frame } = input;
   const { path, probe } = production.source;
   // The whole document runs at the SOURCE rate (the marker exporter's
   // precedent): clip in/out and sequence start/end share one timebase, so no
@@ -189,7 +201,12 @@ export function buildPremiereProject(input: PremiereProjectInput): { xml: string
   const cover = coverTransform(probe, production.source.face, frame);
   // staticCamera kills BOTH motion drivers (produce's render-props contract:
   // zoomPlan alone can't reach the punch) — cover-crop is all that remains.
-  const punches = staticCamera ? spans.map(() => 1) : punchScales(spans);
+  // Otherwise the punch plan's scale and mask apply when present; `punch?.`
+  // collapses both absent and null to undefined, which punchScales reads as
+  // the legacy 1.07-everywhere the render itself falls back to.
+  const punches = staticCamera
+    ? spans.map(() => 1)
+    : punchScales(spans, punch?.scale, undefined, punch?.allowed);
 
   // Per-clip frame geometry. A sub-frame span still occupies one frame on
   // both axes — a zero-length clipitem is undefined importer behavior, same

package/src/fonts.ts

@@ -0,0 +1,17 @@
+import { fileURLToPath } from "node:url";
+
+/**
+ * Node-side half of the bundled caption font (see `captions.ts` for the
+ * browser-safe constants and the reason the font ships at all): the absolute
+ * path produce copies into the render's public dir. Split from captions.ts
+ * because `node:url` must never enter the Remotion bundle — captions.ts is
+ * on the `@ossclip/core/browser` surface.
+ *
+ * The URL below is face.ts's pico-cascade load shape, and the packaging test
+ * (R22 §111) scans this source for exactly that shape to assert the tarball
+ * carries the file — which is also why this comment doesn't spell the
+ * pattern out literally: the scanner reads comments too.
+ */
+export function nastaliqFontFile(): string {
+  return fileURLToPath(new URL("../assets/fonts/NotoNastaliqUrdu-Bold.ttf", import.meta.url));
+}

package/src/index.ts

@@ -16,6 +16,8 @@ export * from "./clip";
 export * from "./blooper";
 export * from "./retake";
 export * from "./captions";
+export * from "./fonts";
+export * from "./dictionary";
 export * from "./zoom";
 export * from "./grounding";
 export * from "./cta";
@@ -25,6 +27,7 @@ export * from "./normalize";
 export * from "./framing";
 export * from "./face";
 export * from "./cover";
+export * from "./thumbnail";
 export * from "./source-text";
 export * from "./report";
 export * from "./export-markers";

package/src/ingest.ts

@@ -85,22 +85,108 @@ export async function extractAudio(tools: IngestTools, src: string, outWav: stri
   ]);
 }
 
+/**
+ * Headroom over the exact displayed size so a zoomed span never renders from
+ * below-native pixels (2026-08-17 render-speed pass). The two motion drivers
+ * stack to at most ZOOM_MAX_SCALE (1.05) × FACE_PUNCH_SCALE (1.015) ≈ 1.066
+ * on any frame a new run emits, so 1.1 covers the worst momentary
+ * magnification with margin. (The legacy punch-less contract renders 1.07 —
+ * still under 1.1 — and pre-existing render-props keep their own full-res
+ * mezzanine anyway; see `mezzanineFileName`.)
+ */
+export const MEZZANINE_SCALE_MARGIN = 1.1;
+
+export interface MezzanineScale {
+  width: number;
+  height: number;
+  fps: number;
+}
+
+/** Nearest even dimension — yuv420 chroma subsampling needs both axes even. */
+function evenDim(v: number): number {
+  return Math.max(2, 2 * Math.round(v / 2));
+}
+
+/**
+ * The size and rate the mezzanine should be encoded at, or null when the
+ * source is already no larger than the render needs (2026-08-17 render-speed
+ * pass). Remotion's OffthreadVideo extracts EVERY sampled frame via ffmpeg
+ * on the CPU, so decode cost scales with pixels × fps — a 3456x2234@60
+ * source feeding a 1920x1080@30 render pays ~4.6× the pixels and 2× the
+ * frames the render ever shows.
+ *
+ * The target is the size at which the source is DISPLAYED: for `cover` the
+ * larger frame/source axis ratio (overflow is cropped, not shown), for
+ * `contain` the smaller (the whole frame fits inside). That target gets
+ * MEZZANINE_SCALE_MARGIN of headroom for the motion drivers, is rounded
+ * even for yuv420, and is capped at native — scaling UP would soften every
+ * frame for zero decode saved.
+ *
+ * fps: min(source, output) — frames the render never samples are pure decode
+ * waste. Safe because EDL `srcIn`/`srcOut` are SECONDS, not frame indexes:
+ * a 60→30 resample moves a cut boundary by at most 1/60s, the same
+ * magnitude whisper's word stamps already jitter by.
+ */
+export function mezzanineScale(
+  source: { width: number; height: number; fps: number },
+  frame: { width: number; height: number; fps: number },
+  sourceFit: "cover" | "contain",
+): MezzanineScale | null {
+  if (source.width <= 0 || source.height <= 0) return null;
+  const displayed =
+    sourceFit === "contain"
+      ? Math.min(frame.width / source.width, frame.height / source.height)
+      : Math.max(frame.width / source.width, frame.height / source.height);
+  const k = Math.min(1, displayed * MEZZANINE_SCALE_MARGIN);
+  // At the cap, keep the source's exact dims — even-rounding a size that is
+  // not being resampled would manufacture a 1px no-op rescale.
+  const width = k < 1 ? evenDim(source.width * k) : source.width;
+  const height = k < 1 ? evenDim(source.height * k) : source.height;
+  const fps = Math.min(source.fps, frame.fps);
+  if (width === source.width && height === source.height && fps >= source.fps) return null;
+  return { width, height, fps };
+}
+
+/**
+ * The mezzanine's filename, which IS its cache key: mezzanines are
+ * existence-keyed in the workdir, so the scale decision must live in the
+ * name — a pre-pass full-res `mezzanine.mp4` must never satisfy a run that
+ * will emit mezzanine-sized framing windows (they would land on a file with
+ * ~1.6× their pixel space and crop the wrong picture). Unscaled runs keep
+ * the legacy names so existing workdir caches stay valid; a scaled run
+ * rebuilds once under its own name and old workdirs' render-props keep
+ * referencing (and rendering from) the file they were emitted against.
+ */
+export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null): string {
+  const base = cropped ? "mezzanine-content" : "mezzanine";
+  if (!scale) return `${base}.mp4`;
+  return `${base}-${scale.width}x${scale.height}@${Math.round(scale.fps)}.mp4`;
+}
+
 /**
  * Re-encode with dense keyframes so EDL playback (<OffthreadVideo> with many
  * small trims) seeks fast. Optional — most sources play fine untouched —
  * EXCEPT when the source is letterboxed: then this pass also trims the baked
  * bars (`crop`), so everything downstream sees the picture, not picture+bars
  * (PLAN Task 7), and the pass stops being optional.
+ *
+ * `scale` (from `mezzanineScale`) downsizes to display size in the SAME
+ * pass, crop first — the scale dims are computed on the post-crop picture.
  */
 export async function makeMezzanine(
   tools: IngestTools,
   src: string,
   out: string,
-  opts: { cropVf?: string } = {},
+  opts: { cropVf?: string; scale?: MezzanineScale } = {},
 ): Promise<void> {
+  const vf = [
+    ...(opts.cropVf ? [opts.cropVf] : []),
+    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
+  ].join(",");
   await run(tools.ffmpegPath, [
     "-y", "-i", src,
-    ...(opts.cropVf ? ["-vf", opts.cropVf] : []),
+    ...(vf ? ["-vf", vf] : []),
+    ...(opts.scale ? ["-r", String(opts.scale.fps)] : []),
     "-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-g", "30", "-pix_fmt", "yuv420p",
     "-c:a", "aac", "-b:a", "192k",
     out,