@cueframe/kernel 0.1.1 → 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/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

@@ -1,68 +1,16 @@
-/**
- * WHICH CLIPS WANT A CROP, AND DO WE HAVE WHAT IT TAKES — answered in the
- * editor, from data the media row already carries.
- *
- * The sibling of `behind-readiness.ts`, one rung down the fidelity ladder. That
- * module asks whether a SILHOUETTE exists so an overlay can go behind a person;
- * this one asks whether a BOX TRACK exists so a clip can follow one. Same shape,
- * same discipline, ~40× apart in what the answer costs.
- *
- * ── WHY IT EXISTS ───────────────────────────────────────────────────────────
- * A follow-the-speaker reframe is authored in the editor and only takes effect
- * at render, because the crop trajectory is derived from a SUBJECT TRACK the
- * editor never asked for. So the editor showed an uncropped source while the
- * render produced a moving crop — the "editor shows something the render will
- * not honour" defect, in its second location. Deriving the trajectory locally
- * fixes that, and the derive needs to find the right track first. That lookup
- * is what this module is.
- *
- * ── IT IS ONLY WORTH ANYTHING IF IT AGREES WITH THE SERVER ──────────────────
- * `reframeTargets` mirrors `collectTrajectoryDeriveJobs` (private
- * `renders.ts`) — the walk the SHIP render uses to decide which clips derive a
- * trajectory and at which window. `sourceWindowKey` mirrors `hashSourceWindow`
- * (private `@cueframe/shared/variant-keys`) byte for byte; the golden fixtures
- * in `__tests__/reframe-readiness.test.ts` are hashes taken from PRODUCTION
- * rather than invented, for the same reason `behind-readiness`'s are.
- *
- * ── WHAT IT DELIBERATELY DOES NOT CHECK ─────────────────────────────────────
- * The DETECTOR VERSION. The server skips a track whose `detectorVersion` is not
- * the current `DETECTOR_VERSION`, and the app cannot ask that without a third,
- * unguarded mirror of a string whose TS↔Python sync is already CI-guarded on
- * both existing copies. So the editor derives off whatever track sits at the
- * window. A version bump means the render re-detects and the framing shifts
- * slightly — same subject, same authored intent, and far closer to the truth
- * than showing an uncropped source. A decision, not an omission.
- */
-/** A source window. Subject tracks key on this — the window, plus the producer
- *  when it is not the default face detector. Mirrors `SourceWindowLike`. */
 export interface SourceWindowLike {
     startSec: number;
     endSec: number;
-    /**
-     * Which producer detected the track: 'face' (YuNet/SCRFD, the default) or
-     * 'person' (YOLO11x + BoT-SORT). Folded into the hash ONLY when it is not
-     * 'face', so existing face-track keys never churn and a person track for the
-     * same window gets a DISTINCT key instead of overwriting the face one.
-     */
     detector?: "face" | "person";
 }
-/** The fields this module reads off a `mediaItems.subjectTracks[hash]` entry. */
 export interface SubjectTrackEntryLike {
-    /** R2 object key — the STABLE identity every server-side reader matches on. */
     trackR2Key?: string;
-    /**
-     * Presigned URL for that key, added ALONGSIDE it by `resolveR2Urls`. The row
-     * carries only a SUMMARY of the track (the face roster, a count); the
-     * per-frame boxes `deriveTrajectory` needs are the R2 object, so this is the
-     * one field that makes a client-side derive possible at all.
-     */
     trackUrl?: string;
     detectorVersion?: string;
     window?: {
         startSec: number;
         endSec: number;
     };
-    /** The inline face roster — who is in this window, for a per-person picker. */
     faces?: Array<{
         faceId: string;
         bbox: {
@@ -74,18 +22,7 @@ export interface SubjectTrackEntryLike {
         speakingShare?: number;
     }>;
 }
-/**
- * Content-address a source window, byte-identically to the server's
- * `hashSourceWindow`. Milliseconds-rounded so float jitter cannot miss a cached
- * track; 12 hex chars. Async because `crypto.subtle` is — available in the
- * webview and in Node alike.
- *
- * The detector is omitted from the canonical form when it is 'face', which is
- * NOT a shortcut: it is what keeps every already-cached face-track key valid.
- */
 export declare function sourceWindowKey(window: SourceWindowLike): Promise<string>;
-/** A clip that has authored a reframe, and the window whose track answers for
- *  it. `segments` travels along because `deriveTrajectory` takes it verbatim. */
 export interface ReframeTarget {
     clipId: string;
     mediaId: string;
@@ -93,64 +30,20 @@ export interface ReframeTarget {
         startSec: number;
         endSec: number;
     };
-    /** The authored `source.reframe.segments`, untouched — the derive owns their
-     *  shape, and re-typing it here would be a fourth place to keep in sync. */
     segments: unknown[];
 }
-/**
- * Does this reframe track a real subject? A geometric one (a screen-recording
- * point-zoom, an honest center crop) needs nothing detected and must NEVER be
- * handed a detection bill — nor be told it is waiting for one.
- */
 export declare function reframeNeedsDetection(segments: unknown[]): boolean;
-/**
- * Every clip in the composition that has authored a reframe, with the source
- * window its track is keyed by.
- *
- * MIRRORS `collectTrajectoryDeriveJobs`, including the two rules that are easy
- * to get subtly wrong:
- *   · only VIDEO and IMAGE tracks (an audio clip is `kind:"media"` too, and a
- *     viewport crop is meaningless for sound)
- *   · the window is the SOURCE TRIM, defaulted exactly as `renders.ts` defaults
- *     it — `trim.start ?? 0`, `trim.end ?? start + clip.duration`
- *
- * Walked defensively with no zod, the `collectBehindWindows` convention, so it
- * is safe in every bundle.
- */
 export declare function reframeTargets(composition: unknown): ReframeTarget[];
-/**
- * What the editor can say about one reframed clip.
- *
- * `geometric` is a distinct state and not a convenience: a point-zoom on a
- * screen recording is fully derivable with no detection, so calling it
- * "waiting for a track" would be a lie that also implies a charge.
- */
-export type ReframeReadiness = 
-/** No detection needed — derives off a faceless stub, today, for free. */
-{
+export type ReframeReadiness = {
     state: "geometric";
-}
-/** The track exists and can be fetched. */
- | {
+} | {
     state: "track-ready";
     entry: SubjectTrackEntryLike;
     trackUrl: string;
-}
-/** A track is registered but carries no presigned URL, so the client cannot
- *  derive. The RENDER still can — it reads the key directly. */
- | {
+} | {
     state: "track-unfetchable";
     entry: SubjectTrackEntryLike;
-}
-/** Nothing detected at this window yet. This is the state that buys one. */
- | {
+} | {
     state: "no-track";
 };
-/**
- * Can the editor derive this clip's crop trajectory right now?
- *
- * `subjectTracks` is `mediaItems.subjectTracks` for the target's media, exactly
- * as it arrives from Convex — undefined for an item with no cloud perception,
- * which is the honest shape for a local-only import.
- */
 export declare function reframeReadinessForTarget(target: ReframeTarget, subjectTracks: Record<string, SubjectTrackEntryLike> | undefined): Promise<ReframeReadiness>;