@cueframe/kernel 0.0.1

package/dist/_members/core/render/emphasis.d.ts

@@ -0,0 +1,13 @@
+export interface EmphasisWord {
+    poolItemId: string;
+    sourceStart: number;
+    sourceEnd: number;
+}
+/**
+ * Build a Set keyed by "poolItemId:sourceStart" for O(1) emphasis lookups.
+ * sourceStart is rounded to 3 decimal places to handle floating-point drift
+ * between transcript sources and stored emphasis data.
+ */
+export declare function buildEmphasisSet(emphasisWords: EmphasisWord[]): Set<string>;
+/** Check if a word (by poolItemId + sourceStart) is in the emphasis set. */
+export declare function isEmphasized(set: Set<string>, poolItemId: string, sourceStart: number): boolean;

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

@@ -0,0 +1,16 @@
+/**
+ * Build a Set keyed by "poolItemId:sourceStart" for O(1) emphasis lookups.
+ * sourceStart is rounded to 3 decimal places to handle floating-point drift
+ * between transcript sources and stored emphasis data.
+ */
+export function buildEmphasisSet(emphasisWords) {
+    const set = new Set();
+    for (const w of emphasisWords) {
+        set.add(`${w.poolItemId}:${w.sourceStart.toFixed(3)}`);
+    }
+    return set;
+}
+/** Check if a word (by poolItemId + sourceStart) is in the emphasis set. */
+export function isEmphasized(set, poolItemId, sourceStart) {
+    return set.has(`${poolItemId}:${sourceStart.toFixed(3)}`);
+}

