@cueframe/kernel 0.0.1

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

@@ -0,0 +1,188 @@
+/**
+ * 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';
+export type { ReframeSegment } from '../../composition/reframe/index.js';
+export { buildEasedZooms, buildPannedCenters, easeOutCubic } from '../../composition/reframe/trajectory.js';
+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;
+} | {
+    kind: 'all-faces';
+} | {
+    kind: 'frame-center';
+} | {
+    kind: 'active-speaker';
+} | {
+    kind: 'point';
+    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[];
+    resolvedFrames: number;
+    shotFits?: ShotFit[];
+};
+export declare function deriveTrajectory(track: SubjectTrack, segments: ReframeSegment[], aspect: string, bakeVersion: string, isGenerated?: boolean): TrajectoryData;