@cueframe/kernel 0.1.1 → 0.1.2

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[];

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

@@ -1,113 +1,20 @@
-/**
- * vcam/constants.ts — all virtual-camera selection params, in one place.
- *
- * Phase 2 (subject-of-interest selection). The deadzone / Hamming-window /
- * zoom-fit params land alongside their modules in Phase 3/5; only the
- * Phase-2 selection params live here today.
- *
- * Sizes are FRAME-HEIGHT fractions (a face box's height ÷ source height), the
- * same units the detector emits. Persistence is a fraction of the shot's frames.
- */
-/** Locked-set gate — drop a track iff
- *  `(persistence < P_MIN AND size_med < SIZE_DOMINANT) OR (size_med < SIZE_MIN)`.
- *  A transient small/brief face is dropped (can't re-weight anything); a
- *  DOMINANT late entrant (low persistence, large size) is KEPT — the flat
- *  `persistence < 0.5` gate would have silently dropped the intended subject. */
 export declare const P_MIN = 0.5;
-/** Minimum face-height fraction to survive the gate at all. */
 export declare const SIZE_MIN = 0.06;
-/** Face-height fraction at/above which a brief track is kept regardless of
- *  persistence (a dominant late entrant). */
 export declare const SIZE_DOMINANT = 0.18;
-/** Max members framed for `all-faces` (top-K by dominance). */
 export declare const MAX_SUBJECTS = 3;
-/** Dominance weights — `0.4·size + 0.2·centrality + 0.2·persistence + 0.2·speaking`.
- *  `speaking`/`centrality` feed dominance, NEVER the gate. */
 export declare const DOMINANCE_WEIGHTS: {
     readonly size: 0.4;
     readonly centrality: 0.2;
     readonly persistence: 0.2;
     readonly speaking: 0.2;
 };
-/** Per-frame set-MEMBERSHIP hysteresis (in seconds; converted to frames with
- *  the source fps). The locked set is the candidate pool; whether a member is
- *  IN the framed region this frame is decided with add/drop hysteresis so a
- *  member flickering at the gate boundary doesn't toggle the framing. The
- *  deadzone (Phase 3) stabilizes PAN; hysteresis stabilizes set MEMBERSHIP. */
 export declare const ENTER_SEC = 0.3;
 export declare const LEAVE_SEC = 0.5;
-/**
- * Headroom pad added around a RequiredRegion's subject/group extent (a fraction
- * of the SOURCE dimension), BEFORE the crop must contain it. This is the
- * "frame the head, not just the box" margin — the region the crop is obliged to
- * keep in view is the subject box grown by this much on every side. Source-
- * normalized (the region geometry is source-normalized; the deadzone below is
- * the output-crop-normalized hold band). ~6% of the source on each side gives a
- * comfortable margin around a face/group without over-zooming.
- */
 export declare const REGION_PAD = 0.06;
-/**
- * Deadzone inclusion gate (OUTPUT-CROP-NORMALIZED — a fraction of the crop
- * WINDOW, the same units as the render's old `DEADZONE`). The camera HOLDS while
- * the padded RequiredRegion stays inside the crop window shrunk by this margin
- * on each side (the "safe region"); it only moves when the region would exit
- * that safe region. Calibrated ≥ the render's old `DEADZONE=0.018` hold effect
- * on a static head, so the relocated deadzone is no looser than before. 0.10 of
- * the crop width is the spec's `REGION_PAD ≈ 0.10 of crop width` value — the
- * band inside which subject motion demands ZERO camera motion (the locked feel).
- */
 export declare const DEADZONE = 0.1;
-/**
- * Hamming smoothing window half-length, in SECONDS (converted to frames with the
- * source fps; `round(0.5·fps)` ≈ 15 frames at 30fps). The single acausal
- * Hamming-weighted mean over each shot run's deadzone-gated centers — replaces
- * the old forward+backward EMA AND the render Gaussian. Clamped to the shot run
- * (forward-fill at the start, window auto-shrinks near a shot boundary) so it
- * never blends across a cut. A shorter window = snappier tracking; longer =
- * more damped glide. 0.5s matches the spec.
- */
 export declare const SMOOTH_WINDOW_SEC = 0.5;
-/**
- * Outlier-reject median-filter radius on the RequiredRegion series, in SECONDS
- * (converted to frames with the source fps). A single-frame detector/ReID spike
- * — the box teleporting across the frame for one frame, then snapping back —
- * would yank the deadzone gate (the chase, re-skinned). A short median rejects
- * it while tracking a clean multi-frame walk exactly (an order statistic, not a
- * low-pass — lag-free on a monotone pan). ~0.12s (≈4 frames at 30fps, ≈7 at
- * 60fps) outvotes a short multi-frame ReID swap without smearing a real walk.
- */
 export declare const REGION_MEDIAN_SEC = 0.12;