package/dist/_members/core/render/eval/cropBox.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Reframe eval — the COMPOSED crop box per output frame.
+ *
+ * The eval target is the crop box the camera ACTUALLY lands on, in
+ * output-crop-normalized space — NOT the raw `centers`/`zoom_scale` of the
+ * trajectory JSON. Per the virtual-camera spec ("the composed (post-floor) crop
+ * is the eval target … zoom is two-layer"), the jitter / center-crop metrics
+ * sample the box `computeCropTransform` produces, so they measure what ships.
+ *
+ * Phase 0 samples the BASE camera path (the trajectory) — the floor yield is a
+ * separate, caption-driven layer with its own golden (Phase 4). The geometry
+ * below is the bake half of `computeCropTransform`
+ * (packages/execution/render-entry/src/CropFromTrajectory.tsx): crop-window size from
+ * `zoom_scale`, center from the per-frame `centers`, coverage-clamped so the
+ * window never runs past the source edge. We replicate it here (rather than
+ * import the renderer — execution must not depend on the Remotion bundle) and a
+ * test pins this replica against the renderer's published clamp behavior.
+ *
+ * Coordinate system: the crop box is expressed in SOURCE-NORMALIZED units —
+ * `cx,cy` ∈ [0,1] (window center vs source dims) and `w,h` ∈ [0,1] (window size
+ * as a fraction of the source). Frame-to-frame motion of THIS box is the camera
+ * motion; normalizing the per-component delta by the box's own size converts it
+ * to output-crop-normalized units (a half-window pan is the same number at any
+ * zoom — the zoom-invariant "held feel" the spec requires).
+ */
+import type { TrajectoryData, TrajectorySegment } from '../../../composition/reframe/trajectory.js';
+/** The composed crop window for one output frame, source-normalized. */
+export interface CropBox {
+    /** Window center x ∈ [0,1] vs source width (after the coverage clamp). */
+    cx: number;
+    /** Window center y ∈ [0,1] vs source height (after the coverage clamp). */
+    cy: number;
+    /** Window width as a fraction of the source width ∈ (0,1]. */
+    w: number;
+    /** Window height as a fraction of the source height ∈ (0,1]. */
+    h: number;
+}
+/**
+ * Crop-window dimensions (source-normalized) for a given `zoom_scale` + output
+ * aspect — the bake half of `computeCropTransform`. The largest output-aspect
+ * rect that fits the source, scaled by the clamped zoom. No `faceScale` (the
+ * floor's caption-band yield) is applied here — Phase 0 samples the base path.
+ */
+export declare function cropWindowSize(srcW: number, srcH: number, zoomScale: number, aspect: string): {
+    w: number;
+    h: number;
+};
+/** The composed crop box for one frame of one segment. */
+export declare function cropBoxForFrame(seg: TrajectorySegment, frameInSeg: number, srcW: number, srcH: number, aspect: string): CropBox;
+/**
+ * Flatten a `TrajectoryData` to the per-output-frame composed crop-box series
+ * over all its segments, in order. This is the series the jitter metric walks.
+ */
+export declare function cropBoxSeries(traj: TrajectoryData): CropBox[];
+/**
+ * The STATIC center-crop baseline a content-aware reframe MUST beat on
+ * smoothness: the same per-segment `zoom_scale` (so the only variable is WHERE
+ * the camera points), but the center pinned to source-center every frame
+ * (coverage-clamped, which for a centered window is a no-op). A static crop has
+ * zero pan jitter by construction — its only frame-to-frame motion is the
+ * per-shot `zoom_scale` steps the algorithm itself authors. The reframe is
+ * "adding jitter for nothing" if it cannot beat THIS.
+ */
+export declare function centerCropBoxSeries(traj: TrajectoryData): CropBox[];
+/**
+ * The RAW subject-centroid path baseline (the research bar): the per-frame
+ * `centers` the algorithm computed, BEFORE any smoothing/deadzone, composed into
+ * a crop box at the same per-segment zoom. A reframe must be SMOOTHER than the
+ * path it is smoothing. Phase 0 cannot reconstruct the pre-EMA centroid from the
+ * shipped trajectory (it only carries the smoothed `centers`), so this is a
+ * scaffold that returns the shipped centers; Phase 3 wires the true raw path via
+ * `eval/inclusion` + `eval/index` (keeping `emaSmooth` importable, per the
+ * spec's characterization gate).
+ */
+export declare function rawCentroidBoxSeries(traj: TrajectoryData): CropBox[];
+/**
+ * Compose an arbitrary per-frame `centers` series (e.g. the raw tracking
+ * centroid, or the same centroid through the OLD `emaSmooth`) into a crop-box
+ * series at a fixed per-frame crop window — the Phase-3 "smoother than EMA"
+ * characterization baseline. `cropFor(frame)` gives the source-normalized window
+ * for that output frame (the same the shipping path uses), so the ONLY variable
+ * between ours and the baseline is the smoother. Centers are coverage-clamped
+ * exactly as the renderer clamps them.
+ */
+export declare function cropBoxSeriesFromCenters(centers: Array<[number, number]>, cropFor: (frame: number) => {
+    w: number;
+    h: number;
+}): CropBox[];

package/dist/_members/core/render/eval/cropBox.js

@@ -0,0 +1,139 @@
+/**
+ * Reframe eval — the COMPOSED crop box per output frame.
+ *
+ * The eval target is the crop box the camera ACTUALLY lands on, in
+ * output-crop-normalized space — NOT the raw `centers`/`zoom_scale` of the
+ * trajectory JSON. Per the virtual-camera spec ("the composed (post-floor) crop
+ * is the eval target … zoom is two-layer"), the jitter / center-crop metrics
+ * sample the box `computeCropTransform` produces, so they measure what ships.
+ *
+ * Phase 0 samples the BASE camera path (the trajectory) — the floor yield is a
+ * separate, caption-driven layer with its own golden (Phase 4). The geometry
+ * below is the bake half of `computeCropTransform`
+ * (packages/execution/render-entry/src/CropFromTrajectory.tsx): crop-window size from
+ * `zoom_scale`, center from the per-frame `centers`, coverage-clamped so the
+ * window never runs past the source edge. We replicate it here (rather than
+ * import the renderer — execution must not depend on the Remotion bundle) and a
+ * test pins this replica against the renderer's published clamp behavior.
+ *
+ * Coordinate system: the crop box is expressed in SOURCE-NORMALIZED units —
+ * `cx,cy` ∈ [0,1] (window center vs source dims) and `w,h` ∈ [0,1] (window size
+ * as a fraction of the source). Frame-to-frame motion of THIS box is the camera
+ * motion; normalizing the per-component delta by the box's own size converts it
+ * to output-crop-normalized units (a half-window pan is the same number at any
+ * zoom — the zoom-invariant "held feel" the spec requires).
+ */
+import { aspectWhRatio } from '../deriveTrajectory';
+/**
+ * Crop-window dimensions (source-normalized) for a given `zoom_scale` + output
+ * aspect — the bake half of `computeCropTransform`. The largest output-aspect
+ * rect that fits the source, scaled by the clamped zoom. No `faceScale` (the
+ * floor's caption-band yield) is applied here — Phase 0 samples the base path.
+ */
+export function cropWindowSize(srcW, srcH, zoomScale, aspect) {
+    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;
+    }
+    // Mirror the renderer: zoom clamps to [0.4, 1.0] (CropFromTrajectory bakedZoom).
+    const bakedZoom = Math.max(0.4, Math.min(1.0, zoomScale));
+    cropW *= bakedZoom;
+    cropH *= bakedZoom;
+    return { w: cropW / srcW, h: cropH / srcH };
+}
+/**
+ * Coverage-clamp a window center so the crop window stays fully inside the
+ * source — the geometric invariant `computeCropTransform` enforces via
+ * `tx = clamp(…)`, expressed here directly on the source-normalized center.
+ * A window of width `w` can have its center range over `[w/2, 1 - w/2]`.
+ */
+function clampCenter(c, sizeFrac) {
+    const half = sizeFrac / 2;
+    if (sizeFrac >= 1)
+        return 0.5; // window covers the whole axis → centered
+    return Math.max(half, Math.min(1 - half, c));
+}
+/** The composed crop box for one frame of one segment. */
+export function cropBoxForFrame(seg, frameInSeg, srcW, srcH, aspect) {
+    // Eased segments carry a per-frame `zooms`; otherwise the scalar `zoom_scale`.
+    const zoom = seg.zooms ? seg.zooms[Math.min(frameInSeg, seg.zooms.length - 1)] : seg.zoom_scale;
+    const { w, h } = cropWindowSize(srcW, srcH, zoom, aspect);
+    const center = seg.centers[Math.min(frameInSeg, seg.centers.length - 1)] ?? [0.5, 0.5];
+    return {
+        cx: clampCenter(center[0], w),
+        cy: clampCenter(center[1], h),
+        w,
+        h,
+    };
+}
+/**
+ * Flatten a `TrajectoryData` to the per-output-frame composed crop-box series
+ * over all its segments, in order. This is the series the jitter metric walks.
+ */
+export function cropBoxSeries(traj) {
+    const out = [];
+    for (const seg of traj.segments) {
+        const n = seg.centers.length;
+        for (let i = 0; i < n; i++) {
+            out.push(cropBoxForFrame(seg, i, traj.src_w, traj.src_h, traj.aspect));
+        }
+    }
+    return out;
+}
+/**
+ * The STATIC center-crop baseline a content-aware reframe MUST beat on
+ * smoothness: the same per-segment `zoom_scale` (so the only variable is WHERE
+ * the camera points), but the center pinned to source-center every frame
+ * (coverage-clamped, which for a centered window is a no-op). A static crop has
+ * zero pan jitter by construction — its only frame-to-frame motion is the
+ * per-shot `zoom_scale` steps the algorithm itself authors. The reframe is
+ * "adding jitter for nothing" if it cannot beat THIS.
+ */
+export function centerCropBoxSeries(traj) {
+    const out = [];
+    for (const seg of traj.segments) {
+        const n = seg.centers.length;
+        for (let i = 0; i < n; i++) {
+            const zoom = seg.zooms ? seg.zooms[Math.min(i, seg.zooms.length - 1)] : seg.zoom_scale;
+            const { w, h } = cropWindowSize(traj.src_w, traj.src_h, zoom, traj.aspect);
+            out.push({ cx: 0.5, cy: 0.5, w, h });
+        }
+    }
+    return out;
+}
+/**
+ * The RAW subject-centroid path baseline (the research bar): the per-frame
+ * `centers` the algorithm computed, BEFORE any smoothing/deadzone, composed into
+ * a crop box at the same per-segment zoom. A reframe must be SMOOTHER than the
+ * path it is smoothing. Phase 0 cannot reconstruct the pre-EMA centroid from the
+ * shipped trajectory (it only carries the smoothed `centers`), so this is a
+ * scaffold that returns the shipped centers; Phase 3 wires the true raw path via
+ * `eval/inclusion` + `eval/index` (keeping `emaSmooth` importable, per the
+ * spec's characterization gate).
+ */
+export function rawCentroidBoxSeries(traj) {
+    return cropBoxSeries(traj);
+}
+/**
+ * Compose an arbitrary per-frame `centers` series (e.g. the raw tracking
+ * centroid, or the same centroid through the OLD `emaSmooth`) into a crop-box
+ * series at a fixed per-frame crop window — the Phase-3 "smoother than EMA"
+ * characterization baseline. `cropFor(frame)` gives the source-normalized window
+ * for that output frame (the same the shipping path uses), so the ONLY variable
+ * between ours and the baseline is the smoother. Centers are coverage-clamped
+ * exactly as the renderer clamps them.
+ */
+export function cropBoxSeriesFromCenters(centers, cropFor) {
+    return centers.map((c, i) => {
+        const { w, h } = cropFor(i);
+        return { cx: clampCenter(c[0], w), cy: clampCenter(c[1], h), w, h };
+    });
+}

