@cueframe/kernel 0.0.1

package/dist/_members/core/render/types.d.ts

@@ -0,0 +1,304 @@
+import type { Scene, GlobalEffects, EffectTarget } from '../../composition/ops/index.js';
+import type { ResolvedBrandKit } from '../../composition/projection/index.js';
+import type { Reframe } from '../../composition/reframe/index.js';
+import type { CaptionWord as WireCaptionWord, CaptionStyle as WireCaptionStyle } from '../../composition/validators/index.js';
+export type OverlayTemplate = 'custom' | 'gif' | 'image' | 'lottie' | (string & {});
+export interface OverlayParams {
+    text: string;
+    subtext?: string;
+    position?: 'left' | 'center' | 'right';
+    accentColor?: string;
+    textColor?: string;
+    fontFamily?: string;
+    backgroundColor?: string;
+    sourceCode?: string;
+    jsxSource?: string;
+    transition?: 'fade' | 'slide' | 'wipe' | 'none';
+    sequenceGroup?: string;
+    src?: string;
+    loop?: boolean;
+    widthPercent?: number;
+    xPercent?: number;
+    yPercent?: number;
+    fontSize?: number;
+    /** heroText (depth grammar §3.4): font size as % of composition height (default 14). */
+    fontSizePct?: number;
+    /** heroText: per-word reveal offsets in ms relative to the overlay's start. */
+    revealAtMs?: number[];
+    /** heroText: display weight override (default 800). */
+    fontWeight?: number;
+    /**
+     * Behind-subject overlays only: `false` opts out of the atmospheric depth
+     * treatment (brightness/saturation/blur — `BEHIND_ATMOSPHERE`) the behind
+     * host applies by default. Ignored on front overlays.
+     */
+    atmosphere?: boolean;
+    /** card overlay: the authored HTML/CSS fragment, rendered VERBATIM via
+     *  dangerouslySetInnerHTML inside the region box (OverlayContent case 'card'). */
+    html?: string;
+    /** card overlay: brand-token map (literal | `$brand:` ref per value),
+     *  resolved at render into `--cf-<key>` CSS custom properties on the wrapper box. */
+    cssTokens?: Record<string, string>;
+}
+export interface CompositionClip {
+    id: string;
+    src: string;
+    /** Proxy URL for preview playback (lighter H.264 transcode) */
+    previewSrc?: string;
+    sourceInFrames: number;
+    sourceOutFrames: number;
+    timelineStartFrames: number;
+    durationInFrames: number;
+    /** The clip's `trim.start` in output-fps frames. With `excludedRanges` the
+     *  clip plays multiple playable spans whose `sourceInFrames` are source-
+     *  absolute; the crop trajectory is clip-relative (frame 0 = trim.start), so
+     *  the renderer needs this to map output frames → trajectory frames across the
+     *  trimmed gaps. Absent ⇒ 0 (clip starts at its source origin).
+     *
+     *  NOT guaranteed non-negative: it is a PURE OFFSET, not a validated
+     *  trim.start echo. When a sandbox harness physically trims the source file
+     *  (materializeSources' shallow-seek), sourceInFrames/sourceOutFrames/
+     *  trimStartFrames are all rebased by the same shift into segment-file
+     *  coordinates — only their differences are meaningful, and trimStartFrames
+     *  can legitimately go negative. Consumers must never validate or seek on
+     *  its absolute value. */
+    trimStartFrames?: number;
+    playbackRate?: number;
+    volume?: number;
+    muted?: boolean;
+    opacity?: number;
+    scale?: number;
+    rotation?: number;
+    /**
+     * TIME-VARYING channels, keyed by param path, times CLIP-RELATIVE in seconds.
+     * When a param appears here it overrides its scalar sibling above for the
+     * clip's duration; the scalar remains what a non-animating consumer reads.
+     * Interpolation is `valueAt` from `@cueframe/composition/timeline` — one
+     * implementation, because the editor, this renderer and the evaluator must
+     * agree or the motion the judge grades is not the motion that ships.
+     */
+    animate?: Record<string, Array<{
+        time: number;
+        value: number;
+        easing?: unknown;
+    }>>;
+    /**
+     * Output-space placement rect (fractions of the output frame, 0..1).
+     * Default (absent) = full frame {x:0,y:0,w:1,h:1}. A sub-frame region makes
+     * the clip occupy only that rect of the output — the foundation for
+     * picture-in-picture / split-screen / inset cards, where lower tracks show
+     * through the uncovered area. The clip's source is fit into the region per
+     * `fit`. Mirrors `Region` on the wire (composition.ts).
+     *
+     * NOTE: the per-frame crop pipeline (CropFromTrajectory) renders against the
+     * FULL output frame; composing a sub-frame region with a non-identity crop
+     * requires the crop to target the region's aspect. The renderer applies the
+     * placement; full region×crop compose is wired incrementally.
+     */
+    region?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** How the source fills `region`: 'cover' (fill+crop, default) or 'contain' (letterbox). */
+    fit?: 'cover' | 'contain';
+    mediaType?: 'video' | 'audio' | 'image';
+    /**
+     * Ken-Burns motion preset for still-image clips (mediaType === 'image').
+     * A convenience the renderer's <StillCrop> lowers to a `reframe`
+     * (kenBurnsToReframe) and runs through the unified per-frame crop renderer.
+     * Default 'in' (gentle zoom-in). Ignored for video / audio clips.
+     */
+    kenBurns?: 'in' | 'out' | 'pan-l' | 'pan-r' | 'none';
+    /**
+     * Authored camera channel for a still (mediaType === 'image'). When present,
+     * <StillCrop> derives the still trajectory from THIS (arbitrary per-frame
+     * point-zoom + center) instead of lowering `kenBurns` — so an image can zoom
+     * into a specific point (a UI element), not just the centered kenBurns
+     * presets. `kenBurns` is the fallback when no reframe was authored.
+     */
+    reframe?: Reframe;
+    /**
+     * Loop the underlying media until the clip's duration runs out. Used by
+     * gif enrichment clips (whose source mp4 may be shorter than the moment)
+     * and audio ambient beds. Ignored on `mediaType === 'image'`.
+     */
+    loop?: boolean;
+    transitionIn?: 'fade' | 'dissolve' | 'wipe' | 'none';
+    transitionDurationFrames?: number;
+    /** Original clip ID — set on sub-clips produced by splitting around deleted ranges. */
+    parentId?: string;
+    /**
+     * Pre-resolved crop-trajectory JSON URL for render-time per-frame
+     * cropping. When set, the renderer reads the trajectory's per-segment
+     * per-frame normalized centers and applies a CSS transform on the
+     * raw source video to produce the cropped output.
+     *
+     * 2026-05-28 substrate revision: replaces the prior baked-mp4
+     * substitution + variantMaskUrl combo. Bake produces only this JSON
+     * now; render-side does the pixel pushing. See
+     * packages/execution/core/src/render/deriveTrajectory.ts for the producer
+     * (TS-side, derived inline at render) and CropFromTrajectory.tsx for the
+     * consumer.
+     */
+    cropTrajectoryUrl?: string;
+    /**
+     * Frame-packed CO-VIEW source for the captions-behind-speaker effect: ONE
+     * opaque H.264 (BiRefNet-portrait) with the scene (top half) and the matte
+     * (bottom half) stacked, baked frame-aligned per source window. When set,
+     * the clip renders via PackedSubjectComposite — a SINGLE decode yields both
+     * halves of the identical instant, so the matte cannot drift from the scene
+     * at any composition fps (the frame-lock fix). Crop-independent: one co-view
+     * per source window, reused across aspect/crop variants. Resolved at the
+     * caller layer (Temporal activity) from mediaItems.mattes[matteHash] and
+     * served same-origin so @remotion/media decodes it.
+     */
+    packedUrl?: string;
+    /** Debug: tint the subject cut-out green to verify coverage. */
+    coViewDebug?: boolean;
+}
+export interface CompositionOverlay {
+    id: string;
+    template: OverlayTemplate;
+    templateId?: string;
+    startFrame: number;
+    durationInFrames: number;
+    params: OverlayParams;
+    /** 'behind-subject' renders under the subject cut-out (matte occludes it). Default front. */
+    zPlane?: 'front' | 'behind-subject';
+    /** Scene-space anchor for world-locking behind overlays through the crop trajectory. */
+    anchor?: {
+        space: 'scene';
+        x: number;
+        y: number;
+    };
+    /** Camera-motion differential for behind overlays: 0 = locked to scene; small ± = depth parallax. Range [-0.3, 0.3]. */
+    parallax?: number;
+    /** Output-space placement rect (fractions of the output frame, 0..1). Default
+     *  (absent) = full frame. A sub-frame region makes the overlay primitive (card,
+     *  text, image/gif/lottie) occupy only that rect — the universal placement
+     *  layer (PiP / inset card / split-screen). Mirrors CompositionClip.region; the
+     *  renderer wraps the overlay in the same RegionBox, and size-from-output
+     *  primitives read the box dims via useEffectiveOutput. */
+    region?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** How the overlay fills `region`: 'cover' (fill+crop, default) or 'contain' (letterbox). */
+    fit?: 'cover' | 'contain';
+    /**
+     * Entrance transition for the overlay — mirrors CompositionClip.transitionIn.
+     * When set, the overlay host (OverlayLayer / BehindOverlayHost) wraps the
+     * mounted content in a frame-pure entrance envelope (opacity fade; slide/scale
+     * for the motion variants) over `transitionDurationFrames` from the overlay's
+     * start. Absent = no envelope (byte-identical to prior behavior). Projected via
+     * the same `mapTransitionType` mapping the video lane uses, so the realized
+     * enum is fade/dissolve/wipe/none (dissolve+wipe degrade to an opacity fade for
+     * a single positioned box). Was silently dropped before: only the video lane
+     * projected `transitionIn`, so an authored overlay transition rendered as a
+     * dead hard cut.
+     */
+    transitionIn?: 'fade' | 'dissolve' | 'wipe' | 'none';
+    transitionDurationFrames?: number;
+    /** Clip-level transform channel (wire `TimelineClip.position/opacity/scale/
+     *  rotation` — "the animation channel"; `region` stays the placement
+     *  primitive). `position` is the overlay's CENTER in output-space fractions
+     *  [0,1] of its containing box (the region box, or the full frame). These
+     *  were silently DROPPED by the projection until 2026-07-20 (spec §2.1.1) —
+     *  an agent could PUT a position, read it back, and watch the render ignore
+     *  it. Absent = the primitive's own layout (no wrapper transform). */
+    position?: {
+        x: number;
+        y: number;
+    };
+    opacity?: number;
+    scale?: number;
+    rotation?: number;
+}
+export type CaptionWord = WireCaptionWord;
+export type CaptionStyle = WireCaptionStyle & Required<Pick<WireCaptionStyle, 'fontFamily' | 'fontSize' | 'fontWeight' | 'color' | 'highlightColor' | 'backgroundColor' | 'position' | 'textTransform'>>;
+/**
+ * Frame-based effect instance the renderer consumes. Mirrors
+ * `EffectInstance` from composition/types but with seconds normalized to
+ * frames so the render path is fps-agnostic.
+ */
+export interface CompositionEffect {
+    id: string;
+    primitiveId: string;
+    params: Record<string, unknown>;
+    target: EffectTarget;
+    /**
+     * For clip targets, frames RELATIVE to the clip's timeline start.
+     * For global targets, ABSOLUTE timeline frames.
+     * Undefined = render across the target's whole span.
+     */
+    startFrame?: number;
+    durationInFrames?: number;
+}
+export interface CompositionAudioTrack {
+    id: string;
+    src: string;
+    sourceInFrames: number;
+    sourceOutFrames: number;
+    startFrame: number;
+    durationInFrames: number;
+    volume: number;
+    fadeInFrames?: number;
+    fadeOutFrames?: number;
+    loop?: boolean;
+    /**
+     * Speech-aware duck envelope (music / vo tracks only; SFX is never ducked).
+     * Frame ranges are SEQUENCE-RELATIVE (0 = the track's `startFrame`) to match
+     * the fade domain `buildVolumeFunction` operates in. Resolved by the
+     * `compositionToRenderInput` post-projection pass from the composition's own
+     * caption words (or explicit `duck.windows`); absent ⇒ no ducking.
+     * `duckVolume` is the linear gain held during speech (10^(duckDb/20)).
+     */
+    duckWindows?: Array<{
+        startFrame: number;
+        endFrame: number;
+    }>;
+    duckVolume?: number;
+    duckAttackFrames?: number;
+    duckReleaseFrames?: number;
+}
+export interface RenderInput {
+    clips: CompositionClip[];
+    overlays: CompositionOverlay[];
+    audioTracks?: CompositionAudioTrack[];
+    effects?: CompositionEffect[];
+    captionSegments?: CaptionWord[][];
+    captionStyle?: Partial<CaptionStyle>;
+    width: number;
+    height: number;
+    fps: number;
+    durationInFrames: number;
+    /**
+     * Target platform frozen from the suggestion (`composition.format.platform`:
+     * tiktok/ig/youtube/…). Output-determining: the composition floor's safe-zone
+     * placement clears that surface's UI chrome from the caption band. Absent ⇒ the
+     * floor falls to its conservative 'unknown' (broadcast) safe-zone profile. Read
+     * straight from the wire `Format.platform`; the renderer threads it to every
+     * CropFromTrajectory so buildFloorInput sees the real destination.
+     */
+    platform?: string;
+    outputWidth?: number;
+    outputHeight?: number;
+    crf?: number;
+    watermark?: boolean;
+    scenes?: Scene[];
+    sceneGlobal?: GlobalEffects;
+    /**
+     * Active brand kit for render-time token resolution. This is the
+     * fully-materialized `ResolvedBrandKit` the render snapshot freezes
+     * (the render intake → resolveBrandKit), NOT the sparse
+     * 5-colour `@cueframe/core` BrandKit — it carries the Tier-2 colour core,
+     * `caption.{fg,scrim}`, and `fonts.{heading,body,caption}`. Overlay params may
+     * contain `"$brand:<path>"` refs that resolve against it. Optional — absent
+     * brand kit makes a `$brand:` ref fall to its contrast-safe / fallback default.
+     */
+    brandKit?: ResolvedBrandKit;
+}

