@cueframe/kernel 0.0.1

package/dist/_members/core/render/deriveTrajectory.js

@@ -0,0 +1,889 @@
+/**
+ * deriveTrajectory — PURE TypeScript STAGE-B crop-trajectory math (the cheap
+ * "apply a crop intent" half), derived over a cached source-level `subjectTrack`.
+ *
+ * This is the SINGLE crop derivation for EVERY render surface — the agent's
+ * in-loop capture, the verifier eval, AND the customer ship render — by
+ * construction: each surface calls THIS function over the SAME cached track +
+ * the SAME authored reframe, so the trajectory is identical bytes with no
+ * pre-baked variant cache to drift. Render-time-resolution (2026-06-14): the
+ * trajectory is DERIVED INLINE at render, never looked up as a baked variant,
+ * which deleted the trajectory variant cache + its `variant_not_baked` bug class.
+ *
+ * Lives in @cueframe/execution/core (`@cueframe/core/render`) — it depends only
+ * on TYPES from @cueframe/perception (`SubjectTrack`/`Face`/`FaceBox`) and
+ * @cueframe/composition (`ReframeSegment` + the eased-ramp helpers), both legal
+ * execution-framework dependencies (execution MAY depend on perception +
+ * composition). The Modal `reframe_bake` re-detection path is retired — there is
+ * one derivation, so there is no TS↔Python drift to guard against.
+ *
+ * Output shape is the canonical `TrajectoryData` from
+ * @cueframe/composition/reframe/trajectory — the SSOT that both this producer and
+ * the renderer (CropFromTrajectory.tsx) import; neither declares a local mirror.
+ *
+ * See brain/Projects/CueFrame/specs/2026-06-14-render-time-resolution-design.md.
+ */
+// Eased zoom / center-pan ramps live in @cueframe/composition (the SINGLE source
+// of truth shared with the renderer's still path), so the still and video paths
+// can't drift. Imported here; re-exported for this module's existing test surface.
+import { buildEasedZooms, buildPannedCenters, CAPTION_BAND_RESERVE } from '@cueframe/composition/reframe/trajectory';
+// The shot-scale target table + clamp — SSOT, shared with the plan-time punch-in
+// guard (`punchInWarrant`). Never re-declare these constants here.
+import { SHOT_SCALE_TARGET, shotScaleZoom } from '@cueframe/composition/reframe/shotScale';
+export { buildEasedZooms, buildPannedCenters, easeOutCubic } from '@cueframe/composition/reframe/trajectory';
+// Typed, fail-loud render error. CFERR-encoded so code+fix survive the Convex
+// action→route error serialization (see @cueframe/errors codec).
+import { CueframeError, encodeError } from '@cueframe/errors';
+// vcam (virtual-camera) subject selection + stability — the `all-faces` chase
+// killer (Phase 2) + the deadzone-glide tracking stage (Phase 3) + the `face`/
+// `active-speaker` single-subject adapter (P4 — those modes now run the SAME
+// geometric-deadzone path as all-faces, no longer the legacy `emaSmooth`).
+import { selectSubjectSet, selectSingleSubjectBoxes } from './vcam/subjectSet';
+import { buildRequiredRegions } from './vcam/requiredRegion';
+import { cameraPath } from './vcam/cameraPath';
+import { fitZoomPerShot } from './vcam/framing';
+import { segmentShots } from './vcam/shots';
+/**
+ * Normalized area of a face detection — used to rank faces largest-first
+ * (largest ≈ closest to camera = `face-0` by convention). Mirrors
+ * reframe_bake.py `_face_area` (width/height path; negatives clamp to 0).
+ */
+export function faceArea(face) {
+    return Math.max(0, face.width) * Math.max(0, face.height);
+}
+/**
+ * Filter the detector's face list by the segment's subject pick:
+ *  - `all-faces` → all faces (cropper fits the union bbox).
+ *  - `frame-center` → [] (cropper centers on the source geometric center).
+ *  - `face` faceId=`face-N` → the face with that STABLE tracker id this frame.
+ *    The roster the agent authors against carries the tracker's stable ids, so
+ *    `face-2` means "that tracked person," NOT "the 3rd-largest face this frame."
+ *    Absent this frame → [] (caller emits no center; EMA forward-fills) rather
+ *    than silently snapping to a DIFFERENT person — the old area-rank +
+ *    out-of-range→largest behavior is exactly what made the crop ping-pong
+ *    between speakers (brain Issue crop-subject-resolved-by-area-rank).
+ *  - The EMPTY-string faceId is a sentinel (the active-speaker degrade, see
+ *    deriveSegment) meaning "no specific subject this frame → largest face."
+ * Throws on an unknown kind.
+ *
+ * NB: the retired Python `reframe_bake._resolve_subject_faces` did area-rank;
+ * that path is dead (TS is the only live derivation), so there is no drift.
+ */
+export function resolveSubjectFaces(faces, subject) {
+    if (faces.length === 0)
+        return faces;
+    if (subject.kind === 'all-faces')
+        return faces;
+    if (subject.kind === 'frame-center')
+        return [];
+    // `point` is detection-free — it never selects a face. deriveSegment
+    // short-circuits before this is reached; kept exhaustive for safety.
+    if (subject.kind === 'point')
+        return [];
+    if (subject.kind === 'face') {
+        const faceId = subject.faceId;
+        // Sentinel: empty / non-`face-` id → "no specific subject → largest face"
+        // (the active-speaker degrade and legacy callers rely on this).
+        if (typeof faceId !== 'string' || faceId === '' || !faceId.startsWith('face-')) {
+            const ranked = [...faces].sort((a, b) => faceArea(b) - faceArea(a));
+            return ranked.slice(0, 1);
+        }
+        // Match the authored STABLE identity; absent this frame → [].
+        const match = faces.find((f) => f.faceId === faceId);
+        return match ? [match] : [];
+    }
+    throw new Error(`unknown_subject_kind: ${subject.kind}`);
+}
+/**
+ * The target crop center from face dets + subject pick. Mirrors
+ * reframe_bake.py `_selected_face_center`: `frame-center` (and no usable
+ * selection) → null (caller centers on source); otherwise the area-weighted
+ * centroid of the selected faces (degenerates to a single face's center).
+ */
+export function selectedFaceCenter(faces, subject) {
+    if (subject.kind === 'frame-center')
+        return null;
+    // `point` centers on a fixed authored location, independent of detection.
+    if (subject.kind === 'point')
+        return [subject.x, subject.y];
+    if (faces.length === 0)
+        return null;
+    const selected = resolveSubjectFaces(faces, subject);
+    if (selected.length === 0)
+        return null;
+    let totalArea = 0;
+    let cxAcc = 0;
+    let cyAcc = 0;
+    for (const f of selected) {
+        const area = faceArea(f) || 1e-6;
+        cxAcc += (f.x + f.width / 2) * area;
+        cyAcc += (f.y + f.height / 2) * area;
+        totalArea += area;
+    }
+    return [cxAcc / totalArea, cyAcc / totalArea];
+}
+/** Normalized distance beyond which adjacent centers are treated as a shot
+ *  change (hard cut / new angle) and smoothing snaps instead of blending —
+ *  mirror of reframe_bake.py `JUMP_THRESHOLD`. */
+export const JUMP_THRESHOLD = 0.15;
+/** Minimum fraction of a segment's frames in which an authored `face` subject
+ *  must actually be tracked. Below this, deriveTrajectory FAILS LOUD instead of
+ *  silently centering the crop — the authored identity isn't really in the clip
+ *  (tracker ID fragmentation). A genuine subject is present for the large
+ *  majority of frames it's framed over; 40% is a generous floor. */
+export const MIN_SUBJECT_RESOLUTION = 0.4;
+export function isJump(a, b) {
+    return Math.abs(a[0] - b[0]) > JUMP_THRESHOLD || Math.abs(a[1] - b[1]) > JUMP_THRESHOLD;
+}
+/**
+ * Shot-aware EMA on per-frame centers. Forward-fill nulls with the last-known
+ * position, then a forward + backward EMA pass, where BOTH passes snap (no
+ * blend) ONLY across a detector-reported shot cut (`cutFrames`).
+ *
+ * Phase 1 (vcam): the `isJump`/`JUMP_THRESHOLD` inference is GONE as a cut
+ * signal. A center jump is NEVER inferred to be a cut — that inference was the
+ * false-cut snap (a ByteTrack detection-lag jiggle read as a new shot →
+ * teleport). Cuts come ONLY from `shotBoundaries`. `isJump`/`JUMP_THRESHOLD`
+ * remain exported (legacy consumers) but no longer drive smoothing here.
+ *
+ * Phase 3 (vcam): the `all-faces` CAMERA-CENTER smoothing is now the deadzone-
+ * inclusion + Hamming-window stage in `cameraPath` (the camera TRACKS a moving
+ * group). `emaSmooth` stays for the SEPARABLE non-center use — the per-subject
+ * `face_box_series` the floor reads (`perSubjectSeries`) — and for the
+ * UNCHANGED face/active-speaker/frame-center center path (byte-identical to the
+ * pre-Phase-3 behavior, the mode-isolation invariant). It is NOT used for the
+ * all-faces centers any more.
+ */
+export function emaSmooth(centers, alpha = 0.4, cutFrames) {
+    const n = centers.length;
+    if (n === 0)
+        return [];
+    // A frame is a hard reset boundary ONLY when it STARTS a new shot per the
+    // detector (`cutFrames`, frame-exact). No jump inference.
+    const isCut = (i) => cutFrames?.has(i) ?? false;
+    // Fill nulls. A gap is normally forward-filled with the prior known position
+    // (a brief occlusion — the subject hasn't moved). When a SHOT CUT falls inside
+    // the gap, split it AT the cut: frames before the cut belong to the old shot
+    // (prior position), frames from the cut on belong to the new shot (next known
+    // position) — so the crop snaps at the cut, not frames late. With no detector
+    // cut in the gap, forward-fill (hold the old position) — no jump back-fill.
+    const fillFirst = centers.find((c) => c !== null) ?? [0.5, 0.5];
+    const filled = new Array(n);
+    let lastVal = fillFirst;
+    let i = 0;
+    while (i < n) {
+        if (centers[i] !== null) {
+            lastVal = centers[i];
+            filled[i] = lastVal;
+            i++;
+            continue;
+        }
+        let j = i;
+        while (j < n && centers[j] === null)
+            j++;
+        const nextVal = j < n ? centers[j] : lastVal;
+        // First detector cut at or after i, within the gap [i, j].
+        let cut = -1;
+        if (cutFrames) {
+            for (let k = i; k <= j; k++) {
+                if (isCut(k)) {
+                    cut = k;
+                    break;
+                }
+            }
+        }
+        if (cut >= 0) {
+            for (let k = i; k < j; k++)
+                filled[k] = k < cut ? lastVal : nextVal;
+        }
+        else {
+            for (let k = i; k < j; k++)
+                filled[k] = lastVal;
+        }
+        i = j;
+    }
+    // Forward EMA — reset (snap) ONLY at a detector shot cut.
+    const forward = [filled[0]];
+    for (let i = 1; i < n; i++) {
+        const prev = forward[i - 1];
+        const curr = filled[i];
+        if (isCut(i)) {
+            forward.push(curr);
+        }
+        else {
+            forward.push([
+                alpha * curr[0] + (1 - alpha) * prev[0],
+                alpha * curr[1] + (1 - alpha) * prev[1],
+            ]);
+        }
+    }
+    // Backward EMA — reset ONLY when the i→i+1 transition crosses a detector cut.
+    const final = new Array(n);
+    final[n - 1] = forward[n - 1];
+    for (let i = n - 2; i >= 0; i--) {
+        const nxt = final[i + 1];
+        const curr = forward[i];
+        if (isCut(i + 1)) {
+            final[i] = curr;
+        }
+        else {
+            final[i] = [
+                alpha * curr[0] + (1 - alpha) * nxt[0],
+                alpha * curr[1] + (1 - alpha) * nxt[1],
+            ];
+        }
+    }
+    return final;
+}
+/** Clamp to [0,1] — mirror of reframe_bake.py `_clip01`. */
+export function clip01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+/** Bottom-band fraction the render keeps clear for captions per aspect.
+ *  CAPTION_BAND_RESERVE is the SSOT in @cueframe/composition (imported above). */
+export function captionBandReserve(aspect) {
+    return CAPTION_BAND_RESERVE[aspect] ?? 0.0;
+}
+/** Output aspect as width/height (e.g. '9:16' → 0.5625). FAILS LOUD on a
+ *  malformed aspect — a silent 9/16 default frames every non-vertical render
+ *  vertically (no-fallbacks rule). Callers pass `composition.format.aspectRatio`,
+ *  which the Composition validator constrains to a known enum, so a throw here
+ *  is a genuine drift/bug, never a user-reachable path. */
+export function aspectWhRatio(aspect) {
+    const parts = aspect.split(':');
+    const w = Number(parts[0]);
+    const h = Number(parts[1]);
+    if (parts.length !== 2 || !Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h === 0) {
+        throw new Error(`aspectWhRatio: invalid aspect ratio '${aspect}' (expected 'W:H')`);
+    }
+    return w / h;
+}
+/**
+ * The crop window size (source-normalized) for a given `zoom_scale` + output
+ * aspect — the bake half of the renderer's `computeCropTransform`: the largest
+ * output-aspect rect that fits the source, scaled by the zoom (clamped to
+ * [0.4,1.0] like `bakedZoom`). Shared so the cameraPath deadzone (output-crop
+ * units) can convert to the source-normalized geometry the regions live in.
+ */
+export function cropWindowSizeFor(srcW, srcH, zoomScale, aspect) {
+    if (srcW <= 0 || srcH <= 0)
+        return { w: 1, h: 1 };
+    const outAR = aspectWhRatio(aspect);
+    const srcAR = srcW / srcH;
+    let cropW;
+    let cropH;
+    if (srcAR > outAR) {
+        cropH = srcH;
+        cropW = srcH * outAR;
+    }
+    else {
+        cropW = srcW;
+        cropH = srcW / outAR;
+    }
+    const bakedZoom = Math.max(0.4, Math.min(1.0, zoomScale));
+    cropW *= bakedZoom;
+    cropH *= bakedZoom;
+    return { w: cropW / srcW, h: cropH / srcH };
+}
+/** Return the value at the largest key ≤ `key` (fallback to the smallest key
+ *  when none precedes; null when empty) — mirror of `_nearest_kp_value`.
+ *  per-keyframe-speaker is a Map<frameOffset, faceId>. */
+export function nearestKpValue(d, key) {
+    if (d.size === 0)
+        return null;
+    const keys = [...d.keys()];
+    const preceding = keys.filter((k) => k <= key);
+    if (preceding.length > 0)
+        return d.get(Math.max(...preceding)) ?? null;
+    return d.get(Math.min(...keys)) ?? null;
+}
+/** Contiguous [startFrame, endFrame) ranges where `faceId` is the active
+ *  speaker; adjacent same-speaker spans merge — mirror of `_active_windows_for`.
+ *  Each keyframe pick holds until the next keyframe (last → frameCount). */
+export function activeWindowsFor(faceId, perKeyframeSpeaker, frameCount) {
+    if (perKeyframeSpeaker.size === 0)
+        return [];
+    const kfs = [...perKeyframeSpeaker.keys()].sort((a, b) => a - b);
+    const windows = [];
+    for (let j = 0; j < kfs.length; j++) {
+        const kf = kfs[j];
+        if (perKeyframeSpeaker.get(kf) !== faceId)
+            continue;
+        const start = kf;
+        const end = j + 1 < kfs.length ? kfs[j + 1] : frameCount;
+        const last = windows[windows.length - 1];
+        if (last && last[1] === start)
+            last[1] = end;
+        else
+            windows.push([start, end]);
+    }
+    return windows;
+}
+/**
+ * Build smoothed per-subject normalized face-box series + active windows from
+ * the tracker's per-frame `{faceId: [x1,y1,x2,y2]}` (pixel) output. Mirror of
+ * reframe_bake.py `_per_subject_series`: stable subject order = first
+ * appearance; centers + sizes EMA-smoothed (alpha 0.35) with the same shot-aware
+ * reset as the crop centers; frames with no tracked face stay null.
+ */
+export function perSubjectSeries(perFrameTracked, srcW, srcH, perKeyframeSpeaker, frameCount, cutFrames) {
+    if (srcW <= 0 || srcH <= 0)
+        return [];
+    // Stable subject order = first appearance across the segment.
+    const faceIds = [];
+    const seen = new Set();
+    for (const tracked of perFrameTracked) {
+        for (const fid of Object.keys(tracked)) {
+            if (!seen.has(fid)) {
+                seen.add(fid);
+                faceIds.push(fid);
+            }
+        }
+    }
+    const subjects = [];
+    for (const fid of faceIds) {
+        const centers = new Array(frameCount).fill(null);
+        const sizes = new Array(frameCount).fill(null);
+        for (let i = 0; i < frameCount; i++) {
+            const tracked = i < perFrameTracked.length ? perFrameTracked[i] : {};
+            const bbox = tracked[fid];
+            if (!bbox || bbox.length < 4)
+                continue;
+            const [x1, y1, x2, y2] = bbox;
+            centers[i] = [(x1 + x2) / 2 / srcW, (y1 + y2) / 2 / srcH];
+            sizes[i] = [Math.max(0, x2 - x1) / srcW, Math.max(0, y2 - y1) / srcH];
+        }
+        const smCenters = emaSmooth(centers, 0.35, cutFrames);
+        const smSizes = emaSmooth(sizes, 0.35, cutFrames);
+        const boxSeries = [];
+        for (let i = 0; i < frameCount; i++) {
+            if (centers[i] === null) {
+                boxSeries.push(null);
+                continue;
+            }
+            const [cx, cy] = smCenters[i];
+            const [w, h] = smSizes[i];
+            boxSeries.push([clip01(cx - w / 2), clip01(cy - h / 2), clip01(w), clip01(h)]);
+        }
+        subjects.push({
+            face_id: fid,
+            face_box_series: boxSeries,
+            active_windows: activeWindowsFor(fid, perKeyframeSpeaker, frameCount),
+        });
+    }
+    return subjects;
+}
+/** §22.1 target face-height fraction of the OUTPUT per editorial shot scale
+ *  (mirror of reframe_bake.py `_SHOT_SCALE_TARGET`). */
+/**
+ * §22.1 (Phase 4): calibrate ZOOM to the DETECTED face for an editorial shot
+ * scale. zoom = median(face_h_px)/fit_h / target, clamped [ZOOM_MIN, ZOOM_MAX].
+ * shotScale seeds ZOOM ONLY — verticalBias (headroom) is the agent's AUTHORED
+ * value, passed through verbatim; it is NEVER overridden here (the floor-vision
+ * fix). When the authored fields are omitted: zoom defaults to 1.0 (frame as-is)
+ * and headroom to 0 (dead-center, never auto-applied). Falls back to the authored
+ * zoom/bias when shotScale is unset or no face was detected.
+ *
+ * The target table + the clamp live in @cueframe/composition/reframe/shotScale —
+ * the SAME module the plan-time punch-in guard reads, so a shotScale the guard
+ * admitted and the zoom this bakes can never disagree. Do NOT re-declare them here.
+ *
+ * NOTE this honors whatever shotScale reaches it. Whether the punch-in was EARNED
+ * (is there room around the face? pixels to magnify?) is decided at the plan, by
+ * `punchInWarrant` in that same module. A shotScale arriving here that the warrant
+ * would refuse is a bug in the guard, not something to re-check.
+ */
+export function calibrateShotScale(shotScale, subjects, srcW, srcH, aspect, fallbackZoom, fallbackVbias, authoredSubject) {
+    const target = shotScale ? SHOT_SCALE_TARGET[shotScale] : undefined;
+    if (target === undefined || srcH <= 0)
+        return [fallbackZoom ?? 1.0, fallbackVbias ?? 0];
+    const outAr = aspectWhRatio(aspect);
+    const srcAr = srcW / srcH;
+    const fitH = srcAr > outAr ? srcH : srcW / outAr;
+    if (fitH <= 0)
+        return [fallbackZoom ?? 1.0, fallbackVbias ?? 0];
+    // Pool face heights from the AUTHORED subject only. Pooling every tracked
+    // person (the old `for (const s of subjects)`) let the OTHER speaker in a
+    // wide two-shot — small, far from camera — drag the median down, flooring
+    // `zoom` at 0.4 and over-tightening the crop until the subject's head was
+    // clipped (the R3 "head-cropped close-up" bug). The zoom must size to the
+    // subject the segment actually frames, not to whoever else is on screen.
+    // Non-`face` picks (all-faces / active-speaker / frame-center) have no single
+    // authored id, so they keep the full pool. Defensive: if the authored id is
+    // absent from the series (shouldn't happen — deriveTrajectory fails loud
+    // below MIN_SUBJECT_RESOLUTION first), fall back to all subjects.
+    const authoredPool = authoredSubject?.kind === 'face' && authoredSubject.faceId.startsWith('face-')
+        ? subjects.filter((s) => s.face_id === authoredSubject.faceId)
+        : subjects;
+    const pool = authoredPool.some((s) => (s.face_box_series ?? []).some((b) => b !== null))
+        ? authoredPool
+        : subjects;
+    const heights = [];
+    for (const s of pool) {
+        for (const b of s.face_box_series ?? []) {
+            if (b !== null && b.length >= 4)
+                heights.push(b[3] * srcH);
+        }
+    }
+    if (heights.length === 0)
+        return [fallbackZoom ?? 1.0, fallbackVbias ?? 0];
+    heights.sort((a, b) => a - b);
+    const medianH = heights[Math.floor(heights.length / 2)];
+    const baseFaceFrac = medianH / fitH;
+    if (baseFaceFrac <= 0)
+        return [fallbackZoom ?? 1.0, fallbackVbias ?? 0];
+    const zoom = shotScaleZoom(baseFaceFrac, shotScale);
+    // shotScale seeds zoom; headroom is the AUTHORED verticalBias (0 when omitted),
+    // never the old hardcoded -0.15 (the floor-vision fix). Phase 4.
+    return [zoom, fallbackVbias ?? 0];
+}
+// ── Contract: STAGE A output (the cached source-level subjectTrack) ──────────
+// TrajectorySubject / TrajectorySegment / TrajectoryData are imported + re-exported
+// from @cueframe/composition/reframe/trajectory at the top of this file (the SSOT).
+/**
+ * Derive ONE segment's per-frame crop centers + per-subject series from a
+ * segment-local slice of the cached track. Mirror of the STAGE B half of
+ * reframe_bake.py `_bake_segment` (steps 4–7): per-frame subject filter
+ * (active-speaker uses the nearest keyframe pick; otherwise largest/face-N) →
+ * shot-aware EMA (alpha 0.35) → holes land at [0.5,0.5] → per-subject series.
+ */
+export function deriveSegment(perFrameTracked, srcW, srcH, perKeyframeSpeaker, subject, cutFrames, fps, 
+// Output aspect + the segment's zoom — used ONLY by the all-faces cameraPath
+// to size the crop window the deadzone-inclusion gate must keep the subject
+// inside. Optional + trailing so the existing face/point/active-speaker/
+// frame-center callers (and the parity test) are unaffected; the all-faces
+// path falls back to a 9:16 / zoom-1.0 window when omitted (a conservative,
+// wide window — the gate still tracks, just with a slightly larger hold band).
+aspect, zoomScale) {
+    const frameCount = perFrameTracked.length;
+    // `point` is detection-free: the crop sits at the authored normalized
+    // location for every frame of the segment. Screen recordings carry no faces,
+    // so the face-resolution loop below would leave every center null and fill
+    // [0.5,0.5]; short-circuit to the authored point instead. resolvedFrames =
+    // frameCount because the subject is, by construction, present every frame.
+    if (subject.kind === 'point') {
+        const centers = new Array(frameCount)
+            .fill(null)
+            .map(() => [subject.x, subject.y]);
+        return { centers, subjects: [], resolvedFrames: frameCount };
+    }
+    // `all-faces` — the CHASE-KILLER (Phase 2) + DEADZONE-GLIDE TRACKING (Phase 3)
+    // path. Select a STABLE subject set (per-shot size-aware locked set → segment
+    // pool → dominance top-K → per-frame membership hysteresis); subjectSet now
+    // emits the per-frame framed-group UNION BOX, which we lower to a per-frame
+    // RequiredRegion (the padded box the crop must contain) and feed to cameraPath
+    // — the single deadzone-inclusion + Hamming-window stability stage. The camera
+    // HOLDS while the group stays inside the safe region of the crop, then GLIDES
+    // to re-contain it when it moves (a walking subject is TRACKED, not lost), and
+    // never chases per-frame transient micro-motion (the gate's hold band).
+    // Mode-isolated: only `all-faces` routes here; every other mode keeps the
+    // existing per-frame selectedFaceCenter → emaSmooth path below verbatim. The
+    // per-subject `subjects` series the floor reads is still produced by
+    // `perSubjectSeries` (unchanged), so this only changes WHERE the camera points.
+    // An empty locked set (faceless / crowd-only clip) → center-hold (a defined
+    // outcome, not a throw) — selectSubjectSet returns [0.5,0.5] every frame and a
+    // null region every frame, which cameraPath turns into a held center.
+    if (subject.kind === 'all-faces') {
+        const sel = selectSubjectSet(perFrameTracked, srcW, srcH, fps ?? 30, perKeyframeSpeaker, cutFrames ?? new Set());
+        // Build the canonical per-frame RequiredRegions (pad + per-shot outlier
+        // reject) — THE region the camera must contain — then run the single
+        // stability stage. The crop window the deadzone gate must keep the region
+        // inside is sized from the segment's authored zoom + output aspect (all-faces
+        // has no per-frame eased zoom, so one window per shot is exact).
+        const regions = buildRequiredRegions(sel.perFrameBoxes, fps ?? 30, cutFrames ?? new Set());
+        // PHASE 5 — automatic zoom-to-fit (ALL modes; all-faces is the headline). Size
+        // the crop PER SHOT to CONTAIN the shot-wide padded union of the locked group:
+        // a group that fits 9:16 is framed TIGHT (zoom < 1.0), an over-wide group
+        // pads-and-holds at zoom 1.0 + emits `overframed`. The min-shot-length floor
+        // (framing.ts) holds the zoom across a sub-second montage so it can't strobe.
+        // The deadzone-inclusion gate then operates inside this FITTED window (a
+        // tighter window has a proportionally tighter hold band — DEADZONE is a
+        // fraction of the crop), so the camera frames the zoom-fit group, not a
+        // stale wide window.
+        const effAspect = aspect ?? '9:16';
+        const shotFits = fitZoomPerShot(sel.perFrameBoxes, cutFrames ?? new Set(), srcW, srcH, effAspect, fps ?? 30, frameCount);
+        // Map each frame → its shot's fitted crop window (the window the deadzone gate
+        // must keep the region inside). Per-shot constant; cameraPath reads it per
+        // frame. The shot order matches `fitZoomPerShot` (both use `segmentShots`).
+        const shotRanges = segmentShots(cutFrames ?? new Set(), frameCount);
+        const winByFrame = new Array(frameCount);
+        const fallbackWin = cropWindowSizeFor(srcW, srcH, zoomScale ?? 1.0, effAspect);
+        for (let s = 0; s < shotRanges.length; s++) {
+            const fit = shotFits[s];
+            const win = fit
+                ? cropWindowSizeFor(srcW, srcH, fit.zoom, effAspect)
+                : fallbackWin;
+            for (let i = shotRanges[s].start; i < shotRanges[s].end; i++)
+                winByFrame[i] = win;
+        }
+        const cropFor = (frame) => winByFrame[frame] ?? fallbackWin;
+        const centers = cameraPath(regions, cropFor, fps ?? 30, cutFrames ?? new Set(), [0.5, 0.5]);
+        const subjects = perSubjectSeries(perFrameTracked, srcW, srcH, perKeyframeSpeaker, frameCount, cutFrames);
+        return { centers, subjects, resolvedFrames: sel.resolvedFrames, shotFits };
+    }
+    // `face` / `active-speaker` — the P4 MIGRATION. These were a per-frame
+    // `selectedFaceCenter` → `emaSmooth(0.35)` over a bare CENTROID. They now run the
+    // SAME geometric-deadzone path as `all-faces` (a DELIBERATE, re-eval'd behavior
+    // change — NOT byte-equivalent): the `topK=1` subjects adapter resolves the
+    // single chosen subject's per-frame BOX (its real extent), lowers it to a padded
+    // + outlier-rejected RequiredRegion (`buildRequiredRegions`, the same builder
+    // all-faces uses), and feeds it to `cameraPath` (the sealed geometric-deadzone
+    // stabilizer). The win, characterized in the P4 eval: a moving subject is TRACKED
+    // with a tighter intra-shot hold and a real box to contain (smoother + better
+    // inclusion than the old point-EMA chase). `frame-center` is the ONLY mode left
+    // on the bare centroid path below — it carries NO subject (selectedFaceCenter →
+    // null → [0.5,0.5]), so it is pure Lowering with an empty selection, byte-
+    // identical to before. `point` short-circuited above.
+    if (subject.kind === 'face' || subject.kind === 'active-speaker') {
+        const pick = subject.kind === 'face'
+            ? { kind: 'face', authoredFaceId: subject.faceId }
+            : { kind: 'active-speaker' };
+        const single = selectSingleSubjectBoxes(perFrameTracked, srcW, srcH, perKeyframeSpeaker, pick, (frame) => nearestKpValue(perKeyframeSpeaker, frame));
+        // Lower the per-frame chosen-subject box → the padded, outlier-rejected
+        // RequiredRegion the crop must contain, then run the single deadzone-inclusion
+        // + Hamming stability stage. A shot with NO resolved subject center-holds (the
+        // documented no-subject outcome; the old emaSmooth instead carried the last
+        // face position across an empty shot — a silent hold-last that framed an absent
+        // subject; the deadzone path is correct, `feedback_never_add_fallbacks`).
+        const regions = buildRequiredRegions(single.perFrameBoxes, fps ?? 30, cutFrames ?? new Set());
+        const effAspect = aspect ?? '9:16';
+        const win = cropWindowSizeFor(srcW, srcH, zoomScale ?? 1.0, effAspect);
+        const centers = cameraPath(regions, () => win, fps ?? 30, cutFrames ?? new Set(), [0.5, 0.5]);
+        const subjects = perSubjectSeries(perFrameTracked, srcW, srcH, perKeyframeSpeaker, frameCount, cutFrames);
+        return { centers, subjects, resolvedFrames: single.resolvedFrames };
+    }
+    // `frame-center` — the bare-centroid path (the ONLY remaining EMA caller). It
+    // carries no subject: `selectedFaceCenter` returns null every frame, so
+    // `emaSmooth` forward-fills [0.5,0.5] — the documented frame-center behavior,
+    // byte-identical to before P4.
+    const rawCenters = new Array(frameCount).fill(null);
+    for (let i = 0; i < frameCount; i++) {
+        const tracked = perFrameTracked[i];
+        if (!tracked || Object.keys(tracked).length === 0)
+            continue;
+        const faceDicts = Object.entries(tracked).map(([faceId, b]) => ({
+            faceId,
+            x: b[0] / srcW,
+            y: b[1] / srcH,
+            width: (b[2] - b[0]) / srcW,
+            height: (b[3] - b[1]) / srcH,
+        }));
+        rawCenters[i] = selectedFaceCenter(faceDicts, subject);
+    }
+    // How many frames a subject was ACTUALLY found in (a non-null center). For
+    // frame-center this is 0 (no subject) — the resolution gate exempts frame-center.
+    const resolvedFrames = rawCenters.reduce((n, c) => (c !== null ? n + 1 : n), 0);
+    const smoothed = emaSmooth(rawCenters, 0.35, cutFrames);
+    const centers = [];
+    for (let i = 0; i < frameCount; i++) {
+        const c = i < smoothed.length ? smoothed[i] : null;
+        // All-null for frame-center → [0.5,0.5] (the intended center).
+        centers.push(c === null ? [0.5, 0.5] : [c[0], c[1]]);
+    }
+    const subjects = perSubjectSeries(perFrameTracked, srcW, srcH, perKeyframeSpeaker, frameCount, cutFrames);
+    return { centers, subjects, resolvedFrames };
+}
+/**
+ * Derive the full crop trajectory for a set of authored reframe segments over a
+ * cached source-level `subjectTrack` — the cheap per-candidate STAGE B run
+ * in-loop before perception. Mirror of reframe_bake.py `_bake_reframe_impl`'s
+ * segment loop: per segment, slice the window-local track to the segment's
+ * frame range, rebase the keyframe picks, derive centers + subjects, then
+ * calibrate zoom/vbias (§22.1) — emitting the `TrajectoryData` the render reads.
+ *
+ * Segment times are CLIP-RELATIVE and index the subjectTrack directly (the track
+ * is detected over the clip's source window, frame 0 = window start). FAILS LOUD
+ * when a specific-face segment resolves in too few frames — the symptom of
+ * tracker ID fragmentation, which used to be hidden by a silent frame-center
+ * fallback (the R3 "crop on nothing" bug).
+ */
+/**
+ * Map a reframe `Focus` → the internal `Subject` the derive math consumes
+ * (mode→kind, same variants). `shotScale` lives ONLY on the `face` focus
+ * variant in the reframe model; the loop reads it off the focus separately
+ * (it is NOT part of `Subject`). Pure rename — no behavior change.
+ */
+function focusToSubject(focus) {
+    switch (focus.mode) {
+        case 'face':
+            return { kind: 'face', faceId: focus.faceId };
+        case 'point':
+            return { kind: 'point', x: focus.x, y: focus.y };
+        case 'all-faces':
+            return { kind: 'all-faces' };
+        case 'frame-center':
+            return { kind: 'frame-center' };
+        case 'active-speaker':
+            return { kind: 'active-speaker' };
+    }
+}
+/** Frame-rounding tolerance for the sub-shot tiling assertion. Sub-shot bounds
+ *  are integer frame indices into the segment slice, so a legitimate tiling has
+ *  ZERO gap; the tolerance (< 1 frame) only absorbs a future float-bound rounding
+ *  drift, never a real dropped sub-shot (which is ≥ 1 frame). NOT a float `==`
+ *  (the first-draft bug that would false-throw on rounding). */
+const FRAME_ROUNDING_TOLERANCE = 0.5;
+/** Build the `trajectory_internal_gap` fail-loud error (registered, category
+ *  `internal`) for a sub-shot non-tiling within one authored segment. */
+function internalGap(seg, segIdx, detail) {
+    return new Error(encodeError(new CueframeError('trajectory_internal_gap', `authored segment ${segIdx} [${seg.startSec}–${seg.endSec}s]: sub-shots do not tile the segment — ${detail}. ` +
+        `A dropped sub-shot leaves an internal coverage gap the render would only catch downstream.`, { segment: [seg.startSec, seg.endSec], segIdx, detail })));
+}
+export function deriveTrajectory(track, segments, aspect, bakeVersion, 
+// D10 (P5 4b): true when the source is AI-GENERATED media
+// (`mediaItems.mediaSource === "generated"`). PURE param — the function never
+// reads Convex / the row; the activity resolves the flag and threads it here.
+// It changes ONLY which error a subject-mode resolution failure throws: a
+// generated clip emits the DISTINCT `subject_detection_failed_on_generated`
+// (the agent should use a GEOMETRIC reframe on faceless b-roll) instead of the
+// generic `subject_not_tracked`. The non-generated path is byte-for-byte
+// unchanged (the flag defaults false). Subject modes are face /
+// active-speaker / all-faces; frame-center / point are geometric and exempt.
+isGenerated = false) {
+    const fps = track.srcFps;
+    const perKf = new Map(Object.entries(track.perKeyframeSpeaker).map(([k, v]) => [Number(k), v]));
+    const out = [];
+    const trackLen = track.perFrameTracked.length;
+    // Window-local frame indices where a new shot begins (detector cuts). Absent
+    // on tracks from the pre-shots detector — the derivation then degrades to the
+    // jump-threshold inference (unchanged behavior).
+    const winCuts = track.shotBoundaries ?? [];
+    for (let idx = 0; idx < segments.length; idx++) {
+        const seg = segments[idx];
+        // Map the reframe segment onto the internal derive inputs — pure rename,
+        // identical math. focus→Subject; shotScale rides the `face` focus variant;
+        // zoom→fallbackZoom (default 1 = frame as-is); bias.y→verticalBias,
+        // bias.x→lateralBias (both default 0 when bias is absent).
+        const subject = focusToSubject(seg.focus);
+        const shotScale = seg.focus.mode === 'face' ? seg.focus.shotScale : undefined;
+        const zoomScale = seg.zoom;
+        // A `point`-focus segment with BOTH `ease` and `bias` is a Ken-Burns PAN
+        // (kenBurnsToReframe): `bias` is the pan ORIGIN offset and the motion is
+        // expressed as a per-frame CENTER ramp (buildPannedCenters), NOT a constant
+        // crop-window bias. So zero the crop bias for a pan — otherwise the pan would
+        // ALSO carry a static lateral shift. All other segments map bias verbatim.
+        const isEasedPan = seg.focus.mode === 'point' && !!seg.ease && !!seg.bias;
+        const verticalBias = isEasedPan ? 0 : seg.bias?.y;
+        const lateralBias = isEasedPan ? 0 : seg.bias?.x ?? 0;
+        // Clamp the segment's frame range to the cached track's extent. The detect
+        // window is meant to cover the whole clip, but a rounding overrun or a
+        // tail-shot read-failure can push segEnd past the track; without the clamp
+        // an over-range slice silently truncates and the render holds the last
+        // center for the uncovered tail. A fully-past segment (segStart ≥ trackLen)
+        // clamps to zero length and is skipped explicitly (review finding #5).
+        const segStart = Math.min(Math.round(seg.startSec * fps), trackLen);
+        const segEnd = Math.min(Math.round(seg.endSec * fps), trackLen);
+        if (segEnd - segStart <= 0)
+            continue;
+        const segPerFrame = track.perFrameTracked.slice(segStart, segEnd);
+        // Rebase the window-local keyframe picks into segment-local offsets.
+        const segKf = new Map();
+        for (const [k, v] of perKf) {
+            if (k >= segStart && k < segEnd)
+                segKf.set(k - segStart, v);
+        }
+        // Rebase the window-local shot cuts into segment-local offsets. Only cuts
+        // STRICTLY inside the segment are interior resets; a cut at segStart is the
+        // segment's own fresh start (frame 0 has no prior to blend), and a cut at
+        // segEnd belongs to the next segment.
+        const segCuts = new Set();
+        for (const b of winCuts) {
+            if (b > segStart && b < segEnd)
+                segCuts.add(b - segStart);
+        }
+        const { centers, subjects, resolvedFrames, shotFits } = deriveSegment(segPerFrame, track.srcW, track.srcH, segKf, subject, segCuts, fps, 
+        // The all-faces cameraPath sizes its deadzone-inclusion crop window from
+        // the output aspect + the segment's authored zoom (default 1.0). Other
+        // modes ignore these. Per-shot zoom calibration (below) is `face`-only, so
+        // the all-faces window matches the emitted `zoom_scale` for every sub-shot.
+        aspect, zoomScale);
+        if (centers.length === 0)
+            continue;
+        // D10 (P5 4b) — GENERATED footage fails loud on ANY under-resolved SUBJECT
+        // mode (face / active-speaker / all-faces). AI-generated b-roll often carries
+        // no detectable faces; a subject-mode reframe on it would silently center-hold
+        // on nobody. Throw a DISTINCT `subject_detection_failed_on_generated` (vs the
+        // generic `subject_not_tracked`) so the driving agent learns the corrective
+        // action is a GEOMETRIC reframe (frame-center / point — exempt below), not a
+        // re-detect. This branch is ONLY taken when `isGenerated` is true, so the
+        // uploaded path is untouched. `point`/`frame-center` are detection-free
+        // (resolvedFrames is geometric) and never enter this block.
+        if (isGenerated &&
+            (subject.kind === 'face' ||
+                subject.kind === 'active-speaker' ||
+                subject.kind === 'all-faces')) {
+            const rate = resolvedFrames / (segEnd - segStart);
+            if (rate < MIN_SUBJECT_RESOLUTION) {
+                throw new Error(encodeError(new CueframeError('subject_detection_failed_on_generated', `segment [${seg.startSec}–${seg.endSec}s] authored subject mode '${subject.kind}'` +
+                    (subject.kind === 'face' ? ` (face '${subject.faceId}')` : '') +
+                    ` resolved in only ${resolvedFrames}/${segEnd - segStart} frames ` +
+                    `(${(rate * 100).toFixed(0)}%) on AI-GENERATED media — generated b-roll carries ` +
+                    `no detectable subject for this reframe. Use a GEOMETRIC reframe (frame-center or ` +
+                    `point) on generated footage instead of a subject-tracking mode.`, {
+                    mode: subject.kind,
+                    ...(subject.kind === 'face' ? { faceId: subject.faceId } : {}),
+                    resolvedFrames,
+                    totalFrames: segEnd - segStart,
+                    segment: [seg.startSec, seg.endSec],
+                })));
+            }
+        }
+        // FAIL LOUD on an unresolvable authored face (no silent frame-center
+        // fallback). When the agent authors `subject: {faceId}` but that id is
+        // tracked in < MIN_SUBJECT_RESOLUTION of the segment's frames, the crop
+        // would silently sit at frame-center on nobody — the R3 bug. A real subject
+        // is present for most of the segment it's authored over; <40% means the
+        // per-frame tracker isn't carrying that identity (ID fragmentation), which
+        // must surface, not ship. frame-center / all-faces / active-speaker don't
+        // require a persistent specific id and are exempt. (The generated path above
+        // already short-circuited for `isGenerated`; this is the UNCHANGED uploaded
+        // gate.)
+        if (subject.kind === 'face') {
+            const rate = resolvedFrames / (segEnd - segStart);
+            if (rate < MIN_SUBJECT_RESOLUTION) {
+                throw new Error(encodeError(new CueframeError('subject_not_tracked', `segment [${seg.startSec}–${seg.endSec}s] authored subject face ` +
+                    `'${subject.faceId}' resolved in only ${resolvedFrames}/${segEnd - segStart} frames ` +
+                    `(${(rate * 100).toFixed(0)}%) — the per-frame tracker does not carry this identity ` +
+                    `across the segment (ID fragmentation). Refusing to ship a frame-centered crop on no subject.`, {
+                    faceId: subject.faceId,
+                    resolvedFrames,
+                    totalFrames: segEnd - segStart,
+                    segment: [seg.startSec, seg.endSec],
+                })));
+            }
+        }
+        // PER-SHOT zoom: split the authored segment at EVERY interior shot cut and
+        // calibrate zoom independently per sub-shot. The agent authors ONE shotScale
+        // across a segment that may MIX a close-up and a wide two-shot; a single
+        // segment-wide zoom is then too loose for the wide shot, so the subject sits
+        // small against the couch/backdrop (the R3 "couch frames"). Per-shot zoom
+        // sizes the subject to target in EVERY shot — a deliberate punch-in at the
+        // cut. Splitting at every detected cut (no minimum-length filter) also makes
+        // a cut that lands a few frames inside a segment — e.g. when the agent's
+        // authored boundary sits just before the real visual cut — fall on its own
+        // sub-shot with the correct (wide) zoom, instead of wearing the next shot's
+        // zoom for those frames (the cut "flash"). `segCuts` already excludes the
+        // segment's own start/end (b>segStart && b<segEnd), so every interior cut is a
+        // real within-segment shot change; zero-length spans are dropped below.
+        // Centers + each subject's face-box series are sliced and re-based to the
+        // sub-shot's frame 0 so the render's resolveSegmentAt (which indexes by
+        // `srcFrame - round(start_sec*fps)`) lands on the right frame.
+        const segLen = segEnd - segStart;
+        const interior = [...segCuts].sort((a, b) => a - b);
+        const bounds = [0, ...interior, segLen];
+        // Collect the EMITTED (non-skipped) sub-shot frame-spans for this authored
+        // segment, so we can assert (after the loop) that they TILE [0, segLen) — a
+        // sub-shot silently dropped (a future regression) would leave an internal gap
+        // the render's coverage guard only catches downstream. See the tiling
+        // assertion below (`trajectory_internal_gap`).
+        const emittedSpans = [];
+        // The per-sub-shot index (incremented only on a NON-skipped span) aligns 1:1
+        // with `shotFits` — both the bounds loop here and `framing.fitZoomPerShot`
+        // enumerate the SAME `segmentShots(segCuts, segLen)` ranges (same cut set,
+        // same zero-length drop, same order), so `shotFits[shotIdx]` is THIS sub-shot's
+        // automatic fit (Phase 5). `shotFits` is emitted ONLY for all-faces.
+        let shotIdx = 0;
+        for (let k = 0; k < bounds.length - 1; k++) {
+            const a = bounds[k];
+            const b = bounds[k + 1];
+            // EXEMPT skip-path: a zero-length sub-shot span (a cut landing on a segment
+            // boundary, or two coincident cuts) emits nothing — a legitimate drop, not
+            // an internal gap. Not recorded in emittedSpans (the tiling assertion treats
+            // these as measure-zero, per the spec's skip-path exemption).
+            if (b - a <= 0)
+                continue;
+            emittedSpans.push([a, b]);
+            const thisShot = shotIdx;
+            shotIdx++;
+            const subSubjects = subjects.map((s) => ({
+                face_id: s.face_id,
+                face_box_series: s.face_box_series.slice(a, b),
+                active_windows: s.active_windows
+                    .map(([ws, we]) => [Math.max(ws, a) - a, Math.min(we, b) - a])
+                    .filter(([ws, we]) => we > ws),
+            }));
+            // ZOOM source: `all-faces` uses the automatic zoom-to-fit (Phase 5) — size
+            // the crop to CONTAIN the shot-wide locked-group union (zoom < 1.0 when it
+            // fits) or pad-and-hold at 1.0 + flag `overframed` when the group is wider
+            // than the aspect. Every OTHER mode keeps `calibrateShotScale` (the
+            // editorial `shotScale` zoom for `face`/`active-speaker`, the authored
+            // fallback elsewhere) — byte-identical to before Phase 5.
+            const allFacesFit = subject.kind === 'all-faces' ? shotFits?.[thisShot] : undefined;
+            const [zoom, vbias] = allFacesFit
+                ? [allFacesFit.zoom, verticalBias ?? 0]
+                : calibrateShotScale(shotScale, subSubjects, track.srcW, track.srcH, aspect, zoomScale, verticalBias, subject);
+            const overframed = allFacesFit?.overframed === true;
+            const subLen = b - a;
+            // Eased centers (Ken-Burns PAN): ramp the per-frame center from the pan
+            // origin (point + bias) to the authored point over this sub-shot's ease-in.
+            const subCenters = isEasedPan && seg.focus.mode === 'point'
+                ? buildPannedCenters(subLen, fps, [seg.focus.x, seg.focus.y], [seg.bias?.x ?? 0, seg.bias?.y ?? 0], seg.ease?.in ?? 0)
+                : centers.slice(a, b);
+            // Per-frame `zooms` — ADDITIVE, emitted ONLY for an eased segment (the
+            // Ken-Burns / image ramp). The ramp holds at the calibrated `zoom` and
+            // sweeps to/from full-frame (1.0) at the eased edges. A segment with no
+            // `ease` omits this entirely → scalar `zoom_scale` path → byte-identical
+            // face/video parity.
+            const zooms = seg.ease
+                ? buildEasedZooms(subLen, fps, zoom, seg.ease.in, seg.ease.out)
+                : undefined;
+            out.push({
+                idx: out.length,
+                // Frame-based off the SNAPPED segStart (not the authored seg.startSec) so
+                // the segment times line up with the cut-aligned slice the render reads.
+                start_sec: (segStart + a) / fps,
+                end_sec: (segStart + b) / fps,
+                zoom_scale: zoom,
+                vertical_bias: vbias,
+                lateral_bias: lateralBias,
+                centers: subCenters,
+                subjects: subSubjects,
+                caption_band_reserve: captionBandReserve(aspect),
+                ...(zooms ? { zooms } : {}),
+                // Emit the DERIVED `overframed` outcome ONLY when true (an all-faces
+                // sub-shot whose group is wider than the aspect). Omitted (undefined) on
+                // a fitting group and every other mode, so the field never appears unless
+                // it is the documented widest-honest-frame case — keeps the trajectory
+                // JSON minimal and the golden diff scoped to real over-wide shots.
+                ...(overframed ? { overframed: true } : {}),
+            });
+        }
+        // ── trajectory_internal_gap: the sub-shots of THIS authored segment must
+        // TILE [0, segLen) (reframe spec Phase 6). A sub-shot silently dropped (a
+        // future regression in the bounds/skip logic) would leave an internal gap the
+        // render's coverage guard only catches downstream at render. Frame-rounding
+        // tolerance (NOT float ==): assert each emitted span's end meets the next
+        // span's start within FRAME_ROUNDING_TOLERANCE, and that the spans span
+        // [0, segLen). Skip-path-exempt: zero-length sub-shots are never recorded
+        // (measure zero); a segment that emitted NOTHING (every sub-shot skipped —
+        // e.g. all-zero-length, or the `centers.length===0`/`segLen<=0` upstream
+        // continues) is also exempt (no sub-shot to gap against). Cross-AUTHORED-
+        // segment gaps (real excludedRanges between segments) are out of scope — this
+        // asserts ONLY within one authored segment's sub-shots.
+        if (emittedSpans.length > 0) {
+            const sorted = [...emittedSpans].sort((x, y) => x[0] - y[0]);
+            // Leading coverage: the first sub-shot starts at frame 0 of the segment.
+            if (Math.abs(sorted[0][0]) > FRAME_ROUNDING_TOLERANCE) {
+                throw internalGap(seg, idx, `first sub-shot starts at frame ${sorted[0][0]}, not 0`);
+            }
+            // Trailing coverage: the last sub-shot ends at segLen.
+            if (Math.abs(sorted[sorted.length - 1][1] - segLen) > FRAME_ROUNDING_TOLERANCE) {
+                throw internalGap(seg, idx, `last sub-shot ends at frame ${sorted[sorted.length - 1][1]}, not ${segLen}`);
+            }
+            // Interior coverage: each span's end meets the next span's start.
+            for (let s = 0; s < sorted.length - 1; s++) {
+                if (sorted[s + 1][0] - sorted[s][1] > FRAME_ROUNDING_TOLERANCE) {
+                    throw internalGap(seg, idx, `gap between sub-shot ending at frame ${sorted[s][1]} and next starting at ${sorted[s + 1][0]}`);
+                }
+            }
+        }
+    }
+    return {
+        bake_version: bakeVersion,
+        aspect,
+        src_w: track.srcW,
+        src_h: track.srcH,
+        src_fps: fps,
+        segments: out,
+    };
+}