@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/composition/projection/composition-floor.d.ts

@@ -1,9 +1,5 @@
 export { apcaLc } from "../../brand-derivation/index.js";
-/** Bump on ANY change to the algorithm or constants below. The render consumer
- *  embeds this into renderCacheKey (spec §15) so a floor change invalidates
- *  cached renders transitively — never a remembered manual bump. */
 export declare const FLOOR_VERSION = "floor-v6-2026.06.09";
-/** Fractions of the OUTPUT rect. Origin TOP-LEFT, y-down, all in [0,1]. */
 export interface Rect {
     x: number;
     y: number;
@@ -11,73 +7,43 @@ export interface Rect {
     h: number;
 }
 export type Anchor = "top" | "bottom" | "lower-third" | "left" | "right" | "free";
-/** A frame window in absolute frame indices (inclusive start, exclusive end). */
 export interface FrameWindow {
     startFrame: number;
     endFrame: number;
 }
-/** Per-frame face box normalized to the OUTPUT frame (the crop is already applied
- *  — render derives this as crop∘FaceBoxSource). `null` = no face that frame. */
 export type FaceBoxOutput = Rect;
-/** One tracked person. The bake (spec §10) emits a per-frame face box per subject
- *  plus the windows where they are the active speaker. */
 export interface Subject {
     id: string;
-    /** Per-frame face box (output coords), `null` where this subject has no face. */
     faceBoxSeries: (FaceBoxOutput | null)[];
-    /** Windows where this subject is the active speaker (drives speaker-switch, spec §8). */
     activeWindows?: FrameWindow[];
 }
-/** The composed layout shape resolved from `subjects[]`. `single-focus` is fully
- *  placed by this module; the designed split/stacked/speaker-switch geometry is a
- *  later plan (spec §8) — reported here so callers branch correctly and the
- *  multi-subject case is never silently flattened. */
 export type LayoutIntent = "single-focus" | "split" | "stacked" | "speaker-switch";
-/** The CEILING contract (spec §7) — declared here so the author-time agent and
- *  the render/ceiling consumers share one shape. The floor only bounds a
- *  treatment's animated EXTENT (a popping word must not pop onto the face); the
- *  treatment library itself lives above the floor. */
 export interface Treatment {
     segmentation: "word" | "phrase" | "line";
     emphasis: {
         keywords: string[];
         style: "color" | "scale" | "weight";
     };
-    /** One of the repo's mood-tagged kinetic caption styles (useWhen/pairsWith/avoidWith honoured above the floor). */
     kineticPreset: string;
     maxLines: number;
-    /** Index into the editorial type scale (spec §7.1) — NOT a raw px guess. */
     typeScaleStep: number;
 }
 export interface PlacedElement {
     id: string;
     kind: "caption" | "graphic";
-    /** `inset` respects face + safe-zones + inter-element; `takeover` is intentional
-     *  full-frame occlusion (honours only safe zones for its internal text). */
     intent: "inset" | "takeover";
-    /** Captions are required (the reframe yields, never drops); graphics default droppable. */
     required: boolean;
-    /** Higher places first. Captions highest by default. */
     priority: number;
     hasText: boolean;
-    /** MEASURED extent (caption layer measures the text; overlay measures the
-     *  primitive at its declared params) — NOT a guess. The hard face guarantee is
-     *  only as hard as this number, so it must be real (spec §5). */
     measuredExtent: {
         w: number;
         h: number;
     };
     preferredRegion?: Anchor;
     treatment?: Treatment;
-    /** Resolved text color (hex) for the legibility check; defaults to the white
-     *  pole when omitted (the safe default text color over an unknown backdrop). */
     textColor?: string;
-    /** Element time window in absolute frames (caller converts seconds→frames up front). */
     timeWindow: FrameWindow;
 }
-/** Caller-supplied luminance summary of the layers BENEATH an element (no
- *  circularity — never the element's own remedy). Each tile is Y∈[0,1]; the
- *  WORST tile drives the decision. Render samples real pixels; tests synthesize. */
 export interface LuminanceSummary {
     tiles: number[];
 }
@@ -90,10 +56,6 @@ export interface ResolvedElement {
         remedy: LegibilityRemedy;
     };
 }