package/dist/_members/core/render/types.js

@@ -0,0 +1,8 @@
+// Self-contained types for the render pipeline.
+// These MUST NOT import from @tauri-apps/* or any barrel that re-exports Tauri types,
+// because Remotion's webpack bundler will try to resolve those imports and fail.
+//
+// OverlayTemplate and OverlayParams are intentionally duplicated from src/types/index.ts.
+// Remotion bundles via webpack which cannot resolve @tauri-apps/* imports that appear
+// in the main types barrel. Keeping these copies decoupled avoids webpack build failures.
+export {};

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

@@ -0,0 +1,51 @@
+/**
+ * vcam/cameraPath.ts — the SINGLE virtual-camera stability stage (Phase 3).
+ *
+ * Replaces both `emaSmooth` (for the centers) and the render-side
+ * `smoothTrajectory` Gaussian with ONE pass per shot. Per the spec
+ * (2026-06-21-virtual-camera-reframe-design.md, "Virtual-camera stability — one
+ * stage, no LP"):
+ *
+ *   1. Deadzone INCLUSION gate (output-crop-normalized): the camera HOLDS while
+ *      the padded RequiredRegion stays inside a safe region of the current crop
+ *      window; it moves ONLY when the region would exit. This is the inclusion
+ *      INVARIANT — the crop always contains the RequiredRegion ⇒ the subject
+ *      never walks out of frame. This is what turns Phase 2's "static hold" into
+ *      "hold, then glide to re-contain" — a moving subject is TRACKED.
+ *   2. One Hamming-window weighted mean over each shot run's gated centers
+ *      (acausal, single pass, no lag). Forward-fill at the start; the window
+ *      AUTO-SHRINKS near a shot boundary so it never blends across a cut.
+ *   3. Null/occluded regions are forward-filled (the last in-shot region) before
+ *      the gate, minus the deleted jump heuristic — gaps longer than the window
+ *      hold; re-emergence outside the pad glides over the window.
+ *
+ * No second smoothing: render samples this base path verbatim. The only reset is
+ * a detector `shotBoundary` — a center jump is NEVER inferred as a cut (the
+ * deleted `isJump`/`JUMP_THRESHOLD` false-cut teleport).
+ *
+ * Coordinate systems: RequiredRegions + centers are SOURCE-NORMALIZED. The
+ * deadzone is OUTPUT-CROP-NORMALIZED (a fraction of the crop window), so the
+ * held feel is zoom-invariant — it is converted to source units here using the
+ * crop-window size. Pure, deterministic, no I/O.
+ */
+import type { RequiredRegion } from './requiredRegion.js';
+import type { Center } from './subjectSet.js';
+/** The crop window the camera commands, source-normalized (the largest output-
+ *  aspect rect that fits the source, scaled by the clamped zoom). */
+export interface CropWindow {
+    /** Window width as a fraction of source width ∈ (0,1]. */
+    w: number;
+    /** Window height as a fraction of source height ∈ (0,1]. */
+    h: number;
+}
+/**
+ * The single stability stage: per-frame RequiredRegions → smoothed, inclusion-
+ * satisfying per-frame crop centers (source-normalized). `cropFor(frame)` gives
+ * the crop window for that frame (it can vary per frame when zoom is eased).
+ *
+ * `interiorCuts` are segment-local frame indices where a new shot begins (the
+ * SAME set the derive already computes). Each shot is gated + smoothed
+ * independently (deadzone, window clamp, forward-fill all reset at the cut).
+ * Frames whose shot never resolved a region hold `centerHold` (source center).
+ */
+export declare function cameraPath(regions: Array<RequiredRegion | null>, cropFor: (frame: number) => CropWindow, fps: number, interiorCuts: Iterable<number>, centerHold?: Center): Center[];

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

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