package/dist/_members/core/render/eval/inclusion.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Reframe eval — the INCLUSION metric (Phase 3 gate) + the shot-aware teleport
+ * and old-vs-new smoothness baselines.
+ *
+ * The Phase-2 gate (jitter ≤ center-crop) is the WRONG bar for a MOVING subject:
+ * a static center crop has jitter 0, but the subject walks out of frame. The
+ * camera that TRACKS the subject HAS motion (jitter > 0) and is CORRECT. So the
+ * Phase-3 gate is INCLUSION: the per-frame RequiredRegion (the padded subject/
+ * group box the crop must contain) must stay ⊆ the crop window. Our reframe must
+ * reach inclusionRate ≈ 1.0 on a moving subject (the camera tracks), and a
+ * static center-crop's inclusionRate must be materially LOWER (the subject walks
+ * out). See the virtual-camera spec, "Virtual-camera stability" + the Phase-3
+ * gate note.
+ *
+ * Pure, deterministic, no I/O. Replays the SAME `selectSubjectSet` +
+ * `regionsFromBoxes` the shipping all-faces derive uses, so the regions are
+ * EXACTLY the boxes the camera was obliged to contain.
+ */
+import type { SubjectTrack } from '../deriveTrajectory.js';
+import type { CropBox } from './cropBox.js';
+import { type RequiredRegion } from '../vcam/requiredRegion.js';
+/** True iff the padded RequiredRegion is fully inside the crop box (the crop
+ *  window contains the region — the subject stays in frame). */
+export declare function regionInCrop(region: RequiredRegion, crop: CropBox): boolean;
+/**
+ * The per-frame RequiredRegions an `all-faces` camera was obliged to contain,
+ * over the WHOLE track window (one all-faces segment). Recomputes the shipping
+ * selection so the regions match the derive exactly. Null where no framed member
+ * is present (occlusion / gap) — those frames are EXCLUDED from inclusionRate
+ * (there's no subject to keep in frame).
+ */
+export declare function requiredRegionsForTrack(track: SubjectTrack): Array<RequiredRegion | null>;
+/** The all-faces `inclusionRate` for a crop-box series vs the per-frame
+ *  RequiredRegions: the fraction of REGION-BEARING frames whose region is fully
+ *  inside the crop. `1.0` ⇒ the subject never walks out of frame. Frames with no
+ *  region (no subject present) are not counted. */
+export declare function inclusionRate(regions: Array<RequiredRegion | null>, crops: CropBox[]): {
+    rate: number;
+    framesWithRegion: number;
+    contained: number;
+};
+/**
+ * The largest per-frame center step measured WITHIN trajectory segments (one per
+ * sub-shot), in output-crop-normalized units. Steps ACROSS a segment boundary
+ * (a detector shot cut) are EXCLUDED — a camera snap at a real cut is intended
+ * (the only reset), so it is not a "teleport". An intra-shot maxStep above the
+ * bar is the chase/teleport the gate guards against. `segLens` are the per-
+ * segment frame counts (so the walk knows where the cut-snaps are).
+ */
+export declare function intraShotMaxStep(crops: CropBox[], segLens: number[]): number;

