@cueframe/kernel 0.1.1 → 0.1.2

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

@@ -1,28 +1,3 @@
-/**
- * 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.
- */
 import type { Face, FaceBox, SubjectTrack } from '../../perception/index.js';
 export type { Face, FaceBox, SubjectTrack } from '../../perception/index.js';
 import type { ReframeSegment } from '../../composition/reframe/index.js';
@@ -31,15 +6,7 @@ export { buildEasedZooms, buildPannedCenters, easeOutCubic } from '../../composi
 import type { TrajectorySubject, TrajectoryData } from '../../composition/reframe/trajectory.js';
 export type { TrajectorySubject, TrajectorySegment, TrajectoryData } from '../../composition/reframe/trajectory.js';
 import { type ShotFit } from './vcam/framing.js';
-/**
- * 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 declare function faceArea(face: Face): number;
-/** The crop subject pick the agent authors on a segment (mirror of the wire
- *  `cropIntents[].subject`). `active-speaker` is resolved upstream (per
- *  keyframe) into a concrete `face` before this is consulted. */
 export type Subject = {
     kind: 'face';
     faceId: string;
@@ -54,131 +21,24 @@ export type Subject = {
     x: number;
     y: number;
 };
-/**
- * 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 declare function resolveSubjectFaces(faces: Face[], subject: Subject): Face[];
-/** A normalized crop center `[cx, cy]` in [0,1] vs source dims. */
 export type Center = [number, number];
-/**
- * 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 declare function selectedFaceCenter(faces: Face[], subject: Subject): Center | null;
-/** 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 declare 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 declare const MIN_SUBJECT_RESOLUTION = 0.4;
 export declare function isJump(a: Center, b: Center): boolean;
-/**
- * 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 declare function emaSmooth(centers: (Center | null)[], alpha?: number, cutFrames?: ReadonlySet<number>): Center[];
-/** Clamp to [0,1] — mirror of reframe_bake.py `_clip01`. */
 export declare function clip01(v: number): number;
-/** Bottom-band fraction the render keeps clear for captions per aspect.
- *  CAPTION_BAND_RESERVE is the SSOT in @cueframe/composition (imported above). */
 export declare function captionBandReserve(aspect: string): number;
-/** 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 declare function aspectWhRatio(aspect: string): number;
-/**
- * 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 declare function cropWindowSizeFor(srcW: number, srcH: number, zoomScale: number, aspect: string): {
     w: number;
     h: number;
 };
-/** 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 declare function nearestKpValue(d: Map<number, string>, key: number): string | 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 declare function activeWindowsFor(faceId: string, perKeyframeSpeaker: Map<number, string>, frameCount: number): Array<[number, number]>;
-/**
- * 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 declare function perSubjectSeries(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, perKeyframeSpeaker: Map<number, string>, frameCount: number, cutFrames?: ReadonlySet<number>): TrajectorySubject[];
-/** §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 declare function calibrateShotScale(shotScale: string | undefined | null, subjects: TrajectorySubject[], srcW: number, srcH: number, aspect: string, fallbackZoom: number | undefined, fallbackVbias: number | undefined, authoredSubject?: Subject): [number, number];
-/**
- * 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 declare function deriveSegment(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, perKeyframeSpeaker: Map<number, string>, subject: Subject, cutFrames?: ReadonlySet<number>, fps?: number, aspect?: string, zoomScale?: number): {
     centers: Center[];
     subjects: TrajectorySubject[];

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

@@ -3,11 +3,5 @@ export interface EmphasisWord {
     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/eval/cropBox.d.ts

@@ -1,87 +1,18 @@
-/**
- * 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;

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

@@ -1,50 +1,11 @@
-/**
- * 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/index.d.ts

@@ -1,93 +1,35 @@
-/**
- * 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/metrics.d.ts

@@ -1,48 +1,12 @@
-/**
- * Reframe eval metrics — pure, label-free, deterministic.
- *
- * Tier 1 (HARD CI BLOCKERS, no human labels): `jitter` + the center-crop
- * comparison. These are what gate the build per the virtual-camera spec —
- * "jitter-beats-center-crop is the only ship-blocker".
- *
- * Tier 2 (REPORTED, not blocking): `mIoU` — scaffolded + reported, NOT a gate,
- * because per-frame human ground-truth boxes don't exist yet (RESOLVED #3).
- *
- * `jitter` = mean over frames of the absolute frame-to-frame difference of the
- * composed crop box (center x/y AND size), in output-crop-normalized units. The
- * per-component delta is normalized by the box's own size, so the metric is
- * zoom-invariant: a half-window pan reads the same number at any zoom (the spec's
- * "held feel is zoom-invariant" requirement). Lower is smoother. A static crop
- * has zero pan jitter; the only motion it carries is the per-shot `zoom_scale`
- * steps, which both paths share — so `jitter(ours) ≤ jitter(centerCrop)` isolates
- * "where the camera points" as the sole variable.
- */
 import type { CropBox } from './cropBox.js';
-/** Per-channel jitter breakdown (so a regression points at center vs zoom). */
 export interface JitterBreakdown {
-    /** Mean |Δ| of the window center, normalized by window size (output-crop units). */
     center: number;
-    /** Mean |Δ| of the window size (zoom channel), normalized by mean window size. */
     zoom: number;
-    /** Combined center + zoom mean absolute step — the headline jitter scalar. */
     total: number;
-    /** The single largest per-frame center step (output-crop units) — teleport guard. */
     maxCenterStep: number;
 }
-/**
- * Jitter of a composed crop-box series. Empty / single-frame series → all zeros
- * (no motion to measure). The center delta is divided by the per-frame window
- * size so it is expressed in fractions of the crop window (output-crop space);
- * the zoom delta is divided by the mean window size for the same normalization.
- */
 export declare function jitter(boxes: CropBox[]): JitterBreakdown;
-/** Intersection-over-union of two source-normalized crop boxes. */
 export declare function iou(a: CropBox, b: CropBox): number;
-/**
- * mIoU + IoU@0.5 vs a per-frame ground-truth crop-box series (Tier 2, REPORTED
- * only). Scaffolded now so the harness emits a number the moment labels exist;
- * NOT a CI gate (no hand-labeled fixtures yet — RESOLVED #3). Lengths must match.
- */
 export declare function mIoU(ours: CropBox[], groundTruth: CropBox[]): {
     mIoU: number;
     iouAt50: number;

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

@@ -1,7 +1,3 @@
-/**
- * Export settings types and constants shared between desktop and cloud render paths.
- * Extracted from apps/studio/src/store/exportStore.ts — pure functions, no store deps.
- */
 import type { CaptionStyle } from './types.js';
 export type ExportQuality = 'maximum' | 'social' | 'web' | 'potato' | 'source';
 export type ExportFormat = 'source' | '16:9' | '9:16' | '4:5' | '1:1';
@@ -28,13 +24,9 @@ export declare const RESOLUTION_PRESETS: Record<Exclude<ExportResolution, 'sourc
     label: string;
     height: number;
 }>;
-/** Convert a BPP value to an approximate CRF (H.264). */
 export declare function bppToCrf(bpp: number): number;
-/** Compute output dimensions and CRF from source dims + quality preset. */
-export declare function computeExportDimensions(sourceWidth: number, sourceHeight: number, format: ExportFormat, quality: ExportQuality): {
-    width: number;
-    height: number;
-    crf: number | undefined;
-};
-/** Ensure a dimension is even (required by most codecs). */
+export declare function qualityToCrf(quality: ExportQuality): number | undefined;
+export declare function resolutionToOutputSize(width: number, height: number, resolution: ExportResolution): {
+    outputWidth: number;
+} | undefined;
 export declare function ensureEven(n: number): number;

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

@@ -7,7 +7,7 @@ export { extractCaptionWordsFromDoc, sliceTranscriptWords, splitIntoSentences }
 export { compositionToRenderInput, referencedMediaIds, componentRefsByClipId, assembleRenderInput, validateComposition, compositionFormatDimensions, playableSpans, } from './compositionRender.js';
 export { bookendFrames, resolveBookendTimeline, CARD_BOOKEND_DEFAULT_MS, VIDEO_BOOKEND_DEFAULT_MS, } from './bookends.js';
 export type { BookendTimeline } from './bookends.js';
-export { DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, computeExportDimensions, ensureEven, } from './exportSettings.js';
+export { DEFAULT_FPS, DEFAULT_WIDTH, DEFAULT_HEIGHT, DEFAULT_RENDER_SETTINGS, FORMAT_PRESETS, RESOLUTION_PRESETS, bppToCrf, ensureEven, qualityToCrf, resolutionToOutputSize, } from './exportSettings.js';
 export type { ExportFormat, ExportQuality, ExportResolution, FormatPreset, RenderSettings, } from './exportSettings.js';
 export { faceArea, resolveSubjectFaces, selectedFaceCenter, isJump, emaSmooth, clip01, captionBandReserve, aspectWhRatio, nearestKpValue, activeWindowsFor, perSubjectSeries, calibrateShotScale, deriveSegment, deriveTrajectory, buildEasedZooms, buildPannedCenters, easeOutCubic, JUMP_THRESHOLD, MIN_SUBJECT_RESOLUTION, } from './deriveTrajectory.js';
 export type { Subject, Center, TrajectorySubject, TrajectorySegment, TrajectoryData, Face, FaceBox, SubjectTrack, ReframeSegment, } from './deriveTrajectory.js';

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

@@ -1,39 +1,12 @@
-/**
- * Face→person identity mapping for the perception ESCALATION path.
- *
- * The plan authors subjects against the FACE roster (`face-N`, YuNet/SCRFD).
- * When the face tracker carries that identity in too few frames
- * (`subject_not_tracked` — e.g. the subject looks away for most of a long
- * segment), the compose escalates to the PERSON detector (YOLO11x + BoT-SORT),
- * whose track names identities `person-N`. This maps the authored face id onto
- * the person id whose body boxes CONTAIN that face, scored over exactly the
- * frames where the face DID resolve — the face evidence is sparse but real, and
- * a face box sits inside its own person's box in every such frame.
- *
- * Pure math, no I/O. Tracks may have different frame counts (defensive):
- * frames align by relative position in the shared detection window.
- */
 type Box = [number, number, number, number];
 interface TrackLike {
     perFrameTracked: Array<Record<string, Box>>;
 }
 export interface FaceToPersonMapping {
     personId: string;
-    /** Frames where the face resolved AND the winning person contained it. */
     matchedFrames: number;
-    /** Frames where the face resolved at all (the scoring denominator). */
     faceFrames: number;
-    /** Winner's total containment score / runner-up's (Infinity when unopposed). */
     margin: number;
 }
-/**
- * Map one authored face id to the person-track id that carries it, or null when
- * the evidence is missing/ambiguous (caller fails loud — never a guess).
- *
- * Decision rule: sum per-frame containment per person id over the frames where
- * the face resolves; the winner needs (a) support in ≥30% of those frames at
- * ≥60% containment, and (b) a 1.5× margin over the runner-up (two people
- * side-by-side must not coin-flip).
- */
 export declare function mapFaceIdToPersonId(faceTrack: TrackLike, personTrack: TrackLike, faceId: string): FaceToPersonMapping | null;
 export {};