@cueframe/kernel 0.1.0 → 0.1.2

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

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

@@ -1,85 +1,14 @@
-/**
- * vcam/requiredRegion.ts — every focus mode's per-frame target, lowered into a
- * `RequiredRegion`: the SOURCE-NORMALIZED box the crop window MUST contain.
- *
- * Phase 3 of the virtual-camera redesign (brain spec
- * 2026-06-21-virtual-camera-reframe-design.md, "Every focus mode lowers to a
- * RequiredRegion" + "Virtual-camera stability"). A RequiredRegion is the padded
- * subject/group extent (subject box + headroom pad). `cameraPath` then enforces
- * the INCLUSION INVARIANT: the crop always contains the RequiredRegion ⇒ the
- * subject can never walk out of frame.
- *
- * This is a REPRESENTATION, not a behavior change for the modes that already
- * work: `face` lowers its single per-frame subject box; `point` a zero-size rect
- * at the authored location; `frame-center` the center rect. Only `all-faces`
- * gains tracking — its region is the per-frame framed-group union box from
- * `subjectSet` (hysteresis-filtered), so the camera follows a moving group.
- *
- * Pure, deterministic, no I/O. All boxes are source-normalized `[x1,y1,x2,y2]`
- * ∈ [0,1]; `REGION_PAD` is a fraction of the source dimension (the geometry is
- * source-normalized — the deadzone in `cameraPath` is the output-crop-normalized
- * hold band, a separate stage).
- */
 import type { Center, NormBox } from './subjectSet.js';
-/** The padded box the crop must contain, as a center+size — the unit the
- *  camera-path solver consumes. Source-normalized: `cx,cy` ∈ [0,1], `w,h` the
- *  fraction of the source the region spans (already padded). */
 export interface RequiredRegion {
     cx: number;
     cy: number;
-    /** Padded region width as a fraction of source width. */
     w: number;
-    /** Padded region height as a fraction of source height. */
     h: number;
 }
-/** Pad a source-normalized box on every side by `pad` (clamped to [0,1]) and
- *  express it as a `RequiredRegion` (center + padded size). A zero-area box (a
- *  `point` target) yields a zero-size padded region at the point. */
 export declare function padBox(box: NormBox, pad?: number): RequiredRegion;
-/** A zero-size RequiredRegion at a single point (the `point` mode target, or any
- *  centroid-only target with no extent). Padded so a point still carries a small
- *  margin the crop must contain. */
 export declare function pointRegion(c: Center, pad?: number): RequiredRegion;
-/** The frame-center RequiredRegion — a zero-size region at source center. The
- *  crop centering on it is a no-op (the window is already centerable), so this
- *  preserves `frame-center`'s `[0.5,0.5]` behavior exactly. */
 export declare function centerRegion(): RequiredRegion;
-/**
- * Lower a per-frame series of source-normalized union boxes (e.g. `all-faces`'s
- * per-frame framed-group box from `subjectSet.perFrameBoxes`) into per-frame
- * RequiredRegions. A null box (no framed member present — occlusion / gap) →
- * null region; `cameraPath` forward-fills the last in-shot region across the
- * gap (so the camera holds, not snaps to center, during a brief occlusion).
- */
 export declare function regionsFromBoxes(boxes: Array<NormBox | null>, pad?: number): Array<RequiredRegion | null>;
-/**
- * Lower a per-frame series of centroid-only targets (the `face` /
- * `active-speaker` per-frame center) into zero-size RequiredRegions. These modes
- * carry a single subject point, not a measured box, in the crop-center path —
- * lowering to a padded point keeps their framing (the camera points at the
- * subject) while giving `cameraPath` a region to include. A null center (subject
- * absent this frame) → null region (forward-filled by `cameraPath`).
- */
 export declare function regionsFromCenters(centers: Array<Center | null>, pad?: number): Array<RequiredRegion | null>;
-/**
- * Outlier-robust median filter on a region series within a SHOT (radius `r`
- * frames). Single-frame detector/ReID spikes — a crowd ReID flicker that
- * teleports the box across the frame for one frame, then snaps back — would
- * otherwise yank the camera (the chase, re-skinned). A short median on
- * cx/cy/w/h rejects them while tracking a clean multi-frame walk (an order
- * statistic, lag-free on a monotone pan). The window is clamped to the shot
- * (never reads past a cut). Null entries are skipped in the window (a present
- * spike isn't outvoted by absent frames). Identity for r < 1.
- */
 export declare function medianFilterRegions(regions: Array<RequiredRegion | null>, r: number, shotStart: number, shotEnd: number): Array<RequiredRegion | null>;
