@cueframe/kernel 0.0.1

package/dist/_members/core/render/vcam/requiredRegion.js

@@ -0,0 +1,137 @@
+/**
+ * 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 { REGION_PAD, REGION_MEDIAN_SEC } from './constants';
+import { segmentShots } from './shots';
+/** 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 function padBox(box, pad = REGION_PAD) {
+    const [x1, y1, x2, y2] = box;
+    const px1 = Math.max(0, Math.min(1, x1 - pad));
+    const py1 = Math.max(0, Math.min(1, y1 - pad));
+    const px2 = Math.max(0, Math.min(1, x2 + pad));
+    const py2 = Math.max(0, Math.min(1, y2 + pad));
+    return {
+        cx: (px1 + px2) / 2,
+        cy: (py1 + py2) / 2,
+        w: Math.max(0, px2 - px1),
+        h: Math.max(0, py2 - py1),
+    };
+}
+/** 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 function pointRegion(c, pad = REGION_PAD) {
+    return padBox([c[0], c[1], c[0], c[1]], pad);
+}
+/** 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 function centerRegion() {
+    return { cx: 0.5, cy: 0.5, w: 0, h: 0 };
+}
+/**
+ * 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 function regionsFromBoxes(boxes, pad = REGION_PAD) {
+    return boxes.map((b) => (b === null ? null : padBox(b, pad)));
+}
+/**
+ * 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 function regionsFromCenters(centers, pad = REGION_PAD) {
+    return centers.map((c) => (c === null ? null : pointRegion(c, pad)));
+}
+/** Median of a numeric window (lower-median for even length). */
+function med(xs) {
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.floor(s.length / 2)];
+}
+/**
+ * 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 function medianFilterRegions(regions, r, shotStart, shotEnd) {
+    const out = [...regions];
+    if (r < 1)
+        return out;
+    for (let i = shotStart; i < shotEnd; i++) {
+        if (regions[i] === null)
+            continue;
+        const lo = Math.max(shotStart, i - r);
+        const hi = Math.min(shotEnd - 1, i + r);
+        const cx = [];
+        const cy = [];
+        const w = [];
+        const h = [];
+        for (let j = lo; j <= hi; j++) {
+            const rj = regions[j];
+            if (rj === null)
+                continue;
+            cx.push(rj.cx);
+            cy.push(rj.cy);
+            w.push(rj.w);
+            h.push(rj.h);
+        }
+        if (cx.length === 0)
+            continue;
+        out[i] = { cx: med(cx), cy: med(cy), w: med(w), h: med(h) };
+    }
+    return out;
+}
+/**
+ * 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 function buildRequiredRegions(boxes, fps, interiorCuts, pad = REGION_PAD) {
+    const padded = regionsFromBoxes(boxes, pad);
+    const r = Math.round(REGION_MEDIAN_SEC * fps);
+    if (r < 1)
+        return padded;
+    let out = padded;
+    for (const shot of segmentShots(interiorCuts, padded.length)) {
+        out = medianFilterRegions(out, r, shot.start, shot.end);
+    }
+    return out;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * 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/shots.js

@@ -0,0 +1,53 @@
+/**
+ * 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).
+ */
+/**
+ * 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 function segmentShots(interiorCuts, segLen) {
+    if (segLen <= 0)
+        return [];
+    const cuts = [...new Set(interiorCuts)]
+        .filter((c) => c > 0 && c < segLen)
+        .sort((a, b) => a - b);
+    const bounds = [0, ...cuts, segLen];
+    const shots = [];
+    for (let i = 0; i < bounds.length - 1; i++) {
+        const start = bounds[i];
+        const end = bounds[i + 1];
+        if (end - start > 0)
+            shots.push({ start, end });
+    }
+    return shots;
+}

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

@@ -0,0 +1,106 @@
+/**
+ * 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;