@cueframe/kernel 0.0.1

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

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

@@ -0,0 +1,43 @@
+/**
+ * kenBurnsToReframe — lower a still-image Ken-Burns preset onto the canonical
+ * `Reframe` camera channel, so a still gets the SAME per-frame viewport
+ * treatment as video (one renderer, arbitrary point-zoom) instead of a
+ * StillFrame-only CSS preset.
+ *
+ * The five legacy presets (StillFrame.computeKenBurnsTransform) map as follows.
+ * A still has NO faces, so every preset uses a detection-free focus
+ * (`frame-center` or `point`) and rides the per-frame zoom/center ramp the
+ * derive bakes from `ease`:
+ *
+ *   - "in"    — frame-center, zoom ramps 1.0 → 0.84 over the clip (slow punch-in).
+ *   - "out"   — frame-center, zoom ramps 0.84 → 1.0 (slow pull-out).
+ *   - "pan-l" — a held slight zoom, focus `point` panning right→left across frame.
+ *   - "pan-r" — a held slight zoom, focus `point` panning left→right.
+ *   - "none"  — frame-center, zoom 1.0, no ease → no motion (identity viewport).
+ *
+ * Reframe `zoom` is a CROP-WINDOW scale: <1 punches in (tighter crop). The
+ * legacy StillFrame used CSS `scale()` where >1 zooms in; the magnitudes here
+ * (≈16% over the clip, vs the old 8%) are tuned for the crop-window convention
+ * and read equivalently against b-roll. Exact pixel parity with the old CSS
+ * preset is NOT a goal (and not asserted) — the unified path is the contract.
+ *
+ * `ease.in` / `ease.out` are the eased-ramp durations the derive consumes. For
+ * a monotonic zoom we put the WHOLE clip under one ease edge (in→ramp at the
+ * head for "out", or — equivalently — ramp the zoom across the clip). The
+ * derive (deriveTrajectory) interpolates the zoom across `ease` so the renderer
+ * stays a single per-frame sampler.
+ */
+import type { Reframe } from "./index.js";
+export type KenBurnsMode = "in" | "out" | "pan-l" | "pan-r" | "none";
+/** The punched-in zoom a Ken-Burns ramp reaches (crop-window scale; <1 = tighter). */
+export declare const KEN_BURNS_ZOOM_TIGHT = 0.84;
+/** The held zoom a pan preset sits at so the lateral move has room before edges. */
+export declare const KEN_BURNS_PAN_ZOOM = 0.9;
+/** How far (source-normalized) a pan preset slides the focus point laterally. */
+export declare 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 declare function kenBurnsToReframe(mode: KenBurnsMode, durationSec: number): Reframe;

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

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

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+export type ShotScale = "close" | "standard" | "wide";
+/** Face height as a fraction of the OUTPUT frame height, per editorial scale. */
+export declare const SHOT_SCALE_TARGET: Record<ShotScale, number>;
+/** The bake clamps the derived zoom to this range. */
+export declare const ZOOM_MIN = 0.4;
+export declare const ZOOM_MAX = 1;
+/**
+ * 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 declare 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 declare const MAX_SOURCE_MAGNIFICATION = 2;
+export interface FrameGeometry {
+    srcW: number;
+    srcH: number;
+    outW: number;
+    outH: number;
+}
+/**
+ * Face facts over ONE framing segment's span. Source-normalized and
+ * output-agnostic — the same facts warrant a 9:16 and a 4:5 render.
+ */
+export interface FaceSpanFraming {
+    faceId: string;
+    /** Median face height / SOURCE height across the span. */
+    heightFrac: number;
+    /** Face-CENTRE travel across the span, source-normalized [0,1]. A static
+     *  subject has cxMin ≈ cxMax; a walking one spreads. */
+    cxMin: number;
+    cxMax: number;
+    cyMin: number;
+    cyMax: number;
+}
+export type PunchInRule = "no-gain" | "no-room" | "no-pixels";
+export type PunchInWarrant = {
+    ok: true;
+    zoom: number;
+} | {
+    ok: false;
+    zoom: number;
+    rule: PunchInRule;
+    reason: string;
+};
+/**
+ * The source rect the output viewport sees at zoom 1.0 — the aspect-fit window.
+ * Mirrors `calibrateShotScale`'s `fitH`.
+ */
+export declare function fitWindow(g: FrameGeometry): {
+    fitW: number;
+    fitH: number;
+};
+/** The zoom a shotScale implies for a face of this height (fraction of the FIT window). */
+export declare function shotScaleZoom(heightFracOfFit: number, shotScale: ShotScale): number;
+/**
+ * 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 declare function punchInWarrant(face: FaceSpanFraming, shotScale: ShotScale, g: FrameGeometry): PunchInWarrant;
+/** One second of one tracked face, source-normalized. */
+export interface FaceSecondRow {
+    heightFrac: number;
+    cx: number;
+    cy: number;
+}
+/**
+ * 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 declare function faceOverSpan(perSecond: Array<Record<string, FaceSecondRow>>, faceId: string, startSec: number, endSec: number): FaceSpanFraming | null;
+/**
+ * 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 declare function tightestWarrantedShotScale(face: FaceSpanFraming, g: FrameGeometry): ShotScale | null;

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

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

@@ -0,0 +1,99 @@
+/**
+ * Pure trajectory math shared by the director's `deriveTrajectory` (the face/
+ * video producer) and the renderer's still path. This is the SINGLE source of
+ * truth for:
+ *   - the eased zoom ramp (`buildEasedZooms`) + center pan ramp (`buildPannedCenters`),
+ *   - the FACELESS still-image trajectory producer (`deriveStillTrajectory`),
+ * so the still and video paths share one renderer (CropFromTrajectory) and one
+ * per-frame center+zoom convention. Framework-free, no perception/face machinery
+ * (composition is a leaf) — a still has no faces, so its trajectory is purely the
+ * authored point/frame-center + the eased zoom/center ramp.
+ *
+ * The `TrajectoryData` / `TrajectorySegment` shapes are MIRRORS of the renderer's
+ * (packages/execution/render-entry/src/CropFromTrajectory.tsx) and the execution derive's
+ * (packages/execution/core/src/render/deriveTrajectory.ts) — three mirrors by
+ * design (different package boundaries; same wire shape).
+ */
+import type { Reframe } from "./index.js";
+/** A normalized crop center `[cx, cy]` in [0,1] vs source dims. */
+export type Center = [number, number];
+/** Clamp to [0,1]. */
+export declare function clip01(v: number): number;
+/**
+ * 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 declare function easeOutCubic(t: number): number;
+/**
+ * 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 declare function buildEasedZooms(frameCount: number, srcFps: number, targetZoom: number, easeInSec: number, easeOutSec: number): number[];
+/**
+ * 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 declare function buildPannedCenters(frameCount: number, srcFps: number, point: Center, biasOffset: Center, easeInSec: number): Center[];
+/** One tracked subject's per-frame face boxes + active-speaker windows. */
+export interface TrajectorySubject {
+    face_id: string;
+    /** Per-frame [x,y,w,h] in [0,1] vs source dims; null where this subject has no face. */
+    face_box_series: Array<[number, number, number, number] | null>;
+    /** [startFrame, endFrame) ranges (segment-relative) where this subject is the active speaker. */
+    active_windows: Array<[number, number]>;
+}
+/** One trajectory segment. */
+export interface TrajectorySegment {
+    idx: number;
+    start_sec: number;
+    end_sec: number;
+    zoom_scale: number;
+    vertical_bias: number;
+    lateral_bias: number;
+    centers: Center[];
+    subjects: TrajectorySubject[];
+    caption_band_reserve: number;
+    zooms?: number[];
+    /**
+     * DERIVED outcome (Phase 5 zoom-to-fit): true iff this (sub-)shot's locked
+     * subject group is WIDER than the output aspect at zoom 1.0, so the camera
+     * pads-and-holds at the widest honest frame rather than containing the whole
+     * group. An emitted authored outcome surfaced to the driving agent (the
+     * editorial drop/cut decision is the agent's, not the renderer's) — NOT an
+     * error and NOT a silent edge-clip. Absent (undefined) on a fitting group and
+     * on every non-`all-faces` mode. The renderer ignores it (it's metadata for
+     * the agent / eval); the crop already pads-and-holds via the coverage clamp.
+     */
+    overframed?: boolean;
+}
+/** The trajectory JSON the render consumes. (No `intent_hash` — no producer emits
+ *  it and nothing reads it; it was a renderer-only drift field, now dropped.) */
+export interface TrajectoryData {
+    bake_version: string;
+    aspect: string;
+    src_w: number;
+    src_h: number;
+    src_fps: number;
+    segments: TrajectorySegment[];
+}
+/** Per-aspect caption keep-out band (fraction of output height). SSOT — the
+ *  execution derive imports this rather than re-declaring it. */
+export declare const CAPTION_BAND_RESERVE: Record<string, number>;
+/**
+ * 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 declare function deriveStillTrajectory(reframe: Reframe, srcW: number, srcH: number, fps: number, aspect: string, bakeVersion: string): TrajectoryData;