@ossclip/core 0.1.24 → 0.1.26

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,

package/src/normalize.ts

@@ -1,6 +1,4 @@
-import { rename, rm } from "node:fs/promises";
-import { run } from "./exec";
-import type { ContentRectSegment } from "./content-rect";
+import { MIN_FRAMING_CLASS_FRAC, type ContentRectSegment } from "./content-rect";
 import type { WindowFace } from "./face";
 
 /**
@@ -14,21 +12,29 @@ import type { WindowFace } from "./face";
  * Smoothing the boundaries cannot fix that; the output would still alternate
  * between two shots.
  *
- * The fix is editorial, applied at bake time: pick ONE field of view — the
- * tightest the source ever shows, i.e. the strip, since the strip's pixels
- * are all those stretches have — and crop every other segment down to a
- * window of that same shape, placed on the measured face. The result is a
- * single, uniform landscape source with constant apparent framing, and the
- * ENTIRE downstream pipeline (face bias, source-text, cover, layouts, zoom)
- * runs its ordinary uniform-source path on it. Tight but stable, by choice.
+ * The fix is editorial: pick ONE field of view — the tightest the source ever
+ * shows, i.e. the strip, since the strip's pixels are all those stretches
+ * have — and crop every other segment down to a window of that same shape,
+ * placed on the measured face. One consistent apparent framing, by choice.
+ *
+ * The plan used to be BAKED into a re-encoded file. That ended with the
+ * 2026-08-16 incident: an over-eager plan destroyed 55% of a screen
+ * recording's picture and the only undo was deleting the baked mp4 — the
+ * editor could not even see the crop had happened. The plan is now emitted
+ * into render-props.json as `framingTimeline` and applied at render time as a
+ * transform (packages/scenes/src/content-crop.ts), fully visible to and
+ * counteractable from the editor. The plan's GEOMETRY is unchanged by that
+ * move: every window shares one aspect, so per-segment render-time cover
+ * shows the same apparent framing on both sides of every boundary — the
+ * invariant the bake existed to enforce (144bbfb).
  *
  * When even the strip cannot cover the output frame without excessive
- * upscaling, normalization refuses (`ok: false`) and the caller falls back to
- * render-time FIT — the strip shown at its natural size rather than
- * fake-zoomed (option (b)).
+ * upscaling — or the plan would discard too much picture — normalization
+ * refuses (`ok: false`) and the caller falls back to render-time FIT — the
+ * strip shown at its natural size rather than fake-zoomed (option (b)).
  */
 