package/dist/_members/core/render/eval/inclusion.js

@@ -0,0 +1,96 @@
+/**
+ * Reframe eval — the INCLUSION metric (Phase 3 gate) + the shot-aware teleport
+ * and old-vs-new smoothness baselines.
+ *
+ * The Phase-2 gate (jitter ≤ center-crop) is the WRONG bar for a MOVING subject:
+ * a static center crop has jitter 0, but the subject walks out of frame. The
+ * camera that TRACKS the subject HAS motion (jitter > 0) and is CORRECT. So the
+ * Phase-3 gate is INCLUSION: the per-frame RequiredRegion (the padded subject/
+ * group box the crop must contain) must stay ⊆ the crop window. Our reframe must
+ * reach inclusionRate ≈ 1.0 on a moving subject (the camera tracks), and a
+ * static center-crop's inclusionRate must be materially LOWER (the subject walks
+ * out). See the virtual-camera spec, "Virtual-camera stability" + the Phase-3
+ * gate note.
+ *
+ * Pure, deterministic, no I/O. Replays the SAME `selectSubjectSet` +
+ * `regionsFromBoxes` the shipping all-faces derive uses, so the regions are
+ * EXACTLY the boxes the camera was obliged to contain.
+ */
+import { selectSubjectSet } from '../vcam/subjectSet';
+import { buildRequiredRegions } from '../vcam/requiredRegion';
+/** True iff the padded RequiredRegion is fully inside the crop box (the crop
+ *  window contains the region — the subject stays in frame). */
+export function regionInCrop(region, crop) {
+    const rx1 = region.cx - region.w / 2;
+    const rx2 = region.cx + region.w / 2;
+    const ry1 = region.cy - region.h / 2;
+    const ry2 = region.cy + region.h / 2;
+    const cx1 = crop.cx - crop.w / 2;
+    const cx2 = crop.cx + crop.w / 2;
+    const cy1 = crop.cy - crop.h / 2;
+    const cy2 = crop.cy + crop.h / 2;
+    // A tiny tolerance absorbs float noise at the exact edge (a region flush with
+    // the crop edge is contained, not out).
+    const eps = 1e-6;
+    return rx1 >= cx1 - eps && rx2 <= cx2 + eps && ry1 >= cy1 - eps && ry2 <= cy2 + eps;
+}
+/**
+ * The per-frame RequiredRegions an `all-faces` camera was obliged to contain,
+ * over the WHOLE track window (one all-faces segment). Recomputes the shipping
+ * selection so the regions match the derive exactly. Null where no framed member
+ * is present (occlusion / gap) — those frames are EXCLUDED from inclusionRate
+ * (there's no subject to keep in frame).
+ */
+export function requiredRegionsForTrack(track) {
+    const cuts = new Set((track.shotBoundaries ?? []).filter((b) => b > 0));
+    const sel = selectSubjectSet(track.perFrameTracked, track.srcW, track.srcH, track.srcFps, new Map(Object.entries(track.perKeyframeSpeaker).map(([k, v]) => [Number(k), v])), cuts);
+    // Use the SAME canonical RequiredRegions the camera frames (pad + per-shot
+    // outlier reject) — the gate measures inclusion against exactly the region the
+    // derive was obliged to contain, so it can't be gamed by measuring a looser box.
+    return buildRequiredRegions(sel.perFrameBoxes, track.srcFps, cuts);
+}
+/** The all-faces `inclusionRate` for a crop-box series vs the per-frame
+ *  RequiredRegions: the fraction of REGION-BEARING frames whose region is fully
+ *  inside the crop. `1.0` ⇒ the subject never walks out of frame. Frames with no
+ *  region (no subject present) are not counted. */
+export function inclusionRate(regions, crops) {
+    let framesWithRegion = 0;
+    let contained = 0;
+    const n = Math.min(regions.length, crops.length);
+    for (let i = 0; i < n; i++) {
+        const r = regions[i];
+        if (r === null)
+            continue;
+        framesWithRegion++;
+        if (regionInCrop(r, crops[i]))
+            contained++;
+    }
+    return {
+        rate: framesWithRegion > 0 ? contained / framesWithRegion : 1,
+        framesWithRegion,
+        contained,
+    };
+}
+/**
+ * The largest per-frame center step measured WITHIN trajectory segments (one per
+ * sub-shot), in output-crop-normalized units. Steps ACROSS a segment boundary
+ * (a detector shot cut) are EXCLUDED — a camera snap at a real cut is intended
+ * (the only reset), so it is not a "teleport". An intra-shot maxStep above the
+ * bar is the chase/teleport the gate guards against. `segLens` are the per-
+ * segment frame counts (so the walk knows where the cut-snaps are).
+ */
+export function intraShotMaxStep(crops, segLens) {
+    let max = 0;
+    let frame = 0;
+    for (const len of segLens) {
+        for (let i = 1; i < len; i++) {
+            const a = crops[frame + i - 1];
+            const b = crops[frame + i];
+            const step = Math.abs(b.cx - a.cx) / Math.max(b.w, 1e-6) + Math.abs(b.cy - a.cy) / Math.max(b.h, 1e-6);
+            if (step > max)
+                max = step;
+        }
+        frame += len;
+    }
+    return max;
+}

