@ossclip/scenes 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/scenes",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "ossclip's scene library and stage geometry — React components shared by preview and render",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "zod": "^3.25.0",
-    "@ossclip/core": "0.1.23"
+    "@ossclip/core": "0.1.25"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/CaptionTrack.tsx

@@ -1,12 +1,24 @@
 import React from "react";
-import { AbsoluteFill, Sequence, useCurrentFrame, useVideoConfig } from "remotion";
+import {
+  AbsoluteFill,
+  Sequence,
+  continueRender,
+  delayRender,
+  staticFile,
+  useCurrentFrame,
+  useVideoConfig,
+} from "remotion";
 import {
   captionAnchorOf,
+  captionsNeedNastaliq,
   lineDirection,
+  NASTALIQ_FONT_NAME,
+  NASTALIQ_FONT_REL,
   type CaptionLine,
   type SceneCue,
+  type Theme,
 } from "@ossclip/core/browser";
-import { safeAreaFor, activeCueAt } from "./stage";
+import { safeAreaFor, activeCueAt, captionFontSizeFor, type FrameSize } from "./stage";
 import { frameWindow } from "./frames";
 import { captionAnchorAvoiding, regionsDuring, type OccupiedRegion } from "./source-fit";
 import { CAPTION_POP_SEC, easeOutQuad } from "./motion";
