@cueframe/kernel 0.1.1 → 0.1.2

package/dist/_members/composition/projection/safe-zones.d.ts

@@ -1,38 +1,9 @@
-/**
- * Destination safe-zone registry — the platform-UI + broadcast keep-outs the
- * composition floor carves out of the output rect before placing any element
- * (spec §9). Fractions of the OUTPUT rect (origin top-left, y-down, [0,1]); one
- * math path for every aspect because the coordinates are already normalized to
- * the destination frame.
- *
- * Convention-grounded, NOT research-grounded: platform chrome (TikTok's right
- * action rail + bottom username/caption strip, Reels/Shorts variants) is
- * industry convention, not something the layout/saliency papers model. Keep this
- * a plain data table so it stays legible and versionable as platforms change
- * their chrome.
- *
- * Pure data + one lookup. No I/O. Same input → same output.
- */
 import type { Rect } from "./composition-floor.js";
-/** Bump on ANY change to a profile rect or the broadcast defaults below. The
- *  render consumer embeds this into renderCacheKey (spec §15) so a profile edit
- *  invalidates cached renders transitively, the way BAKE_VERSION already does —
- *  never a remembered manual bump. */
 export declare const SAFE_ZONE_PROFILE_VERSION = "safezones-v2-2026.06.05";
 export interface SafeZoneProfile {
-    /** Platform-UI rects the floor treats as hard keep-outs (never place text/graphics under them). */
     exclusions: Rect[];
-    /** Broadcast title-safe: text should stay inside this inset. */
     titleSafe: Rect;
-    /** Broadcast action-safe: critical action inside this (slightly larger) inset. */
     actionSafe: Rect;
 }
-/** Normalize a platform name to a PROFILES key (lowercased, aliased). */
 export declare function normalizePlatform(platform: string): string;
-/**
- * Resolve the safe-zone profile for a destination. Unknown platform (or an
- * aspect a known platform has no profile for) → broadcast title/action-safe only
- * (no platform exclusions) so the floor degrades to a correct, conservative
- * result rather than throwing.
- */
 export declare function lookupSafeZones(platform: string, aspect: string): SafeZoneProfile;

package/dist/_members/composition/reframe/aspectLoss.d.ts

