@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/composition/reframe/derive.js

@@ -1,73 +0,0 @@
-const area = (f) => Math.max(0, f.bbox.width) * Math.max(0, f.bbox.height);
-/**
- * Geometric single-subject focus for the target aspect:
- *  - no faces → frame-center (screen-recording / faceless b-roll; honest center crop).
- *  - 2+ faces carry a speakingShare signal → active-speaker (the wedge follows the speaker).
- *  - otherwise → the single largest detected face (dominant subject).
- */
-export function pickGeometricFocus(faces) {
-    if (!faces || faces.length === 0)
-        return { mode: "frame-center" };
-    const withSpeaking = faces.filter((f) => typeof f.speakingShare === "number");
-    if (faces.length >= 2 && withSpeaking.length >= 2)
-        return { mode: "active-speaker" };
-    // Equal-area tie-break: Array.prototype.sort is STABLE (ES2019+), so ties keep
-    // roster order and `[0]` resolves to the FIRST-in-roster face — a deterministic
-    // pick that P5.3 content-addressing relies on.
-    const dominant = [...faces].sort((a, b) => area(b) - area(a))[0];
-    return { mode: "face", faceId: dominant.faceId };
-}
-/** Clip-relative full-clip span [0, duration]. deriveTrajectory indexes segments
- *  clip-relative (frame 0 = the clip's source-window start). */
-function fullClipDurationSec(content) {
-    const d = content.duration;
-    if (typeof d === "number" && d > 0)
-        return d;
-    const trim = content.source?.trim;
-    if (trim && typeof trim.start === "number" && typeof trim.end === "number" && trim.end > trim.start) {
-        return trim.end - trim.start;
-    }
-    return 0;
-}
-export function deriveReframedComposition(source, targetFormat, perceptionByClipId) {
-    // Deep copy so the source row is never mutated (structuredClone is available in
-    // the V8 isolate + Node test runtime; the wire shape is plain JSON).
-    const out = structuredClone(source);
-    // Format = target aspect; fps/resolution default to source (intrinsic to the
-    // edit unless the caller overrides); platform carried over from source.
-    out.format = {
-        aspectRatio: targetFormat.aspectRatio,
-        ...(targetFormat.fps ?? source.format.fps ? { fps: (targetFormat.fps ?? source.format.fps) } : {}),
-        ...(targetFormat.resolution ?? source.format.resolution
-            ? { resolution: (targetFormat.resolution ?? source.format.resolution) }
-            : {}),
-        ...(source.format.platform ? { platform: source.format.platform } : {}),
-    };
-    for (const track of out.tracks) {
-        // Audio clips are MediaClipSource too (`source.kind === "media"`) but live on
-        // audio tracks — a geometric viewport reframe is meaningless for sound, so skip
-        // the whole track. Target AUDIO specifically: IMAGE clips are also `kind:"media"`
-        // and legitimately keep a pan/zoom reframe, so this is not a "non-video" skip.
-        if (track.kind === "audio")
-            continue;
-        const contents = track.contents;
-        if (!Array.isArray(contents))
-            continue;
-        for (const content of contents) {
-            const src = content.source;
-            if (!src || src.kind !== "media")
-                continue; // overlay/component untouched
-            if (src.reframe)
-                continue; // already authored → copied verbatim
-            const dur = fullClipDurationSec(content);
-            if (dur <= 0)
-                continue; // degenerate clip: no crop target
-            const clipId = content.id;
-            const roster = typeof clipId === "string" ? perceptionByClipId[clipId] : undefined;
-            src.reframe = {
-                segments: [{ startSec: 0, endSec: dur, focus: pickGeometricFocus(roster), zoom: 1 }],
-            };
-        }
-    }
-    return out;
-}

package/dist/_members/composition/reframe/index.js

