@cueframe/kernel 0.1.0 → 0.1.1

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

@@ -1,248 +0,0 @@
-/**
- * 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 { segmentShots } from './shots';
-import { DEADZONE, SMOOTH_WINDOW_SEC, REACQUIRE_GLIDE_PER_SEC } from './constants';
-/** Clamp a window center so the crop window stays fully inside the source (the
- *  same coverage invariant the renderer enforces). A window wider than the axis
- *  centers. */
-function clampCenter(c, sizeFrac) {
-    if (sizeFrac >= 1)
-        return 0.5;
-    const half = sizeFrac / 2;
-    return Math.max(half, Math.min(1 - half, c));
-}
-/**
- * Minimal center that contains a 1-D interval `[lo, hi]` inside a window of size
- * `win` whose interior is shrunk by the deadzone margin `dz` on each side (the
- * "safe region"). Returns the current `held` center UNCHANGED when the interval
- * already fits in the held window's safe region; otherwise the nearest center
- * that just re-contains it (push the window the smallest distance). The deadzone
- * is the hold band: motion inside it demands zero camera motion.
- */
-function gate1D(held, lo, hi, win, dz) {
-    const safe = Math.max(0, win - 2 * dz); // safe-region width (window minus margins)
-    const ext = hi - lo;
-    const mid = (lo + hi) / 2;
-    // Region wider than the safe band: can't be fully contained at this zoom (an
-    // OVER-WIDE group — surfaced upstream as `overframed` in a later phase). HOLD
-    // on the midpoint within the SAME deadzone so the camera doesn't wobble as
-    // members enter/exit the union box; only re-centre when the midpoint itself
-    // drifts beyond the deadzone (a real group shift). Without this hold an over-
-    // wide held group jitters every frame on the union-box breathing.
-    if (ext >= safe) {
-        if (Math.abs(mid - held) <= dz)
-            return held;
-        return mid > held ? mid - dz : mid + dz;
-    }
-    const safeLo = held - safe / 2;
-    const safeHi = held + safe / 2;
-    if (lo >= safeLo && hi <= safeHi)
-        return held; // already contained → HOLD
-    // Push minimally: if the region exits left, align its left to the safe edge;
-    // if it exits right, align its right. (Both can't exit — ext < safe.)
-    if (lo < safeLo)
-        return lo + safe / 2;
-    return hi - safe / 2;
-}
-/**
- * Inclusion clamp with a per-frame GLIDE cap: re-contain the FULL region
- * `[lo,hi]` inside a window of size `win` centered near `c`, but move no more
- * than `maxStep` (source units) from the PREVIOUS output center `prev` in one
- * frame. This preserves the inclusion invariant during CONTINUOUS tracking (the
- * needed correction is sub-`maxStep`, so it's applied in full) while letting a
- * far RE-ACQUISITION (subject re-emerges across the frame after a gap) GLIDE
- * over several frames instead of teleporting — the spec's "re-emergence glides
- * over the window" (the parabolic re-acquire ease is the deferred L1 slot; this
- * is the linear floor). A region wider than the window can't be contained →
- * ease toward its midpoint.
- */
-function includeGlide1D(c, prev, lo, hi, win, maxStep) {
-    const ext = hi - lo;
-    let target;
-    if (ext >= win) {
-        // Over-wide: can't be contained at this zoom. Keep the smoothed (held) center
-        // — the gate already held it on the union midpoint within the deadzone, so
-        // re-snapping to the raw midpoint here would re-introduce the wobble.
-        target = c;
-    }
-    else {
-        const winLo = c - win / 2;
-        const winHi = c + win / 2;
-        if (lo >= winLo && hi <= winHi)
-            target = c; // already contains the region
-        else if (lo < winLo)
-            target = lo + win / 2;
-        else
-            target = hi - win / 2;
-    }
-    // Glide cap: never jump more than maxStep from the previous output center.
-    const d = target - prev;
-    if (d > maxStep)
-        return prev + maxStep;
-    if (d < -maxStep)
-        return prev - maxStep;
-    return target;
-}
-/**
- * The deadzone INCLUSION gate over one shot's regions. Walks frames in order,
- * holding the camera while the padded region stays inside the safe region of the
- * current crop window, stepping minimally to re-contain it when it exits. The
- * gate is seeded from the first region (so the shot opens framed on its subject,
- * not at a stale center). Returns the per-frame GATED center (source-normalized),
- * the input to the Hamming smoother.
- */
-function deadzoneGate(regions, crop, dzX, dzY) {
-    const out = [];
-    // Seed the held center on the first region, coverage-clamped.
-    let hx = clampCenter(regions[0].cx, crop.w);
-    let hy = clampCenter(regions[0].cy, crop.h);
-    for (const r of regions) {
-        const loX = r.cx - r.w / 2;
-        const hiX = r.cx + r.w / 2;
-        const loY = r.cy - r.h / 2;
-        const hiY = r.cy + r.h / 2;
-        hx = clampCenter(gate1D(hx, loX, hiX, crop.w, dzX), crop.w);
-        hy = clampCenter(gate1D(hy, loY, hiY, crop.h, dzY), crop.h);
-        out.push([hx, hy]);
-    }
-    return out;
-}
-/**
- * Acausal Hamming-weighted moving average over a shot run's gated centers. The
- * half-window auto-shrinks at the shot ENDS (it never reads past `[0, n)`), so a
- * shot shorter than the window smooths over its own length and never blends
- * across the cut. Single pass, symmetric weights → no lag.
- */
-function hammingSmooth(centers, halfWindow) {
-    const n = centers.length;
-    if (n <= 1 || halfWindow < 1)
-        return centers.map((c) => [c[0], c[1]]);
-    // Hamming weight at offset d (|d| ≤ halfWindow): 0.54 + 0.46·cos(π·d/halfWindow).
-    const weight = (d) => 0.54 + 0.46 * Math.cos((Math.PI * d) / halfWindow);
-    const out = new Array(n);
-    for (let i = 0; i < n; i++) {
-        const lo = Math.max(0, i - halfWindow);
-        const hi = Math.min(n - 1, i + halfWindow);
-        let sx = 0;
-        let sy = 0;
-        let sw = 0;
-        for (let j = lo; j <= hi; j++) {
-            const w = weight(j - i);
-            sx += centers[j][0] * w;
-            sy += centers[j][1] * w;
-            sw += w;
-        }
-        out[i] = sw > 0 ? [sx / sw, sy / sw] : [centers[i][0], centers[i][1]];
-    }
-    return out;
-}
-/**
- * Forward-fill null regions within a shot slice. A gap (subject occluded) holds
- * the LAST in-shot region; a leading gap (no region yet) borrows the first known
- * region in the shot. A shot with no region at all (never resolved) → null,
- * handled by the caller (center-hold). NO jump back-fill (the deleted heuristic).
- */
-function fillShot(regions) {
-    const first = regions.find((r) => r !== null) ?? null;
-    if (first === null)
-        return null;
-    const out = new Array(regions.length);
-    let last = first;
-    for (let i = 0; i < regions.length; i++) {
-        if (regions[i] !== null)
-            last = regions[i];
-        out[i] = last;
-    }
-    return out;
-}
-/**
- * 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 function cameraPath(regions, cropFor, fps, interiorCuts, centerHold = [0.5, 0.5]) {
-    const n = regions.length;
-    if (n === 0)
-        return [];
-    const halfWindow = Math.max(1, Math.round(SMOOTH_WINDOW_SEC * fps));
-    const out = new Array(n);
-    const shots = segmentShots(interiorCuts, n);
-    for (const shot of shots) {
-        const slice = regions.slice(shot.start, shot.end);
-        // `regions` are already the outlier-robust RequiredRegions
-        // (`buildRequiredRegions`): single-frame detector/ReID spikes rejected, so
-        // the gate frames the temporally-coherent subject, not a flicker.
-        const filled = fillShot(slice);
-        if (filled === null) {
-            // No region resolved anywhere in this shot → hold source center (the
-            // documented faceless/occluded outcome).
-            for (let i = shot.start; i < shot.end; i++)
-                out[i] = [centerHold[0], centerHold[1]];
-            continue;
-        }
-        // Use the shot's first crop window for the deadzone margins (zoom is per-shot
-        // constant for the non-eased path; eased zoom is rare on all-faces and the
-        // gate margin is robust to small per-frame zoom drift).
-        const crop0 = cropFor(shot.start);
-        const dzX = DEADZONE * crop0.w;
-        const dzY = DEADZONE * crop0.h;
-        const gated = deadzoneGate(filled, crop0, dzX, dzY);
-        // Auto-shrink the window to the shot length so it never blends across a cut.
-        const hw = Math.min(halfWindow, Math.max(1, gated.length - 1));
-        const smoothed = hammingSmooth(gated, hw);
-        // Post-smooth: re-establish the INCLUSION INVARIANT with a per-frame GLIDE
-        // cap. Continuous tracking needs a sub-cap correction → applied in full (the
-        // crop contains the RequiredRegion ⇒ the subject never walks out of frame).
-        // A far RE-ACQUISITION after a gap (subject re-emerges across the frame)
-        // exceeds the cap → it GLIDES over several frames instead of teleporting (the
-        // spec's "re-emergence glides over the window"). Then the coverage clamp
-        // keeps the window inside the source.
-        const maxStepX = (REACQUIRE_GLIDE_PER_SEC * crop0.w) / fps;
-        const maxStepY = (REACQUIRE_GLIDE_PER_SEC * crop0.h) / fps;
-        let prevX = clampCenter(smoothed[0][0], crop0.w);
-        let prevY = clampCenter(smoothed[0][1], crop0.h);
-        for (let i = 0; i < smoothed.length; i++) {
-            const crop = cropFor(shot.start + i);
-            const r = filled[i];
-            const incX = includeGlide1D(smoothed[i][0], prevX, r.cx - r.w / 2, r.cx + r.w / 2, crop.w, maxStepX);
-            const incY = includeGlide1D(smoothed[i][1], prevY, r.cy - r.h / 2, r.cy + r.h / 2, crop.h, maxStepY);
-            prevX = clampCenter(incX, crop.w);
-            prevY = clampCenter(incY, crop.h);
-            out[shot.start + i] = [prevX, prevY];
-        }
-    }
-    return out;
-}

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

@@ -1,115 +0,0 @@
-/**
- * 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 const P_MIN = 0.5;
-/** Minimum face-height fraction to survive the gate at all. */
-export const SIZE_MIN = 0.06;
-/** Face-height fraction at/above which a brief track is kept regardless of
- *  persistence (a dominant late entrant). */
-export const SIZE_DOMINANT = 0.18;
-/** Max members framed for `all-faces` (top-K by dominance). */
-export 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 const DOMINANCE_WEIGHTS = {
-    size: 0.4,
-    centrality: 0.2,
-    persistence: 0.2,
-    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 const ENTER_SEC = 0.3;
-export const LEAVE_SEC = 0.5;
-// ── Phase 3: virtual-camera stability (requiredRegion + cameraPath) ──────────
-/**
- * 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 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 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 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 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 const REACQUIRE_GLIDE_PER_SEC = 8;
-// ── Phase 5: zoom-to-fit framing (framing.ts) ────────────────────────────────
-/**
- * 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 const ZOOM_MIN = 0.4;
-export const ZOOM_MAX = 1.0;
-/**
- * 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 const MIN_ZOOM_SHOT_FRAMES = 0.4;

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

@@ -1,39 +0,0 @@
-/**
- * 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 const VCAM_ERROR_CODES = [
-    'subject_not_tracked',
-    // D10 (P5 4b): generated-footage sibling of `subject_not_tracked`, thrown by the
-    // same `deriveTrajectory` resolution gate when `isGenerated` is true. Listed so
-    // the membership test covers it (it would otherwise CFERR-decode to
-    // internal_error → 500, the clip_source_track_mismatch landmine).
-    'subject_detection_failed_on_generated',
-    'subject_uncontainable',
-    'trajectory_internal_gap',
-    'clip_trajectory_merge_conflict',
-];

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

@@ -1,136 +0,0 @@
-/**
- * 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 { REGION_PAD, MIN_ZOOM_SHOT_FRAMES, ZOOM_MIN, ZOOM_MAX } from './constants';
-import { segmentShots } from './shots';
-import { cropWindowSizeFor } from '../deriveTrajectory';
-/**
- * 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 function shotUnionExtent(boxes, start, end, pad = REGION_PAD) {
-    let x1 = Infinity;
-    let y1 = Infinity;
-    let x2 = -Infinity;
-    let y2 = -Infinity;
-    let any = false;
-    for (let i = start; i < end; i++) {
-        const b = i >= 0 && i < boxes.length ? boxes[i] : null;
-        if (!b)
-            continue;
-        any = true;
-        if (b[0] < x1)
-            x1 = b[0];
-        if (b[1] < y1)
-            y1 = b[1];
-        if (b[2] > x2)
-            x2 = b[2];
-        if (b[3] > y2)
-            y2 = b[3];
-    }
-    if (!any)
-        return null;
-    const px1 = Math.max(0, x1 - pad);
-    const py1 = Math.max(0, y1 - pad);
-    const px2 = Math.min(1, x2 + pad);
-    const py2 = Math.min(1, y2 + pad);
-    return { w: Math.max(0, px2 - px1), h: Math.max(0, py2 - py1) };
-}
-/**
- * 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 function fitZoom(extent, srcW, srcH, aspect) {
-    if (extent === null || extent.w <= 0 || extent.h <= 0) {
-        return { zoom: ZOOM_MAX, overframed: false };
-    }
-    const base = cropWindowSizeFor(srcW, srcH, ZOOM_MAX, aspect); // zoom-1.0 window
-    if (base.w <= 0 || base.h <= 0)
-        return { zoom: ZOOM_MAX, overframed: false };
-    const needed = Math.max(extent.w / base.w, extent.h / base.h);
-    if (needed > ZOOM_MAX) {
-        // Wider than the output aspect at zoom 1.0 — the documented `overframed`
-        // outcome. Pad-and-hold at the widest honest frame.
-        return { zoom: ZOOM_MAX, overframed: true };
-    }
-    // Fits: take the contained zoom, clamped to the zoom floor (so an extremely
-    // small group can't over-zoom past ZOOM_MIN — the bake's tightest crop).
-    return { zoom: Math.max(ZOOM_MIN, needed), overframed: false };
-}
-/**
- * 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 function fitZoomPerShot(boxes, interiorCuts, srcW, srcH, aspect, fps, segLen, pad = REGION_PAD) {
-    const shots = segmentShots(interiorCuts, segLen);
-    const minLen = Math.max(1, Math.round(MIN_ZOOM_SHOT_FRAMES * fps));
-    const out = [];
-    let prev = null;
-    for (const shot of shots) {
-        const shotLen = shot.end - shot.start;
-        if (prev !== null && shotLen < minLen) {
-            // Sub-MIN_ZOOM_SHOT_FRAMES → inherit the previous shot's zoom (no recalibrate
-            // → no strobe). Pan still resets at the cut in cameraPath.
-            out.push({ zoom: prev.zoom, overframed: prev.overframed });
-            continue;
-        }
-        const extent = shotUnionExtent(boxes, shot.start, shot.end, pad);
-        const fit = fitZoom(extent, srcW, srcH, aspect);
-        out.push(fit);
-        prev = fit;
-    }
-    return out;
-}

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

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