@cueframe/kernel 0.1.1 → 0.1.3

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 {};

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

@@ -22,47 +22,21 @@ export interface OverlayParams {
     xPercent?: number;
     yPercent?: number;
     fontSize?: number;
-    /** heroText (depth grammar §3.4): font size as % of composition height (default 14). */
     fontSizePct?: number;
-    /** heroText: per-word reveal offsets in ms relative to the overlay's start. */
     revealAtMs?: number[];
-    /** heroText: display weight override (default 800). */
     fontWeight?: number;
-    /**
-     * Behind-subject overlays only: `false` opts out of the atmospheric depth
-     * treatment (brightness/saturation/blur — `BEHIND_ATMOSPHERE`) the behind
-     * host applies by default. Ignored on front overlays.
-     */
     atmosphere?: boolean;
-    /** card overlay: the authored HTML/CSS fragment, rendered VERBATIM via
-     *  dangerouslySetInnerHTML inside the region box (OverlayContent case 'card'). */
     html?: string;
-    /** card overlay: brand-token map (literal | `$brand:` ref per value),
-     *  resolved at render into `--cf-<key>` CSS custom properties on the wrapper box. */
     cssTokens?: Record<string, string>;
 }
 export interface CompositionClip {
     id: string;
     src: string;
-    /** Proxy URL for preview playback (lighter H.264 transcode) */
     previewSrc?: string;
     sourceInFrames: number;
     sourceOutFrames: number;
     timelineStartFrames: number;
     durationInFrames: number;
-    /** The clip's `trim.start` in output-fps frames. With `excludedRanges` the
-     *  clip plays multiple playable spans whose `sourceInFrames` are source-
-     *  absolute; the crop trajectory is clip-relative (frame 0 = trim.start), so
-     *  the renderer needs this to map output frames → trajectory frames across the
-     *  trimmed gaps. Absent ⇒ 0 (clip starts at its source origin).
-     *
-     *  NOT guaranteed non-negative: it is a PURE OFFSET, not a validated
-     *  trim.start echo. When a sandbox harness physically trims the source file
-     *  (materializeSources' shallow-seek), sourceInFrames/sourceOutFrames/
-     *  trimStartFrames are all rebased by the same shift into segment-file
-     *  coordinates — only their differences are meaningful, and trimStartFrames
-     *  can legitimately go negative. Consumers must never validate or seek on
-     *  its absolute value. */
     trimStartFrames?: number;
     playbackRate?: number;
     volume?: number;
@@ -70,112 +44,28 @@ export interface CompositionClip {
     opacity?: number;
     scale?: number;
     rotation?: number;
-    /**
-     * TIME-VARYING channels, keyed by param path, times CLIP-RELATIVE in seconds.
-     * When a param appears here it overrides its scalar sibling above for the
-     * clip's duration; the scalar remains what a non-animating consumer reads.
-     * Interpolation is `valueAt` from `@cueframe/composition/timeline` — one
-     * implementation, because the editor, this renderer and the evaluator must
-     * agree or the motion the judge grades is not the motion that ships.
-     */
     animate?: Record<string, Array<{
         time: number;
         value: number;
         easing?: unknown;
     }>>;
-    /**
-     * Output-space placement rect (fractions of the output frame, 0..1).
-     * Default (absent) = full frame {x:0,y:0,w:1,h:1}. A sub-frame region makes
-     * the clip occupy only that rect of the output — the foundation for
-     * picture-in-picture / split-screen / inset cards, where lower tracks show
-     * through the uncovered area. The clip's source is fit into the region per
-     * `fit`. Mirrors `Region` on the wire (composition.ts).
-     *
-     * NOTE: the per-frame crop pipeline (CropFromTrajectory) renders against the
-     * FULL output frame; composing a sub-frame region with a non-identity crop
-     * requires the crop to target the region's aspect. The renderer applies the
-     * placement; full region×crop compose is wired incrementally.
-     */
     region?: {
         x: number;
         y: number;
         w: number;
         h: number;
     };
-    /** How the source fills `region`: 'cover' (fill+crop, default) or 'contain' (letterbox). */
     fit?: 'cover' | 'contain';
     mediaType?: 'video' | 'audio' | 'image';
-    /**
-     * Ken-Burns motion preset for still-image clips (mediaType === 'image').
-     * A convenience the renderer's <StillCrop> lowers to a `reframe`
-     * (kenBurnsToReframe) and runs through the unified per-frame crop renderer.
-     * Default 'in' (gentle zoom-in). Ignored for video / audio clips.
-     */
     kenBurns?: 'in' | 'out' | 'pan-l' | 'pan-r' | 'none';
-    /**
-     * Authored camera channel for a still (mediaType === 'image'). When present,
-     * <StillCrop> derives the still trajectory from THIS (arbitrary per-frame
-     * point-zoom + center) instead of lowering `kenBurns` — so an image can zoom
-     * into a specific point (a UI element), not just the centered kenBurns
-     * presets. `kenBurns` is the fallback when no reframe was authored.
-     */
     reframe?: Reframe;
-    /**
-     * Loop the underlying media until the clip's duration runs out. Used by
-     * gif enrichment clips (whose source mp4 may be shorter than the moment)
-     * and audio ambient beds. Ignored on `mediaType === 'image'`.
-     */
     loop?: boolean;
     transitionIn?: 'fade' | 'dissolve' | 'wipe' | 'none';
     transitionDurationFrames?: number;
-    /** Original clip ID — set on sub-clips produced by splitting around deleted ranges. */
     parentId?: string;
-    /**
-     * Pre-resolved crop-trajectory JSON URL for render-time per-frame
-     * cropping. When set, the renderer reads the trajectory's per-segment
-     * per-frame normalized centers and applies a CSS transform on the
-     * raw source video to produce the cropped output.
-     *
-     * 2026-05-28 substrate revision: replaces the prior baked-mp4
-     * substitution + variantMaskUrl combo. Bake produces only this JSON
-     * now; render-side does the pixel pushing. See
-     * packages/execution/core/src/render/deriveTrajectory.ts for the producer
-     * (TS-side, derived inline at render) and CropFromTrajectory.tsx for the
-     * consumer.
-     */
     cropTrajectoryUrl?: string;
-    /**
-     * The same per-frame crop trajectory, IN MEMORY rather than behind a URL.
-     *
-     * The editor derives a clip's trajectory client-side — `deriveTrajectory` is
-     * pure, and the cached subject track it reads arrives presigned on the media
-     * row — so there is no object to fetch and nothing to presign. Handing the
-     * renderer a URL would mean minting a blob one per keystroke, into a
-     * module-level per-URL cache that never evicts.
-     *
-     * `CropFromTrajectory` has taken an in-memory trajectory since the still path
-     * needed one (`traj = trajectory ?? fetched`), so this is a channel to a prop
-     * that already exists, not a second rendering path. The server render keeps
-     * using `cropTrajectoryUrl`: its trajectory is written to R2 by an action, and
-     * inlining it would put a per-frame series in the render snapshot.
-     *
-     * Exactly one of the two is set. When both are, this wins — it is the fresher
-     * of the two by construction, since it was derived from the edit in hand.
-     */
     cropTrajectory?: TrajectoryData;
-    /**
-     * Frame-packed CO-VIEW source for the captions-behind-speaker effect: ONE
-     * opaque H.264 (BiRefNet-portrait) with the scene (top half) and the matte
-     * (bottom half) stacked, baked frame-aligned per source window. When set,
-     * the clip renders via PackedSubjectComposite — a SINGLE decode yields both
-     * halves of the identical instant, so the matte cannot drift from the scene
-     * at any composition fps (the frame-lock fix). Crop-independent: one co-view
-     * per source window, reused across aspect/crop variants. Resolved at the
-     * caller layer (Temporal activity) from mediaItems.mattes[matteHash] and
-     * served same-origin so @remotion/media decodes it.
-     */
     packedUrl?: string;
-    /** Debug: tint the subject cut-out green to verify coverage. */
     coViewDebug?: boolean;
 }
 export interface CompositionOverlay {
@@ -185,51 +75,22 @@ export interface CompositionOverlay {
     startFrame: number;
     durationInFrames: number;
     params: OverlayParams;
-    /** 'behind-subject' renders under the subject cut-out (matte occludes it). Default front. */
     zPlane?: 'front' | 'behind-subject';
-    /** Scene-space anchor for world-locking behind overlays through the crop trajectory. */
     anchor?: {
         space: 'scene';
         x: number;
         y: number;
     };
-    /** Camera-motion differential for behind overlays: 0 = locked to scene; small ± = depth parallax. Range [-0.3, 0.3]. */
     parallax?: number;
-    /** Output-space placement rect (fractions of the output frame, 0..1). Default
-     *  (absent) = full frame. A sub-frame region makes the overlay primitive (card,
-     *  text, image/gif/lottie) occupy only that rect — the universal placement
-     *  layer (PiP / inset card / split-screen). Mirrors CompositionClip.region; the
-     *  renderer wraps the overlay in the same RegionBox, and size-from-output
-     *  primitives read the box dims via useEffectiveOutput. */
     region?: {
         x: number;
         y: number;
         w: number;
         h: number;
     };
-    /** How the overlay fills `region`: 'cover' (fill+crop, default) or 'contain' (letterbox). */
     fit?: 'cover' | 'contain';
-    /**
-     * Entrance transition for the overlay — mirrors CompositionClip.transitionIn.
-     * When set, the overlay host (OverlayLayer / BehindOverlayHost) wraps the
-     * mounted content in a frame-pure entrance envelope (opacity fade; slide/scale
-     * for the motion variants) over `transitionDurationFrames` from the overlay's
-     * start. Absent = no envelope (byte-identical to prior behavior). Projected via
-     * the same `mapTransitionType` mapping the video lane uses, so the realized
-     * enum is fade/dissolve/wipe/none (dissolve+wipe degrade to an opacity fade for
-     * a single positioned box). Was silently dropped before: only the video lane
-     * projected `transitionIn`, so an authored overlay transition rendered as a
-     * dead hard cut.
-     */
     transitionIn?: 'fade' | 'dissolve' | 'wipe' | 'none';
     transitionDurationFrames?: number;
-    /** Clip-level transform channel (wire `TimelineClip.position/opacity/scale/
-     *  rotation` — "the animation channel"; `region` stays the placement
-     *  primitive). `position` is the overlay's CENTER in output-space fractions
-     *  [0,1] of its containing box (the region box, or the full frame). These
-     *  were silently DROPPED by the projection until 2026-07-20 (spec §2.1.1) —
-     *  an agent could PUT a position, read it back, and watch the render ignore
-     *  it. Absent = the primitive's own layout (no wrapper transform). */
     position?: {
         x: number;
         y: number;
@@ -237,24 +98,15 @@ export interface CompositionOverlay {
     opacity?: number;
     scale?: number;
     rotation?: number;
+    animate?: CompositionClip['animate'];
 }
 export type CaptionWord = WireCaptionWord;
 export type CaptionStyle = WireCaptionStyle & Required<Pick<WireCaptionStyle, 'fontFamily' | 'fontSize' | 'fontWeight' | 'color' | 'highlightColor' | 'backgroundColor' | 'position' | 'textTransform'>>;
-/**
- * Frame-based effect instance the renderer consumes. Mirrors
- * `EffectInstance` from composition/types but with seconds normalized to
- * frames so the render path is fps-agnostic.
- */
 export interface CompositionEffect {
     id: string;
     primitiveId: string;
     params: Record<string, unknown>;
     target: EffectTarget;
-    /**
-     * For clip targets, frames RELATIVE to the clip's timeline start.
-     * For global targets, ABSOLUTE timeline frames.
-     * Undefined = render across the target's whole span.
-     */
     startFrame?: number;
     durationInFrames?: number;
 }
@@ -269,14 +121,6 @@ export interface CompositionAudioTrack {
     fadeInFrames?: number;
     fadeOutFrames?: number;
     loop?: boolean;
-    /**
-     * Speech-aware duck envelope (music / vo tracks only; SFX is never ducked).
-     * Frame ranges are SEQUENCE-RELATIVE (0 = the track's `startFrame`) to match
-     * the fade domain `buildVolumeFunction` operates in. Resolved by the
-     * `compositionToRenderInput` post-projection pass from the composition's own
-     * caption words (or explicit `duck.windows`); absent ⇒ no ducking.
-     * `duckVolume` is the linear gain held during speech (10^(duckDb/20)).
-     */
     duckWindows?: Array<{
         startFrame: number;
         endFrame: number;
@@ -291,30 +135,12 @@ export interface RenderInput {
     audioTracks?: CompositionAudioTrack[];
     effects?: CompositionEffect[];
     captionSegments?: CaptionWord[][];
-    /**
-     * The caption layer renders UNDER the speaker's silhouette
-     * (`composition.captions.zPlane === 'behind-subject'`). One choice for the
-     * whole layer, because it decides whether the SOURCE needs a matte — the
-     * $0.12/source-minute rung, not the $0.004 one, and a caption layer usually
-     * spans the whole video.
-     *
-     * Requested, not guaranteed: the renderer degrades to the front mount when no
-     * co-view is on the timeline (nothing to hide behind).
-     */
     captionsBehind?: boolean;
     captionStyle?: Partial<CaptionStyle>;
     width: number;
     height: number;
     fps: number;
     durationInFrames: number;
-    /**
-     * Target platform frozen from the suggestion (`composition.format.platform`:
-     * tiktok/ig/youtube/…). Output-determining: the composition floor's safe-zone
-     * placement clears that surface's UI chrome from the caption band. Absent ⇒ the
-     * floor falls to its conservative 'unknown' (broadcast) safe-zone profile. Read
-     * straight from the wire `Format.platform`; the renderer threads it to every
-     * CropFromTrajectory so buildFloorInput sees the real destination.
-     */
     platform?: string;
     outputWidth?: number;
     outputHeight?: number;
@@ -322,14 +148,5 @@ export interface RenderInput {
     watermark?: boolean;
     scenes?: Scene[];
     sceneGlobal?: GlobalEffects;
-    /**
-     * Active brand kit for render-time token resolution. This is the
-     * fully-materialized `ResolvedBrandKit` the render snapshot freezes
-     * (the render intake → resolveBrandKit), NOT the sparse
-     * 5-colour `@cueframe/core` BrandKit — it carries the Tier-2 colour core,
-     * `caption.{fg,scrim}`, and `fonts.{heading,body,caption}`. Overlay params may
-     * contain `"$brand:<path>"` refs that resolve against it. Optional — absent
-     * brand kit makes a `$brand:` ref fall to its contrast-safe / fallback default.
-     */
     brandKit?: ResolvedBrandKit;
 }

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

@@ -0,0 +1 @@
+export declare const BAKE_VERSION = "subjtrack-persistent-deadzone-fitzoom-v8-2026.06.21";

package/dist/_members/core/render/vcam/cameraPath.d.ts

@@ -1,51 +1,7 @@
-/**
- * vcam/cameraPath.ts — the SINGLE virtual-camera stability stage (Phase 3).
- *
- * Replaces both `emaSmooth` (for the centers) and the render-side
- * `smoothTrajectory` Gaussian with ONE pass per shot. Per the spec
- * (2026-06-21-virtual-camera-reframe-design.md, "Virtual-camera stability — one
- * stage, no LP"):
- *
- *   1. Deadzone INCLUSION gate (output-crop-normalized): the camera HOLDS while
- *      the padded RequiredRegion stays inside a safe region of the current crop
- *      window; it moves ONLY when the region would exit. This is the inclusion
- *      INVARIANT — the crop always contains the RequiredRegion ⇒ the subject
- *      never walks out of frame. This is what turns Phase 2's "static hold" into
- *      "hold, then glide to re-contain" — a moving subject is TRACKED.
- *   2. One Hamming-window weighted mean over each shot run's gated centers
- *      (acausal, single pass, no lag). Forward-fill at the start; the window
- *      AUTO-SHRINKS near a shot boundary so it never blends across a cut.
- *   3. Null/occluded regions are forward-filled (the last in-shot region) before
- *      the gate, minus the deleted jump heuristic — gaps longer than the window
- *      hold; re-emergence outside the pad glides over the window.
- *
- * No second smoothing: render samples this base path verbatim. The only reset is
- * a detector `shotBoundary` — a center jump is NEVER inferred as a cut (the
- * deleted `isJump`/`JUMP_THRESHOLD` false-cut teleport).
- *
- * Coordinate systems: RequiredRegions + centers are SOURCE-NORMALIZED. The
- * deadzone is OUTPUT-CROP-NORMALIZED (a fraction of the crop window), so the
- * held feel is zoom-invariant — it is converted to source units here using the
- * crop-window size. Pure, deterministic, no I/O.
- */
 import type { RequiredRegion } from './requiredRegion.js';
 import type { Center } from './subjectSet.js';
-/** The crop window the camera commands, source-normalized (the largest output-
- *  aspect rect that fits the source, scaled by the clamped zoom). */
 export interface CropWindow {
-    /** Window width as a fraction of source width ∈ (0,1]. */
     w: number;
-    /** Window height as a fraction of source height ∈ (0,1]. */
     h: number;
 }
-/**
- * The single stability stage: per-frame RequiredRegions → smoothed, inclusion-
- * satisfying per-frame crop centers (source-normalized). `cropFor(frame)` gives
- * the crop window for that frame (it can vary per frame when zoom is eased).
- *
- * `interiorCuts` are segment-local frame indices where a new shot begins (the
- * SAME set the derive already computes). Each shot is gated + smoothed
- * independently (deadzone, window clamp, forward-fill all reset at the cut).
- * Frames whose shot never resolved a region hold `centerHold` (source center).
- */
 export declare function cameraPath(regions: Array<RequiredRegion | null>, cropFor: (frame: number) => CropWindow, fps: number, interiorCuts: Iterable<number>, centerHold?: Center): Center[];