@@ -1,109 +0,0 @@
-/**
- * Reframe — the canonical, typed model for "the camera": an at-most-one
- * top-slot transform whose segments animate a source→output viewport over
- * time. This is the REAL model the new pipeline derives + renders from
- * natively (not a facade over `cropIntents`).
- *
- * Status: `reframe` is built correctly here as the canonical shape. The legacy
- * `cropIntents` (subject-centric, source-level, required `lateralBias`, no
- * `ease`) remains the live podcast path for now and is MIGRATED onto `reframe`
- * later — at which point `cropIntents` is deleted. No lowering shim exists;
- * the two coexist only during the migration window and share the per-frame
- * trajectory back-end + the renderer.
- *
- * Design vs legacy:
- *  - `focus` (not `subject`): adds `point`; `shotScale` lives on `face` only.
- *  - `zoom` (not `zoomScale`): same meaning (<1 punches in).
- *  - `bias` optional (legacy `lateralBias` was required — podcast baggage).
- *  - `ease` is HONORED: the reframe derive bakes the eased zoom/center ramp
- *    into the per-frame trajectory channel, so the renderer is unchanged.
- */
-import { z } from "zod";
-// The shot-scale table + the punch-in warrant (the SSOT both the plan-time guard
-// and the bake's `calibrateShotScale` read).
-export * from "./shotScale.js";
-// Render-time advisory for media cropped hard by an aspect mismatch with no
-// authored camera. Pure; no zod, no I/O.
-export * from "./aspectLoss.js";
-export const Focus = z.discriminatedUnion("mode", [
-    z.object({ mode: z.literal("frame-center") }),
-    z.object({ mode: z.literal("point"), x: z.number().min(0).max(1), y: z.number().min(0).max(1) }),
-    z.object({
-        mode: z.literal("face"),
-        faceId: z.string().min(1),
-        shotScale: z.enum(["close", "standard", "wide"]).optional(),
-    }),
-    z.object({ mode: z.literal("all-faces") }),
-    z.object({ mode: z.literal("active-speaker") }),
-]);
-/**
- * The segment's FIELDS, unrefined. `ReframeSegment` below wraps this in the
- * shotScale-XOR-zoom refine, which makes it a ZodEffects with no `.shape` — so
- * anything introspecting the field set (the OpenAPI doc-mirror lockstep guard)
- * reads THIS. Validation always goes through `ReframeSegment`.
- */
-export const ReframeSegmentFields = z.object({
-    startSec: z.number().nonnegative().describe("Segment START in seconds, clip-relative. Segments tile the clip's duration in order."),
-    endSec: z.number().positive().describe("Segment END in seconds, clip-relative. The span (endSec − startSec) is this segment's duration — the window `ease` ramps over."),
-    /** WHO/WHAT the camera tracks — see the `.describe()` for per-mode guidance. */
-    focus: Focus.describe("WHO/WHAT the camera tracks this segment (the reframe center), selected by `mode`: " +
-        "`frame-center` = no tracking, hold the geometric center (static/graphic footage, or a pure zoom); " +
-        "`point` = lock to a fixed source-normalized {x,y} (a non-moving on-screen element); " +
-        "`face` = track a detected face by `faceId` (from get_media_context), with optional `shotScale` close|standard|wide for tightness; " +
-        "`all-faces` = frame the bounding box of every detected face (group/ensemble shots); " +
-        "`active-speaker` = follow whoever is speaking (diarized talking-head / podcast). " +
-        "Pick by what the beat is about; pair with `zoom` for how tight."),
-    /** Editorial language for diff/log readability ("speaker-tight",
-     *  "wide-context", "interviewer-reaction"). Not honored by the derive math
-     *  — a relabel must not bust the variant cache, so it is EXCLUDED from
-     *  `hashReframe`. */
-    intent: z.string().optional().describe("Optional editorial LABEL for diff/log readability (e.g. 'speaker-tight', 'wide-context'). Cosmetic — NOT honored by the derive math and excluded from the variant cache key."),
-    /** <1 punches in; 1 = full frame. Omitted when `focus.shotScale` governs — the
-     *  two are MUTUALLY EXCLUSIVE (see the refine below). Absent = 1 (full frame),
-     *  which is how `hashReframe` has always canonicalized it. */
-    zoom: z.number().min(0.1).max(1).optional().describe("How TIGHT the framing is — the fraction of the source the output viewport shows. " +
-        "<1 punches IN (a smaller source fraction, magnified to fill the frame); 1 = the full frame (no crop). " +
-        "~0.6–0.8 is a moderate push-in, ~0.5 a tight close-up, 0.1 the maximum zoom. " +
-        "There is NO zoom-OUT past the full frame (max 1). Omit for the full frame. " +
-        "MUTUALLY EXCLUSIVE with `focus.shotScale`: a face-tracked shot is sized EITHER by the editorial " +
-        "scale (shotScale, calibrated to the detected face) OR by an explicit zoom — never both."),
-    /** Ease-in / ease-out durations (seconds) for the zoom ramp at this segment's
-     *  edges. Honored at derive time (baked into the per-frame channel). */
-    ease: z
-        .object({
-        in: z.number().nonnegative().describe("Ease-IN ramp DURATION in seconds at the segment START."),
-        out: z.number().nonnegative().describe("Ease-OUT ramp DURATION in seconds at the segment END."),
-    })
-        .optional()
-        .describe("Zoom/center ramp DURATIONS in SECONDS at this segment's edges — NOT a unitless 0–1 curve. " +
-        "~0.3–0.6s reads as a snappy push; >1s reads sluggish. Keep `in` + `out` ≤ the segment's duration " +
-        "(endSec − startSec): the two edges share the span, so to ramp across the WHOLE segment set one edge " +
-        "to the full duration and the other to 0. Omit for an instant cut to this framing."),
-    /** Optional fine framing nudge, source-normalized [-0.3,0.3]. */
-    bias: z
-        .object({
-        x: z.number().min(-0.3).max(0.3).describe("Horizontal nudge, source-normalized (+ = right)."),
-        y: z.number().min(-0.3).max(0.3).describe("Vertical nudge, source-normalized (+ = down)."),
-    })
-        .optional()
-        .describe("Optional FINE framing nudge off the focus center, source-normalized in [−0.3, 0.3]. " +
-        "A small correction (headroom, rule-of-thirds), NOT a reframe — use `focus`/`zoom` for the actual shot. " +
-        "Omit (treated as 0) to sit dead-center on the focus."),
-});
-export const ReframeSegment = ReframeSegmentFields.refine(
-// ONE knob sizes the crop. `shotScale` and `zoom` both do, and the bake gives
-// shotScale precedence (calibrateShotScale takes zoom only as a FALLBACK) — so a
-// segment carrying both SILENTLY discards the zoom. That is how a stored
-// composition came to claim `zoom: 1` (full frame) on a segment the renderer
-// punched in to 0.55: reading the artifact said "no zoom" while the render
-// plainly zoomed (2026-07-13). The state is incoherent, so make it
-// unrepresentable — here, at the wire shape, not just at the authoring tools.
-//
-// Rows written before compile stopped stamping `zoom: 1` are MIGRATED (convex
-// migrations: dropZoomUnderShotScale), not tolerated.
-(s) => !(s.focus.mode === "face" && s.focus.shotScale !== undefined && s.zoom !== undefined), {
-    message: "a face segment takes EITHER focus.shotScale (editorial scale, calibrated to the detected face) OR an explicit zoom — never both; shotScale wins at bake time and the zoom would be silently discarded",
-    path: ["zoom"],
-});
-/** The camera channel: exactly one per layer; segments tile the clip. */
-export const Reframe = z.object({ segments: z.array(ReframeSegment).min(1) });