-/**
- * Build the canonical per-frame RequiredRegions for an `all-faces` segment from
- * the per-frame framed-group union boxes (`subjectSet.perFrameBoxes`): pad each
- * box, then outlier-reject single-frame spikes per shot. This is THE region the
- * camera is obliged to contain AND the region the eval measures inclusion
- * against — one source of truth, so the gate is honest (the camera is judged on
- * the same temporally-coherent region it frames). `interiorCuts` are the segment-
- * local shot boundaries (median windows never cross a cut). `fps` sizes the
- * median radius. Null boxes (occlusion) stay null (forward-filled by cameraPath).
- */
 export declare function buildRequiredRegions(boxes: Array<NormBox | null>, fps: number, interiorCuts: Iterable<number>, pad?: number): Array<RequiredRegion | null>;

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

@@ -1,45 +1,5 @@
-/**
- * vcam/shots.ts — shot segmentation, the SOLE cut source.
- *
- * Phase 1 of the virtual-camera redesign (brain spec
- * 2026-06-21-virtual-camera-reframe-design.md, "Shot/segment handling"):
- * cuts come ONLY from the detector's `track.shotBoundaries` (HSV hard cuts),
- * NEVER inferred from a face-center jump. The deleted `isJump`-as-cut inference
- * is the false-cut snap (the 1.6-frame-widths/sec teleport) — structurally
- * impossible once the only reset is a real detector boundary.
- *
- * Two scopes the selection math must NOT conflate:
- *   - **Identity scope = the authored segment** (cross-shot). A tracker id is
- *     stable within a shot; the same person is followed across cuts. The
- *     `MIN_SUBJECT_RESOLUTION` resolution gate lives at segment granularity.
- *   - **Camera re-lock scope = the shot.** The per-shot LOCKED subject set
- *     (quality gate) is computed per shot; deadzone / window / zoom-fit reset
- *     at a shot boundary (the latter two land in Phase 3/5).
- *
- * Pure, deterministic, no I/O. Inputs are already segment-local frame indices
- * (the caller rebased the window-local `shotBoundaries` into segment offsets).
- */
-/** A half-open shot range `[start, end)` in segment-local frame indices. */
 export interface ShotRange {
-    /** First frame of the shot (segment-local, inclusive). */
     start: number;
-    /** One past the last frame of the shot (segment-local, exclusive). */
     end: number;
 }
-/**
- * Split `[0, segLen)` into shot ranges at the interior cut frames.
- *
- * `interiorCuts` are segment-local frame indices where a NEW shot begins — the
- * SAME set `deriveTrajectory` already derives (`segCuts`: window-local
- * `shotBoundaries` strictly inside the segment, rebased to segment offsets). A
- * cut at frame `c` ends the prior shot at `c` and starts the next at `c`.
- *
- * Legacy tracks with no `shotBoundaries` → no interior cuts → ONE shot covering
- * the whole segment (the safe hold). `shot_boundaries_missing` is NOT thrown —
- * a one-shot segment is a legal, documented outcome, never a degrade.
- *
- * Out-of-range / duplicate / unsorted cuts are tolerated: cuts are sorted,
- * deduped, and clamped to `(0, segLen)`; zero-length spans are dropped. A
- * segment of length 0 yields no shots.
- */
 export declare function segmentShots(interiorCuts: Iterable<number>, segLen: number): ShotRange[];

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

@@ -1,106 +1,21 @@
-/**
- * vcam/subjectSet.ts — the CHASE KILLER (Phase 2).
- *
- * The `all-faces` failure is the per-frame area-weighted centroid of EVERY
- * detected face: any transient face (a crowd extra, a ByteTrack fragment, a
- * background head) yanks the centroid, so the camera ping-pongs (the "chase").
- * This module selects a STABLE subject set and frames the GROUP smoothly,
- * beating a static center crop on jitter — the headline behavioral fix.
- *
- * Mode-isolated: this is consulted ONLY for the `all-faces` path in
- * `deriveSegment`. `face` / `point` / `frame-center` / `active-speaker` keep
- * their existing selection verbatim.
- *
- * Pipeline (brain spec 2026-06-21-virtual-camera-reframe-design.md, "Subject-of
- * -interest selection"):
- *   1. Per-shot LOCKED subject set (quality gate) — size-aware drop, NOT a flat
- *      persistence gate, so a dominant late entrant is kept and a transient
- *      small face is dropped.
- *   2. Identity scope = the authored SEGMENT: union the per-shot locked sets →
- *      the segment candidate pool; rank by segment-wide dominance; take top-K.
- *   3. Per-frame set-MEMBERSHIP hysteresis over the pool (add/drop debounce) so
- *      a member flickering at the gate boundary doesn't toggle the framing.
- *   4. Emit, PER FRAME, the area-weighted centroid + union bbox over the framed
- *      members PRESENT this frame. The centroid is the raw crop target; the box
- *      is the RequiredRegion source. Transient entries/exits can't yank the
- *      camera (they're gated out of the framed set), but the framed group's own
- *      motion IS followed — Phase 3's deadzone + Hamming window in `cameraPath`
- *      turn this per-frame target into a held-then-glide path, so a walking
- *      subject stays in frame (the camera tracks) without chasing micro-jitter.
- *      (Phase 2 held this target static, which kept a moving subject framed only
- *      while it stayed near the centroid; Phase 3 lets the hold glide to re-
- *      contain the subject when it walks.)
- *
- * The per-subject `face_box_series` the floor reads is produced UNCHANGED by
- * `perSubjectSeries` — this module only chooses WHERE the camera points.
- */
 import type { FaceBox } from '../../../perception/index.js';