@@ -1,29 +1,3 @@
-/**
- * Aspect-loss advisory: a source whose shape disagrees with the output frame,
- * placed with no authored camera.
- *
- * A `cover` fill scales the source until it covers the frame and throws the
- * overflow away, centred. For a 3840×5760 portrait photo in a 16:9 frame that
- * discards ~62% of the image about the middle — reliably decapitating anyone in
- * it. In the 2026-08-05 toddler-parks session 15 of 68 imported candidates were
- * portrait, every one placed into 16:9 with no crop intent, and nothing said a
- * word at any point in the pipeline.
- *
- * Note this is WORSE for stills than the `fit` field suggests: `fit` is not
- * threaded to the image path at all (MainComposition routes `kind:'image'` to
- * StillCrop, which has no `fit` prop), so an image is always cropped by the
- * derived still trajectory — whose faceless default centre is a hardcoded
- * [0.5, 0.5]. Declaring `fit:"contain"` does not avoid this; authoring a
- * `reframe` (or a `kenBurns`) does.
- *
- * ADVISORY only — same `(input) => string[]` contract as `detectNoAudioTrack`.
- * Cropping to fill is a legitimate choice; this only says nobody made it.
- */
-/**
- * Fraction of the source that survives a `cover` fill. Purely a function of the
- * two aspect ratios: the narrower dimension is fully used, the wider one is
- * trimmed to match.
- */
 export declare function coverVisibleFraction(source: {
     width: number;
     height: number;
@@ -31,15 +5,18 @@ export declare function coverVisibleFraction(source: {
     width: number;
     height: number;
 }): number;
-/**
- * Advisory for media placed into a materially different frame shape with no
- * authored camera.
- *
- * `dimensionsByMediaId` is expected to be partial: image dimensions are
- * populated LAZILY (they are not known at upload /complete), so a media with no
- * width/height is SKIPPED rather than guessed at — an advisory that fires on
- * missing metadata would train agents to ignore the channel.
- */
+export interface AspectCropLoss {
+    clipId?: string;
+    mediaId: string;
+    lostPct: number;
+}
+export declare function findAspectCropLosses(composition: unknown, dimensionsByMediaId: Record<string, {
+    width?: number;
+    height?: number;
+} | undefined>, target: {
+    width: number;
+    height: number;
+}): AspectCropLoss[];
 export declare function detectAspectCropLoss(composition: unknown, dimensionsByMediaId: Record<string, {
     width?: number;
     height?: number;

package/dist/_members/composition/reframe/coverage.d.ts

@@ -1,44 +1,4 @@
-/**
- * Reframe coverage invariant — the SINGLE source of truth for
- * "a clip's `reframe.segments` MUST tile its PLAYED window: `[0, duration]`
- * minus the clip's excluded spans" (clip-relative source seconds; segment 0 =
- * the clip's `trim.start`). An excluded span is never walked by the renderer
- * (`playableSpans` skips it and rebases across the gap), so it needs NO
- * reframe coverage — demanding it would reject the compiler's own canonical
- * trim output (trim → excludedRange + segments tiling the remainder).
- *
- * Pure arithmetic, ZERO runtime imports (structural param types only), so it is
- * safe in BOTH the Convex V8 isolate (save-time `validateReframeCoverage`) AND
- * the Temporal workflow sandbox (the compose-loop pre-derive gate). One
- * definition, no drift — the two chokepoints enforce the exact same rule.
- *
- * Why it matters: `deriveTrajectory` bakes coverage = the union of the AUTHORED
- * segments (it clamps, never extends). If the segments leave a gap (a forgotten
- * head lead-in, or a source-absolute-vs-clip-relative time-base mis-map), the
- * render walks a played frame no segment covers and `resolveSegmentAt` throws
- * `trajectory_coverage_gap` deep in the renderer. Catching the gap on this pure
- * path — where BOTH the played window and the segments are known — turns that
- * cryptic late crash into an early, actionable, clip-named error.
- */
-/** Seam-rounding slack: two segments meeting within EPS seconds are contiguous,
- *  not a gap (matches the fps-conversion tolerance at a segment edge). */
 export declare const REFRAME_COVERAGE_EPS = 0.001;
-/**
- * The FIRST uncovered `[start, end]` span (in clip-relative source seconds) where
- * `segments` fail to tile the PLAYED window — `[0, duration]` minus `excluded` —
- * or `null` when every played instant is covered. Order-independent (sorts a
- * copy). A legitimate subjectless lead-in is NOT a gap only when it is handled
- * EXPLICITLY: either a frame-center segment covering it, or an excluded span
- * removing it from playback (the compiler's trim → excludedRange path). This
- * helper never invents either (feedback_never_add_fallbacks).
- *
- * `excluded` spans are clip-relative like the segments (source-absolute
- * `excludedRanges` convert via `- trim.start` at the call site). An excluded
- * instant counts as covered because the renderer never resolves a trajectory
- * there (`playableSpans` drops it), so the sweep unions segments + exclusions
- * and any remaining hole is exactly a played-and-uncovered span — the set that
- * crashes `resolveSegmentAt`.
- */
 export declare function firstReframeCoverageGap(segments: ReadonlyArray<{
     startSec: number;
     endSec: number;

package/dist/_members/composition/reframe/derive.d.ts

@@ -1,19 +1,5 @@
-/**
- * derive — PURE multi-format derivation core (P5). Produce a reframed SIBLING
- * composition for a new target Format: copy authored intent verbatim, set the
- * new `format`, and author a GEOMETRIC single-subject `reframe` on every media
- * clip that doesn't already carry one. Aspect-specific crop-window geometry,
- * caption-band reserve, and width-anchored brand are re-resolved DOWNSTREAM at
- * render from `composition.format` (deriveTrajectory + compositionFormatDimensions)
- * — this module never touches them. Single-subject focus is aspect-independent.
- *
- * Group/editorial refinement (e.g. all-faces → active-speaker for a narrower
- * aspect) is the explicit follow-on: an existing reframe is copied verbatim and
- * the render honestly pads-and-holds (overframed) for the new aspect.
- */
 import type { Composition, Format } from "../validators/composition.js";
 import type { Focus } from "./index.js";
-/** The inline face roster cached on `mediaItems.subjectTracks[windowHash].faces`. */
 export interface RosterFace {
     faceId: string;
     bbox: {
@@ -25,13 +11,6 @@ export interface RosterFace {
     speakingShare?: number;
 }
 export type ClipFaceRoster = RosterFace[];
-/** Output FormatSpec the caller targets (no `platform` — preserved from source). */
 export type TargetFormat = Pick<Format, "aspectRatio" | "fps" | "resolution">;
-/**
- * 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 declare function pickGeometricFocus(faces: ClipFaceRoster | undefined): Focus;
 export declare function deriveReframedComposition(source: Composition, targetFormat: TargetFormat, perceptionByClipId: Record<string, ClipFaceRoster>): Composition;

package/dist/_members/composition/reframe/index.d.ts

@@ -1,23 +1,3 @@
-/**
- * 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";
 export * from "./shotScale.js";
 export * from "./aspectLoss.js";
@@ -65,16 +45,9 @@ export declare const Focus: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
     mode: "active-speaker";
 }>]>;
 export type Focus = z.infer<typeof Focus>;
-/**
- * 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 declare const ReframeSegmentFields: z.ZodObject<{
     startSec: z.ZodNumber;
     endSec: z.ZodNumber;
-    /** WHO/WHAT the camera tracks — see the `.describe()` for per-mode guidance. */
     focus: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
         mode: z.ZodLiteral<"frame-center">;
     }, "strip", z.ZodTypeAny, {
@@ -118,17 +91,8 @@ export declare const ReframeSegmentFields: z.ZodObject<{
     }, {
         mode: "active-speaker";
     }>]>;
-    /** 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.ZodOptional<z.ZodString>;
-    /** <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.ZodOptional<z.ZodNumber>;
-    /** 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.ZodOptional<z.ZodObject<{
         in: z.ZodNumber;
         out: z.ZodNumber;
@@ -139,7 +103,6 @@ export declare const ReframeSegmentFields: z.ZodObject<{
         in: number;
         out: number;
     }>>;
-    /** Optional fine framing nudge, source-normalized [-0.3,0.3]. */
     bias: z.ZodOptional<z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
@@ -210,7 +173,6 @@ export declare const ReframeSegmentFields: z.ZodObject<{
 export declare const ReframeSegment: z.ZodEffects<z.ZodObject<{
     startSec: z.ZodNumber;
     endSec: z.ZodNumber;
-    /** WHO/WHAT the camera tracks — see the `.describe()` for per-mode guidance. */
     focus: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
         mode: z.ZodLiteral<"frame-center">;
     }, "strip", z.ZodTypeAny, {
@@ -254,17 +216,8 @@ export declare const ReframeSegment: z.ZodEffects<z.ZodObject<{
     }, {
         mode: "active-speaker";
     }>]>;
-    /** 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.ZodOptional<z.ZodString>;
-    /** <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.ZodOptional<z.ZodNumber>;
-    /** 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.ZodOptional<z.ZodObject<{
         in: z.ZodNumber;
         out: z.ZodNumber;
@@ -275,7 +228,6 @@ export declare const ReframeSegment: z.ZodEffects<z.ZodObject<{
         in: number;
         out: number;
     }>>;
-    /** Optional fine framing nudge, source-normalized [-0.3,0.3]. */
     bias: z.ZodOptional<z.ZodObject<{
         x: z.ZodNumber;
         y: z.ZodNumber;
@@ -400,12 +352,10 @@ export declare const ReframeSegment: z.ZodEffects<z.ZodObject<{
     } | undefined;
 }>;
 export type ReframeSegment = z.infer<typeof ReframeSegment>;
-/** The camera channel: exactly one per layer; segments tile the clip. */
 export declare const Reframe: z.ZodObject<{
     segments: z.ZodArray<z.ZodEffects<z.ZodObject<{
         startSec: z.ZodNumber;
         endSec: z.ZodNumber;
-        /** WHO/WHAT the camera tracks — see the `.describe()` for per-mode guidance. */
         focus: z.ZodDiscriminatedUnion<"mode", [z.ZodObject<{
             mode: z.ZodLiteral<"frame-center">;
         }, "strip", z.ZodTypeAny, {
@@ -449,17 +399,8 @@ export declare const Reframe: z.ZodObject<{
         }, {
             mode: "active-speaker";
         }>]>;
-        /** 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.ZodOptional<z.ZodString>;
-        /** <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.ZodOptional<z.ZodNumber>;
-        /** 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.ZodOptional<z.ZodObject<{
             in: z.ZodNumber;
             out: z.ZodNumber;
@@ -470,7 +411,6 @@ export declare const Reframe: z.ZodObject<{
             in: number;
             out: number;
         }>>;
-        /** Optional fine framing nudge, source-normalized [-0.3,0.3]. */
         bias: z.ZodOptional<z.ZodObject<{
             x: z.ZodNumber;
             y: z.ZodNumber;

package/dist/_members/composition/reframe/kenBurns.d.ts

@@ -1,43 +1,6 @@
-/**
- * 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/shotScale.d.ts

@@ -1,50 +1,8 @@
-/**
- * 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;
@@ -52,16 +10,9 @@ export interface FrameGeometry {
     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;
@@ -77,42 +28,16 @@ export type PunchInWarrant = {
     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/trajectory.d.ts

@@ -1,52 +1,14 @@
-/**
- * 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;
@@ -58,20 +20,8 @@ export interface TrajectorySegment {
     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;
@@ -80,20 +30,5 @@ export interface TrajectoryData {
     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;

package/dist/_members/composition/timeline/compound.d.ts

@@ -1,36 +1,5 @@
-/**
- * FLATTENING COMPOUND CLIPS.
- *
- * A `{kind:'composition'}` source is a reference; nothing downstream — the
- * renderer, the evaluator, the still lane — knows how to draw a reference.
- * Flattening resolves each compound clip into the child composition's own
- * clips, shifted into the host's time and clipped to the compound's window,
- * producing a composition with no compound sources left. It runs at the ONE
- * translator every render lane already flows through, so a composition that
- * embeds another renders identically on desktop, cloud and still lanes.
- *
- * Semantics, stated because each was a decision:
- *
- *   - The child's tracks come in as NEW tracks directly after the host track
- *     carrying the compound clip (precomp semantics). Merging child clips into
- *     the HOST's lanes would collide with whatever else the host has there,
- *     and "my intro overwrote my b-roll" is not a bug anyone should meet.
- *   - `trim` selects a window of the child's own timeline; the compound's
- *     `duration` clips the result. Content beyond either is dropped, exactly
- *     as a media trim drops frames.
- *   - Child clip ids are prefixed with the compound clip's id, so two
- *     instances of the same child in one host cannot collide.
- *   - Child MARKERS are dropped. The host's marker lane is the host's.
- *
- * CYCLES AND DEPTH FAIL LOUD. A composition that embeds itself — directly or
- * through a chain — has no finite flattening; and unbounded nesting is a
- * stack-shaped denial of service. Both throw `InvariantError` rather than
- * rendering something partial: a render that silently dropped an embedded
- * sequence is a corrupted deliverable with a green checkmark.
- */
 import type { Composition } from "../validators/composition.js";
 export declare const MAX_COMPOUND_DEPTH = 4;
 export type ResolveComposition = (compositionId: string) => Composition | undefined;
-/** Does this composition contain any compound clip at all? Cheap gate. */
 export declare function hasCompoundClips(composition: Pick<Composition, "tracks">): boolean;
 export declare function flattenCompoundClips(composition: Composition, resolve: ResolveComposition): Composition;

package/dist/_members/composition/timeline/intent.d.ts

@@ -1,39 +1,15 @@
-/**
- * INTENT → PLAN.
- *
- * The single entry point every gesture goes through. A caller says what it
- * wants in timeline terms — "these clips, to this track, starting here" — and
- * gets back a plan it can apply or a set of named refusals it can render. It
- * never gets back a mutation.
- *
- * WHY THIS EXISTS AT ALL. The drag path used to do its own placement inline:
- * hit-test a Y coordinate, look up the track, check kind compatibility, commit.
- * It had no occupancy test (so two clips could be stacked at identical times on
- * one track), no way to mint a lane, and no way to say why a drag was refused —
- * the user just got a silent snap-back. Meanwhile the occupancy test, the
- * placement resolver and TWO separate overlap invariant checkers all existed and
- * none of them ran in production.
- *
- * The fix is not to add a call to the drag path. It is to make a drag path that
- * skips placement unrepresentable, by giving the applier nothing to accept
- * except the value this module produces.
- */
 import type { Composition } from "../validators/composition.js";
 import type { OverlapPolicy } from "./resolve.js";
 import type { TimelinePlan } from "./plan.js";
-/** One clip's requested destination. */
 export interface ClipMove {
     clipId: string;
-    /** Target lane. Same as the clip's current track for an in-lane slide. */
     toTrackId: string;
     startTime: number;
-    /** Timeline duration after the gesture — unchanged for a pure move. */
     duration: number;
 }
 export interface MoveIntent {
     type: "moveClips";
     moves: readonly ClipMove[];
-    /** Default `resolve`; `refuse` is for callers that want a dry-run answer. */
     policy?: OverlapPolicy;
     label?: string;
 }
@@ -43,11 +19,6 @@ export interface ResolveIntentArgs {
     newClipId: () => string;
 }
 export declare function resolveMoveIntent(args: ResolveIntentArgs): TimelinePlan;
-/**
- * The gate's read-only half: does this composition still satisfy the one rule
- * the move path exists to protect? Kept next to the resolver so a resolution
- * bug fails here rather than reaching the document.
- */
 export declare function planLeavesOverlaps(composition: Pick<Composition, "tracks">): Array<{
     trackId: string;
     clipIds: [string, string];