package/dist/_members/core/render/eval/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Reframe eval harness — the public surface for the metrics + the fixture-driven
+ * report. Pure TS, no Modal, no R2: every metric replays a cached `SubjectTrack`
+ * fixture through the REAL `deriveTrajectory` and measures the composed crop box.
+ * See the virtual-camera spec's "Eval / metrics / test harness (built FIRST)".
+ *
+ * Phase 0 shipped jitter + center-crop. Phase 3 adds the INCLUSION gate (the
+ * camera tracks a moving subject ⇒ region ⊆ crop) + the shot-aware teleport
+ * metric + the "smoother than the old EMA path" characterization, because pure
+ * jitter-beats-center-crop is the WRONG bar once the camera legitimately moves to
+ * track (a static center-crop has jitter 0 but loses a walking subject).
+ */
+import type { SubjectTrack, ReframeSegment } from '../deriveTrajectory.js';
+import { type JitterBreakdown } from './metrics.js';
+export type { CropBox } from './cropBox.js';
+export { cropBoxSeries, centerCropBoxSeries, rawCentroidBoxSeries, cropBoxSeriesFromCenters, cropWindowSize, cropBoxForFrame, } from './cropBox.js';
+export { jitter, iou, mIoU, type JitterBreakdown } from './metrics.js';
+export { requiredRegionsForTrack, inclusionRate, intraShotMaxStep, regionInCrop, } from './inclusion.js';
+/** One fixture's reframe-eval report — the numbers a CI gate / RED baseline reads. */
+export interface ReframeEvalReport {
+    /** Composed-crop-box jitter of the algorithm under test. */
+    jitter: JitterBreakdown;
+    /** Composed-crop-box jitter of the static center crop (same per-shot zoom). */
+    centerCropJitter: JitterBreakdown;
+    /** Composed-crop-box jitter of the raw subject-centroid path (research bar). */
+    rawCentroidJitter: JitterBreakdown;
+    /** True iff the algorithm beats the static center crop on smoothness (the bar). */
+    beatsCenterCrop: boolean;
+    /** Frames in the composed series (one per output frame across all segments). */
+    frames: number;
+}
+/**
+ * Run the base eval over a fixture track + authored reframe segments. Derives the
+ * trajectory through the SHIPPING `deriveTrajectory`, composes the crop boxes,
+ * and reports jitter vs the center-crop + raw-centroid baselines.
+ */
+export declare function evalReframe(track: SubjectTrack, segments: ReframeSegment[], aspect: string, bakeVersion: string): ReframeEvalReport;
+/** The Phase-3 tracking report — the gate for a MOVING subject (inclusion, not
+ *  jitter-beats-center-crop). All over a single full-window `all-faces` segment. */
+export interface ReframeTrackingReport {
+    /** Inclusion rate of OUR camera path (region ⊆ crop) — ≈1.0 ⇒ subject tracked. */
+    inclusionRate: number;
+    /** Inclusion rate of a STATIC center crop (same per-shot zoom) — lower ⇒ subject
+     *  walks out of a static crop, which our tracking camera fixes. */
+    centerCropInclusionRate: number;
+    /** Frames that had a RequiredRegion (a subject to keep in frame). */
+    framesWithRegion: number;
+    /** Composed-crop jitter of OUR camera path. */
+    jitter: JitterBreakdown;
+    /** Composed-crop jitter of the SAME per-frame tracking centroid through the OLD
+     *  `emaSmooth` (the characterization baseline — ours must be ≤ this). */
+    emaPathJitter: JitterBreakdown;
+    /** Composed-crop jitter of the RAW (unsmoothed) per-frame tracking centroid. */
+    rawPathJitter: JitterBreakdown;
+    /** Largest per-frame center step WITHIN a shot (cut-snaps excluded) — teleport
+     *  guard. Motion exists (tracking), but no intra-shot jump. */
+    intraShotMaxStep: number;
+    frames: number;
+}
+/**
+ * The Phase-3 tracking eval for an `all-faces` segment over the whole window.
+ * Recomputes the per-frame RequiredRegions (the SAME `selectSubjectSet` the
+ * derive uses) and measures whether the camera keeps the subject in frame
+ * (inclusion), how it compares to the old EMA path (smoothness), and that it
+ * never teleports within a shot. The fixed crop window per frame is the
+ * segment's authored zoom + aspect (all-faces has no eased per-frame zoom).
+ */
+export declare function evalTracking(track: SubjectTrack, aspect: string, bakeVersion: string): ReframeTrackingReport;
+/** One mode's OLD-vs-NEW report for a `face` / `active-speaker` segment. */
+export interface SingleSubjectEvalReport {
+    /** NEW (core geometric-deadzone) composed-crop jitter. */
+    jitter: JitterBreakdown;
+    /** OLD (emaSmooth 0.35 over the bare centroid) composed-crop jitter. */
+    emaJitter: JitterBreakdown;
+    /** NEW inclusion vs the chosen subject's per-frame padded BOX region. */
+    inclusionRate: number;
+    /** OLD inclusion vs the SAME region (so the two paths are judged on one bar). */
+    emaInclusionRate: number;
+    /** NEW intra-shot max center step (cut-snaps excluded) — the teleport guard. */
+    intraShotMaxStep: number;
+    /** OLD intra-shot max center step. */
+    emaIntraShotMaxStep: number;
+    /** Frames the chosen subject was resolved (had a box) — the inclusion denominator. */
+    framesWithRegion: number;
+}
+/**
+ * Characterize the P4 `face` / `active-speaker` migration on a real fixture: the
+ * NEW core geometric-deadzone path (run via the SHIPPING `deriveTrajectory`) vs
+ * the OLD `emaSmooth` path (reconstructed here over the SAME per-frame chosen-
+ * subject centroid the old code used), measured against ONE inclusion region (the
+ * chosen subject's per-frame padded BOX). All over a single full-window segment.
+ */
+export declare function evalSingleSubject(track: SubjectTrack, mode: 'face' | 'active-speaker', aspect: string, bakeVersion: string, faceId?: string): SingleSubjectEvalReport;