-/** A normalized crop center `[cx, cy]` in [0,1] vs source dims. */
 export type Center = [number, number];
-/** A source-normalized axis-aligned box `[x1, y1, x2, y2]` ∈ [0,1]. */
 export type NormBox = [number, number, number, number];
-/** The selection result for one segment's `all-faces` path. */
 export interface SubjectSetResult {
-    /** Per-frame crop target (the basis for `centers`). For `all-faces` this is
-     *  the per-frame framed-group centroid — the basis Phase 3's cameraPath
-     *  smooths into a tracking glide. (Phase 2 held it static; Phase 3 lets the
-     *  camera follow a walking subject because this now varies per frame.) */
     centers: Center[];
-    /** Per-frame UNION bbox of the framed members PRESENT this frame (after the
-     *  membership hysteresis), source-normalized `[x1,y1,x2,y2]`, or null when no
-     *  framed member is present (occlusion / between-shot gap). This is the
-     *  RequiredRegion source: Phase 3 lowers it to the padded box the crop must
-     *  contain so the subject can never walk out of frame. */
     perFrameBoxes: Array<NormBox | null>;
-    /** The tracker ids chosen as the framed set (top-K by dominance). For
-     *  diagnostics / the per-subject floor series (which is produced separately
-     *  but lists the SAME framed ids). Empty when no face survives the gate. */
     framedIds: string[];
-    /** How many frames the framed set was present in (≥1 member) — feeds the
-     *  segment-level resolution accounting (so `all-faces` on a faceless clip
-     *  center-holds, the documented outcome, rather than throwing). */
     resolvedFrames: number;
 }
-/**
- * Select the stable subject set for an `all-faces` segment and emit the per-
- * frame crop target. Pure over the segment-local slice.
- *
- * Empty locked set (no face survives the gate — a faceless / crowd-only clip) →
- * center-hold (`[0.5,0.5]` every frame), a DEFINED outcome, never a throw
- * (per spec fail-loud invariants).
- */
 export declare function selectSubjectSet(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, fps: number, perKeyframeSpeaker: Map<number, string>, interiorCuts: Iterable<number>): SubjectSetResult;
-/** How the single chosen subject is resolved per frame. `authoredFaceId` is the
- *  agent's `face` pick (a `face-N` id); `null` means active-speaker (resolve via
- *  the per-keyframe speaker, then degrade to the largest face). */
 export type SingleSubjectPick = {
     kind: 'face';
     authoredFaceId: string;
 } | {
     kind: 'active-speaker';
 };
-/** The per-frame chosen-subject box series for a `topK=1` segment (face /
- *  active-speaker). The box is the chosen subject's source-normalized extent
- *  `[x1,y1,x2,y2]`, or null when the chosen subject is absent this frame
- *  (occlusion / between-shot gap) — `cameraPath` forward-fills the last in-shot
- *  region across a brief gap and center-holds a shot with no subject at all. */
 export interface SingleSubjectResult {
-    /** Per-frame chosen-subject box (source-normalized) or null when absent. */
     perFrameBoxes: Array<NormBox | null>;
-    /** How many frames the chosen subject was actually resolved (a non-null box) —
-     *  feeds the `MIN_SUBJECT_RESOLUTION` fail-loud gate for an authored `face`. */
     resolvedFrames: number;
 }
-/**
- * The `topK=1` subjects adapter for `face` / `active-speaker`. Per frame, resolve
- * the single chosen subject and emit its source-normalized box. Pure over the
- * segment-local slice.
- *
- *  - `face` (authored id): the box of that STABLE tracker id this frame; absent →
- *    null (no silent snap to a different person — the roster rule). The empty /
- *    non-`face-` sentinel id resolves to the largest face (legacy callers).
- *  - `active-speaker`: the box of the per-keyframe speaker pick when tracked this
- *    frame; otherwise the largest face this frame (the ASD degrade, mirror of
- *    `deriveSegment`'s active-speaker path).
- */
 export declare function selectSingleSubjectBoxes(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, perKeyframeSpeaker: Map<number, string>, pick: SingleSubjectPick, nearestSpeaker: (frame: number) => string | null): SingleSubjectResult;