package/dist/_members/composition/reframe/kenBurns.js

@@ -1,64 +0,0 @@
-/** The punched-in zoom a Ken-Burns ramp reaches (crop-window scale; <1 = tighter). */
-export const KEN_BURNS_ZOOM_TIGHT = 0.84;
-/** The held zoom a pan preset sits at so the lateral move has room before edges. */
-export const KEN_BURNS_PAN_ZOOM = 0.9;
-/** How far (source-normalized) a pan preset slides the focus point laterally. */
-export const KEN_BURNS_PAN_BIAS = 0.08;
-/**
- * Lower a Ken-Burns preset to a single-segment `Reframe` over `[0, durationSec)`.
- * Pure; no detection. `durationSec` sets the segment span (and the ease edge
- * length, so the ramp fills the whole clip).
- */
-export function kenBurnsToReframe(mode, durationSec) {
-    const endSec = durationSec > 0 ? durationSec : 1e-3;
-    // "none" → identity viewport: frame-center, full frame, no ease. The derive
-    // emits a scalar zoom_scale=1 and NO per-frame zooms (byte-parity with a
-    // plain face segment), so the renderer plays the still uncropped.
-    if (mode === "none") {
-        const seg = {
-            startSec: 0,
-            endSec,
-            focus: { mode: "frame-center" },
-            zoom: 1,
-            intent: "ken-burns-none",
-        };
-        return { segments: [seg] };
-    }
-    if (mode === "in" || mode === "out") {
-        // A monotonic zoom ramp across the whole clip. We author the segment at the
-        // ramp's END zoom and let the FULL-clip ease edge sweep from the start zoom:
-        //   "in"  start 1.0 → end 0.84  → ease.in spans the clip (ramp head→settle).
-        //   "out" start 0.84 → end 1.0  → ease.out spans the clip (ramp settle→head).
-        // deriveTrajectory reads `ease` + `zoom` and emits the per-frame `zooms`.
-        const seg = {
-            startSec: 0,
-            endSec,
-            focus: { mode: "frame-center" },
-            zoom: mode === "in" ? KEN_BURNS_ZOOM_TIGHT : 1,
-            ease: mode === "in"
-                ? { in: endSec, out: 0 } // ramp 1.0 → zoom over the clip head
-                : { in: 0, out: endSec }, // ramp zoom → 1.0 over the clip tail
-            intent: `ken-burns-${mode}`,
-        };
-        return { segments: [seg] };
-    }
-    // pan-l / pan-r — a held slight zoom with the focus point sliding laterally.
-    // The point starts off-center one way and eases to the other; ease spans the
-    // clip so the derive ramps the CENTER (not the zoom) across the segment.
-    const fromX = mode === "pan-l" ? 0.5 + KEN_BURNS_PAN_BIAS : 0.5 - KEN_BURNS_PAN_BIAS;
-    const toX = mode === "pan-l" ? 0.5 - KEN_BURNS_PAN_BIAS : 0.5 + KEN_BURNS_PAN_BIAS;
-    const seg = {
-        startSec: 0,
-        endSec,
-        // `point` focus: detection-free, centers on the authored location. The pan
-        // sweep is expressed as a center ramp the derive bakes from ease (from→to).
-        focus: { mode: "point", x: toX, y: 0.5 },
-        zoom: KEN_BURNS_PAN_ZOOM,
-        ease: { in: endSec, out: 0 },
-        // `bias.x` carries the pan ORIGIN offset (fromX − toX) so the derive can ramp
-        // the center from origin→authored-point across the ease edge. Source-normalized.
-        bias: { x: fromX - toX, y: 0 },
-        intent: `ken-burns-${mode}`,
-    };
-    return { segments: [seg] };
-}