-/** The reframe's yield. `transform` is a per-frame additive adjustment on the
- *  baked trajectory (generalises the old caption scalar shift); `mat` is a
- *  DESIGNED reserved band (the render fills it with blurred-glass/gradient —
- *  NEVER a flat letterbox on 9:16/4:5). */
 export type ReframeAdjustment = {
     kind: "transform";
     dy: number;
@@ -118,129 +80,46 @@ export interface FloorInput {
         platform: string;
         aspect: "9:16" | "1:1" | "4:5" | "16:9";
     };
-    /** Multi-subject native (spec §5/§8). One subject → single-focus. */
     subjects: Subject[];
     elements: PlacedElement[];
-    /** depthMode relaxes the face keep-out's LOWER edge into a torso band (spec §12).
-     *  When `captionsBehind` is supplied, depthMode is GATED by the eligibility
-     *  predicate (§22.2) — ineligible degrades to a normal lower-third caption. */
     depthMode?: boolean;
-    /** Captions-behind-speaker eligibility signals (§22.2), injected by the render
-     *  env: `activeSpeakerPresenceFraction` summarized from the bake's activeWindows;
-     *  `activeBandCoverage` = the post-sizing matte occlusion of the caption band
-     *  (a render-time sample, like `backdrop`). Absent ⇒ the gate is inert and
-     *  depthMode is honored as authored (today's behavior). */
     captionsBehind?: {
         activeSpeakerPresenceFraction: number;
         activeBandCoverage: number | null;
     };
-    /** Layers-beneath luminance for an element's region+window. Render supplies the
-     *  real sampler; tests supply a synthetic one. */
     backdrop: (rect: Rect, frames: number[]) => LuminanceSummary;
 }
 export interface FloorEnvelope {
     perElement: ResolvedElement[];
     reframe: ReframeAdjustment;
-    /** Per-frame UNION face keep-out across all subjects (`null` where no subject has a face). */
     faceKeepOut: (Rect | null)[];
     layout: LayoutIntent;
     diagnostics: FloorDiagnostics;
 }
-/** Face keep-out padding, in fractions of the FACE box (scales with face size,
- *  aspect-agnostic). Top grows most (hair/headroom), then bottom, then sides. */
 export declare const FACE_PADDING: {
     readonly top: 0.6;
     readonly bottom: 0.3;
     readonly side: 0.25;
 };
-/** APCA Lc target for caption/graphic text over video (spec §2 invariant 2).
- *  Numerically equals brand-derivation's `FLOORS.nonBody`, but it is a DISTINCT
- *  concept (text-over-hostile-video, not muted-UI-text) — kept separate on
- *  purpose so a change to one never silently moves the other. */
 export declare const CAPTION_LC_FLOOR = 60;
-/** Minimum effective zoom the yield may request — mirrors the bake's source-fit
- *  floor (`CropFromTrajectory` effectiveZoom clamp). Below this the source no
- *  longer fills the frame, so we fall to a designed mat instead. */
 export declare const MIN_ZOOM = 0.4;
-/** Pad a single face box by the face-relative padding vector and clamp to [0,1].
- *  `null` (no-face frame) → `null`. In depthMode the lower edge is NOT grown
- *  (the torso band is legible-behind, spec §12). */
 export declare function faceKeepOut(face: FaceBoxOutput | null, depthMode?: boolean): Rect | null;
-/** Axis-aligned bounding box of a set of rects. */
 export declare function boundingBox(rects: Rect[]): Rect;
-/** Per-frame UNION of every subject's padded face keep-out. `null` for a frame
- *  where no subject has a face. This is the floor's "face class" — captions never
- *  occlude ANY subject's face, single- or multi-subject. */
 export declare function unionFaceKeepOutSeries(subjects: Subject[], depthMode?: boolean): (Rect | null)[];
-/** Per-frame keep-out for SPEAKER-SWITCH (spec §8): the crop follows the active
- *  speaker, so only THEY are prominently in frame — the keep-out tracks the
- *  active subject (whose `activeWindows` cover the frame), NOT the union of all
- *  subjects. This lets captions sit tight under the in-frame speaker instead of
- *  clearing an off-frame second subject's union (the over-conservative single-
- *  stage behavior). Gaps (before the first switch, or no window covers the frame)
- *  hold the first subject that has a face there; truly faceless frames → null. */
 export declare function activeFaceKeepOutSeries(subjects: Subject[], depthMode?: boolean): (Rect | null)[];