@@ -17,8 +29,16 @@ export interface CaptionTrackProps {
   cues?: SceneCue[];
   /** Vertical center of the caption block, as a fraction of frame height. */
   verticalAnchor?: number;
+  /** Explicit size wins outright; unset = frame-derived (`captionFontSizeFor`). */
   fontSizePx?: number;
   activeColor?: string;
+  /**
+   * Design tokens for the caption type (F6, 2026-08-16): `fontDisplay` and
+   * `fg` replace the historical literals so a config theme reaches the
+   * captions. Optional and absent-means-the-old-literals (`captionTypography`)
+   * so pre-theme callers and render-props render unchanged.
+   */
+  theme?: Theme;
   /**
    * The comment-CTA word: at the moment it is ASKED FOR, the caption word
    * renders quoted and capitalized — reinforcing the ask for muted viewers
@@ -68,6 +88,116 @@ export function inCtaWindow(
   );
 }
 
+/** The size a line renders at: an explicit prop wins outright, else the frame default. */
+export function resolveCaptionFontSize(
+  fontSizePx: number | undefined,
+  frame: FrameSize,
+): number {
+  return fontSizePx ?? captionFontSizeFor(frame);
+}
+
+/**
+ * Stroke width for a caption font size. The historical 10px stroke was tuned
+ * against 64px portrait type; fixed at 10 it swallows the smaller landscape
+ * letterforms (44px default, 2026-08-16), so it rides the font instead.
+ * Portrait output is byte-identical: 64 → 10.
+ */
+export function captionStrokePx(fontSizePx: number): number {
+  return (fontSizePx * 10) / 64;
+}
+
+/**
+ * Caption typography from the theme (F6, 2026-08-16). The fallbacks ARE the
+ * historical literals, so a themeless caller (pre-theme render-props, the
+ * editor before it passes one) renders byte-identically — and the default
+ * theme differs from them only in spelling white as #FFFFFF, the same color.
+ * The stroke's rgba is deliberately NOT themed: it is an outline for
+ * contrast against arbitrary video, not a palette color, and a light theme
+ * fg with a theme-matched light stroke would erase caption legibility.
+ * Pure — the theme prop's honored/absent matrix is testable without Remotion.
+ */
+export function captionTypography(theme: Theme | undefined): {
+  fontFamily: string;
+  color: string;
+} {
+  return {
+    fontFamily:
+      theme?.fontDisplay ?? "'Inter', 'Helvetica Neue', 'Arial Black', Arial, sans-serif",
+    color: theme?.fg ?? "white",
+  };
+}
+
+/**
+ * Per-line font stack (bundled Nastaliq, 2026-08-17). An RTL line leads with
+ * the bundled Noto Nastaliq Urdu; an LTR line keeps the resolved base stack
+ * BYTE-IDENTICAL, so Latin captions cannot change appearance. PREPENDED, not
+ * replacing: a config theme's `fontDisplay` (F6) stays the rest of the stack,
+ * so an RTL line still falls back to the user's own fonts for anything
+ * Nastaliq lacks. Within an RTL line, embedded Latin loanwords and digits DO
+ * render in Nastaliq's own Latin glyphs (verified against the v3.007 TTF's
+ * cmap: A–z and 0–9 are covered) — accepted, since one face per line keeps
+ * the weight consistent through a code-switched Urdu line.
+ */
+export function captionFontFamilyFor(
+  direction: "rtl" | "ltr",
+  baseFontFamily: string,
+): string {
+  return direction === "rtl" ? `'${NASTALIQ_FONT_NAME}', ${baseFontFamily}` : baseFontFamily;
+}
+
+/**
+ * Per-line line-height. Nastaliq's diagonal stacking runs far above and below
+ * the Latin baseline — the bundled face declares ascender−descender = 2.5×
+ * its em (read from the v3.007 TTF's hhea table; Inter is ~1.2×) — so at the
+ * historical 1.15 a wrapped Urdu line's stacks collide with the row beneath.
+ * RTL lines get 1.9: glyphs are never CLIPPED (nothing here sets
+ * overflow:hidden — the box is just spacing), and most caption lines are a
+ * single ≤3-word row, so going all the way to the font's own 2.5 would only
+ * push a rare two-row line out of its safe-area band. LTR lines keep 1.15,
+ * the byte-identical historical value.
+ */
+export function captionLineHeightFor(direction: "rtl" | "ltr"): number {
+  return direction === "rtl" ? 1.9 : 1.15;
+}
+
+/**
+ * Registers the bundled Nastaliq face for this render. FontFace + delayRender
+ * rather than a <style> @font-face: the render seeks and screenshots, so a
+ * lazily-fetched stylesheet font can miss the first captioned frames — the
+ * same no-wall-clock reasoning as the word-pop animation above. Mounted only
+ * when a line actually lays out RTL (`captionsNeedNastaliq`, the predicate
+ * produce's font copy shares), so pure-Latin runs fetch nothing. A load
+ * FAILURE continues the render on the fallback stack instead of cancelling:
+ * captions are the accessibility layer, and a wrong font still beats a dead
+ * render.
+ */
+const NastaliqFontLoader: React.FC = () => {
+  const [handle] = React.useState(() => delayRender(`load ${NASTALIQ_FONT_NAME}`));
+  React.useEffect(() => {
+    let done = false;
+    const finish = () => {
+      if (!done) {
+        done = true;
+        continueRender(handle);
+      }
+    };
+    const face = new FontFace(
+      NASTALIQ_FONT_NAME,
+      `url("${staticFile(NASTALIQ_FONT_REL)}") format("truetype")`,
+      // The captions render at fontWeight 900; declaring the (nominally 700)
+      // Bold face AS 900 makes it the exact match there, so the browser never
+      // synthetic-bolds Nastaliq's already-dense strokes on top.
+      { weight: "900" },
+    );
+    face.load().then((loaded) => {
+      document.fonts.add(loaded);
+      finish();
+    }, finish);
+    return finish;
+  }, [handle]);
+  return null;
+};
+
 const LineView: React.FC<{
   line: CaptionLine;
   /** This line's first word's index in the WHOLE caption stream — the id the
@@ -76,9 +206,22 @@ const LineView: React.FC<{
   verticalAnchor: number;
   fontSizePx: number;
   activeColor: string;
+  /** Resolved by `captionTypography` in the parent — one resolution per track. */
+  fontFamily: string;
+  textColor: string;
   ctaKeyword?: string;
   ctaWindow?: { startSec: number; endSec: number };
-}> = ({ line, wordOffset, verticalAnchor, fontSizePx, activeColor, ctaKeyword, ctaWindow }) => {
+}> = ({
+  line,
+  wordOffset,
+  verticalAnchor,
+  fontSizePx,
+  activeColor,
+  fontFamily,
+  textColor,
+  ctaKeyword,
+  ctaWindow,
+}) => {
   const frame = useCurrentFrame();
   const { fps, width, height } = useVideoConfig();
   const safeArea = safeAreaFor({ width, height });
@@ -109,16 +252,20 @@ const LineView: React.FC<{
           // Keep caption text clear of the platform's right-hand action rail.
           paddingLeft: `${safeArea.left * 100}%`,
           paddingRight: `${safeArea.right * 100}%`,
-          fontFamily:
-            "'Inter', 'Helvetica Neue', 'Arial Black', Arial, sans-serif",
+          // Direction-keyed (bundled Nastaliq, 2026-08-17): RTL lines lead
+          // with the bundled face and get its deeper line box; LTR lines are
+          // byte-identical to before — see the two helpers for the metrics.
+          fontFamily: captionFontFamilyFor(direction, fontFamily),
           fontWeight: 900,
           fontSize: fontSizePx,
-          lineHeight: 1.15,
+          lineHeight: captionLineHeightFor(direction),
           textAlign: "center",
-          color: "white",
-          WebkitTextStroke: "10px rgba(0,0,0,0.85)",
+          color: textColor,
+          WebkitTextStroke: `${captionStrokePx(fontSizePx)}px rgba(0,0,0,0.85)`,
           paintOrder: "stroke fill",
-          textShadow: "0 4px 24px rgba(0,0,0,0.55)",
+          // Shadow blur rides the font for the same reason as the stroke
+          // (portrait byte-identical: 64 → 24).
+          textShadow: `0 4px ${(fontSizePx * 24) / 64}px rgba(0,0,0,0.55)`,
         }}
       >
         {line.words.map((w, i) => {
@@ -161,7 +308,7 @@ const LineView: React.FC<{
                 // Colour stays keyed to the window, not the ramp: colour has
                 // no in-between worth animating, and lerping it would fight
                 // the stroke.
-                color: inWindow ? activeColor : "white",
+                color: inWindow ? activeColor : textColor,
               }}
             >
               {/* Per WORD, not per line: a line straddling the cue boundary
@@ -184,14 +331,19 @@ export const CaptionTrack: React.FC<CaptionTrackProps> = ({
   lines,
   cues = [],
   verticalAnchor = 0.76,
-  fontSizePx = 64,
+  fontSizePx,
   activeColor = "#FFE14D",
+  theme,
   ctaKeyword,
   ctaWindow,
   sourceTextRegions = [],
 }) => {
   const { fps, width, height } = useVideoConfig();
   const frame = { width, height };
+  // Frame-derived default (2026-08-16): an explicit prop still wins outright.
+  const resolvedFont = resolveCaptionFontSize(fontSizePx, frame);
+  // One resolution for the whole track — every line shares the theme's type.
+  const { fontFamily, color: textColor } = captionTypography(theme);
   // Each line's first-word index in the whole stream, so a word's id is
   // stable regardless of which line the layout put it on.
   const offsets: number[] = [];
@@ -202,6 +354,10 @@ export const CaptionTrack: React.FC<CaptionTrackProps> = ({
   }
   return (
     <AbsoluteFill>
+      {/* Mounted once for the whole track, and only when some line is RTL —
+          the same predicate produce keys the font copy on, so the fetch and
+          the file can't disagree. */}
+      {captionsNeedNastaliq(lines) ? <NastaliqFontLoader /> : null}
       {lines.map((line, i) => {
         const active = cues.length > 0 ? activeCueAt(cues, line.start) : null;
         // ONE rect-aware path for every line (R11 Task 2b). The old split —
@@ -237,8 +393,10 @@ export const CaptionTrack: React.FC<CaptionTrackProps> = ({
               verticalAnchor={anchor}
               // Per-scene size multiplier (R16 §64) — resolved per line like
               // the anchor, from the cue the line starts under.
-              fontSizePx={fontSizePx * (active?.captionScale ?? 1)}
+              fontSizePx={resolvedFont * (active?.captionScale ?? 1)}
               activeColor={activeColor}
+              fontFamily={fontFamily}
+              textColor={textColor}
               ctaKeyword={ctaKeyword}
               ctaWindow={ctaWindow}
             />

package/src/EdlVideo.tsx

@@ -2,6 +2,7 @@ import React, { useMemo } from "react";
 import { AbsoluteFill, OffthreadVideo, Sequence, useVideoConfig } from "remotion";
 import type { KeptSpan } from "@ossclip/core/browser";
 import { frameWindow } from "./frames";
+import { punchScalesFor, type PunchPlan } from "./punch-plan";
 
 export interface EdlVideoProps {
   src: string;
@@ -9,6 +10,14 @@ export interface EdlVideoProps {
   spans: KeptSpan[];
   /** Scale applied on alternating segments to conceal jump cuts. */
   punchInScale?: number;
+  /**
+   * The face-only punch plan from render-props (punch-plan.ts). When present
+   * its scale replaces `punchInScale` and its mask gates which spans render
+   * it; absent/null is the LEGACY contract — `punchInScale` everywhere — so
+   * every pre-feature render-props renders unchanged. Callers gate the raw
+   * JSON through `punchPropsFor` first (parse, never coerce).
+   */
+  punch?: PunchPlan | null;
   /** Removed gaps shorter than this don't toggle the punch-in (cut is invisible anyway). */
   punchThresholdSec?: number;
   /** Audio micro-fade at each cut boundary, in seconds. */
@@ -32,23 +41,20 @@ export const EdlVideo: React.FC<EdlVideoProps> = ({
   src,
   spans,
   punchInScale = 1.07,
+  punch = null,
   punchThresholdSec = 0.15,
   audioFadeSec = 0.01,
   background = "black",
 }) => {
   const { fps } = useVideoConfig();
 
-  const scales = useMemo(() => {
-    const out: number[] = [];
-    let punched = false;
-    for (let i = 0; i < spans.length; i++) {
-      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);
-    }
-    return out;
-  }, [spans, punchInScale, punchThresholdSec]);
+  // Extracted to punch-plan.ts so the mask/parity interaction is testable
+  // without mounting a composition; the loop there is the reference
+  // implementation the Premiere export mirrors.
+  const scales = useMemo(
+    () => punchScalesFor(spans, punch, punchInScale, punchThresholdSec),
+    [spans, punch, punchInScale, punchThresholdSec],
+  );
 
   const fadeFrames = Math.max(1, Math.round(audioFadeSec * fps));
 

package/src/VideoStage.tsx

@@ -3,15 +3,15 @@ import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
 import type {
   ContentRectSegment,
   FaceCrop,
+  FramingSegment,
   SceneCue,
   Theme,
   ZoomSegment,
 } from "@ossclip/core/browser";
 import { zoomScaleAt } from "@ossclip/core/browser";
-import { activeCueAt, backdropOpacityAt, videoSlotAt } from "./stage";
+import { activeCueAt, backdropOpacityAt, contentTransformFor, videoSlotAt } from "./stage";
 import {
-  contentBox,
-  contentRectAtOutput,
+  activeCropBox,
   sourceFitBox,
   type ContentCropMode,
   type SourceFit,
@@ -43,6 +43,14 @@ export const VideoStage: React.FC<{
    * timeline for it would crop the same bars twice.
    */
   contentTimeline?: ContentRectSegment[];
+  /**
+   * The render-time framing plan over SOURCE time — the props-based successor
+   * to the destructive normalization bake (2026-08-16 incident). Preferred
+   * over `contentTimeline` when present: the plan was computed FROM that
+   * timeline and already accounts for the bars. Absent means no plan, so
+   * every pre-existing render-props renders unchanged.
+   */
+  framingTimeline?: FramingSegment[];
   /** Kept spans, needed to read the timeline's SOURCE clock at an output time. */
   spans?: SpanLike[];
   /** The source's own pixel dimensions — the frame the timeline is measured in. */
@@ -68,6 +76,7 @@ export const VideoStage: React.FC<{
   zoomPlan,
   sourceTextRegions,
   contentTimeline,
+  framingTimeline,
   spans,
   sourceSize,
   contentCropMode = "cover",
@@ -117,13 +126,10 @@ export const VideoStage: React.FC<{
   const userScale = userVideo?.scale ?? 1;
   const userDx = userVideo?.dx ?? 0;
   const userDy = userVideo?.dy ?? 0;
-  const contentTransform =
-    [
-      userDx !== 0 || userDy !== 0 ? `translate(${userDx}px, ${userDy}px)` : "",
-      zoom * userScale !== 1 ? `scale(${zoom * userScale})` : "",
-    ]
-      .filter(Boolean)
-      .join(" ") || undefined;
+  // Built OUTSIDE the crop on purpose: the transform wraps ContentCrop below,
+  // so a user correction composes ON TOP of the framing plan instead of being
+  // consumed by it (see contentTransformFor's contract).
+  const contentTransform = contentTransformFor(zoom, userScale, userDx, userDy);
 
   return (
     <AbsoluteFill>
@@ -182,6 +188,7 @@ export const VideoStage: React.FC<{
           ) : (
             <ContentCrop
               timeline={contentTimeline}
+              framing={framingTimeline}
               spans={spans}
               sourceSize={sourceSize}
               mode={contentCropMode}
@@ -229,9 +236,14 @@ const FitBox: React.FC<{
  * covers the slot. The resulting box carries the source's own aspect ratio, so
  * the video's `object-fit: cover` has no overflow left to crop and its
  * `object-position` becomes a no-op — the bias has already been spent here.
+ *
+ * A `framing` plan (2026-08-16) takes the same box-shaped path with its own
+ * windows and bias; the which-crop-wins decision lives in `activeCropBox`, a
+ * pure function, so this component stays a dumb box painter.
  */
 const ContentCrop: React.FC<{
   timeline?: ContentRectSegment[];
+  framing?: FramingSegment[];
   spans?: SpanLike[];
   sourceSize?: { width: number; height: number };
   mode: ContentCropMode;
@@ -240,14 +252,9 @@ const ContentCrop: React.FC<{
   posX: number;
   posY: number;
   children: React.ReactNode;
-}> = ({ timeline, spans, sourceSize, mode, tSec, slot, posX, posY, children }) => {
-  const passthrough = <div style={{ position: "absolute", inset: 0 }}>{children}</div>;
-  if (!timeline || timeline.length < 2 || !sourceSize) return passthrough;
-
-  const rect = contentRectAtOutput(timeline, spans ?? [], tSec, sourceSize);
-  if (rect.full) return passthrough;
-
-  const box = contentBox(mode, sourceSize, rect, slot, posX, posY);
+}> = ({ timeline, framing, spans, sourceSize, mode, tSec, slot, posX, posY, children }) => {
+  const box = activeCropBox(framing, timeline, spans ?? [], tSec, sourceSize, mode, slot, posX, posY);
+  if (!box) return <div style={{ position: "absolute", inset: 0 }}>{children}</div>;
   return (
     <div
       style={{

package/src/content-crop.ts

@@ -1,4 +1,9 @@
-import { contentRectAt, type ContentRect, type ContentRectSegment } from "@ossclip/core/browser";
+import {
+  contentRectAt,
+  type ContentRect,
+  type ContentRectSegment,
+  type FramingSegment,
+} from "@ossclip/core/browser";
 
 /**
  * Rendering a source whose framing changes mid-take (PLAN Task C).
@@ -177,3 +182,73 @@ export function contentRectAtOutput(
   }
   return contentRectAt(timeline, sourceTimeAt(spans, outSec), source);
 }
+
+/**
+ * The framing segment to render at an OUTPUT time — the props-based successor
+ * to the destructive normalization bake (2026-08-16 incident: the bake
+ * crop+scale+re-encoded the mezzanine, irreversibly; expressed as data, the
+ * same window renders as a per-frame box the editor can see and counteract).
+ *
+ * Mirrors `contentRectAtOutput` exactly: the same span→source time mapping,
+ * and the same edge clamping `contentRectAt` does — a time outside the
+ * timeline resolves to its nearest segment, so a rounding error at a boundary
+ * cannot flash the unframed picture back for one frame. Null only when there
+ * is no plan at all, which is the legacy passthrough.
+ */
+export function framingWindowAtOutput(
+  timeline: readonly FramingSegment[],
+  spans: readonly SpanLike[],
+  outSec: number,
+): FramingSegment | null {
+  if (timeline.length === 0) return null;
+  const srcSec = sourceTimeAt(spans, outSec);
+  if (srcSec < timeline[0]!.startSec) return timeline[0]!;
+  for (const seg of timeline) {
+    if (srcSec >= seg.startSec && srcSec < seg.endSec) return seg;
+  }
+  return timeline[timeline.length - 1]!;
+}
+
+/**
+ * Which crop applies at this output moment, as the box to render — or null
+ * for the byte-identical passthrough every legacy render-props takes.
+ *
+ * Precedence: a framing plan wins over the letterbox content timeline. The
+ * plan was computed FROM that timeline and already accounts for the bars, so
+ * consulting both would crop the same pixels twice. A framing window renders
+ * through `contentCoverBox` with the segment's own bias as the anchor
+ * fractions — NOT the stage's face bias, which the plan already spent — so a
+ * "screen" full-rect window with a 0.5/0.5 bias reduces to plain centred
+ * cover: the same "one code path" property the module doc promises for
+ * content rects, and the reason the common case cannot drift.
+ *
+ * Pure and JSX-free on purpose: this IS the precedence decision, and it has
+ * to be testable without mounting a Remotion composition (house rule — pure
+ * logic separated from I/O).
+ */
+export function activeCropBox(
+  framing: readonly FramingSegment[] | undefined,
+  timeline: readonly ContentRectSegment[] | undefined,
+  spans: readonly SpanLike[],
+  outSec: number,
+  source: { width: number; height: number } | undefined,
+  mode: ContentCropMode,
+  slot: { width: number; height: number },
+  posX: number,
+  posY: number,
+): CoverBox | null {
+  // Both paths window the SOURCE frame; without its dimensions there is
+  // nothing to window — the same guard VideoStage always applied.
+  if (!source) return null;
+  if (framing && framing.length > 0) {
+    const seg = framingWindowAtOutput(framing, spans, outSec);
+    if (seg) return contentCoverBox(source, seg.window, slot, seg.bias.x, seg.bias.y);
+  }
+  // A single-segment content timeline means UNIFORM framing, which ffmpeg
+  // already cropped into the mezzanine — cropping again here would trim the
+  // same bars twice (the VideoStage guard, kept verbatim in this extraction).
+  if (!timeline || timeline.length < 2) return null;
+  const rect = contentRectAtOutput(timeline, spans, outSec, source);
+  if (rect.full) return null;
+  return contentBox(mode, source, rect, slot, posX, posY);
+}

package/src/index.ts

@@ -5,4 +5,5 @@ export { SceneLayer } from "./SceneLayer";
 export { Watermark } from "./Watermark";
 export * from "./stage";
 export * from "./watermark-layout";
+export * from "./punch-plan";
 export * from "./caption-visibility";

package/src/punch-plan.ts

@@ -0,0 +1,75 @@
+/**
+ * The face-only jump-cut punch plan (2026-08-16 incident, Task 6).
+ *
+ * `punch` in render-props is produce's per-span verdict on the cut punch-in:
+ * one scale, and a per-span mask saying which spans may render it. It exists
+ * because the legacy everywhere-punch scaled screen shares too, and punching
+ * a screen share SLIDES its content — text visibly drifting is worse than
+ * the jump the punch conceals. The scale itself dropped from the legacy 7%
+ * to ~1.5% (user decision 2026-08-16, "minimal, ~1%") for the same reason:
+ * on the spans that ARE allowed, a large punch reads as the camera lurching.
+ *
+ * ABSENT MEANS LEGACY: every pre-feature render-props.json has no `punch`
+ * key, and those renders must come out byte-identical to what they always
+ * were — the 1.07 punch on every alternating span. Presence is the opt-in.
+ *
+ * Pure and JSX-free (house rule): the mask/parity interaction is the whole
+ * behavior, and it has to be assertable without mounting a Remotion
+ * composition.
+ */
+
+export interface PunchPlan {
+  /** Scale allowed spans render on their punched turns (e.g. 1.015). */
+  scale: number;
+  /** Per-span gate, indexed like `spans`; false = never punch this span. */
+  allowed: boolean[];
+}
+
+/**
+ * Whether a render-props `punch` field is a plan this renderer will follow —
+ * `showWatermark`'s posture (watermark-layout.ts), parse-don't-coerce
+ * (CLAUDE.md): the file is user-visible and hand-editable, and a truncated
+ * or tweaked plan must fall back to the LEGACY behavior rather than scale
+ * spans by `undefined` or a string. Null is the legacy signal the callers
+ * already treat "no plan at all" as, so malformed and pre-feature converge
+ * on the one path that always worked.
+ */
+export function punchPropsFor(punch: unknown): PunchPlan | null {
+  if (typeof punch !== "object" || punch === null) return null;
+  const p = punch as { scale?: unknown; allowed?: unknown };
+  if (typeof p.scale !== "number" || !Number.isFinite(p.scale) || p.scale <= 0) return null;
+  if (!Array.isArray(p.allowed) || p.allowed.some((v) => typeof v !== "boolean")) return null;
+  return { scale: p.scale, allowed: p.allowed as boolean[] };
+}
+
+/**
+ * The per-span scales EdlVideo renders — the alternating jump-cut concealer,
+ * now mask-aware. THE PARITY STILL FLIPS ON EVERY QUALIFYING GAP, masked
+ * spans included: the toggle is stable indexing, so adding or removing a
+ * span from the mask can never re-phase which of the OTHER spans punch — a
+ * masked span simply renders its punched turn at 1 instead of the scale.
+ * `allowed[i] !== false` (not `=== true`): a mask shorter than the spans
+ * reads as allowed, matching the plan-less legacy default.
+ *
+ * export-premiere-project.ts (core) replicates this loop for the Premiere
+ * export and its doc comment demands lockstep — change one, change both,
+ * and both hand-computed tests.
+ */
+export function punchScalesFor(
+  spans: readonly { srcIn: number; srcOut: number }[],
+  plan: PunchPlan | null,
+  punchInScale: number,
+  punchThresholdSec: number,
+): number[] {
+  const scale = plan ? plan.scale : punchInScale;
+  const out: number[] = [];
+  let punched = false;
+  for (let i = 0; i < spans.length; i++) {
+    const prev = spans[i - 1];
+    const gap = prev ? spans[i]!.srcIn - prev.srcOut : 0;
+    if (i > 0 && gap >= punchThresholdSec) punched = !punched;
+    const allowed = plan ? plan.allowed[i] !== false : true;
+    out.push(punched && allowed ? scale : 1);
+  }
+  return out;
+}

package/src/stage.ts

@@ -141,6 +141,14 @@ export function objectPosYFor(
   face: FaceCrop,
   frame: FrameSize = PORTRAIT_FRAME,
 ): number {
+  // A face that is not the frame's SUBJECT must not steer the crop
+  // (2026-08-16 incident: the global face median landed on a screen
+  // recording's camera PiP — 12% of frame height, bottom-right — and pinned
+  // objectPosY to 1.0, cutting off the top 28% of every full-frame stretch).
+  // "screen" means the measured face is incidental: centre the cover instead.
+  // Strict equality — absent means "face", so every pre-existing
+  // render-props keeps its old behaviour byte-for-byte.
+  if (face.subject === "screen") return 0.5;
   const slotH = rect.h * frame.height;
   const displayedH = displayedHeight(rect, face, frame);
   const overflow = displayedH - slotH;
@@ -254,6 +262,10 @@ export function objectPosXFor(
   face: FaceCrop,
   frame: FrameSize = PORTRAIT_FRAME,
 ): number {
+  // Same subject guard as `objectPosYFor` (2026-08-16 incident): a "screen"
+  // frame's incidental face — a camera PiP in a corner — must not drag the
+  // horizontal window to that corner. Strict equality; absent means "face".
+  if (face.subject === "screen") return 0.5;
   const slotW = rect.w * frame.width;
   const slotH = rect.h * frame.height;
   const displayedW = Math.max(slotW, slotH * (face.sourceAspect ?? frame.width / frame.height));
@@ -381,6 +393,17 @@ export const COVER_TEXT_RECT: Rect = (() => {
 /** Approximate half-height of a caption line block, for free-band math/tests. */
 export const CAPTION_HALF_BAND = 0.045;
 
+/**
+ * Default caption font size for a frame. Portrait keeps the historical 64px
+ * (≈3.3% of a 1080x1920 frame's height); the same 64 in 1920x1080 is 5.9% of
+ * frame height and reads as a billboard (user complaint 2026-08-16), so
+ * landscape drops to 44 (≈4% of 1080). An explicit `fontSizePx` prop on
+ * CaptionTrack still wins over this default.
+ */
+export function captionFontSizeFor(frame: FrameSize): number {
+  return frame.width > frame.height ? 44 : 64;
+}
+
 /** A vertical interval in frame fractions. */
 export interface Band {
   start: number;
@@ -504,12 +527,18 @@ export function layoutSlots(
     avoidSlicingText(objectPosYFor(rect, face, frame), rect, face, textBands, frame);
   const posX = (rect: Rect) => objectPosXFor(rect, face, frame);
   const landscape = frame.width > frame.height;
+  // Landscape anchors sit LOWER than portrait's (user screenshot 2026-08-16:
+  // the frame-agnostic anchors below put landscape captions mid-frame — 0.7
+  // of a 16:9 frame is chest height, not a lower third). The legal ceiling is
+  // 0.835 = 1 − LANDSCAPE_SAFE_AREA.bottom (0.12) − CAPTION_HALF_BAND
+  // (0.045); each landscape anchor stays under it. Portrait literals are
+  // unchanged.
   switch (layout) {
     case "full-bleed":
       return {
         video: { rect: FULL, cornerRadius: 0, blurPx: 0, dim: 0, opacity: 1, objectPosY: posY(FULL), objectPosX: posX(FULL) },
         graphic: null,
-        captionAnchor: 0.7,
+        captionAnchor: landscape ? 0.80 : 0.7,
       };
     case "lower-third": {
       // Broadcast lower third: the picture stays whole; the card sits in the
@@ -565,7 +594,7 @@ export function layoutSlots(
           objectPosY: posY(PIP_RECT), objectPosX: posX(PIP_RECT),
         },
         graphic: { x: 0.06, y: 0.14, w: 0.78, h: 0.42 },
-        captionAnchor: 0.61,
+        captionAnchor: landscape ? 0.78 : 0.61,
       };
     case "graphic-only":
       return {
@@ -578,13 +607,13 @@ export function layoutSlots(
           objectPosY: posY(PIP_RECT), objectPosX: posX(PIP_RECT),
         },
         graphic: { x: 0.04, y: 0.14, w: 0.8, h: 0.54 },
-        captionAnchor: 0.73,
+        captionAnchor: landscape ? 0.80 : 0.73,
       };
     case "blurred-behind":
       return {
         video: { rect: FULL, cornerRadius: 0, blurPx: 22, dim: 0.55, opacity: 1, objectPosY: posY(FULL), objectPosX: posX(FULL) },
         graphic: { x: 0.07, y: 0.24, w: 0.77, h: 0.36 },
-        captionAnchor: 0.69,
+        captionAnchor: landscape ? 0.80 : 0.69,
       };
   }
 }
@@ -732,13 +761,50 @@ export function videoSlotAt(
   return target;
 }
 
+/**
+ * The CSS transform for the user's per-scene crop correction, composed with
+ * the idle zoom (multiplicative — VideoStage's §15 comment owns the why).
+ *
+ * Extracted pure to pin the compose-on-top contract of the render-time
+ * framing plan (2026-08-16): VideoStage applies this transform on the wrapper
+ * AROUND the framing crop box (`activeCropBox`), and the two are sealed off
+ * from each other by construction — this function's inputs are ONLY the zoom
+ * and the user's scale/dx/dy, and `activeCropBox` never sees an override. That
+ * separation is what makes the editor's "Reset framing" mean "return exactly
+ * to auto framing" instead of "return to auto framing as bent by the crop".
+ */
+export function contentTransformFor(
+  zoom: number,
+  userScale: number,
+  userDx: number,
+  userDy: number,
+): string | undefined {
+  return (
+    [
+      userDx !== 0 || userDy !== 0 ? `translate(${userDx}px, ${userDy}px)` : "",
+      zoom * userScale !== 1 ? `scale(${zoom * userScale})` : "",
+    ]
+      .filter(Boolean)
+      .join(" ") || undefined
+  );
+}
+
 /**
  * Caption anchor at time t. Resolved from the settled layout at the line's
  * start (never animated — a caption sliding mid-word reads as a bug).
+ *
+ * Frame-aware since 2026-08-16: anchors differ per frame shape, so a 16:9
+ * caller must pass its frame rather than inherit the portrait default.
  */
-export function captionAnchorAt(cues: readonly SceneCue[], tSec: number): number {
+export function captionAnchorAt(
+  cues: readonly SceneCue[],
+  tSec: number,
+  frame: FrameSize = PORTRAIT_FRAME,
+): number {
   const cue = activeCueAt(cues, tSec);
-  return cue ? layoutSlots(cue.layout).captionAnchor : layoutSlots("full-bleed").captionAnchor;
+  return cue
+    ? layoutSlots(cue.layout, DEFAULT_FACE, [], frame).captionAnchor
+    : layoutSlots("full-bleed", DEFAULT_FACE, [], frame).captionAnchor;
 }
 
 function backdropTarget(layout: Layout): number {