package/dist/_members/core/select/errorCodes.d.ts

@@ -1,27 +1,2 @@
-/**
- * select/errorCodes.ts — the Selector error vocabulary, as VALUES.
- *
- * Every code the Selector core / adapters / lowerings can throw (now or in a
- * later phase) is listed here as a literal value, and the registry-membership CI
- * test (`__tests__/selectorErrorRegistry.test.ts`) imports THIS list and asserts
- * each exists in `@cueframe/errors`'s `ERROR_CODES`. Importing the codes as VALUES
- * (not grepping literals) means a template/variable code can't slip past — an
- * unregistered code would make the CFERR decode fall back to `internal_error` and
- * 500 (the `clip_source_track_mismatch` landmine).
- *
- * Phase 1 (this phase) registers all of these even though only the CORE codes
- * (`selector_signal_absent`, `selector_override_conflict`) are thrown today; the
- * adapter/lowering codes (`selector_timebase_undefined`, `selector_group_unsynced`,
- * `selector_segment_out_of_media`) are thrown by the Phase-2 switch adapters and
- * are registered now so they can never 500 when that phase lands. Phase 3
- * (active-speaker) adds `selector_speaking_double_count` — the structural double-
- * count guard (§11-L5): weighting both `activeSpeaker` and `speaking` fails loud.
- * Phase 6 (cross-source identity) adds `selector_identity_detector_version_mismatch`
- * — a `lockPersonId` match over a STALE-detector-version embedding fails loud (the
- * 3-stamp lesson: a person-lock cosine over embeddings from a different
- * `DETECTOR_VERSION` than the reference is meaningless; refuse rather than guess).
- */
-/** The error codes the Selector layer is allowed to throw. Each MUST be a row in
- *  `@cueframe/errors` `ERROR_CODES` (asserted in CI). */
 export declare const SELECTOR_ERROR_CODES: readonly ["selector_signal_absent", "selector_override_conflict", "selector_timebase_undefined", "selector_group_unsynced", "selector_segment_out_of_media", "selector_speaking_double_count", "selector_identity_detector_version_mismatch"];
 export type SelectorErrorCode = (typeof SELECTOR_ERROR_CODES)[number];

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

@@ -1,27 +1,7 @@
-/**
- * @cueframe/core/select — the durable Selector core (selector-abstraction spec).
- *
- * The candidate-agnostic data model + the ~40-line `select()` scoring contract +
- * the per-kind `stabilize` seam. Reframe is its first instance (the subjects
- * adapter lives in `render/vcam/subjectSet.ts`, which calls `scoreAndRank` +
- * `stabilizeSelectionHysteresis` and lowers via the sealed `cameraPath`).
- *
- * Switch (Phase 2) is the second instance — same core, new candidate adapter +
- * the incumbent-challenger/presence-gate stabilizers + the cut/overlay lowering.
- */
 export type { SignalKey, Signal, CandidateSignals, Candidate, CandidateTimebase, CoreCandidate, WhenClause, EligibilityClause, SelectorRule, OverrideSpan, SelectorPolicy, Chosen, CandidateScore, PacingNote, SelectorSegment, Advisory, } from './model.js';
 export { HOLD } from './model.js';
 export { select, scoreAndRank, type SelectOptions } from './select.js';
 export { stabilizeSelectionHysteresis, stabilizeIncumbentChallenger, stabilizePresenceGate, cameraPath, type StabilizerKind, type SelectionHysteresisParams, type SelectionHysteresisResult, type IncumbentChallengerParams, type IncumbentChallengerResult, type SuppressedSwitch, type PresenceGateParams, type PresenceWindow, type CropWindow, } from './stabilize.js';
 export { SELECTOR_ERROR_CODES, type SelectorErrorCode } from './errorCodes.js';
-/** The default prominence weights — vcam's `DOMINANCE_WEIGHTS`, re-exported as the
- *  canonical "dominant-subject" `policy.weights` for the SCORE combinator. The
- *  switch instance's video-on-prominence path uses these directly (spec §9.1 P2 —
- *  "video-switch on prominence = vcam dominance, exists"); reframe uses the same
- *  constant. Re-exporting it here keeps the scoring default in the select surface.
- *  (This import is in index.ts, NOT select.ts — the rot-guard scans select.ts.) */
 export { DOMINANCE_WEIGHTS } from '../render/vcam/constants.js';
-/** The Selector engine version (spec §8). DISTINCT from BAKE_VERSION (the crop
- *  lowering stamp) and the per-signal stamps. Bump when the scoring/stabilizer
- *  math changes in a way that changes the Advisory for fixed inputs. */
 export declare const SELECTOR_VERSION = "selector-core-v1-2026.06.21";