-/**
- * Maximum per-frame camera-center move during the inclusion clamp, as a fraction
- * of the CROP WINDOW per second (converted to source-units-per-frame with the
- * crop size + fps). Sized GENEROUSLY: a real walking subject (≈3–5 crop-widths/s)
- * tracks unthrottled, so the inclusion invariant holds frame-to-frame and the
- * subject stays in frame (inclusionRate ≈ 1.0). The cap exists only to convert a
- * single-frame TELEPORT — a detector ReID swap or a far re-emergence after a gap
- * that would otherwise snap the camera a full frame-width in one frame — into a
- * bounded ≤`cap/fps` step (the spec's "re-emergence glides over the window"; the
- * parabolic re-acquire ease is the deferred L1 slot). At the cap the worst step
- * is bounded well below the raw-centroid chase, while continuous tracking is
- * unaffected. 8 crop-widths/sec ≈ 0.13 crop-widths/frame at 60fps.
- */
 export declare const REACQUIRE_GLIDE_PER_SEC = 8;
-/**
- * The bake's crop-window zoom clamp, mirrored here so `fitZoom` produces a zoom
- * inside the SAME envelope the renderer (`computeCropTransform` `bakedZoom`) and
- * `cropWindowSizeFor` enforce. ZOOM_MAX = 1.0 is the widest honest frame (the
- * largest source-fitting output-aspect rect — can't widen past the source);
- * ZOOM_MIN = 0.4 is the tightest crop the bake allows. A fitting group is framed
- * at the contained zoom clamped into [ZOOM_MIN, ZOOM_MAX]; an over-wide group
- * pads-and-holds at ZOOM_MAX and is flagged `overframed`.
- */
 export declare const ZOOM_MIN = 0.4;
 export declare const ZOOM_MAX = 1;
-/**
- * Min-shot-length floor for ZOOM recalibration, in SECONDS (converted to frames
- * with the source fps; round(0.4*fps) is ~12 frames at 30fps). A shot SHORTER
- * than this inherits the PREVIOUS shot's zoom rather than recalibrating, so a
- * sub-second montage (3-15-frame sub-shots, each independently zoom-fit) can't
- * STROBE the zoom channel (the named regression risk this design introduces).
- * Pan still resets at every cut - only the zoom is held; the floor is zoom-only.
- */
 export declare const MIN_ZOOM_SHOT_FRAMES = 0.4;

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

@@ -1,30 +1,2 @@
-/**
- * vcam/errorCodes.ts — the virtual-camera error vocabulary, as VALUES.
- *
- * Every code the vcam layer can throw (now or in a later phase) is listed here
- * as a literal value, and the registry-membership CI test
- * (`__tests__/vcamErrorRegistry.test.ts`) imports THIS list and asserts each one
- * exists in `@cueframe/errors`'s `ERROR_CODES`. Importing the codes as values
- * (not grepping string literals) means a template/variable code can't slip past
- * the gate — an unregistered code would make the CFERR decode fall back to
- * `internal_error` and 500 (the `clip_source_track_mismatch` landmine).
- *
- * Phase 1 registers all of these in `packages/errors/src/registry.ts` even
- * though some are thrown only in later phases (`subject_uncontainable`,
- * `trajectory_internal_gap`, `clip_trajectory_merge_conflict`) — registered now
- * so they can never 500 when the phase that throws them lands.
- *
- * `subject_not_tracked` is the EXISTING segment-level resolution gate (kept,
- * registered already); it's listed so the membership test covers the full vcam
- * throw surface in one place.
- *
- * NOT codes (documented emitted outcomes / legal inputs, never throws):
- *   - `overframed` — an emitted boolean OUTCOME on an `all-faces` segment whose
- *     group is wider than the aspect (the widest honest frame), NOT an error.
- *   - a legacy track with no `shotBoundaries` → ONE shot (no
- *     `shot_boundaries_missing` throw); an empty locked set → center-hold.
- */
-/** The error codes the vcam (virtual-camera) layer is allowed to throw. Each
- *  MUST be a row in `@cueframe/errors` `ERROR_CODES` (asserted in CI). */
 export declare const VCAM_ERROR_CODES: readonly ["subject_not_tracked", "subject_detection_failed_on_generated", "subject_uncontainable", "trajectory_internal_gap", "clip_trajectory_merge_conflict"];
 export type VcamErrorCode = (typeof VCAM_ERROR_CODES)[number];

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