-/** One baked stretch: this window of the source, scaled to the canvas. */
+/** One planned stretch: this window of the source, covering the slot. */
 export interface NormalizeSegment {
   startSec: number;
   endSec: number;
@@ -53,6 +59,28 @@ export interface NormalizePlan {
    * soft fake is worse than an honest fit.
    */
   coverUpscale: number;
+  /**
+   * Duration-weighted mean of the picture area each window discards from its
+   * segment's rect (`1 - windowArea / rectArea`). The other half of the
+   * quality gate, and the number the refusal log reports: coverUpscale alone
+   * measured softness, never loss (2026-08-16 incident).
+   */
+  areaDiscardWeighted: number;
+  /**
+   * Per timeline segment, what the window is anchored on. "face" means the
+   * segment passed `segmentIsFaceOnly` and its window is sized and placed on
+   * the measured face; "screen" means the window is the segment's own rect,
+   * centered and clipped to the shared aspect — the picture, not the person,
+   * is the subject there (2026-08-16 incident: the PiP was not the subject).
+   */
+  subject: ("face" | "screen")[];
+  /**
+   * Per timeline segment, where the subject sits INSIDE its window, both axes
+   * in 0..1. For a face segment this is the measured face centre relative to
+   * the final window, so a render-time cover crop can keep the head where the
+   * plan put it; a screen segment's subject is the whole picture, so 0.5/0.5.
+   */
+  bias: { x: number; y: number }[];
   ok: boolean;
 }
 
@@ -64,6 +92,52 @@ export interface NormalizePlan {
  */
 export const MAX_NORMALIZE_UPSCALE = 2.6;
 
+/**
+ * Ceiling on the duration-weighted mean fraction of picture area a plan may
+ * throw away. coverUpscale 0.77 passed while 37% of the frame area was being
+ * thrown away — the gate measured softness, never loss (2026-08-16 incident).
+ */
+export const MAX_MEAN_AREA_DISCARD = 0.5;
+
+/**
+ * Ceiling on the picture area a SCREEN-subject segment's window may discard
+ * from its own rect. A screen segment's window is its rect clipped to the
+ * shared aspect — losing more than this means the shared aspect is genuinely
+ * fighting that segment's shape, and cropping screen content slides text and
+ * UI out of frame. Face segments are exempt: a face crop discards area by
+ * design. Applies to MATERIAL segments only, mirroring the aspect vote — a
+ * sliver class gets no vote on the aspect, so it cannot veto the plan for
+ * being clipped to it either (the 1.1% dark segment of the 2026-08-16
+ * incident loses ~16% to the shared aspect; the duration-weighted mean gate
+ * is what bounds slivers).
+ */
+export const MAX_SCREEN_AREA_DISCARD = 0.1;
+
+/**
+ * Smallest face (box height over segment-rect height) that makes a segment
+ * "just a face". Equals DEFAULT_FACE.sizeFrac (stage.ts): a face smaller than
+ * the assumed arm's-length selfie box is not the frame's subject. 2026-08-16
+ * incident: the camera PiP measured 0.119 and the crop chased it, discarding
+ * the screen content that WAS the subject; a real talking head measures 0.28+.
+ */
+export const FACE_ONLY_MIN_FRAC = 0.22;
+
+/**
+ * Below this fraction of sampled frames with a detection, the measurement is
+ * not confident enough to reframe on — a face seen in under half the looks is
+ * as likely a false positive or an occasional glance at a webcam.
+ */
+export const FACE_MIN_DETECTION_RATIO = 0.5;
+
+/**
+ * Extra breathing room, as a fraction of the window height, kept above the
+ * crown and below the chin when the window slides to contain the head. The
+ * user's rule (2026-08-16): the ENTIRE head including hair stays in frame,
+ * with ~1% of margin — touching the frame edge reads as a crop even when
+ * nothing is technically cut.
+ */
+export const HEAD_WINDOW_MARGIN = 0.01;
+
 /**
  * A head is about 1.55x the detector's face box tall — the box bounds eyes,
  * nose and mouth, and `stage.ts` models the crown at 0.35x above it and the
@@ -96,6 +170,25 @@ const median = (xs: number[]): number => {
   return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
 };
 
+/**
+ * Is this segment essentially JUST a face — the only case where a
+ * face-anchored reframe is allowed (user decision, 2026-08-16)?
+ *
+ * Classified on the representative `sizeFrac`, not `sizeFracMax`: a segment
+ * is face-only by what it looks like most of the time, not at its one biggest
+ * lean-in (sizing, once classified, still uses the max — see planNormalization).
+ * The detection ratio guards against reframing on a face the detector barely
+ * ever saw.
+ */
+export function segmentIsFaceOnly(face: WindowFace | null): boolean {
+  if (!face) return false;
+  if (face.sizeFrac < FACE_ONLY_MIN_FRAC) return false;
+  return (
+    face.framesSampled > 0 &&
+    face.framesDetected / face.framesSampled >= FACE_MIN_DETECTION_RATIO
+  );
+}
+
 /**
  * Decide the canvas and each segment's crop window.
  *
@@ -119,6 +212,12 @@ const median = (xs: number[]): number => {
  * zoom out as far as its own rect — clamping there rather than inventing
  * pixels. The median (not the max) is what keeps that clamping rare and the
  * upscale inside the quality gate.
+ *
+ * All of that applies ONLY to segments that are essentially just a face
+ * (`segmentIsFaceOnly`). Anything else — a screen share, a face-and-screen
+ * mix, a PiP — keeps its whole rect, centered and clipped to the shared
+ * aspect: the 2026-08-16 incident chased a 0.119 PiP and cropped away the
+ * screen content that was the actual subject.
  */
 export function planNormalization(
   timeline: readonly ContentRectSegment[],
@@ -133,10 +232,22 @@ export function planNormalization(
       segments: [],
       faceFracOfCanvas: [],
       coverUpscale: Infinity,
+      // Nothing was planned, so nothing was discarded; `ok: false` is the
+      // refusal signal, not this number.
+      areaDiscardWeighted: 0,
+      subject: [],
+      bias: [],
       ok: false,
     };
   }
 
+  // Face-anchored sizing and placement ONLY where the frame is essentially
+  // just a face (user decision, 2026-08-16). Everything else is a "screen"
+  // subject: its window is its own rect, centered and clipped to the shared
+  // aspect — the incident's PiP (sizeFrac 0.119) must never drag the crop
+  // to the bottom-right corner of a screen recording again.
+  const faceOnly = timeline.map((_, i) => segmentIsFaceOnly(faces[i] ?? null));
+
   /**
    * The LARGEST face fraction in each segment, not the median. A window sized
    * on the median is correct only at the median moment: the author's clip
@@ -144,39 +255,60 @@ export function planNormalization(
    * the frame edge whenever they leaned in — which is precisely the frame they
    * flagged. Sizing on the maximum makes the tightest moment the safe one and
    * every other moment merely roomier.
+   *
+   * Only FACE-ONLY segments contribute a measurement: a PiP-sized face must
+   * not drag the target down for the real talking heads (2026-08-16 incident).
    */
-  const measured = timeline.map((_, i) => faces[i]?.sizeFracMax ?? faces[i]?.sizeFrac ?? null);
+  const measured = timeline.map((_, i) =>
+    faceOnly[i] ? (faces[i]!.sizeFracMax ?? faces[i]!.sizeFrac) : null,
+  );
   const known = measured.filter((v): v is number => v !== null);
 
   // ---- Window heights ------------------------------------------------------
-  // Without a single measurement there is no subject to hold constant, so the
-  // rect-shaped fallback stands: the tightest field of view, uniformly.
+  // Without a single face-only segment there is no subject to hold constant,
+  // and the whole plan degrades to rect-shaped windows: the tightest field of
+  // view, uniformly, with nothing anchored on a face.
   const target = known.length > 0 ? Math.min(median(known), MAX_FACE_FRACTION) : null;
-  const rectShapedHeights = (): number[] => {
-    const canvasRect = boxed.reduce((a, b) => (b.rect.h < a.rect.h ? b : a)).rect;
-    const a = canvasRect.w / canvasRect.h;
-    return timeline.map((s) => even(Math.min(s.rect.w, s.rect.h * a) / a));
-  };
-  const windowHeights =
-    target === null
-      ? rectShapedHeights()
-      : timeline.map((s, i) => {
-          // An unmeasured segment inherits the median fraction of the segments
-          // framed like it (same rect height), so it is sized in ITS OWN class
-          // rather than averaged across two different shots.
-          const sameClass = timeline.flatMap((o, j) =>
-            measured[j] !== null && Math.abs(o.rect.h - s.rect.h) <= 2 ? [measured[j]!] : [],
-          );
-          const frac = measured[i] ?? (sameClass.length > 0 ? median(sameClass) : median(known));
-          return even(clamp((frac * s.rect.h) / target, 16, s.rect.h));
-        });
+  const canvasRect = boxed.reduce((a, b) => (b.rect.h < a.rect.h ? b : a)).rect;
+  const canvasRectAspect = canvasRect.w / canvasRect.h;
+  /** The tallest window of the tightest rect's shape that fits in `s.rect`. */
+  const rectShapedHeight = (s: ContentRectSegment): number =>
+    even(Math.min(s.rect.w, s.rect.h * canvasRectAspect) / canvasRectAspect);
+  const windowHeights = timeline.map((s, i) =>
+    target === null || !faceOnly[i]
+      ? rectShapedHeight(s)
+      : even(clamp((measured[i]! * s.rect.h) / target, 16, s.rect.h)),
+  );
 
   // ---- Canvas --------------------------------------------------------------
-  // The widest aspect every window can actually hold. Wider than the output's
-  // own aspect leaves the stage some horizontal freedom for the face bias;
-  // narrower simply means the output crops height, which cover already does.
+  // The widest aspect every MATERIAL window can actually hold. Wider than the
+  // output's own aspect leaves the stage some horizontal freedom for the face
+  // bias; narrower simply means the output crops height, which cover already
+  // does.
+  //
+  // Material = the segment's framing class (same rect within 2px) totals at
+  // least
+  // MIN_FRAMING_CLASS_FRAC of the runtime — the constant content-rect's
+  // materiality filter uses, belt-and-braces with it. A sliver class still gets a
+  // window — the rect clamp below bounds it — it just gets no vote here: one
+  // 15.4s segment (1.1% of a 1435s take, rect 2848x2234) set canvas aspect
+  // 1.2748 for the whole video and baked away 28% of source width
+  // (2026-08-16 incident).
+  const totalDur = timeline.reduce((a, s) => a + Math.max(0, s.endSec - s.startSec), 0);
+  const classDur = timeline.map((s) =>
+    timeline.reduce(
+      (a, o) =>
+        Math.abs(o.rect.w - s.rect.w) <= 2 && Math.abs(o.rect.h - s.rect.h) <= 2
+          ? a + Math.max(0, o.endSec - o.startSec)
+          : a,
+      0,
+    ),
+  );
+  const material = classDur.map((d) => totalDur > 0 && d / totalDur >= MIN_FRAMING_CLASS_FRAC);
+  // If every class is a sliver there is no majority to defer to — all vote.
+  const votes = material.some(Boolean) ? material : material.map(() => true);
   const aspect = timeline.reduce(
-    (a, s, i) => Math.min(a, s.rect.w / windowHeights[i]!),
+    (a, s, i) => (votes[i] ? Math.min(a, s.rect.w / windowHeights[i]!) : a),
     Number.POSITIVE_INFINITY,
   );
   // The smallest window, so baking never upscales — the tightest segment sets
@@ -185,14 +317,16 @@ export function planNormalization(
   const canvas = { width: even(canvasHeight * aspect), height: canvasHeight };
 
   // ---- Face placement inside the window ------------------------------------
-  // Taken from the segments whose window IS their rect: their framing is the
-  // author's own and survives untouched, so it is the one to reproduce.
+  // Taken from the FACE-ONLY segments whose window IS their rect: their
+  // framing is the author's own and survives untouched, so it is the one to
+  // reproduce. Screen segments get no say — the incident's PiP at 0.88/0.76
+  // would anchor every window bottom-right.
   let wx = 0;
   let wy = 0;
   let weight = 0;
   timeline.forEach((seg, i) => {
     const f = faces[i];
-    if (!f || windowHeights[i]! < seg.rect.h - 2) return;
+    if (!f || !faceOnly[i] || windowHeights[i]! < seg.rect.h - 2) return;
     const dur = Math.max(1e-6, seg.endSec - seg.startSec);
     wx += f.centerXFrac * dur;
     wy += f.centerYFrac * dur;
@@ -205,31 +339,54 @@ export function planNormalization(
     const r = seg.rect;
     const wH = windowHeights[i]!;
     const wW = even(Math.min(r.w, wH * aspect));
-    const f = faces[i];
-    // Face position in source px; the rect centre when nothing was measured.
-    const faceX = r.x + (f ? f.centerXFrac : 0.5) * r.w;
-    const faceY = r.y + (f ? f.centerYFrac : 0.5) * r.h;
+
+    // Screen subject: no face math at all. The window is the segment's own
+    // rect clipped to the shared aspect, centered on BOTH axes — the picture
+    // is the subject, and a centered clip is the only placement that does not
+    // pick a corner of it to sacrifice (2026-08-16 incident).
+    if (!faceOnly[i]) {
+      return {
+        startSec: seg.startSec,
+        endSec: seg.endSec,
+        window: {
+          x: even(r.x + (r.w - wW) / 2),
+          y: even(r.y + (r.h - wH) / 2),
+          w: wW,
+          h: wH,
+        },
+      };
+    }
+
+    const f = faces[i]!;
+    // Face position in source px.
+    const faceX = r.x + f.centerXFrac * r.w;
+    const faceY = r.y + f.centerYFrac * r.h;
     const x = even(clamp(faceX - targetX * wW, r.x, r.x + r.w - wW));
 
     let y = clamp(faceY - targetY * wH, r.y, r.y + r.h - wH);
     // Then slide — never resize — so the whole HEAD is inside the window at
     // the segment's largest face, since the aesthetic anchor above is about
-    // where the face sits, and this is about not amputating it. Bounded by
-    // the rect: if the head genuinely runs past the source's own edge there
-    // is nothing to slide toward, and the clamp leaves it where it was.
-    if (f) {
-      const maxFace = (f.sizeFracMax ?? f.sizeFrac) * r.h;
-      const headTop = faceY - HEAD_ABOVE * maxFace;
-      const headBottom = faceY + HEAD_BELOW * maxFace;
-      if (headBottom - headTop <= wH) {
-        y = clamp(y, headBottom - wH, headTop);
-      } else {
-        // Head taller than the window: centre it, so what is lost is shared
-        // between crown and chin instead of taking the whole bite off one end.
-        y = (headTop + headBottom) / 2 - wH / 2;
-      }
-      y = clamp(y, r.y, r.y + r.h - wH);
+    // where the face sits, and this is about not amputating it. The margin is
+    // the user's ~1% rule (2026-08-16): the entire head including hair stays
+    // in frame with a hair of breathing room — a crown touching the edge
+    // reads as cropped. Bounded by the rect: if the head genuinely runs past
+    // the source's own edge there is nothing to slide toward, and the clamp
+    // leaves it where it was.
+    const maxFace = (f.sizeFracMax ?? f.sizeFrac) * r.h;
+    const headTop = faceY - HEAD_ABOVE * maxFace;
+    const headBottom = faceY + HEAD_BELOW * maxFace;
+    const margin = HEAD_WINDOW_MARGIN * wH;
+    if (headBottom - headTop + 2 * margin <= wH) {
+      y = clamp(y, headBottom + margin - wH, headTop - margin);
+    } else if (headBottom - headTop <= wH) {
+      // Head fits but its margin does not: keep the head, split the shortfall.
+      y = clamp(y, headBottom - wH, headTop);
+    } else {
+      // Head taller than the window: centre it, so what is lost is shared
+      // between crown and chin instead of taking the whole bite off one end.
+      y = (headTop + headBottom) / 2 - wH / 2;
     }
+    y = clamp(y, r.y, r.y + r.h - wH);
     return {
       startSec: seg.startSec,
       endSec: seg.endSec,
@@ -237,6 +394,23 @@ export function planNormalization(
     };
   });
 
+  const subject = timeline.map((_, i): "face" | "screen" => (faceOnly[i] ? "face" : "screen"));
+  // Where the subject sits inside its FINAL window (post-clamp, post-even):
+  // the render-time cover crop uses this to keep the head where the plan put
+  // it. Clamped to 0..1 because a rect-bounded window can leave the face
+  // centre outside it in the degenerate edge cases the clamps above allow.
+  const bias = timeline.map((seg, i) => {
+    if (!faceOnly[i]) return { x: 0.5, y: 0.5 };
+    const f = faces[i]!;
+    const w = segments[i]!.window;
+    const faceX = seg.rect.x + f.centerXFrac * seg.rect.w;
+    const faceY = seg.rect.y + f.centerYFrac * seg.rect.h;
+    return {
+      x: clamp(w.w > 0 ? (faceX - w.x) / w.w : 0.5, 0, 1),
+      y: clamp(w.h > 0 ? (faceY - w.y) / w.h : 0.5, 0, 1),
+    };
+  });
+
   // Cover the output with the canvas: for a canvas wider than the output's
   // aspect the height binds, otherwise the width does.
   const coverUpscale =
@@ -246,19 +420,54 @@ export function planNormalization(
 
   // What each segment actually achieved once its window is scaled to the
   // canvas — measured from the plan, never assumed to equal the target: a
-  // segment clamped at its own rect lands wherever its rect put it.
+  // segment clamped at its own rect lands wherever its rect put it. A screen
+  // segment reports 0: it has no face SUBJECT, and downstream framing advice
+  // (assessCueFraming, framing.ts) rightly skips zeros rather than warning
+  // about the head of a PiP nobody is framing on.
   const faceFracOfCanvas = timeline.map((seg, i) => {
     const frac = measured[i];
-    if (frac === null || frac === undefined) return target ?? 0;
+    if (frac === null || frac === undefined) return 0;
     return (frac * seg.rect.h) / segments[i]!.window.h;
   });
 
+  /** Picture area the window throws away from its segment's rect. */
+  const discardFrac = (i: number): number => {
+    const r = timeline[i]!.rect;
+    const w = segments[i]!.window;
+    return r.w * r.h > 0 ? 1 - (w.w * w.h) / (r.w * r.h) : 0;
+  };
+
+  // How much of each segment's picture the windows throw away, weighted by
+  // how long the viewer looks at it. coverUpscale 0.77 passed while 37% of
+  // the frame area was being thrown away — the gate measured softness, never
+  // loss (2026-08-16 incident).
+  const areaDiscardWeighted = timeline.reduce((acc, seg, i) => {
+    const dur = Math.max(0, seg.endSec - seg.startSec);
+    return acc + (totalDur > 0 ? dur / totalDur : 0) * discardFrac(i);
+  }, 0);
+
+  // Per-segment bound for SCREEN subjects: their window is meant to be
+  // (essentially) their whole rect, so a material screen segment losing more
+  // than MAX_SCREEN_AREA_DISCARD means the plan is cropping content nobody
+  // asked it to reframe — refuse and let render-time fit show it honestly.
+  // Face segments are exempt (a face crop discards area by design); sliver
+  // segments are exempt for the same reason they get no aspect vote.
+  const screenLossOk = timeline.every(
+    (_, i) => faceOnly[i] || !material[i] || discardFrac(i) <= MAX_SCREEN_AREA_DISCARD,
+  );
+
   return {
     canvas,
     segments,
     faceFracOfCanvas,
     coverUpscale,
-    ok: coverUpscale <= MAX_NORMALIZE_UPSCALE,
+    areaDiscardWeighted,
+    subject,
+    bias,
+    ok:
+      coverUpscale <= MAX_NORMALIZE_UPSCALE &&
+      areaDiscardWeighted <= MAX_MEAN_AREA_DISCARD &&
+      screenLossOk,
   };
 }
 
@@ -355,66 +564,3 @@ export function assessCueFraming(
   }
   return out;
 }
-
-/**
- * The ffmpeg filter graph baking the plan: each segment trimmed, cropped to
- * its window, scaled to the canvas, and the pieces concatenated back into one
- * continuous stream. The segment boundaries partition the source exactly, so
- * the output timeline equals the input's and the untouched audio stays in
- * sync.
- */
-export function normalizationFilterGraph(plan: NormalizePlan): string {
-  const parts = plan.segments.map((s, i) => {
-    const w = s.window;
-    return (
-      `[0:v]trim=start=${s.startSec.toFixed(3)}:end=${s.endSec.toFixed(3)},` +
-      `setpts=PTS-STARTPTS,crop=${w.w}:${w.h}:${w.x}:${w.y},` +
-      // setsar=1 is load-bearing, not tidiness (R27 §125). Every segment is
-      // scaled to the SAME canvas, but from a DIFFERENT crop, and ffmpeg
-      // derives a sample aspect from that ratio: a 946x1682 crop yields SAR
-      // 1683:1682 and a 932x1660 crop 1377:1376. `concat` requires identical
-      // SAR across inputs and aborts the whole bake when they disagree, so a
-      // take whose framing varies — exactly the take normalization exists
-      // for — failed to render at all.
-      `scale=${plan.canvas.width}:${plan.canvas.height},setsar=1[v${i}]`
-    );
-  });
-  const inputs = plan.segments.map((_, i) => `[v${i}]`).join("");
-  return `${parts.join(";")};${inputs}concat=n=${plan.segments.length}:v=1:a=0[v]`;
-}
-
-/**
- * Bake the normalized source. Encoded with the mezzanine's own settings
- * (dense keyframes) because it REPLACES the mezzanine — normalizing and then
- * re-encoding for seekability would be two generations of loss for nothing.
- */
-export async function bakeNormalizedSource(
-  tools: { ffmpegPath: string },
-  input: string,
-  plan: NormalizePlan,
-  outPath: string,
-): Promise<void> {
-  // Encode to a sibling temp path and rename only on success (R27 §125).
-  // ffmpeg writes the container header as it goes, so a bake that dies
-  // mid-graph leaves a file with no `moov` atom — and the cache upstream keys
-  // on EXISTENCE, so that corpse is then reused as a valid normalized source
-  // on every later run. The failure surfaces as "moov atom not found" from a
-  // step that never ran, and deleting the workdir is the only way out. Rename
-  // is atomic on a POSIX filesystem, so the cache can only ever see a file
-  // ffmpeg finished writing.
-  const partial = `${outPath}.partial.mp4`;
-  try {
-    await run(tools.ffmpegPath, [
-      "-y", "-i", input,
-      "-filter_complex", normalizationFilterGraph(plan),
-      "-map", "[v]", "-map", "0:a?",
-      "-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-g", "30", "-pix_fmt", "yuv420p",
-      "-c:a", "aac", "-b:a", "192k",
-      partial,
-    ]);
-    await rename(partial, outPath);
-  } catch (err) {
-    await rm(partial, { force: true });
-    throw err;
-  }
-}