@cueframe/kernel 0.0.1

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

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

@@ -0,0 +1,115 @@
+/**
+ * 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.d.ts

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

@@ -0,0 +1,39 @@
+/**
+ * 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.d.ts

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

@@ -0,0 +1,136 @@
+/**
+ * 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.d.ts

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