package/dist/_members/composition/reframe/shotScale.js

@@ -1,176 +0,0 @@
-/**
- * Shot scale — the ONE table that turns an editorial shot scale into a crop
- * zoom, and the DECIDE-point test for whether that punch-in is earned at all.
- *
- * `shotScale` is a TARGET, not a zoom: put the tracked face at `target` of the
- * output frame's height. The bake (`deriveTrajectory.calibrateShotScale`) reads
- * the same table from here, so the plan-time guard and the render agree by
- * construction — neither side keeps a copy.
- *
- * WHY THE WARRANT EXISTS: the bake honors ANY shotScale. It computes
- * `zoom = faceHeight / target`, clamps to [0.4, 1.0], and crops — with no idea
- * whether the source has the ROOM or the PIXELS to give. On 2026-07-13 a planner
- * asked for `close` on a 720x900 talking-head already framed chest-up and
- * centred; the bake dutifully cropped to ~392x490 and magnified it 2.7x to fill
- * a 1080x1350 output. Nothing objected. The shot was already the shot.
- *
- * A punch-in is warranted only when all three hold:
- *   no-gain   — the face is genuinely SMALLER than the scale asks for, so the
- *               crop reframes rather than merely resampling.
- *   no-room   — the crop window, centred on the face and widened by how far the
- *               subject DRIFTS across the span, still fits inside the source.
- *               Otherwise the window clamps, the subject slides off its framing,
- *               and heads get clipped.
- *   no-pixels — the crop still has enough source pixels to fill the output
- *               without magnifying past MAX_SOURCE_MAGNIFICATION.
- *
- * Pure numbers in, pure verdict out — no perception types, no I/O. The caller
- * supplies the face facts (the director reads them off the SubjectTrack) and the
- * frame geometry.
- */
-/** Face height as a fraction of the OUTPUT frame height, per editorial scale. */
-export const SHOT_SCALE_TARGET = {
-    close: 0.55,
-    standard: 0.42,
-    wide: 0.3,
-};
-/** The bake clamps the derived zoom to this range. */
-export const ZOOM_MIN = 0.4;
-export const ZOOM_MAX = 1.0;
-/**
- * A crop showing this much of the frame or more is not a reframe — it is a
- * resample. Below the threshold the punch-in has to actually change the shot.
- */
-export const NO_GAIN_ZOOM = 0.9;
-/**
- * Ceiling on how far the render may magnify SOURCE pixels to fill the output.
- * 2x is the practical blow-up limit — past it the punch-in reads soft and mushy
- * next to the un-cropped spans it cuts against. (A 4K source punches in freely;
- * a 720p source has nothing to give.)
- */
-export const MAX_SOURCE_MAGNIFICATION = 2.0;
-/**
- * The source rect the output viewport sees at zoom 1.0 — the aspect-fit window.
- * Mirrors `calibrateShotScale`'s `fitH`.
- */
-export function fitWindow(g) {
-    const outAr = g.outW / g.outH;
-    const srcAr = g.srcW / g.srcH;
-    const fitH = srcAr > outAr ? g.srcH : g.srcW / outAr;
-    return { fitW: fitH * outAr, fitH };
-}
-/** The zoom a shotScale implies for a face of this height (fraction of the FIT window). */
-export function shotScaleZoom(heightFracOfFit, shotScale) {
-    const target = SHOT_SCALE_TARGET[shotScale];
-    return Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, heightFracOfFit / target));
-}
-const pct = (n) => `${Math.round(n * 100)}%`;
-const px = (n) => Math.round(n);
-/**
- * Is this punch-in earned? Refusals carry the NUMBERS — they route back to the
- * planner verbatim as its next-turn instruction, so they must say what is true
- * of THIS footage and what to do instead.
- */
-export function punchInWarrant(face, shotScale, g) {
-    const { fitW, fitH } = fitWindow(g);
-    if (fitH <= 0 || face.heightFrac <= 0) {
-        return {
-            ok: false,
-            zoom: 1,
-            rule: "no-gain",
-            reason: `shotScale '${shotScale}' on ${face.faceId}: no face height detected on this span — nothing to calibrate a punch-in against. Omit shotScale.`,
-        };
-    }
-    // The bake sizes the face against the FIT window, not the raw source.
-    const heightOfFit = (face.heightFrac * g.srcH) / fitH;
-    const zoom = shotScaleZoom(heightOfFit, shotScale);
-    // ── no-gain: the shot is already the shot ──
-    if (zoom >= NO_GAIN_ZOOM) {
-        return {
-            ok: false,
-            zoom,
-            rule: "no-gain",
-            reason: `shotScale '${shotScale}' on ${face.faceId}: the face already fills ${pct(heightOfFit)} of the frame height, ` +
-                `so this scale computes zoom ${zoom.toFixed(2)} — a crop that shows ${pct(zoom)} of the frame and changes nothing but the resampling. ` +
-                `Omit shotScale and show the shot as it was captured.`,
-        };
-    }
-    const cropW = zoom * fitW;
-    const cropH = zoom * fitH;
-    // ── no-room: the window must fit around the subject WHERE THE SUBJECT IS ──
-    // Clearance the crop window needs from each source edge, source-normalized.
-    const halfW = cropW / 2 / g.srcW;
-    const halfH = cropH / 2 / g.srcH;
-    if (face.cxMin < halfW ||
-        face.cxMax > 1 - halfW ||
-        face.cyMin < halfH ||
-        face.cyMax > 1 - halfH) {
-        return {
-            ok: false,
-            zoom,
-            rule: "no-room",
-            reason: `shotScale '${shotScale}' on ${face.faceId}: a ${px(cropW)}x${px(cropH)} window centred on the subject needs ` +
-                `${pct(halfW)} horizontal / ${pct(halfH)} vertical clearance from every edge, but the subject's centre sits at ` +
-                `x ${pct(face.cxMin)}–${pct(face.cxMax)}, y ${pct(face.cyMin)}–${pct(face.cyMax)} of a ${g.srcW}x${g.srcH} source. ` +
-                `The window would run off the frame and clamp — the subject slides out of its framing and the head clips. ` +
-                `There is not enough room around this face to punch in.`,
-        };
-    }
-    // ── no-pixels: the crop must still be able to fill the output ──
-    const magnification = g.outW / cropW;
-    if (magnification > MAX_SOURCE_MAGNIFICATION) {
-        return {
-            ok: false,
-            zoom,
-            rule: "no-pixels",
-            reason: `shotScale '${shotScale}' on ${face.faceId}: crops to ${px(cropW)}x${px(cropH)} of a ${g.srcW}x${g.srcH} source, ` +
-                `which must then be magnified ${magnification.toFixed(1)}x to fill ${g.outW}x${g.outH} (limit ${MAX_SOURCE_MAGNIFICATION}x). ` +
-                `This source has no pixels to spare — it renders soft against the un-cropped spans it cuts against. Omit shotScale.`,
-        };
-    }
-    return { ok: true, zoom };
-}
-/**
- * Aggregate per-second face rows into the facts a warrant needs over ONE span:
- * the MEDIAN height (robust to a stray frame) and the RANGE the centre travels
- * (a walking subject spreads it; a static one collapses it to a point).
- *
- * Returns null when the face is absent for more than half the span — there is
- * nothing to frame, and the caller must refuse rather than invent a box. Shared
- * by the planner's guard and the author's `set_crop_intents`, so both judge a
- * punch-in against the same aggregate.
- */
-export function faceOverSpan(perSecond, faceId, startSec, endSec) {
-    const from = Math.max(0, Math.floor(startSec));
-    const to = Math.min(perSecond.length, Math.ceil(endSec));
-    const rows = [];
-    for (let s = from; s < to; s++) {
-        const f = perSecond[s]?.[faceId];
-        if (f)
-            rows.push(f);
-    }
-    const spanSeconds = Math.max(1, to - from);
-    if (rows.length < spanSeconds / 2)
-        return null;
-    const heights = rows.map((r) => r.heightFrac).sort((a, b) => a - b);
-    return {
-        faceId,
-        heightFrac: heights[Math.floor(heights.length / 2)],
-        cxMin: Math.min(...rows.map((r) => r.cx)),
-        cxMax: Math.max(...rows.map((r) => r.cx)),
-        cyMin: Math.min(...rows.map((r) => r.cy)),
-        cyMax: Math.max(...rows.map((r) => r.cy)),
-    };
-}
-/**
- * The tightest scale this face+source actually supports, or null when none does
- * (the source is already framed as tight as it can usefully go). This is what
- * the PLANNER is told, so it never has to guess at a punch-in the guard refuses.
- */
-export function tightestWarrantedShotScale(face, g) {
-    for (const s of ["close", "standard", "wide"]) {
-        if (punchInWarrant(face, s, g).ok)
-            return s;
-    }
-    return null;
-}