-/** Resolve the composed layout shape from `subjects[]`. One subject → single-
- *  focus. Two+ subjects → speaker-switch when active-speaker windows exist,
- *  else a static split. (The DESIGNED geometry for the multi cases is spec §8 /
- *  a later plan; this module places them with a correct union keep-out and
- *  reports the intent so nothing is silently flattened.) */
 export declare function resolveLayoutIntent(subjects: Subject[]): LayoutIntent;
-/**
- * Compute the reframe yield needed to open `neededBand` of vertical space below
- * the (clip-max) face keep-out for a required element. Precedence:
- *   1. already enough band below → identity transform
- *   2. reposition: raise the source so the keep-out leaves `neededBand` below it
- *   3. zoom-out: shrink the subject (capped at MIN_ZOOM) to free vertical space
- *   4. designed mat: a reserved band at the bottom (the render fills it with a
- *      designed treatment — NEVER a flat letterbox; forbidden as a frame-border
- *      pillarbox on 9:16/4:5).
- */
 export declare function reframeYield(input: {
     maxFaceKeepOut: Rect;
     neededBand: number;
     aspect: string;
 }): ReframeAdjustment;
-/**
- * TOP-direction reframe-yield — open `neededBand` of vertical space ABOVE the
- * face keep-out for a HERO caption that sits ABOVE the subject (the "STEAL"
- * composition: subject low, big text in the headroom). Mirror of `reframeYield`
- * but UP-direction:
- *   1. already enough band above → identity
- *   2. reposition: LOWER the subject (dy>0) so the keep-out's top leaves the band
- *   3. zoom-out: shrink the subject (capped at MIN_ZOOM) to free the rest
- *   4. INFEASIBLE → `null` (NEVER a designed mat — "no fake stuff", per the hero
- *      caption decision). The caller degrades to a readable FRONT caption when
- *      real headroom can't fit the band (e.g. the head is already frame-high).
- * NOTE: operates in OUTPUT-frame keep-out coords like reframeYield; the SOURCE
- * headroom check (whether the source actually has room above the head) belongs
- * to the eligibility gate that feeds this — see captionsBehind eligibility.
- */
 export declare function reframeYieldTop(input: {
     maxFaceKeepOut: Rect;
     neededBand: number;
     aspect: string;
 }): ReframeAdjustment | null;
-/** Speaker silhouette width ÷ face KEEP-OUT width. Shoulders span ~2.2× the bare
- *  face; the keep-out already carries side padding (~1.5× the face), so the
- *  silhouette is ~1.5× the keep-out. Used to size the co-view crop. */
 export declare const SILHOUETTE_TO_KEEPOUT_W = 1.5;
-/** Co-view target: the speaker silhouette must occupy at most this fraction of
- *  the OUTPUT width, so a centred caption (~0.8 wide) extends past the body on
- *  both sides and reads WITH a body-bite (spec §12) instead of vanishing. At 0.45
- *  the body covers ~45% of the width → ~44% of the caption is visible (a clear
- *  readable bite, not just the stray ends) while keeping a comfortable medium
- *  shot. Lower = more caption shown but a smaller subject (pure aesthetic knob). */
 export declare const COVIEW_MAX_SILHOUETTE_W = 0.45;
-/**
- * Reframe for CAPTIONS-BEHIND (co-view, depthMode). Unlike reframeYield (which
- * opens a vertical band BELOW the face for a lower-third caption), the co-view
- * caption sits CENTRED behind the speaker — so the constraint is LATERAL: the
- * silhouette must be narrower than the caption or the body hides the whole line
- * (the over-occlusion bug). Widen the crop (shrink the subject, face-scale<1,
- * capped at MIN_ZOOM) until the silhouette fits COVIEW_MAX_SILHOUETTE_W. dy=0 —
- * no vertical reposition; the caption is behind, not below.
- */
 export declare function coViewReframe(maxFaceKeepOut: Rect): ReframeAdjustment;
 export declare const MIN_ACTIVE_SPEAKER_PRESENCE = 0.6;
 export declare const COVIEW_MIN_BAND_COVERAGE = 0.15;