package/dist/_members/core/render/eval/index.js

@@ -0,0 +1,146 @@
+/**
+ * Reframe eval harness — the public surface for the metrics + the fixture-driven
+ * report. Pure TS, no Modal, no R2: every metric replays a cached `SubjectTrack`
+ * fixture through the REAL `deriveTrajectory` and measures the composed crop box.
+ * See the virtual-camera spec's "Eval / metrics / test harness (built FIRST)".
+ *
+ * Phase 0 shipped jitter + center-crop. Phase 3 adds the INCLUSION gate (the
+ * camera tracks a moving subject ⇒ region ⊆ crop) + the shot-aware teleport
+ * metric + the "smoother than the old EMA path" characterization, because pure
+ * jitter-beats-center-crop is the WRONG bar once the camera legitimately moves to
+ * track (a static center-crop has jitter 0 but loses a walking subject).
+ */
+import { deriveTrajectory, emaSmooth, cropWindowSizeFor, nearestKpValue } from '../deriveTrajectory';
+import { cropBoxSeries, centerCropBoxSeries, rawCentroidBoxSeries, cropBoxSeriesFromCenters, } from './cropBox';
+import { jitter } from './metrics';
+import { requiredRegionsForTrack, inclusionRate, intraShotMaxStep, regionInCrop, } from './inclusion';
+import { selectSubjectSet, selectSingleSubjectBoxes, } from '../vcam/subjectSet';
+import { buildRequiredRegions } from '../vcam/requiredRegion';
+import { segmentShots } from '../vcam/shots';
+export { cropBoxSeries, centerCropBoxSeries, rawCentroidBoxSeries, cropBoxSeriesFromCenters, cropWindowSize, cropBoxForFrame, } from './cropBox';
+export { jitter, iou, mIoU } from './metrics';
+export { requiredRegionsForTrack, inclusionRate, intraShotMaxStep, regionInCrop, } from './inclusion';
+/**
+ * Run the base eval over a fixture track + authored reframe segments. Derives the
+ * trajectory through the SHIPPING `deriveTrajectory`, composes the crop boxes,
+ * and reports jitter vs the center-crop + raw-centroid baselines.
+ */
+export function evalReframe(track, segments, aspect, bakeVersion) {
+    const traj = deriveTrajectory(track, segments, aspect, bakeVersion);
+    const ours = cropBoxSeries(traj);
+    const center = centerCropBoxSeries(traj);
+    const raw = rawCentroidBoxSeries(traj);
+    const j = jitter(ours);
+    const cj = jitter(center);
+    const rj = jitter(raw);
+    return {
+        jitter: j,
+        centerCropJitter: cj,
+        rawCentroidJitter: rj,
+        beatsCenterCrop: j.total <= cj.total,
+        frames: ours.length,
+    };
+}
+/**
+ * The Phase-3 tracking eval for an `all-faces` segment over the whole window.
+ * Recomputes the per-frame RequiredRegions (the SAME `selectSubjectSet` the
+ * derive uses) and measures whether the camera keeps the subject in frame
+ * (inclusion), how it compares to the old EMA path (smoothness), and that it
+ * never teleports within a shot. The fixed crop window per frame is the
+ * segment's authored zoom + aspect (all-faces has no eased per-frame zoom).
+ */
+export function evalTracking(track, aspect, bakeVersion) {
+    const segments = [
+        { startSec: 0, endSec: track.window.endSec, focus: { mode: 'all-faces' }, zoom: 1 },
+    ];
+    const traj = deriveTrajectory(track, segments, aspect, bakeVersion);
+    const ours = cropBoxSeries(traj);
+    const center = centerCropBoxSeries(traj);
+    const regions = requiredRegionsForTrack(track);
+    // The fixed per-frame crop window (zoom 1.0 here — the authored all-faces zoom).
+    const win = cropWindowSizeFor(track.srcW, track.srcH, 1.0, aspect);
+    const cropFor = () => win;
+    // Reconstruct the RAW per-frame tracking centroid + the OLD emaSmooth path over
+    // the SAME selection, to prove ours (cameraPath) is no rougher than EMA.
+    const cuts = new Set((track.shotBoundaries ?? []).filter((b) => b > 0));
+    const sel = selectSubjectSet(track.perFrameTracked, track.srcW, track.srcH, track.srcFps, new Map(Object.entries(track.perKeyframeSpeaker).map(([k, v]) => [Number(k), v])), cuts);
+    const rawCenters = sel.centers;
+    const emaCenters = emaSmooth(rawCenters, 0.35, cuts);
+    const rawBoxes = cropBoxSeriesFromCenters(rawCenters, cropFor);
+    const emaBoxes = cropBoxSeriesFromCenters(emaCenters, cropFor);
+    const segLens = traj.segments.map((s) => s.centers.length);
+    return {
+        inclusionRate: inclusionRate(regions, ours).rate,
+        centerCropInclusionRate: inclusionRate(regions, center).rate,
+        framesWithRegion: inclusionRate(regions, ours).framesWithRegion,
+        jitter: jitter(ours),
+        emaPathJitter: jitter(emaBoxes),
+        rawPathJitter: jitter(rawBoxes),
+        intraShotMaxStep: intraShotMaxStep(ours, segLens),
+        frames: ours.length,
+    };
+}
+/** Resolve a Focus mode + faceId into the single-subject adapter pick. */
+function pickFor(mode, faceId) {
+    return mode === 'face' ? { kind: 'face', authoredFaceId: faceId ?? '' } : { kind: 'active-speaker' };
+}
+/**
+ * Characterize the P4 `face` / `active-speaker` migration on a real fixture: the
+ * NEW core geometric-deadzone path (run via the SHIPPING `deriveTrajectory`) vs
+ * the OLD `emaSmooth` path (reconstructed here over the SAME per-frame chosen-
+ * subject centroid the old code used), measured against ONE inclusion region (the
+ * chosen subject's per-frame padded BOX). All over a single full-window segment.
+ */
+export function evalSingleSubject(track, mode, aspect, bakeVersion, faceId) {
+    const segments = [
+        {
+            startSec: 0,
+            endSec: track.window.endSec,
+            focus: mode === 'face' ? { mode: 'face', faceId: faceId ?? 'face-0' } : { mode: 'active-speaker' },
+            zoom: 1,
+        },
+    ];
+    // NEW: the shipping migrated derive.
+    const traj = deriveTrajectory(track, segments, aspect, bakeVersion);
+    const newBoxes = cropBoxSeries(traj);
+    // The chosen subject's per-frame box (the adapter the migrated derive uses) →
+    // the SINGLE inclusion region both paths are judged against + the centroid the
+    // OLD emaSmooth consumed.
+    const cuts = new Set((track.shotBoundaries ?? []).filter((b) => b > 0));
+    const perKf = new Map(Object.entries(track.perKeyframeSpeaker).map(([k, v]) => [Number(k), v]));
+    const single = selectSingleSubjectBoxes(track.perFrameTracked, track.srcW, track.srcH, perKf, pickFor(mode, faceId), (frame) => nearestKpValue(perKf, frame));
+    const regions = buildRequiredRegions(single.perFrameBoxes, track.srcFps, cuts);
+    // OLD: emaSmooth(0.35) over the chosen subject's per-frame centroid (the bare
+    // center the deleted branch produced), composed at the SAME zoom-1.0 window.
+    const win = cropWindowSizeFor(track.srcW, track.srcH, 1.0, aspect);
+    const cropFor = () => win;
+    const centroids = single.perFrameBoxes.map((b) => b === null ? null : [(b[0] + b[2]) / 2, (b[1] + b[3]) / 2]);
+    const emaCenters = emaSmooth(centroids, 0.35, cuts);
+    const emaBoxes = cropBoxSeriesFromCenters(emaCenters.map((c) => [c[0], c[1]]), cropFor);
+    // Inclusion vs the chosen subject's padded box region (one bar for both paths).
+    const incl = (crops) => {
+        let fw = 0;
+        let contained = 0;
+        for (let i = 0; i < regions.length; i++) {
+            const r = regions[i];
+            if (r === null)
+                continue;
+            fw++;
+            if (regionInCrop(r, crops[i]))
+                contained++;
+        }
+        return { rate: fw > 0 ? contained / fw : 1, framesWithRegion: fw };
+    };
+    // Intra-shot max step (cut-snaps excluded) needs per-shot frame counts.
+    const segLens = segmentShots(cuts, regions.length).map((s) => s.end - s.start);
+    const newIncl = incl(newBoxes);
+    return {
+        jitter: jitter(newBoxes),
+        emaJitter: jitter(emaBoxes),
+        inclusionRate: newIncl.rate,
+        emaInclusionRate: incl(emaBoxes).rate,
+        intraShotMaxStep: intraShotMaxStep(newBoxes, segLens),
+        emaIntraShotMaxStep: intraShotMaxStep(emaBoxes, segLens),
+        framesWithRegion: newIncl.framesWithRegion,
+    };
+}