package/dist/_members/composition/reframe/trajectory.js

@@ -1,124 +0,0 @@
-/** Clamp to [0,1]. */
-export function clip01(v) {
-    return Math.max(0, Math.min(1, v));
-}
-/**
- * Cubic ease-out `1 - (1-t)^3` for t∈[0,1] — matches the legacy StillFrame's
- * `Easing.out(Easing.cubic)` so motion decelerates ("settled").
- */
-export function easeOutCubic(t) {
-    const x = Math.max(0, Math.min(1, t));
-    return 1 - (1 - x) * (1 - x) * (1 - x);
-}
-/**
- * Per-frame crop-window zoom for an EASED segment. Holds at `targetZoom` through
- * the body; ramps to/from full-frame (1.0) at the eased edges:
- *   - `easeInSec` at the HEAD: 1.0 → targetZoom.
- *   - `easeOutSec` at the TAIL: targetZoom → 1.0.
- * Frame times are `frameIdx / srcFps` (segment-local). Edges clamp to the span.
- */
-export function buildEasedZooms(frameCount, srcFps, targetZoom, easeInSec, easeOutSec) {
-    const segSec = frameCount / srcFps;
-    const inDur = Math.max(0, Math.min(easeInSec, segSec));
-    const outDur = Math.max(0, Math.min(easeOutSec, segSec));
-    const zooms = new Array(frameCount);
-    for (let i = 0; i < frameCount; i++) {
-        const tSec = i / srcFps;
-        let z = targetZoom;
-        if (inDur > 0 && tSec < inDur) {
-            const p = easeOutCubic(tSec / inDur);
-            z = 1.0 + (targetZoom - 1.0) * p;
-        }
-        else if (outDur > 0 && tSec > segSec - outDur) {
-            const p = easeOutCubic((tSec - (segSec - outDur)) / outDur);
-            z = targetZoom + (1.0 - targetZoom) * p;
-        }
-        zooms[i] = z;
-    }
-    return zooms;
-}
-/**
- * Ramp per-frame CENTERS for a `point`-focus pan: from an ORIGIN
- * (`point + biasOffset`) to the authored `point`, eased over `easeInSec` at the
- * head (then held). Used by Ken-Burns `pan-l` / `pan-r`.
- */
-export function buildPannedCenters(frameCount, srcFps, point, biasOffset, easeInSec) {
-    const segSec = frameCount / srcFps;
-    const inDur = Math.max(0, Math.min(easeInSec, segSec));
-    const origin = [point[0] + biasOffset[0], point[1] + biasOffset[1]];
-    const out = new Array(frameCount);
-    for (let i = 0; i < frameCount; i++) {
-        const tSec = i / srcFps;
-        const p = inDur > 0 ? easeOutCubic(Math.min(tSec / inDur, 1)) : 1;
-        out[i] = [
-            clip01(origin[0] + (point[0] - origin[0]) * p),
-            clip01(origin[1] + (point[1] - origin[1]) * p),
-        ];
-    }
-    return out;
-}
-/** Per-aspect caption keep-out band (fraction of output height). SSOT — the
- *  execution derive imports this rather than re-declaring it. */
-export const CAPTION_BAND_RESERVE = {
-    "9:16": 0.15,
-    "4:5": 0.12,
-    "1:1": 0.1,
-    "16:9": 0.0,
-};
-/**
- * Derive a FACELESS still-image trajectory from a `Reframe` (typically the one
- * `kenBurnsToReframe` produced). A still has no detection, so every focus reduces
- * to a constant authored center (`point` → `[x,y]`; everything else → frame-center
- * `[0.5,0.5]`), and the only motion is the eased zoom (`buildEasedZooms`) / center
- * pan (`buildPannedCenters`). Output is the SAME `TrajectoryData` shape the video
- * path produces, so the renderer (CropFromTrajectory) consumes both identically.
- *
- * `srcW`/`srcH` are the IMAGE pixel dims (used by the renderer's crop-window math).
- * Each segment's `[startSec, endSec)` × `fps` sets its per-frame series length.
- * `fps` is the OUTPUT fps (the trajectory is sampled at this rate — `src_fps = fps`
- * for a still, since the "source" is one frozen image with no native timeline).
- */
-export function deriveStillTrajectory(reframe, srcW, srcH, fps, aspect, bakeVersion) {
-    const segments = [];
-    let cursorSec = 0;
-    for (const seg of reframe.segments) {
-        const startSec = seg.startSec;
-        const endSec = seg.endSec;
-        const frameCount = Math.max(1, Math.round((endSec - startSec) * fps));
-        // Faceless center: `point` → authored location; anything else → frame-center.
-        const point = seg.focus.mode === "point" ? [seg.focus.x, seg.focus.y] : [0.5, 0.5];
-        const isPan = seg.focus.mode === "point" && !!seg.ease && !!seg.bias;
-        const targetZoom = seg.zoom ?? 1;
-        const centers = isPan
-            ? buildPannedCenters(frameCount, fps, point, [seg.bias?.x ?? 0, seg.bias?.y ?? 0], seg.ease?.in ?? 0)
-            : new Array(frameCount).fill(null).map(() => [point[0], point[1]]);
-        // A pan expresses its motion via centers → zero the crop bias (mirror of the
-        // director's isEasedPan handling). Otherwise pass the authored bias through.
-        const verticalBias = isPan ? 0 : seg.bias?.y ?? 0;
-        const lateralBias = isPan ? 0 : seg.bias?.x ?? 0;
-        const zooms = seg.ease
-            ? buildEasedZooms(frameCount, fps, targetZoom, seg.ease.in, seg.ease.out)
-            : undefined;
-        segments.push({
-            idx: segments.length,
-            start_sec: cursorSec,
-            end_sec: cursorSec + frameCount / fps,
-            zoom_scale: targetZoom,
-            vertical_bias: verticalBias,
-            lateral_bias: lateralBias,
-            centers,
-            subjects: [],
-            caption_band_reserve: CAPTION_BAND_RESERVE[aspect] ?? 0,
-            ...(zooms ? { zooms } : {}),
-        });
-        cursorSec += frameCount / fps;
-    }
-    return {
-        bake_version: bakeVersion,
-        aspect,
-        src_w: srcW,
-        src_h: srcH,
-        src_fps: fps,
-        segments,
-    };
-}