@@ -250,20 +129,6 @@ export interface CaptionsBehindEligibility {
     eligible: boolean;
     reason: CaptionsBehindReason;
 }
-/**
- * Pure eligibility gate for captions-behind-speaker. Evaluated AFTER the co-view
- * reframe sizing (spec §22.2), so `activeBandCoverage` is the post-sizing
- * occlusion of the caption band by the active speaker's silhouette.
- *
- * @param activeSpeakerPresenceFraction fraction of clip frames with ANY active
- *   speaker present (single or two-shot; not "single speaker"). Injected.
- * @param activeBandCoverage mean fraction of the caption band the active
- *   speaker's silhouette occludes over its windows; `null` ⇒ NOT YET MEASURED
- *   (the bake-time coverage scalar is a follow-on) → the coverage gate is
- *   SKIPPED and presence + coViewReframe sizing gate instead. Injected like
- *   `LuminanceSummary` (bake/render-env), keeping this function pure.
- * @param legible APCA decision (Lc ≥ CAPTION_LC_FLOOR) on the visible portion.
- */
 export declare function captionsBehindEligible(input: {
     activeSpeakerPresenceFraction: number;
     activeBandCoverage: number | null;
@@ -279,26 +144,7 @@ interface Blockers {
     faceKeepOut: Rect[];
     safeZones: Rect[];
 }
-/**
- * Place a full-width-ish horizontal band element (caption / lower-third) in the
- * legal area. Two-zone model (spec §6.2): center-crossing blockers carve the
- * legal vertical GAPS (1-D solve); side regions (rails) cap the horizontal
- * CORRIDOR of the chosen band. Returns `null` when no legal vertical gap of
- * `minH` fits, or when side rails squeeze the corridor below MIN_CAPTION_WIDTH.
- * (Full 2-D packing for split/stacked layouts is spec §8 / a later plan.)
- */
 export declare function placeInLegalArea(el: PlaceReq, b: Blockers): Rect | null;
-/**
- * The safe caption REGION for a destination — the floor's caption placement
- * WITHOUT per-clip face context. The reframe handles faces per clip; the caption
- * position itself is clip-independent (safe-zone-driven), so the GLOBAL caption
- * layer renders into THIS band and it matches the per-clip floor's caption region
- * (and its scrim) by construction — same placeInLegalArea, same safe zones.
- *
- * For a bottom/lower-third anchor the region's BOTTOM edge sits at the top of the
- * platform's bottom-UI strip, so a caption rendered into it clears the chrome on
- * any vertical surface (lookupSafeZones unions platforms when none is threaded).
- */
 export declare function resolveCaptionRegion(input: {
     aspect: string;
     platform?: string;
@@ -308,17 +154,6 @@ export declare function resolveCaptionRegion(input: {
     };
     anchor?: Anchor;
 }): Rect;
-/**
- * The region a code/graphic overlay (jsxSource) must render WITHIN — the largest
- * band clear of the caption + platform safe zones (item #10: floor assigns the
- * region, the jsx obeys). Keeps editorial graphics off the captions and the
- * platform UI; the agent's jsx reads `params.region` (output fractions) for its
- * bounds instead of hard-coding positions / full-frame useVideoConfig math.
- *
- * v1 is face-agnostic (clip-independent, like the caption band); per-clip
- * face-aware overlay placement is a follow-up — the brief tells the agent the
- * region may contain the speaker, so graphic elements should favour its edges.
- */
 export declare function resolveOverlayRegion(input: {
     aspect: string;
     platform?: string;
@@ -328,22 +163,8 @@ export declare function resolveOverlayRegion(input: {
         h: number;
     };
 }): Rect;
-/**
- * Decide the legibility remedy for text of `textColor` over a backdrop luminance
- * summary. Real APCA (no proxy): the text's relative luminance vs each tile's
- * luminance, reduced to the WORST tile. ≥ CAPTION_LC_FLOOR → no remedy; else the
- * floor REQUESTS the cheapest always-legible remedy (`scrim`; the render makes it
- * a designed blurred-glass/gradient, never a hard stroke — spec §14). The
- * `lcTarget` is always the floor (the remedy must clear it).
- */
 export declare function decideLegibility(backdrop: LuminanceSummary, textColor?: string): {
     lcTarget: number;
     remedy: LegibilityRemedy;
 };
-/**
- * Resolve the composition floor for one clip. Linear, single-stage-per-clip, no
- * feedback loop → deterministic. Never throws; required elements are never
- * dropped (they get a forced designed-mat / lowest-gap placement), only
- * non-required elements may drop (logged in diagnostics).
- */
 export declare function resolveCompositionFloor(input: FloorInput): FloorEnvelope;

package/dist/_members/composition/projection/cropProjection.d.ts

@@ -1,45 +1,21 @@
 import type { TrajectoryData, TrajectorySegment } from "../reframe/trajectory.js";
 import type { Rect, ReframeAdjustment, Subject } from "./composition-floor.js";
 export declare const FRAME_ROUNDING_TOLERANCE = 2;
-/**
- * Resolve which trajectory segment (and index within it) a clip-relative source
- * frame lands in. A frame within FRAME_ROUNDING_TOLERANCE of a segment edge
- * clamps to the nearest edge; ANY larger gap FAILS LOUD (a real coverage/mapping
- * bug — a cropIntent gap with no excludedRange, or a bad trim/section mapping —
- * must not silently clamp onto the wrong frames).
- */
 export declare function resolveSegmentAt(traj: TrajectoryData, srcFrame: number): {
     seg: TrajectorySegment;
     inSegIdx: number;
 };
-/** A playable span of the clip — one JumpCutVideo section. `sourceInFrames` is
- *  the SOURCE-ABSOLUTE frame (output fps) the span seeks to. */
 export interface CropSection {
     sourceInFrames: number;
     durationInFrames: number;
 }
-/**
- * Map an OUTPUT frame to the CLIP-RELATIVE trajectory frame, section-aware. The
- * trajectory is clip-relative (frame 0 = the clip's `trim.start`), but a clip
- * with `excludedRanges` plays N playable spans, each seeking to a
- * SOURCE-ABSOLUTE `sourceInFrames` with the trimmed gaps removed. So output
- * frame F does NOT equal trajectory frame F; the section walk bridges the gaps.
- */
 export declare function outputToTrajectoryFrame(sections: CropSection[], trimStartFrames: number, outFrame: number, srcFps: number, fps: number): number;
-/** The per-frame crop-transform pieces `sourceRectToOutput` needs — the subset of
- *  `computeCropTransform`'s output that maps source pixels to output pixels. */
 export interface CropTransform {
     tx: number;
     ty: number;
     scaledSrcW: number;
     scaledSrcH: number;
 }
-/**
- * Pure crop-transform math. Given the resolved per-frame center + crop params,
- * the output dims, and the composition floor's reframe, returns the CSS
- * transform (`tx`, `ty`, scaled source dims). `tyNoShift` is the y-translation
- * WITHOUT the reframe, exposed so tests can assert magnitude.
- */
 export declare function computeCropTransform(input: {
     traj: {
         src_w: number;
@@ -60,13 +36,6 @@ export declare function computeCropTransform(input: {
     scaledSrcW: number;
     scaledSrcH: number;
 };
-/**
- * Map a SOURCE-normalized rect (`{x,y,w,h}` in [0,1] against source dims) to an
- * OUTPUT-normalized rect, applying the per-frame crop — the `crop∘FaceBoxSource`
- * the composition floor's `FaceBoxOutput` is defined as. NOT clamped: a face near
- * the source edge can map partly off-frame, and that is the truth the floor needs
- * (`faceKeepOut` clamps to [0,1] when it builds the keep-out).
- */
 export declare function sourceRectToOutput(src: Rect, t: CropTransform, outW: number, outH: number): Rect;
 export interface BuildSubjectsOutputArgs {
     traj: TrajectoryData;
@@ -77,38 +46,12 @@ export interface BuildSubjectsOutputArgs {
     outH: number;
     fps: number;
 }
-/**
- * Build per-clip `Subject[]` with OUTPUT-space face boxes, accumulated by
- * `face_id` across the clip's output frames — the projection loop factored out of
- * the render's buildFloorInput so the Director derives IDENTICAL keep-outs. For
- * each output frame: section-aware output→trajectory map → resolve segment →
- * crop transform → project each source face box to output.
- */
 export declare function buildSubjectsOutput(args: BuildSubjectsOutputArgs): Subject[];
-/**
- * The face keep-out rect(s) covering a beat window [startFrame, endFrame) in
- * OUTPUT coords — for the structure-first graphics solver. Unions the
- * speaker-active face keep-outs across the window into ONE bounding rect (so a
- * graphic placed clear of it is clear of the face at EVERY frame of the beat).
- * Empty when no face is present in the window (e.g. b-roll).
- */
 export declare function faceKeepOutForWindow(subjects: Subject[], startFrame: number, endFrame: number, depthMode?: boolean): Rect[];
-/**
- * A SOURCE-space subject-silhouette provider: given a CLIP-RELATIVE source frame
- * (frame 0 = the clip's trim.start, at src_fps), return the subject's silhouette
- * bbox source-normalized [0,1] (`{x,y,w,h}`), or `null` when no subject is present
- * that frame. The matte-geometry sidecar's per-frame foreground bbox is today's
- * concrete provider (see the director's buildEvalSilhouette); a person-track union
- * is a drop-in alternate. DECOUPLED from the crop on purpose: the SILHOUETTE comes
- * from here; the CROP comes from `traj` (the render's reframe) — so the box lands
- * exactly where the shipped render places the subject.
- */
 export interface SubjectSilhouetteSource {
     bboxAtSourceFrame: (srcFrame: number) => Rect | null;
 }
 export interface BuildSilhouetteKeepOutArgs {
-    /** The RENDER's reframe trajectory (FACE-derived — the SHIPPED crop). Its
-     *  segments supply the per-frame crop transform; its `subjects` are unused. */
     traj: TrajectoryData;
     silhouette: SubjectSilhouetteSource;
     sections: CropSection[];
@@ -118,23 +61,5 @@ export interface BuildSilhouetteKeepOutArgs {
     outH: number;
     fps: number;
 }
-/**
- * Per-output-frame OUTPUT-space subject-SILHOUETTE keep-out — the silhouette twin
- * of buildSubjectsOutput. For each output frame: section-aware output→trajectory
- * map → resolve segment → crop transform (the SAME primitives buildSubjectsOutput
- * uses for the FACE box) → project the source silhouette bbox supplied by the
- * provider. `null` where the provider has no subject that frame. Unlike the face
- * path this applies NO face-relative padding — the silhouette already includes
- * hair/head/torso, so the projected box IS the keep-out. Off-crop overflow is
- * clamped into the visible output frame [0,1] (the keep-out only concerns what is
- * on screen).
- */
 export declare function buildSilhouetteKeepOutOutput(args: BuildSilhouetteKeepOutArgs): (Rect | null)[];
-/**
- * Union the projected silhouette keep-out across a beat window [startFrame,
- * endFrame) into ONE OUTPUT-space rect (so a graphic clear of it is clear of the
- * subject at EVERY frame of the window) — the silhouette twin of
- * faceKeepOutForWindow. Empty when no frame in the window carries a silhouette
- * (degenerate zero-area rects are dropped).
- */
 export declare function silhouetteKeepOutForWindow(series: (Rect | null)[], startFrame: number, endFrame: number): Rect[];

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

@@ -3,5 +3,7 @@ export * from "./cardTokens.js";
 export * from "./composition-floor.js";
 export * from "./safe-zones.js";
 export * from "./behind-placement.js";
+export * from "./behind-readiness.js";
+export * from "./reframe-readiness.js";
 export * from "./occlusion-budget.js";
 export * from "./cropProjection.js";

package/dist/_members/composition/projection/occlusion-budget.d.ts

@@ -1,61 +1,24 @@
-/**
- * Occlusion budget for behind-subject text (launch-grade text-behind-subject,
- * Phase 2). Pure decisions over matte geometry sidecar frames: estimate how much
- * of a text rect the subject covers, then verdict the window — too little bite
- * reads as no depth at all; too much swallows the line; a covered TOP half eats
- * the letter tops that carry legibility. The caller (a director activity) maps
- * timeline→source frames, samples K frames, and degrades the overlay to front
- * on any non-pass verdict — the overlay is never dropped.
- */
 import type { MatteGeometryFrame } from "./behind-placement.js";
-/** Budget thresholds (frame-fraction coverage of the TEXT rect). Calibration
- *  defaults — Phase-7 fixtures tune them, the deploy-test is the truth.
- *  `minBite`: below this at EVERY sample the silhouette never bites the line —
- *  the depth effect is invisible, so don't pay its cost. `maxCoverage`: above
- *  this at ANY sample the body swallows the line. `maxTopHalf`: text-bearing
- *  overlays lose legibility when letter TOPS go under — cap the upper half. */
 export declare const BUDGET: {
     readonly minBite: 0.15;
     readonly maxCoverage: 0.65;
     readonly maxTopHalf: 0.35;
 };
-/** Behind hero text extent heuristic (calibration constants; Phase-7 fixtures tune). */
 export declare const BEHIND_TEXT_EXTENT: {
     readonly heightFrac: 0.18;
 };
-/** Coverage at one sampled geometry frame: `total` over the full text rect,
- *  `topHalf` over its upper half. Both ∈ [0,1]. */
 export interface CoverageSample {
     f: number;
     total: number;
     topHalf: number;
 }
 export type BudgetVerdict = "pass" | "no-depth" | "swallow" | "tops-occluded";
-/**
- * Verdict a window of coverage samples against the budget. Samples are checked
- * in order; the FIRST violating sample decides (deterministic): a text-bearing
- * overlay whose top half exceeds `maxTopHalf` → "tops-occluded"; any sample over
- * `maxCoverage` → "swallow". If no sample violates but the maximum total never
- * reaches `minBite` → "no-depth" (so is an empty window). Else "pass".
- * `worstFrame` is the violating sample's frame for the two per-sample verdicts.
- */
 export declare function evaluateOcclusionBudget(samples: CoverageSample[], opts?: {
     textBearing: boolean;
 }): {
     verdict: BudgetVerdict;
     worstFrame?: number;
 };
-/**
- * Estimate matte coverage of a text rect from the sidecar's marginal profiles.
- * APPROXIMATION (documented): overlap(textRect, bbox) area fraction, weighted by the
- * mean col-bucket coverage across the intersected x-span (cols[i] = fraction of that
- * column covered by the subject). topHalf uses the same estimate restricted to the
- * text rect's upper half via the rows marginal weighting. Marginals can't give exact
- * 2-D intersection — constants are calibrated against fixtures, and the deploy-test
- * is the truth.
- *
- * All rects source-normalized [0,1]. A null bbox (no subject) → {0, 0}.
- */
 export declare function estimateCoverage(textRect: {
     x: number;
     y: number;

package/dist/_members/composition/projection/reframe-readiness.d.ts

@@ -0,0 +1,49 @@
+export interface SourceWindowLike {
+    startSec: number;
+    endSec: number;
+    detector?: "face" | "person";
+}
+export interface SubjectTrackEntryLike {
+    trackR2Key?: string;
+    trackUrl?: string;
+    detectorVersion?: string;
+    window?: {
+        startSec: number;
+        endSec: number;
+    };
+    faces?: Array<{
+        faceId: string;
+        bbox: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        speakingShare?: number;
+    }>;
+}
+export declare function sourceWindowKey(window: SourceWindowLike): Promise<string>;
+export interface ReframeTarget {
+    clipId: string;
+    mediaId: string;
+    window: {
+        startSec: number;
+        endSec: number;
+    };
+    segments: unknown[];
+}
+export declare function reframeNeedsDetection(segments: unknown[]): boolean;
+export declare function reframeTargets(composition: unknown): ReframeTarget[];
+export type ReframeReadiness = {
+    state: "geometric";
+} | {
+    state: "track-ready";
+    entry: SubjectTrackEntryLike;
+    trackUrl: string;
+} | {
+    state: "track-unfetchable";
+    entry: SubjectTrackEntryLike;
+} | {
+    state: "no-track";
+};
+export declare function reframeReadinessForTarget(target: ReframeTarget, subjectTracks: Record<string, SubjectTrackEntryLike> | undefined): Promise<ReframeReadiness>;

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;