@@ -1,90 +1,14 @@
-/**
- * vcam/framing.ts — zoom-to-fit for ALL modes (Phase 5).
- *
- * Generalizes today's face-only `calibrateShotScale` (which sizes ZOOM to a
- * single detected face's median height for an editorial `shotScale`) into a
- * mode-agnostic `fitZoom` that sizes the crop to CONTAIN a locked subject set's
- * union extent — the automatic fit the spec mandates (brain spec
- * 2026-06-21-virtual-camera-reframe-design.md, "Framing & zoom-to-fit (ALL
- * modes)" + RESOLVED #2 "automatic-fit only for the ship").
- *
- * The headline consumer is `all-faces`: today every all-faces segment ships at
- * zoom 1.0 (the widest honest frame) because `calibrateShotScale` has no
- * `shotScale` target for it and returns the fallback. A group that FITS 9:16 is
- * then left with wasted margin instead of being framed tight. `fitZoom` sizes the
- * crop to the group's union so a fitting group is zoom-fit (zoom < 1.0), while an
- * over-wide group (members at opposite edges of a 16:9 frame) is the documented
- * `overframed` outcome: pad-and-hold at zoom 1.0, emit the flag, NEVER silently
- * clip a wing and NEVER auto-drop a member (the editorial drop/cut decision
- * belongs to the driving agent — RESOLVED #1).
- *
- * Hold scope is explicit (resolves the per-frame-vs-per-shot contradiction):
- * zoom re-fits PER SHOT (a punch-in at every detector cut), but WITHIN a shot the
- * fit is sized ONCE over the shot-wide union extent and HELD — no per-frame
- * breathing. A pre-pass here computes the shot-max union BEFORE the per-shot zoom
- * split slices the series.
- *
- * Sub-second montage cuts are a named zoom-strobe regression risk (3–15-frame
- * sub-shots each independently calibrated → strobe). Mitigation: a min-shot-
- * length floor — a shot shorter than `MIN_ZOOM_SHOT_FRAMES` INHERITS the previous
- * shot's zoom (pan still resets at the cut; pan is cameraPath's job). So a 1-frame
- * shot can't spike the zoom channel.
- *
- * Pure, deterministic, no I/O. Boxes are source-normalized `[x1,y1,x2,y2]` ∈
- * [0,1]; `pad` is a fraction of the source dimension (the SAME `REGION_PAD` the
- * RequiredRegion uses, so the crop is sized to contain exactly the padded region
- * the camera is obliged to keep in frame).
- */
 import type { NormBox } from './subjectSet.js';
-/** One shot's automatic-fit result. */
 export interface ShotFit {
-    /** Source-normalized zoom_scale (the largest output-aspect rect that fits the
-     *  source × this contains the shot-wide padded union), clamped [ZOOM_MIN,
-     *  ZOOM_MAX]. */
     zoom: number;
-    /** True iff the padded union is WIDER than the crop window at zoom 1.0 — the
-     *  group cannot be contained at the output aspect, so the camera pads-and-holds
-     *  at zoom 1.0 (the widest honest frame). An emitted authored outcome, surfaced
-     *  to the agent; NOT an error and NOT a silent clip. */
     overframed: boolean;
 }
-/**
- * The shot-wide padded union extent of a per-frame box series, over `[start,
- * end)`. The union of every present box in the shot, grown by `pad` on each side
- * (clamped to [0,1]). Returns null when no box is present anywhere in the shot
- * (the camera center-holds; there is nothing to fit). Source-normalized.
- */
 export declare function shotUnionExtent(boxes: Array<NormBox | null>, start: number, end: number, pad?: number): {
     w: number;
     h: number;
 } | null;
-/**
- * The automatic zoom-to-fit for ONE shot's union extent. Sizes the crop so the
- * largest output-aspect rect that fits the source, scaled by this zoom, CONTAINS
- * the padded union on BOTH axes. The crop window scales linearly with zoom
- * (`cropWindowSizeFor`: `cropW *= zoom`), so the smallest zoom that contains a
- * source-normalized union of size `(uw, uh)` is `max(uw/Wb, uh/Hb)` where
- * `(Wb, Hb)` is the zoom-1.0 window.
- *
- * Fits (≤ 1.0) → that zoom, clamped to the floor. Doesn't fit (> 1.0 needed, the
- * group is wider than the output aspect) → `overframed`, pad-and-hold at 1.0. A
- * null/empty extent → no subject to fit → zoom 1.0, not overframed (center-hold).
- */
 export declare function fitZoom(extent: {
     w: number;
     h: number;
 } | null, srcW: number, srcH: number, aspect: string): ShotFit;
-/**
- * Per-shot automatic zoom-to-fit over a segment's per-frame union-box series.
- * Computes the shot-wide union extent per shot, then `fitZoom`, applying the
- * min-shot-length floor: a shot shorter than `MIN_ZOOM_SHOT_FRAMES` INHERITS the
- * previous shot's fit (zoom + overframed) so a sub-second montage cut can't strobe
- * the zoom channel; pan still resets at the cut (cameraPath owns pan). The first
- * shot has no predecessor → it fits on its own extent regardless of length (a
- * single short clip must still frame its subject).
- *
- * Returns one `ShotFit` per shot, in shot order — the same shot order
- * `segmentShots(interiorCuts, segLen)` produces. The caller (deriveTrajectory)
- * applies the per-shot zoom to the matching sub-shot it already slices.
- */
 export declare function fitZoomPerShot(boxes: Array<NormBox | null>, interiorCuts: Iterable<number>, srcW: number, srcH: number, aspect: string, fps: number, segLen: number, pad?: number): ShotFit[];